Documentation page

8 Sep 2010

The manual is included in the product web pages.

USER  MANUAL

It has two parts:

  • Quick Guide - Tour of the basic mathematical areas covered by WIRIS cas. Includes a chapter to learn how to use it in one minute.
  • Alphabetic Index - Complete list of WIRIS cas commands.
3 Aug 2010

 

Introduction

 

This document will provide assistance to those developers who want to integrate WIRIS Formula Editor and CAS in their platforms and there is not a specific plugin already available. More precisely this document covers two scenarios:

  • Integrating the WIRIS components into an HTML editor. See a live demo.
  • Integrating the WIRIS components into a simple Textarea. For example into wiki’s, blog’s and other Web applications that uses plain textarea’s to edit rich HTML text. See a live demo.

Before starting any development, please, ensure that there is no plugin already available for your needs. See WIRIS editor and WIRIS cas plugins.
 

DOWNLOAD - HTML editor Plugin                DOWNLOAD - Textarea Plugin


1 Requirements

  • A web server with PHP, ASP.NET, ASP or Java servlets compatibility (or other language, but our internal engine is only distributed in PHP, ASP.NET and as Java servlet).
  • A web server with UTF-8 encoding compatibility.
  • Knowledge about Javascript language.
     
  • A valid license to install the plugin in a production environment; otherwise, you can use the downloaded file just for demo purposes.

Important note: In versions older than 3.50.0 the name of the plugin directory was pluginwiris instead of generic_wiris.

2 Starting

2.1 For PHP servers

  1. mbstring extension must be installed and enabled in the server.
  2. Copy generic_wiris directory in your web system root path. Then, open generic_wiris/configuration.ini and set your own values. This table specifies all possible parameters.
  3. Give execution right to the web server user on the PHP files contained at generic_wiris/integration.

2.2 For ASP.NET servers

Copy generic_wiris directory in your web system root path.

Create an application on your IIS through your control panel. The application root directory depends on the WIRIS Plugin package that you have downloaded.

  • For demo package: create an application with root directory on the extracted folder.
  • For integration package: create an application with root directory on /generic_wiris. For versions older than 3.50.0 you need to create the application at /pluginwiris/integration. If, given your project requirements or architecture, you need to have only one application move /generic_wiris/bin contents to the /bin directory of your project and copy the Web.config configuration to your project Web.config. If you use .NET 4.0 or above use the values of Web.config4.0.

Now, open generic_wiris/configuration.ini and set your own values. This table specifies all possible parameters.

2.3 For ASP servers

Copy pluginwiris directory in your web system root path. Then, open pluginwiris/configuration.ini and set your own values. This table specifies all possible parameters.

2.4 As Java servlet

  1. Install the pluginwiris_engine.war in your Java web applications server (tomcat).
  2. By default, the javascript code loads the pluginwiris_engine from the root of web application server (/pluginwiris_engine/app). However, if you want to store the pluginwiris_engine in another path, you should edit these javascript codes:
    1. Open generic_wiris/integration/integration.js.
    2. Change the variables _wrs_conf_editorPath, _wrs_conf_CASPath, _wrs_conf_createimagePath and _wrs_conf_createcasimagePath with your preferred values.
    3. Save changes.
  3. Copy generic_wiris directory in your web system root path. Then, open pluginwiris_engine/WEB-INF/generic_wiris/configuration.ini and set your own values. This table specifies all possible parameters. For versions older than 3.50.0 it is essential that you set wiriscachedirectory and wirisformuladirectory.

3 Rules

There are some rules for plugin develop:

  • Don’t edit generic_wiris/core files. These files are the plugin kernel. We pledge to upgrade only those files in future versions.
  • Edit your generic_wiris/integration/integration.js file to integrate the plugin. That file contains instructions about how to do it.

Important complementary information

WIRIS Plugin follows this criterion:

  • It uses the generic_wiris/formulas (on Java servlet integration you specify this directory) directory to save the MathML of the formulas (source of the formulas). These files are very important. If you want to migrate your web server, remember copying that directory, or your created formulas (for example, in post forums) will be lost.
  • It uses generic_wiris/cache (on Java servlet integration you specify this directory) directory to save image files. These files aren’t very important. You can delete them whenever you want; they will be created again automatically when browsers will request the images of the formulas.

You can use this example code to load your implementation:

<script type="text/javascript" src="./generic_wiris/core/core.js"></script>
<script type="text/javascript" src="./generic_wiris/integration/integration.js"></script>

Then, you can use this example code to start the WIRIS plugin when your editor is loaded:

wrs_int_init(<your wrs_int_params, see integration.js>);

Environment variables

WIRIS Plugin core uses three global variables that you should use/modify:

  • _wrs_currentPath: contains the current URL path (for Safari fixes).
  • _wrs_isNewElement: you must set this Boolean variable when you are opening a new editor window true or false depending if you are creating a new formula or editing it.
  • _wrs_temporalImage: you must set this object variable when you are opening a new editor window. It must contain the image that you are editing. See integration.js for more information.

6 Functions

There are core functions that you can use but not modify. These functions are in generic_wiris/core/core.js .

7 Simple examples

There are simple examples of WIRIS Plugin integrations that you can download. These are our live demos.

3 Aug 2010
v2.3    v3.0

WIRIS Editor is a WYSIWYG formula editor designed to streamline the process of writing mathematical formulae. It is a powerful tool that allows composing any math expression with high graphics quality, while remaining simple and easy to learn.

The formulae written have to be placed somewhere; in this section we will describe its use within Moodle, but WIRIS editor is used in other contexts with a minimum of differences.

There are two ways you can open WIRIS editor:

  • If you want to modify an existing formula, double click on it;
  • If you want to write a new formula, move the cursor to the place you want to write it in, and then click on the icon in the editor toolbar.

editor_in_context

After writing or modifying the formula, click on OK if you want to insert the formula as it is shown, or Cancel if you want to exit without saving changes.

Formulae are treated as any other kind of object:

  • You can select formulae by either clicking on them or by moving the cursor over them while holding the SHIFT key.
  • You can erase formulae by selecting them and pressing delete, or by moving the cursor after (before) them and pressing the delete (supr) key. If you delete a formula accidentally, you can recover it by clicking on the undo icon, .
  • You can cut, copy and paste formulae in the usual way, by pressing CTRL-X, CTRL-C and CTRL-V; this is particularly useful when you have to write several formulae which are very similar. You can apply all of those edition operations to a single formula or to combinations of formulae and text, and you can paste to other WIRIS windows.
  • Some text formatting functions work with formulae; for instance, if you want to center a formula, select it and click on the icon.
28 Jul 2010

The architecture of a system that uses the WIRIS editor with a WIRIS plugins is explained here.

Architecture related to the view mode

Formulas that appear in HTML Web pages are encoded using ordinary images. This allows that such pages can be displayed correctly in all web browsers. The names of the images are irrelevant from the point of view of the user. For the curious, it corresponds to the md5 computation of the source code of the formula (usually MathML).

Web Page example with formulas

A fragment of the source code of the example HTML page is the following:

...
<p>Example 4.6.2.</p>
<ul>
    <li>
        <img align="middle"
            src="http://.../wrs_showimage.php/ebcec7125e1caefc7da84ce32862edc3.png"
            alt="limit under x to infinity..."
            data-mathml="«math»«munder»«mi»lim«/mi»…«/math»"
            class="Wirisformula" />
    </li>
    <li>
        <img align="middle"
            src="http://.../wrs_showimage.php/ab12ce19d310b571533a4a202a21ujhg.png"
            alt="limit under x to infinity..."
            data-mathml="«math»«munder»«mi»lim«/mi»…«/math»"
            class="Wirisformula" />
    </li>
...

The ugly name ebcec7125e1caefc7da84ce32862edc3is the md5 encoding of the source of the formula which is MathML.

<math>
  <munder>
    <mi>lim</mi>
    <mrow>
      <mi>x</mi>
      <mo>&rarr;</mo>
      <mo>&infin;</mo>
    </mrow>
  </munder>
  <mfenced>
    <mrow>
      <mn>2</mn>
      <mo>+</mo>
      <mfrac>
        <mn>1</mn>
        <msup>
          <mi>x</mi>
          <mn>2</mn>
        </msup>
      </mfrac>
    </mrow>
  </mfenced>
  <mo>=</mo>
  <mn>2</mn>
</math>

The MathML will be used to modify existing formulas by authors.

The alt attribute stores the textual version of the formula used for accessibility and that can be read by assistive technologies like, for example, JAWS.

The data-mathml attribute stores a copy of the MathML of the formula. In view mode, this attribute is not used but is needed for the edition. In both cases (viewing and edition), the <img> tag is the same. Note that the MathML stored in this tag does not use the common <, > symbols but «, » (see the page encoding MathML in HTML attributes for more information).

The server is responsible to provide such images, because they are stored in the file system or are computed dynamically calling the Web WIRIS Formula Image service. The server must also keep a cache of the computed images and a way to recover the source code of the image from its name (the md5). This task is performed by server-side scripting with technologies like PHP, Java or others.

Note that the WIRIS Formula Image Service can be located in a different machine than the Http Server.

Diagram with the main components of the view mode

To see this in more detail, the sequence diagram associated to the view mode is the following:

The User opens a Web page that contains formulas.

The responsibility of the Http Server is serving content to the user computer, in particular, all formulas and images.

WIRIS plugin server-scripting is a collection of scripts that executes on the server side and is part of the WIRIS plugin. For example, they can be written in PHP or Java.

WIRIS plugin storage. The WIRIS plugin needs to store information about how to recover the formulas source (MathML) from the md5 computation. This storage can be files or a database.

WIRIS plugin cache. The images associated to the formulas are stored here. Because this is a cache they can be removed anytime.

WIRIS Formula Image Service. It is the Web Service that generates images from the formula source.

The events proceed as following:

  1. formula (md5 image): The user opens a Web page that contains formulas. The formulas are images; so, they are requested to the remote Http Server. The name of each formula is the md5 computation of the source code of the formula.
  2. The Http Server delegates the formula image request to the WIRIS plugin server-scripting.
  3. The WIRIS plugin server-scripting tries to retrieve the image from the cache (get image from md5). However, the image might be inexistent (because this is the first time the image is requested or the cache has been cleaned).
  4. If the image is not in the cache, the source code of the formula is recovered from the WIRIS plugin storage (get image from md5) and the WIRIS Formula Image Service is called (get image from formula). The image is stored in the cache (put image and md5).
  5. Either because the image is in the cache or is computed with the Image Service, it is finally returned to the Web browser.

Architecture related to edit mode

The edition of formulas is a little bit more complex. We assume that the edition of formulas is done inside an HTML editor.

The following is a screen-shot of an HTML editor which contains an icon to insert formulas (this example is taken from the Moodle integration).

The following sequence diagram explains how the edition on a new formula works.

The User means the author who wants to edit a new formula once he HTML editor is already loaded in a Web page.

The HTML Editor is the software component that manages the HTML edition.

The WIRIS plugin javascript is the component that has been installed inside the HTML editor that enables the insertion and edition of formulas. It is implemented with JavaScript and related resources.

The WIRIS plugin Formula Editor PopUp is a pop up Window that contains a Java applet with the Formula Editor.

WIRIS plugin server scripting is a set of scripts that are called by the WIRIS plugin.

WIRIS plugin storage means any way to store the association from the computed md5 to the original formula source code. This can be done using simple files or a database.

The sequence of messages is the following.

  1. The user “clicks the new formula icon” to insert a new formula where the cursor is placed. The event is intercepted by the HTML Editor which delegates it to the WIRIS plugin.
  2. The WIRIS plugin “opens” a PopUp window with the formula editor.
  3. Then, the user edits the desired formula (“formula edition”).
  4. And decides to “accept” the formula.
  5. The “formula” is sent to the WIRIS plugin.
  6. The WIRIS plugin calls a server-side script to compute the img tag with the md5 that will be inserted in the HTML editor.
  7. The WIRIS plugin inserts the img tag in the HTML editor where the cursor is placed.

Now, the editing HTML page contains an img tag that corresponds to a formula. Then, all the process explained in the view mode takes place.

The edition of existing formulas process is quite similar to the creation of new ones. When the user clicks over the “formula icon”, the WIRIS plugin checks whether an image of a formula is selected and if it is the case, the Pop Up Window with the formula editor is opened. The content of the formula editor is populated with the value of the data-mathml attribute of the img tag of the existing formula (see view mode). On accepting the formula, the image is replaced instead of being inserted anew.

28 Jul 2010

Find in the submenu on the left the available documents.

If you can't find what you are looking for, do not hesitate to message support@wiris.com.