DragMath equation editor

Introduction

To quote the W3C [1]:

This is an open-source drag and drop equation editor written in Java.
Once an expression is created the user can convert it into a variety 
of different linear syntax for mathematics, including MathML, LaTeX,
Maple, Maxima or any user defined style.

Created by Christoper Sangwin and Alexander Billingsley at the University of Birmingham as part of the STACK project, DragMath allows students to build mathematical expressions using a graphical drag-and-drop interface similar in appearance to that available in a number of office productivity suites.

Initially integrated with Moodle to be used with Moodle's Tex filter, the export feature available with DragMath has now allowed an integration that supports the creation of LaTex text expressions with and without the doubledollar signs used to signal parsing by the filter as well as AsciiMathML text expressions.

To use DragMath, users must have the Java Runtime Environment (JRE) version 1.5 or higher installed on their desktop computers. Most systems come with the JRE as standard equipment, so you may not have to do anything. If you need to install the JRE manually, you can download it from here. Note that the JRE is variously known as Java software for your computer, Java Runtime Environment, the Java Runtime, Runtime Environment, Runtime, Java Virtual Machine, Virtual Machine, Java VM, JVM, VM, or Java download.

You can see a demo of the DragMath editor here. The DragMath interface is highly intuitive and anyone can be using it productively after a few minutes of trial-and-error. If you have questions about the editor, there is a short manual here.

How the DragMath editor has been integrated with Moodle

DragMath is integrated with Moodle through a new button on the editor toolbar. This way, the DragMath editor is available everywhere that you or your students are called upon to enter text. Please note: The DragMath editor does not come supplied with Moodle. You (or your administrator) will have to install it. The following comments are targeted at the single file install, which has retained the beloved smileys.

Getting Started

Suppose that you're entering text in the HTML editor and you reach a point where you want to insert a mathematical expression. You want to be able to show the tedxt expression you would use to create an equations as well as the equations itself. Pushing the DragMath button launches the DragMath editor in a small popup window (Note: the first time you do this, there will be a delay of a few seconds due to applet initialization).

Create the math expression in DragMath

Drag the various graphic constituents of your equation into the construction area until the equation is to your satisfaction.

Save the expression

From the Menu Bar click File->Save As or click on the floppy icon. Provide a local location where you want to save the equation and the applet stores the equation there in a .dgrm file.

Select Export Format

From the Menu Bar click Options->Set Export Format. If you want to insert the text expression for a tex formula, select LaTex. If you wish to insert the text expression with the doubledollar toeksn so that the expression will be converted by the moodle tex filter, select MoodleTex (this will likely be the default choice in your applet). If you have replaced your tex filter with the ASCIIMathML filter, select ASCIIMathML.

Insert the expression

Click the "Insert button" and you're done. The editor will disappear and the output you selected will be inserted. If you chose MoodleTex, the LaTeX expression (with $$ delimiters added at both ends) will be inserted into your text at the current cursor position. Note the screen shot below. This demonstrates the results when you have selected MoodleTex to insert the equation in your work. Note ASCIIMathML users: the ASCIIMathML.xml file currently has backtics set as tokens. You can edit that file to use the auto nomenclature if you choose

Altering Applet Parameters

In the case of HTMLarea, the applet parameters are set in dlg_ins_dragmath.php which can be found in moodleroot/lib/editor/htmlarea/popups . Should you wish to change the default export format or implement additional parameters after reviewing the DragMath documentation, please remember to back up a copy of your original file. The various XML export formats, which you can customize (with care) can be found at moodleroot/lib/editor/htmlarea/plugins/applet/classes/formats and the xml configuration file, Config.xml, in classes.

Installing DragMath

Initially, DragMath required separate installation of both the Moodle Integration package and the DragMath package. DragMath has become so popular, that it is now offered in a simgle zip that includes not only the integration files (at least for htmlarea for the present) but the integration files as well. For the user this means that one can simply download one zip file, place it in the moodle root and unzip.

However, in as much as there are innumerable installations of DragMath based on the separate install, installation documents and source information will remain published here for the short term.

Installing DragMath From the Moodle CVS

This could not be easier. If you are running verion 1.9.+ click here or if you are running Moodle version 1.8.4 or greater but not 1.9.x click here and you will start the download of the zip file (at present there are no differences between the two versions. At this point you can unzip on your workstation and then you can upload the included files to their appropriate locations. This version retains the smileys and includes all integration files and all DragMath files (demos, docs, and all export formats) Warning: At present the zip file includes a version of adminlib.php that should NOT be used with Moodle 1.8.2 If you are using 1.8 DO NOT over write your adminlib.php. Install the rest of the files (other than adminlib.php) and DragMath will work without a problem.

Apparently the Moodle automagically creates the zip with a parent directory of "dragmath". Should you wish you can unzip the files and then rezip with the top level directory being /lib, and this will allow you to simply upload the zip you just created to your moodle root and unzip there, and the files will be placed in their appropriate locations. However, please make sure all files are backed up, and in as much as there are only a few files you may want to manually install even if a zip with /lib as top directory were provided here just to ensure each file is backed up before installation. Upload the zip file to your Moodle root and unzip.

Installing DragMath Integration and DragMath Applet Separately

You install DragMath in two steps

Install the DragMath package
Install the DragMath integration package

=====Install the DragMath package =====

Download the latest DragMath package from sourceforge and unzip it in the $CFG->dirroot/lib/editor/htmlarea/popups directory (where $CFG->dirroot is your "moodle" directory as defined in config.php. NOTE there is also a popups directory directly in the editor directory. Don't use that one!). This will create a new directory under popups called DragMath containing all the necessary DragMath components.

=====Install the DragMath integration package=====

Important Note: These instructions will REPLACE the smiley button on the HTML editor toolbar with the DragMath editor button. This was done to keep the installation instructions simple. If you want to keep your smiley button, see the section at the end of this article.

Download the latest DragMath integration package from the modules and plugins database. In the zip archive, you will find two files.

dlg_ins_smile.php -- Copy this file to your $CFG->dirroot/lib/editor/htmlarea/popups directory, overwriting the existing file (you may want to make a copy of the original file before overwriting it)
em.icon.smile.gif -- Copy this file to your $CFG->dirroot/lib/editor/htmlarea/images directory, overwriting the existing file (you may want to make a copy of the original file before overwriting it)

You must also change two lines in the file $CFG->dirroot/lib/editor/htmlarea/dialog.js

around line 34 you will see the line:

case "dlg_ins_smile": x = 330; y = 320; break;

Change this line to

case "dlg_ins_smile": x = 540; y = 340; break;

around line 47, you will see a line that begins

var dlg = window.open(url, "ha_dialog", "toolbar=no, menubar=no, ...

Modify this line, changing

resizable=no

to

resizable=yes

You might also want to change the mouse over popup from "Insert Smiley" to "Insert Equation". to do this you need to edit the file $CFG->dirroot/lib/editor/htmlarea/htmlarea.php

around line 275 you will see the line:

case "insertsmile: ["Insert Smiley", "em.icon.smile.gif", false, ...

Change this line to

case "insertsmile: ["Insert Equation", "em.icon.smile.gif", false, ...

Finally, make sure that the new files and directories you create in the above steps are readable by the Web server. For example, make sure that the em.icon.smile.gif file has the same permissions as other gif files in the images directory.

=====If you want to keep your smiley button...=====

For those users who want to keep their smiley button, there are postings in this discussion that explain how to do it. You may also download a special version of the DragMath integration package here. Unzip it in your moodle root directory.

Locally saving and restoring a DragMath expression

When you press the Insert button, DragMath inserts the export string into your text and the DragMath window closes. The exported string can no longer be manipulated using DragMath. If you decide to change the string, you have two options:

delete the string (including the dollar signs or other token) and completely recreate it using DragMath
edit the expression by hand

You can not tell DragMath to re-read the expression and show it again in two dimensions. This is a theoretical limitation, not a limitation of DragMath.

But suppose the expression is very complicated. It would be impractical to start over just to make a simple change. Before you Insert the expression, you can save a copy of the expression (a .drgm file) to your local disk using the Save button (see screenshot). Later, if you need to make a change, you open the saved .drgm file.

A .drgm file contains three-dimensional representation of your mathematical expression. It is a binary file that can only be opened by DragMath.

Development

Square brackets

Use of text expressions in the Moodle Wiki can create problems when the text expression includes square brackets, which is how TeX expresses the nth root. Pending a simple wiki based solution users may want to use the ASCIIMathML filter and the ASCIIMathML export format as this combination avoids the use of square brackets.

Consistent integration with all html editors

The Moodle discussion regarding html editors suggests that it will be important for DragMath to have consistent integration with a variety of html editors as htmlarea passes into obsolescence. Plugins for tinyMCE, Xinha and FCKEditor with a similar structure and common codebase are ready and compatible with all browsers that support javascript and Java.

Additional formats

There are quite a few options now available for creating text expressions to for displaying equations and moodle functionality can only be increased if tools were able to create and parse expressions created by the tools a user is most comfortable with. ASCIIMathML is one tool now available as a filter for Moodle that allows the parsing of both TeX and its own ASCIIMathML text expression syntax. Microsoft has now launched its OMML initiative in Office 2007 (see footnotes on http://en.wikipedia.org/wiki/Office_Open_XML and OpenOffice employs its own text expression syntax (the OOo syntax is described at http://documentation.openoffice.org/manuals/oooauthors2/0216WG-MathObjects.pdf). The ability to have DragMath create text expressions that can be used in native documents as well as parsed by filters such as ASCIIMathML will help make use of equations on-line more transparent for everyone.

Documentation