-

Note: You are currently viewing documentation for Moodle 3.10. Up-to-date documentation for the latest stable version of Moodle may be available here: DragMath equation editor.

DragMath equation editor: Difference between revisions

From MoodleDocs
Line 67: Line 67:
{| class="nicetable"
{| class="nicetable"
|-  
|-  
! colspan="4" A sequence for DragMath - click an image to enlarge
| colspan="4"| A sequence for DragMath - click an image to enlarge
|-
|-
|[[Image:dragmath04f.png|thumb|150px|Select the Tab with the symbols required]]
|[[Image:dragmath04f.png|thumb|150px|Select the Tab with the symbols required]]

Revision as of 21:32, 14 September 2011

WARNING

The docs below have been copied from the prexisting docs prior to the decision to break out separate docs for each major version of Moodle. As of Moodle 2.x DragMath is now in Moodle core (you need not install the code if you are running Moodle 2.x.) However, the decision was made that you must turn on the Tex filter in order to access it from the tinyMCE editor. If you think that requirement should be altered, post to the forum or the tracker and good luck with that!

You may 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) the Math Plugins Mauno has been developing as well as here Advanced_Maths_Tools - an "alpha" version of docs for installation and use. If these tools are too your liking they will largely eliminate your need to wrestle ith 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 convert.

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 text 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 tokens 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

The window presented by the dragmath plugin is controlled by an applet reference in a php file, which for htmlarea in Moodle 1.9.x is dlg_ins_dragmath.php, one of the files included in the distribution, which can be found in moodleroot/lib/editor/htmlarea/popups . Applet parameters, per the dragmath documentation, can be changed in this file. By default, the language is set to English and the output format is set to MoodleTex (that is, the output will include double dollars signs, and if you have turned off your tex filter and are using asciimath then you will probably want to set your default export format to ASCIIMathML.)

In answer to the prayers of users, the STACK folk added the ability to drop the dot that DragMath had always inserted in 3x between the coefficient and the variable as in 3∙x . You will find a menu item in DragMath's gui to turn this on and off right next to the menu items for formatting. This setting can also be set via an applet parameter.

You can add formats and languages via /lib/DragMath/Config.xml with the various XML export formats in the formats subdirectory of applets and the languages in the lang subdirectory. Of course you can, with care, edit the various xml files.

Should you wish to make any changes, please remember to back up a copy of your original file.

DragMath instructions

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 GradMath 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 drang and 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.

Managing Your Editor Icons Through adminlib.php

To be able to add your dragmath icon, save your existing copy of adminlib.php (you will find it in the /lib directory) and insert this line:

                    'insertdragmath' => 'em.icon.dragmath.gif',

below this line:

                    'insertsmile' => 'em.icon.smile.gif',

and save. The line can really be placed anywhere in that array, but by providing a specific location it will help when addressing requests for assistance in hiding buttons. And, having taken the time to explore this beautiful little array, you can now alter your button images to your hearts content!

The array is employed by the admin GUI (Site Administration-> Appearance->HTML editor) to provide you the Administrator with the ability to hide buttons in the HTML editor via editorhidebuttons. Once you have installed Dragmath and added the button, you can use the GUI to hide the insertdragmath button.

You may ask, what about altering the adminlib.php file in the CVS or providing a patch? This was raised and you can vote on it. Let's get real here folks, we are talking about one line which could be added to adminlib.php at 1.8.4 or later without any other impact. Is it really necessary to provide a separate adminlib.php for dragmath everytime someone changes adminlib.php in the core? If you have an opinion on this please edit the page comments on this and provide your input as to whether adminlib.php should just be dropped from the dragmath distribution.

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.

DragMath instructions

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

Troubleshooting

Before Posting to the Forum

DragMath is a java applet which in Moodle 1.9 is being invoked through the editor htmlarea. This means that there are a number of places to check to determine what the trouble might be.

You don't see any editor icons: Safari and Chrome, for example, do not handle htmlarea, and without access to htmlarea, you are stuck. Use a different browser or if you are an advanced user, consider moving to tinyMCE.

Htmlarea comes up, but you don't see the DragMath button: Flush your cache and try again.

You flushed your cache and still don't see the DragMath button: Retrace your installation steps-make sure that you placed the zip file in your moodle root and that you did an unzip that overwrote htmlarea.php and dialog.js. If the problem persists post to the forum with specifics regarding how you followed the steps above.

You clicked on the DragMath button but DragMath did not come up: In Moodle 1.9 with DragMath 0.7.8.2, open the URL http://yourFQDN/moodlerootifappropriate/lib/DragMath/DragMath%20Demonstration.html . A demo page with DragMath should come up and be functional. If the demo works, please post the details of the process you have followed to date along with your java log (please include all details of the versions of the OS, browser, java, etc you are using.) If the demo does not work, then the issue likely is with your browser's use of java (see, e.g. http://support.mozilla.com/en-US/kb/Using+the+Java+plugin+with+Firefox.) Please update to the most recent version of java available to you and make sure that you have installed all plugins your browser needs to open a java applet. Then flush your cache browser cache and your java cache, make sure you have pointed your browser to your most current version of java and retry. If it still does not work post the details as above.

Everything seemed to work but all that happened was that you text expression was inserted (with or without tokens such as double dollar signs): DragMath is a GUI constructor that allows you to create text expressions from a GUI representation of your equation. IT DOES NOT display your equation. To do that you need a display application installed. While Moodle comes with an antiquated but functional Tex filter, that filter DOE NOT include Tex itself (though it does include a fallback to mimetex, another application discussed in Mathematics. There are also other display applications discussed there, such as ASCIIMathML and MathJax. As noted below, DragMath can render an equation in a variety of formats each with its own tokens, or can insert the text expression with no tokens at all.

After Update Dragmath Disappears

Unfortunately there are files that DragMath shares with core Moodle files that Moodle developers won't change, which means each time you update Moodle you must reinstall the integration files. You can do this by identifying each of the files and making a backup of them with a filename that the update won;t overwrite, or you can simply keep the DragMath install zip in the root of your Moodle and do an unzip after each update. Quick and easy.

unzip

Some packages like winRAR provide a separate setting that prefixes the archives name on directories. In order for the files to be properly placed when the archive is unzipped you must make sure this is not the case. In winRAR for Windows for example you can go to Options->Settings and on the Compression tab you will see something to the effect of "Append archive name to path"; make sure this is not set!

Also, please note that the non-cvs zip is created so that the files in various directories are placed correctly. If, however, you set unzip or instruct unzip not to overwrite but to rename, then you will unpack the archived files into new directories (for example /lib(2) instead of /lib) and your install will not work.

java jre

Dragmath is java based, and unless you have a current java runtime environment you will likely run into trouble. Make sure you keep your JRE current and that the current JRE is selected. You can check here for latest versions: http://www.java.com/en/download/manual.jsp. Note that Apple packages java itself, so OS X users can be caught in the Apple development cycle. The best option is to make sure you use Software Update frequently. DragMath has been shown to work fine with OS X 10.5 using FF 3.6.3 and the latest Java update. As of June 2010 Apple has released Java for Mac OS X 10.6 Update 2 and Java for Mac OS X 10.5 Update 7. These releases correspond to the latest Java released by Sun (Oracle), Java 6 update 20. Check here for the most recent downloads from Apple: http://support.apple.com/downloads/

Development

Language Files

The 0.7.8.1 package now includes language files (with Finnish, courtesy of Mauno Korpelainen) and the integration files should provide for automatic selection of the language based on the Moodle language setting.

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.

Extending DragMath to a Math Chat

Having been introduced by Marc Grober to a math chat application (http://www.imathas.com/cur/mathchat/testchat.html [NB: the mathchat referenced here is the creation of David Lippman]) it would be useful to see similar features in Moodle's chat, specifically:

1. The ability to easily display mathematical symbols with DragMath incorporated into the chat window.

2. The ability to create and display mathematical graphs.

Moodle 2

As part of planning for Moodle 2 we have recommended that DragMath be placed in /lib/editor/common/dragmath alongside asciimathml (which is located in /lib/editor/common/asciimath). This should not result in any other major changes and those wanting to stay abreast may either want to look moving files before Moodle 2 or may want to keep an eye out for a zip of asciimath and dragmath packaged as a precursor to Moodle 2.


Discussion of the transition of DragMath to Moodle core: http://moodle.org/mod/forum/discuss.php?d=125977&parent=551794