WIRIS editor and WIRIS plugins for

developers
Document Release: 1.4
2011 april, Maths for More
www.wiris.com

Contents
WIRIS editor and WIRIS plugins for developers............................................................................................................. 2
WIRIS plugin configuration ........................................................................................................................................ 3
Runtime configuration........................................................................................................................................... 3
Other ways to set the configuration...................................................................................................................... 3
Editing and displaying formulas with a Web HTML editor ........................................................................................ 3
Low level visualization of formulas ........................................................................................................................... 3
Filtering formulas in a bunch of content ............................................................................................................... 4
Low level use of the editor Java plugin ..................................................................................................................... 4
WIRIS plugin core reference ...................................................................................................................................... 5
Formula persistence and cache ............................................................................................................................. 5
Configuration override .......................................................................................................................................... 5
Storing MathML ..................................................................................................................................................... 6
WIRIS plugin core server API ................................................................................................................................. 6
WIRIS plugin core client API .................................................................................................................................. 6
WIRIS editor API reference ........................................................................................................................................ 6

2010, Maths for More

WIRIS quizzes in your assessment system. V1

WIRIS editor and WIRIS plugins for developers

WIRIS editor provides the visual editor (Java plugin) and the formula image service. They are the basic ingredients
of the formula edition and visualization process.
WIRIS plugins wrap WIRIS editor (and also WIRIS CAS) and are essential components to any WIRIS integration.
There is not a single WIRIS plugin but a whole family of plugins, each one targeting its specific functionality. The
common features of all WIRIS plugins are called the WIRIS plugin core.

Layer diagrams: WIRIS editor/WIRIS plugin core/WIRIS plugin/Web application

Web application is any Web portal/Web application where exists the need to visualize and/or edit formulas.
WIRIS plugin is the out of a box product that can be installed on a given set of HTML editors and Web applications.
Thus, it is installed in the servers of our customers. It is the easiest way to add a formula editor to any system.
Formulas are stored as an <img> tag in the database with the associated MathML is stored as an attribute. Plugins
can be configured to store MathML instead of the <img> tag. But in this case, the web application is responsible to
filter back the MathML to <img>. The WIRIS plugins can be downloaded for free provided you have a valid license
to a WIRIS editor.
WIRIS plugin core is a component present on each WIRIS plugin: it does not constitute a product by itself. It
provides a subset of functionality shared by all plugins. You only need to call the WIRIS plugin core directly if you
are doing a low level integration with an html editor which not exists yet a WIRIS plugin or a more sophisticate
application like a mathematical assessment system. The WIRIS plugin core is not distributed alone but inside any
WIRIS plugin. To get the most lightweight version of the WIRIS plugin core, you can use the generic WIRIS plugin.
WIRIS editor it is rarely used alone. It provides a Java applet for the edition of formulas which is responsible of
generating MathML and an image service that translates from MathML to images. WIRIS editor is software used as
service (SAS) but it can be hosted by our customers if some additional requirements are met.

2010, Maths for More

WIRIS quizzes in your assessment system. V1

WIRIS plugin configuration

A lot of things can be configured for the WIRIS plugin:
1.
2.
3.
4.

Font size, colors and type face of the formulas.

Whether store MathML or <img> tags in the database.
The language, size and features of the user interface editor applet and window.
The web addresses of the WIRIS editor services.

The place of the configuration files and its possible values can be found at
1. http://www.wiris.com/plugins/docs/resources/configuration-table
2. The XXX_plugin.js that can be located in any WIRIS plugin.
The configuration of the font typeface can be found at
http://www.wiris.com/en/editor/docs/resources/font-configuration
Runtime configuration
The configuration described above can be overridden at runtime. For example, if you have a multilingual Web site,
you will need to select the language at runtime regardless the value of the configuration.
How to set a runtime configuration will depend on the configuration item. For example, the language of the editor
should be specified in the user interface scripting while there are other parameters that have to be set at the
server scripting. In any case, to learn how to set the runtime configuration, you will need to check the specific
installation documentation for each plugin.
Other ways to set the configuration
The section of this document concerning the WIRIS plugin core reference explains other ways to store the
configuration in the server-side. For example, some values could be stored in a database.
Editing and displaying formulas with a Web HTML editor
The most frequent use case is solved directly by the WIRIS plugins with minimal configuration. For example, the
following scenario is fully supported
1. A user edits some piece of content with a Web HTML editor.
2. The user adds a formula using a WYSIWYG editor in a very straightforward way.
3. Formulas are displayed properly when the content is finally rendered.
4. Formulas can be changed when the main content is reedited.
Other uses not covered by the above scenario can be implemented in any system with the help of the WIRIS plugin
core features.
Low level visualization of formulas
This section starts with the hypothesis that there is some MathML that needs to be rendered in the browser. The
MathML might come from the WIRIS editor, WIRIS quizzes or even from any other software (like a mathematical
engine or, more specifically, a computer algebra system).
The easiest, but not recommended, way to do that is simply writing in the html page
<img src=http://www.wiris.net/demo/formula?mml=<mahtml> />

2010, Maths for More

WIRIS quizzes in your assessment system. V1

Assuming that <mathml> is property encoded as URL, the above might fail if the formula is too long. The solution
needs that the server calls the createimage previous generate the <img>. It is as follows:
1. In the server, send the formula to the Web service createimage implemented by the WIRIS plugin core.
2. Write an img tag with a src with the form
<img src=http://<domain>/<some-path>/showimage?formula=<digest>.png />

Where <digest> is what was returned in the step 1.

Another benefit of using createimage is that the styling attributes specified in the configuration configuration
are applied.
The WIRIS plugin core also provides an API to call createimage directly without the need to call a Web service.
Filtering formulas in a bunch of content
You can use a filter function of the WIRIS plugin core to automatically detect the MathML fragments scattered
among the content and transform them into the appropriate <img> tags. Such filter will transparently call
createimage as many times as necessary.
Low level use of the editor Java plugin
You can check the source code of the main page of the editor at
http://www.wiris.net/demo/formula
To add an editor in a Web page, just add the following <applet> tag
<applet name="FormulaEditor" code="WirisFormulaEditor"
archive="wiriseditor.jar"
codebase="http://www.wiris.net/demo/formula/codebase"
width="600" height="400">
Your browser does not appear to support applets
<param name="version" value="2.0"/>
</applet>

To initialize it with a formula just add the content parameter:

<applet name="FormulaEditor" code="WirisFormulaEditor"
archive="wiriseditor.jar"
codebase="http://www.wiris.net/demo/formula/codebase"
width="600" height="400">
Your browser does not appear to support applets
<param name="version" value="2.0"/>
<param name="content" value="<math><mfrac><mn>1</mn><mi>x</mi></mfrac></math>"/>
</applet>

The WIRIS applet exposes a public API that allows, for example, setting or getting the MathML of the formula with
JavaScript. Such API is documented at
http://www.wiris.net/demo/formula/docs/api/
For example, a form that submits the content of the editor might be:
<form
onsubmit="getElementById('formula').value=getElementById('edt').getContent();">
<applet id="edt" code="WirisFormulaEditor"
archive="wiriseditor.jar"
codebase="http://www.wiris.net/demo/formula/codebase"
width="600" height="400">
Your browser does not appear to support applets
<param name="version" value="2.0"/>
</applet>
<br/>

2010, Maths for More

WIRIS quizzes in your assessment system. V1

<input type="hidden" id="formula" name="formula"/>

<input type="submit"/>
</form>

The configuration of the plugin allows selecting how formulas are stored.
WIRIS plugin core reference
You need to know about the WIRIS plugin core if you require a functionality not currently provided by the existing
WIRIS plugins.
WIRIS plugin core is the common part of all WIRIS plugins. The main objective is to grant the long term software
maintenance of the plugins via a reusable component.
WIRIS plugin core is divided in two main subcomponents: client and server parts. The client subcomponent of the
core is based on a series of html and JavaScript files. The server subcomponent is implemented in different server
technologies: PHP, Java, .NET, ASP.
Formula persistence and cache
The WIRIS plugin needs to store two kind of information (see the section Low level use of the editor). By default,
such information is stored in the file system.
1. The inverse association <digest> to MathML. This information cannot be removed unless exists a
mechanism that is able to regenerate them.
2. A cache with the images generated from MathML. This cache can be removed if necessary and it will be
regenerated when formulas are displayed.
Configuring the formula persistence and cache
In the configuration.ini is specified the class that will perform the persistence and cache of the formulas. You will
not generally need to change such class unless you want to redefine any of the following features:
1. The algorism used as <digest> of a formula. For example, change from md5 to sha1.
2. Change the way the <digest> values are stored. For example, they could be stored in a relational
database. The default behavior is use the file system.
3. Change the way the images are stored. For example, they could be stored in a relational database. The
default behavior is use the file system.
You can define your own class. That class should implement the interface
com.wiris.plugin.storage.StorageAndCache

and modify the configuration.ini to point to your class. The documentation of the interface can be found at
http://www.wiris.com/pluginwiris_engine/docs/api
For the Java plugin, inside pluginwiris_engine.war can be found the compilation-time library WEBINF/lib/wirisplugin-api.jar.
Configuration override
The configuration of the plugin is read from the configuration.ini file. However, it is possible to provide a class used
to override any value of the configuration. For example, it could be used to store some entries of the configuration
in a database.
Such class must be specified in the configuration.ini (the class overrides some definitions but the configuration.ini
file is still necessary). The class must implement the interface

2010, Maths for More

WIRIS quizzes in your assessment system. V1

com.wiris.plugin.configuration.ConfigurationUpdater

For the Java plugin, inside pluginwiris_engine.war can be found the compilation-time library WEBINF/lib/wirisplugin-api.jar. The API documentation is at
http://www.wiris.com/pluginwiris_engine/docs/api
Storing MathML
WIRIS plugin, by default, stores formulas edited with the HTML editor as <img> tags with the MathML in the alt
attribute. Let us note that the src attribute of the <img> tag contains only the <digest> value.
You can configure to store directly MathML instead of the <img> tag. In this case, a filter should be applied to
transform the MathML content into images. This is the recommended way to use the WIRIS plugin if there is the
possibility to develop such filter. The WIRIS plugin core server API contains functions to help develop such filter.
WIRIS plugin core server API
The server subcomponent provides the following services:

createimage. Inputs the MathML of a formula and styling attributes. It returns the URL where the image

is found. The resulting url has the form:

<some-domain>/<some-path>/showimage?formula=<digest>.png

showimage. Inputs the <digest> of a formula and returns the associated image in png format. It is

possible to specify additional styling attributes in addition to the ones encoded inside the <digest>.
getmathml. Inputs the <digest> of a formula and returns the MathML of the formula and styling
attributes.

Note. The <digest> is the computed id of the MathML and styling attributes. It is usually the md5, sha1 or even
the gzipped compression of the formula.
The server components are also responsible to caching the images. This feature is especially important when the
WIRIS editor is hosted in a different server for performance reasons.
WIRIS plugin core client API
At present, the WIRIS pluginc core client components are not documented and not expected to be reused.
WIRIS editor API reference
WIRIS editor API reference can be accessed at
http://www.wiris.net/demo/formula/docs/api/
The parameters that the applet accept are defined at
http://www.wiris.net/demo/formula/docs/other/parameters.html