Documentation page

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.

26 Jul 2010

DOWNLOAD

These are installation instructions for Moodle 2.x. There is another page for installation instructions for Moodle 1.x.

It’s important to note that the installation of the WIRIS plugin for Moodle 2.x implies installing two components: the WIRIS plugin for Moodle 2 and a configured version of the WIRIS plugin for TinyMCE.

Requirements

  • mbstring extension must be installed and enabled in the server.
  • There must be no errors in http://<moodle>/admin/environment.php

1 Install WIRIS plugin for Moodle 2

The WIRIS plugin for Moodle is a Moodle filter. To install the filter, it suffices to copy the content of the package into the folder filter under the root of moodle.
 

2 Install WIRIS plugin for TinyMCE

2.1 For Moodle 2.4, 2.5 and 2.6

Starting from Moodle 2.4 WIRIS plugin for TinyMCE is a standard Moodle plugin. To install it just copy the tiny_mce_wiris directory into lib\editor\tinymce\plugins under the root of moodle.

2.2 For Moodle 2.2 and 2.3

  1. Copy the files in TinyMCE plugins folder
    You need to install a pre-configured version of the WIRIS plugin for TinyMCE that can be found here.Unzip the above file and copy the tiny_mce_wiris directory into lib\editor\tinymce\tiny_mce\<tiny_mce-version>\plugins under the root of moodle.
     
  2. Activate the icons in the TinyMCE editor
    Edit the file lib\editor\tinymce\lib.php and before the line (which is by the end of the file)

    return $params;

    insert the following code in dark green

    $params['plugins'] .= ",tiny_mce_wiris";
    $params['theme_advanced_buttons3'] = "tiny_mce_wiris_formulaEditor,tiny_mce_wiris_CAS,|," . $params['theme_advanced_buttons3'];

    return $params;

3 Enable the WIRIS plugin for Moodle 2

To enable the WIRIS plugin for Moodle, login as administrator and go to Settings, Site administration, Plugins, Filters and Manage filters. You will see the Wiris filter and you will be able to enable it.

In order to avoid problems, Wiris filter must be the first. For sure it must be placed before Convert URLs into links and images.

Activating the WIRIS filter

4 Check all is OK

The best way to check all is OK is just to create a formula, save and display it.

Additionally there is an info page at http://<moodle>/filter/wiris/info.php. In any issue, please send screenshots of that to support.

26 Jul 2010

There are two important directories:

Integration Cache directory Formula directory
CKEditor <CKEditor>/plugins/ckeditor_wiris/cache <CKEditor>/plugins/ckeditor_wiris/formulas
Cute Editor <Cute Editor>/cuteeditor_wiris/cache <Cute Editor>/cuteeditor_wiris/formulas
FCKEditor <FCKEditor>/editor/plugins/fckeditor_wiris/cache <FCKEditor>/editor/plugins/fckeditor_wiris/formulas
RadEditor <RadEditor>/cuteeditor_wiris/cache <RadEditor>/cuteeditor_wiris/formulas
TinyMCE <TinyMCE>/plugins/tiny_mce_wiris/cache <TinyMCE>/plugins/tiny_mce_wiris/formulas
Xinha <Xinha>/plugins/xinha_wiris/cache <Xinha>/plugins/xinha_wiris/formulas

On Java integration, these paths are provided by you on the configuration.ini file.

Freeing disk space: cleaning the image cache folder

If you want to free your disk space, you can empty the contents of the cache directory. Do not delete the directory but only remove its contents. The cache directory will be repopulated when users view the formulas. 

Important! Do not remove the formula directory because you will lose all your formulas and it will be difficult to recover them. Some plugins, like the Moodle one, do not have this requirement.

Migrating your web server

If you want to migrate your web server, and you want to backup your formula images, you must migrate also the formula directory.

The formula directory contains the MathML of your web site formula images. If these files are removed, you will lose your formulas. Note that the MathML is still stored in the <IMG> tag but it is useless for recovery purposes.

26 Jul 2010

Server configuration file (configuration.ini)

Each plugin has the configuration.ini file in a different place. Check this table to find your file.

Integration File
Moodle 1.x filter/wiris/wrs_config.php (plugin version 2.3 or newer)
pluginwiris/wrs_config.php (plugin version 2.2 or older)
FCKEditor in PHP, ASP and ASP.net <FCKEditor directory>/editor/ plugins/fckeditor_wiris/configuration.ini
CKEditor in PHP, ASP and ASP.net <CKeditor directory>/plugins/ ckeditor_wiris/configuration.ini
TinyMCE in PHP, ASP and ASP.net <TinyMCE directory>/jscripts/tiny_mce/ plugins/tiny_mce_wiris/configuration.ini
Xinha in PHP, ASP and ASP.net <Xinha directory>/plugins/xinha_wiris/configuration.ini
NicEdit in PHP, ASP and ASP.net <NicEdit directory>/nicedit_wiris/configuration.ini
RadEditor in ASP.net <RadEditor directory>/radeditor_wiris/configuration.ini
Cute Editor in ASP.net <Cute Editor directory>/cuteeditor_wiris/configuration.ini
Any editor in Java WEB-INF/pluginwiris/configuration.ini

configuration.ini table

Connection properties
Key Description Default value Possible values
wirisimageserviceprotocol Specifies formula image server protocol. If left blank, it is computed automatically   http, https
wirisimageservicehost(1) Specifies formula image server host. www.wiris.net  
wirisimageserviceport Specifies formula image server port. If left blank, it is computed automatically   (number)
wirisimageservicepath Specifies formula image server path. /demo/editor/render  
wirisimageservice version Specifies formula image version. 2.0 1.0, 2.0
wirisproxy(2) Specifies if your server is using a proxy connection or not. false true, false
wirisproxy_host(2) If wirisproxy is true, this value specifies the proxy host.    
wirisproxy_port(2) If wirisproxy is true, this value specifies the proxy port.    

Configuration & folder properties
Key Description Default value Possible values
wiriscachedirectory(3)(4) Directory where the images of the created formulas are stored.    
wirisformuladirectory(3)(4) Directory where the created formulas are stored.    
wirisstorageclass(3) Name of the class that manages the storage of formulas. This is an advanced feature. See this page. See this page.
wirisconfigurationclass(3) Name of the class that updates the loaded configuration. This is an advanced feature. See this page. See this page.

 

Style properties
Key Description Default value Possible values
wirisimagebackgroundcolor Specifies formula background color. #FFFFFF  
wirisimagecolor Specifies formula foreground color. #000000  
wirisimagefontsize Specifies formula font size. 16px  
wirisfontfamily Specifies formula font family. Arial  
See also the style properties at WIRIS editor.

 

Other properties
Key Description Default value Possible values
wirisimagedpi Defines the dpi's of the formula. A number. 96
wirisimagedefaultstretchy Whether the MathML of the parenthesis are interpreted as stretchy by default. true, false false
See also the other properties at WIRIS editor.

 

WIRIS editor properties
Key Description Default value Possible values
wirisrtllanguages List of Right to Left languages. When the language parameter (see above) belongs to this list, formulas are edited right to left. ar See list of languages
wirisltrlanguages

Used to define Left to Right languages and to overwrite rtlLanguages.

For example, if rtlLanguages is ar and ltrLanguages is ar_ma, all arabic languages are defined as RTL except arabic from Morocco.

ar_ma See list of languages
wirisarabicindiclanguages Used to define languages that use Arabic-Indic numerals(5). ar_eg, ar_sd, ar_sa See list of languages
wiriseasternarabicindiclanguages Used to define languages that use Eastern Arabic-Indic numerals(5). fa, ps, ur See list of languages
wiriseuropeanlanguages Used to define languages that use European numerals and overwrite arabicIndicLanguages and easternArabicIndicLanguages(5).   See list of languages

See also the arabic countries table.

(5) Numbers entered with keyboard are replaced by their equivalents in the numerals assigned to the current editor language.

WIRIS cas properties
Key Description Default value Possible values
wiriscascodebase(1) Specifies where is your CAS applet codebase. http://www.wiris.net/ demo/wiris/wiris-codebase/  
wiriscasarchive(1) Specifies the CAS applet file name. wrs_net_en.jar  
wiriscasclass(1) Specifies main CAS applet class. WirisApplet_net_en  
CAS_width Specifies the default CAS applet width. 450  
CAS_height Specifies the default CAS applet height. 400  

WIRIS editor 2 properties (old)
Key Description Default value Possible values
wirisformulaeditor codebase(1) Specifies where is your formula editor applet codebase. http://www.wiris.net/ demo/formula/codebase/  
wirisformulaeditorarchive Specifies the formula editor applet file name. wiriseditor.jar  
wirisformulaeditorcode Specifies main formula editor applet class. WirisFormulaEditor  
wirisformulaeditorlang

Specifies main formula editor language. See list of languages

en  

(1)The WIRIS plugin needs to access an external server to get additional resources (formula editor applet, image service and WIRIS cas). See architecture for more information. The default configuration connects to www.wiris.com to get such services. However, you might consider acquiring a production access. Under certain circumstances it is possible to install all necessary services in the customer server (not only the plugin).

(2)These options are only available on PHP integrations.

(3)These options are only available on Java integrations.

(4)These options must be filled on Java integrations and are not optional.

JavaScript configuation files

Some configuration parameters should be defined directly in the following javascript files.

JavaScript configuration files
Integration File
CKEditor ckeditor/plugins/ckeditor_wiris/plugin.js
FCKEditor fckeditor/editor/plugins/fckeditor_wiris/fckplugin.js
TinyMCE tiny_mce/plugins/tiny_mce_wiris/editor_plugin.js
Xinha xinha/plugins/xinha_wiris/xinha_wiris.js
Generic pluginwiris/integration/integration.js