DragMath equation editor: Difference between revisions

Revision as of 16:40, 2 May 2012

WARNING: As of Moodle 2.x DragMath is now in Moodle core (you need not install the code if you are running Moodle 2.x.) To use DragMath, you are "required" to activate the TeX filter on the server side because the core devs decided so (they were well advised that this wold annoy countless users.....) However, there is a hack to sever the connection between DragMath and TeX included below for your convenience. You will also need to have a recent version of a Java Runtime Environment installed on the end-user's machine which is properly configured.

You may also want to look in the Math Forum for the latest discussion of SEE (Super Equation Editor, an initial nickname for this effort though the product has far outgrown just an equation editor). SEE is a comprehensive set of Math Plugins Mauno Korpelainen has been developing which are discussed here Advanced Maths Tools (this is only an "alpha" version of docs for installation and use.) If these tools are to your liking they will largely eliminate your need to wrestle with TeX (unless you wish so to do.) And, if you want a full distro of TeX, consider doing a local install of TexLive and cobbling your code to eliminate the need for the convert binary.

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.

John Isner initially created and maintained several files that allowed for integration of DragMath with HTMLArea, Moodle's editor in 2007. DragMath was then maintained by Marc Grober until it was integrated into core Moodle with the release of Moodle 2.0. An outgrowth of the development to integrate DragMath into tinyMCE has been the development of SEE by Mauno Korpelainen (a link to those plugins can be found below.)

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 which also discusses the various configuration options, some of which are mentioned briefly below.

Using DragMath

DragMath is based on the simple idea that the User who does not know a lot of TeX (pronounced Tech) can still create mathematical formula for publishing. In this case, Moodle is the dispaly agent so the TeX formulae are then rendered to a Moodle screen. This essentially means that with little experience, any Junior High Maths teacher can generate all the formulae they need for most aspects of Maths in Moodle.

Creating simple expressions

To begin, click on the DragMath insertion button. This opens The DragMath interface.

Opening Dragmath

The toolbar is different than you may expect, we are used to nice neat rows of buttons, but Dragmath has to use tabs. Each tab is tab is a collection of "templates", that is each symbol is a "template" and can be dragged and dropped onto the work space.

The DragMath Interface

To end editing and insert the script into the Moodle page, click the Insert button. This simple, but not simplistic, interface is a strength of DragMath. It make it easy for even novices to create complex formulae.

A sequence for DragMath - click an image to enlarge
Select the Tab with the symbols required	Click, hold then drag'n'drop a symbol	Enter the values, select an operation symbol	Select another symbol and drag'n'drop
Add an equal (or other) sign	Add in a variable, (chi in this case)	Click Insert	See the encoded result in the editing dialog.

This same sequence of operations apply equally for all formulae, all insertions, no matter how complex they become.

You can insert a template from the toolbar by drag and drop or by a click on the template in the tab, then clicking in the workspace.

Creating more complex expressions

More complex expressions are pretty much more of the same as above. Creating a simple multiplication table matrix, for example, seems complex,but in DragNath, it is actually simple:

A sequence for a simple Multiplication Matrice in DragMath - click an image to enlarge
Select the Tab and add in the multiplier	Click, hold then drag'n'drop the Matrix symbol	Enter the values, select a equal symbol	Add in the rows required
Add in the columns required	Edit the Matrice	Add the equal symbol	Add and edit in the second Matrice.

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.

Additional Editing

There are times when DragMath is not going to have a symbol or something you might want. Or perhaps you left something out of the DragMath constuctor, so you want to include it manually. Most likely, for something like the matrix created earlier, I want to go to 15, which means I have to change the structure of the matrix, and edit in some numbers. This is easily done with a little forethought. Copy and paste and delete or edit what you want and do not want.

Manually editing a DragMath construction - click an image to enlarge
Select, copy and paste the original matrix	Edit to what is actually required	Delete the original matrix

Sometimes however, you just want to include something you forgot, or rather, add something that was not there in the first place.

Accurately editing a DragMath construction manually - click an image to enlarge
Construct the original equation	Copy, then edit to what is actually required	Return to the edited page

What DragMath Does and How It Does It

Configuration files

DragMath allows you to create your own configuration files. That means it can be used to parse and display what you tell it to parse and display. By way of example, DragMath comes with a number of configuration files, one of which has been specifically designed to place doubledollar tokens before and after inserted text. We have seen a number of people change the TeX tokens in Modle using MathJax, and then become nonplussed that DragMath stops working. No DragMath still works, but it is likely inserting tokens that MathJax is not parsing. This can get confusing if you have more than one display technology in place. DragMath allows you to alter the tokens it inserts, so you can quite easily, for example, have DragMath insert startmath or endmath if that is what you want to use for tokens.

Language Files

DragMath can also use quite a few languages.

So! You want to use DragMath but don't want to use the TeX filter?

What?

Yes. Moodle devs decided that you should not use DragMath unless you used the Moodle TeX filter (yes, over objections from lots of folk.) Does that mean that the TeX filter is the best way to go? Hardly. The TeX filter is rather long in the tooth, desperately in need of revision, and essentially only provides a fallback to a mimetex binary if you have not installed a TeX distribution. There are lots of other options for Math display in Moodle, may of them much easier to configure and use!

Procedure

Decoupling DragMath from the Tex Filter

Since default configuration of tinymce (the default editor) requires that TeX filter is enabled before Dragmath plugin can be used we need to edit file lib/editor/tinymce/lib.php

First, make a copy of that file to make sure that you can revert back to the original.

Second, open the file for editing (with an appropriate editor that will not do unseen things to the contents of your file)

Third, locate lines 107-111:

if (array_key_exists('filter/tex', $filters)) {
$xdragmath = 'dragmath,';
} else {
$xdragmath = ;
}

Fourth, replace all those lines with this one line:

$xdragmath = 'dragmath,';

removing the if statement that makes DragMath visible only if the TeX filter is turned on.

Fifth, save the file.

Sixth, replace the original file lib/editor/tinymce/lib.php with this modified version.

Setting up another display mechanism

Now DragMath will show up in your editor, but you have no way of displaying the TeX or other code that you might insert with DragMath. You can explore the docs and the Math forum and you will find quite a few other ways to display Math in Moodle. One very popular way is to use MathJax. Under Moodle 2.x the AdditionalHtml field can be used to add the reference to MathJax and even do some configuration. To accomplish this, as an administrator of your site go to: Site administration -> Appearance -> Additional HTML -> Within HEAD Now, add

<link rel="stylesheet" type="text/css" href="http://jsxgraph.uni-bayreuth.de/distrib/jsxgraph.css" media="screen" />
<script type="text/javascript" src="http://jsxgraph.uni-bayreuth.de/distrib/jsxgraphcore.js"></script>
<script type="text/javascript" src="http://jsxgraph.uni-bayreuth.de/distrib/GeonextReader.js"></script>
<script type="text/javascript" src="http://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML">
MathJax.Hub.Config({
   tex2jax: {
     inlineMath: [ ['$$','$$'], ['@i','@i'], ["\\(","\\)"] ], 
     displayMath:[ ["\\(","\\)"], ['@d','@d'] ],
     processEscapes: true
   }
 });
</script>

Save changes. Make sure that Tex filter and Algebra filter are disabled in Site administration > Plugins > Filters > Manage filters Your moodle 2 is now using MathJax from a cloud server in cdn.mathjax.org with given delimiters (in this example double dollars and @i for inlineMath and @d for displayMath). You can choose to use other delimiters in configuration if you want or swap hat are there, BUT you may not use delimiters Moodle employs for other purposes and you need to be very careful of the syntax. You do not need to have the same token for beginning and end (for example, one could use startmath and endmath as tokens. See http://mathjax.org for additional information on these and other parameters. "Wait!", you say. "What about the first three lines I added to AdditionalHtml?" We thought you would never ask. These lines add access to jsxgraph and GeoNextReader which you can find discussed in these forums and at the jsxgraph site, http://jsxgraph.uni-bayreuth.de/wp/ COnsider this temporary, as you shoulod update the jsxgraph reference to use its cloud source. See a discussion here: http://jsxgraph.uni-bayreuth.de/wp/download/

Documentation