Generic WIRIS plugin

1        Generic WIRIS plugin guide

1.1      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 http://www.geniisoft.com/showcase.nsf/WebEditors. See a live demo here.
  • 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 here.

 

Before staring any development, please, ensure that there is no plugin already available for your needs. See Formula and CAS plugin’s.

Note: you should have a valid license to install the plugin in a production environment; otherwise, you can use the downloaded file just for demo purposes. To acquire the full rights license, please contact to info@wiris.com or visit www.wiris.com.

1.2      Prerequisites

  • Generic PluginWIRIS.
    1. If you want to integrate PluginWIRIS with an HTML editor, you can download it from here (for PHP servers), here (for ASP.NET servers) or here (as Java servlet). Also you can download an integrated demo from here (for PHP servers), here (for ASP.NET servers) or here (as Java servlet).
    2. But if you want to integrate PluginWIRIS with a simple textarea, you can download it from here (for PHP servers), here (for ASP.NET servers) or here (as Java servlet). Also you can download an integrated demo from here (for PHP servers), here (for ASP.NET servers) or here (as Java servlet).
  • A web server with PHP, ASP.NET 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.

1.3      Starting

1.3.1      On PHP and ASP.NET integrations

The first step is copying pluginwiris directory (next to this readme file) in your web system root path. Then, open pluginwiris/configuration.ini and set these fields:

1.3.2      On Java integration

  1. Install the pluginwiris_engine.war (next to this readme file) in your Java web applications server (tomcat).
  2. Edit the WEB-INF/web.xml and set the params cacheDirectory and formulaDirectory. cacheDirectory is the directory where your temporal formula images will be stored. formulaDirectory is the directory where your formula will be stored (as xml files). You must create both directories. The servlet should have write rights on both directories.
  3. 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 pluginwiris/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.
  4. Copy pluginwiris directory (next to this readme file) in your web system root path. Then, open pluginwiris/configuration.ini and set these fields:

 

Key

Description

Default value

Possible values

wirisimageservicehost(1)

Specifies formula image server host.

services.wiris.net

 

wirisimageserviceport

Specifies formula image server port.

80

 

wirisimageservicepath

Specifies formula image server path.

/formula/render

 

wirisimagebgcolor

Specifies formula background color.

#FFFFFF

 

wiristransparency

Specifies whether formula background must be transparent.

true

true, false

wirisimagesymbolcolor

Specifies formula foreground color.

#000000

 

wirisimagefontsize

Specifies formula font size.

16

 

wirisformulaeditorcodebase(1)

Specifies where is your formula editor applet codebase.

http://services.wiris.net/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.

en

ar, ca, de, es, et, en, eu, fr, gl, it, nl, pt, zh

wiriscascodebase(1)

Specifies where is your CAS applet codebase.

http://www.wiris.net/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

 

wirisproxy

Specifies if your server is using a proxy connection or not.

false

true, false

wirisproxy_host

If wirisproxy is true, this value specifies the proxy host.

 

 

wirisproxy_port

If wirisproxy is true, this value specifies the proxy port.

 

 

(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 services.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).

1.3.3      For ASP.NET servers

If you are using PluginWIRIS for ASP.NET version, you must create an application on your IIS through your control panel. The application root directory depends on the PluginWIRIS 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 ./<plugin directory>/integration/.

 

How to create applications: http://support.microsoft.com/kb/172138

1.4      Rules

There are some rules for plugin develop:

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

1.5      Important complementary information

PluginWIRIS follows this criterion:

  • It uses the pluginwiris/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 pluginwiris/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="./pluginwiris/core/core.js"></script>
<script type="text/javascript" src="./pluginwiris/integration/integration.js"></script>

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

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

1.6      Environment variables

PluginWIRIS 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.

1.7      Functions

There are the core functions that you can use (but not modify!). There are in pluginwiris/core/core.js.

 

wrs_addEvent(element, event, func);

            Cross-browser addEventListener/attachEvent function.

            @param object element Element target

            @param event event Event

            @param function func Function to run

 

wrs_removeEvent(element, event, func);

            Cross-browser removeEventListener/detachEvent function.

            @param object element Element target

            @param event event Event

            @param function func Function to run

 

wrs_addIframeEvents(iframe, doubleClickHandler, mousedownHandler, mouseupHandler);

            Adds iframe events.

            @param object iframe Target

            @param function doubleClickHandler Function to run when user double clicks the iframe

            @param function mousedownHandler Function to run when user mousedowns the iframe

            @param function mouseupHandler Function to run when user mouseups the iframe

 

wrs_addTextareaEvents(textarea, clickHandler);

            Adds textarea events.

            @param object textarea Target

            @param function clickHandler Function to run when user clicks the textarea

 

wrs_mathmlDecode(input);

            WIRIS special encoding.

            We use these entities because IE doesn’t support html entities on its attributes.

            @param string input

            @return string

 

wrs_mathmlEncode(input);

            WIRIS special encoding.

            We use these entities because IE doesn’t support html entities on its attributes.

            @param string input

            @return string

 

wrs_mathmlEntities(mathml);

            Converts special symbols (> 128) to entities.

            @param string mathml

            @return string

 

wrs_updateFormula(iframe, mathml);

            Inserts or modifies formulas.

            @param object iframe Target

            @param string mathml Mathml code

 

wrs_updateCAS(iframe, appletCode, image, imageWidth, imageHeight);

            Inserts or modifies CAS.

            @param object iframe Target

            @param string appletCode Applet code

            @param string image Base 64 image stream

            @param int imageWidth Image width

            @param int imageHeight Image height

 

wrs_updateTextarea(textarea, text);

            Inserts or modifies formulas or CAS on a textarea.

            @param object textarea Target

            @param string text Text to add in the textarea. For example, if you want to add the link to the image, you can call this function as wrs_updateTextarea(textarea, wrs_createImageSrc(mathml));

 

wrs_mathmlToImgObject(creator, mathml);

            Converts mathml to img object.

            @param object creator Object with “createElement” method

            @param string mathml Mathml code

            @return object

 

wrs_createImageSrc(mathml);

            Gets formula image src with AJAX.

            @param mathml Mathml code

            @return string

 

wrs_appletCodeToImgObject(creator, appletCode, image, imageWidth, imageHeight);

            Converts applet code to img object.

            @param object creator Object with “createElement” method

            @param string appletCode Applet code

            @param string image Base 64 image stream

            @param int imageWidth Image width

            @param int imageHeight Image height

            @return object

 

wrs_createImageCASSrc(image);

            Gets CAS image src with AJAX.

            @param string image Base 64 image stream

            @return string

 

wrs_urlencode(clearString);

            URL encode function.

            @param string clearString Input

            @return string

 

wrs_createHttpRequest();

            Cross-browser httpRequest creation.

            @return object

 

wrs_getCode(imageMd5);

            Gets the formula mathml or CAS appletCode using its image md5 sum.

            @param string imageMd5 Image md5 sum.

            @return string

 

wrs_createObject(objectCode);

            Creates new object using its html code.

            @param string objectCode

            @return object

 

wrs_createObjectCode(object);

            Converts an object to its HTML code.

            @param object object

            @return string

 

wrs_initParse(code);

            Parses initial HTML code, converts CAS applets to CAS images.

@param string code

@return string

 

wrs_endParse(code);

            Parses end HTML code, converts CAS images to CAS applets.

            @param string code

            @return string

1.8      About demonstrations

We have some WIRIS Plugin demonstrations. You can download these demonstrations and read the code to know how Plugin WIRIS really works. Also, you can integrate this code on your own platform.

Available demonstrations:

  • Plugin WIRIS integrated with a HTML editor (PHP demo, ASP.NET demo, Java servlet demo; download for PHP, download for ASP.NET, download as Java servlet). This demonstration creates a new HTML editor and uses Plugin WIRIS over it. All of the integration is at client side. You don’t need to develop any kind of filter for HTML code at server side. This demonstration provides WIRIS Formula Editor (create and edit formula images) and WIRIS CAS (create and edit CAS java applets, for advanced results).
  • Plugin WIRIS integrated with a textarea (PHP demo, ASP.NET demo, Java servlet demo; download for PHP, download for ASP.NET, download as Java servlet). This demonstration creates a textarea based editor and uses PluginWIRIS over it. The integration inserts formula images as links to the PNG file, and the server is who must convert these links to image HTML tags. This demonstration provides a filter example to create and edit formula images. Also you can insert CAS objects as links to the PNG previsualization files. The server is who must convert these links to applet tags. This demonstration also provides a filter example to create and edit CAS objects.