fxEditor API

Places the Equation Editor toolbar on the page, e.g.

<div id="toolbar"></div>
<div id="input"></div>
<script>
  var tb = new EqEditor.Toolbar('toolbar');
  tb.addTextArea(new EqEditor.TextArea('input'), true);
</script>
Copy

You can use any of the standard toolbar designs: 'default', 'full', 'mini', 'chemistry', 'sidebar' and 'inactive'. e.g.

  var tb = new EqEditor.Toolbar('toolbar','mini');
Copy

Alternatively you can select the panels you require, in any order. Each inner array is one row of the toolbar, so the example below produces a single row of six panels:

  var tb = new EqEditor.Toolbar('toolbar', '[["operators_core","greeklower","chemistry_arrows",
                                              "mhchem","mhchem_arrows","colors"]]');
Copy

The available panel names are: 'binary', 'accents', 'accents_ext', 'arrows', 'brackets', 'chemistry_arrows', 'chemistry_letters', 'colors', 'foreign', 'greeklower', 'greekupper', 'matrix', 'mhchem', 'mhchem_arrows', 'operators', 'operators_core', 'relations', 'spaces', 'style', 'subsupset', 'symbols'

Connects a MathView with the current Toolbar, the same way addTextArea() does for a TextArea - so the toolbar's buttons insert into the MathView whenever it has focus. Returns the current Toolbar object.

Connects a TextArea with the current Toolbar. For example:

<div id="editor"></div>
<div id="input"></div>
<script>
  EqEditor.Toolbar.link('editor', true)
    .addTextArea(new EqEditor.TextArea('input'), true)
</script>
Copy

Returns the current Toolbar object.

Appends a new panel, with a custom set of buttons, to the end of an existing toolbar row.

The function accepts either a string naming one of the built-in panels (e.g. "matrix"), or an object describing a panel of your own, with the following properties:

• name {string} - A unique name for the panel.
• class {string} - [optional] CSS class to assign to each button.
• width {number} - Width of the panel in pixels.
• buttons {array} - List of button objects (see below).

A button is defined with the following properties:

• latex {string} - What the button displays. This can be plain text, or a single supported LaTeX string, which is rendered as MathML on the button face.
• width {number} - Width of the button in pixels.
• operation {string} - Command to be executed, typically "insert", but it may be any method of the active TextArea or MathView.
• args {array} - Arguments passed to the 'operation' function. For "insert" the first argument is the LaTeX to be added to the TextArea; for other operations it depends on the method being called.

By default all text buttons are given the class CCButton, while rendered ones are given the class CCImage.

Key examples:

EqEditor.Toolbar.link('toolbar','[["operators"]]')
   .addTextArea(textarea)
   .appendPanel(0,"matrix")
   .appendPanel(0,{
       "name":"textvariables",
       "width":40,
       "buttons":[
           {"latex":"bill"},
           {"latex":"jill"},
           {"latex":"jack"}
       ]
   })
   .appendPanel(0,{
       "name":"any_unique_name",
       "class":"green",
       "width":50,
       "buttons":[
           {
               "latex": "\\mp",
               "width": 35,
               "operation": "insert",
               "args": ["\\mp"],
           },
           {
               "latex": "alpha",
               "width": 35,
               "operation": "insert",
               "args": ["\\alpha"],
           }
       ]
   });
Copy

Returns the HTMLDivElement for an equation editor toolbar panel, given its name. This is typically required when dynamically moving a panel from the 'inactive' toolbar onto the main toolbar.

Moves the toolbar from one location on the page to another. This is useful when a single toolbar is shared between several inputs and should appear beside whichever one the user is currently editing. For example:

<div id="editor1"></div>
<div id="input1" onClick="tb.moveTo('editor1')"></div>
<div id="editor2"></div>
<div id="input2" onClick="tb.moveTo('editor2')"></div>
<script>
  tb = EqEditor.Toolbar.link('editor1', true)
    .addTextArea(new EqEditor.TextArea('input1'), true)
    .addTextArea(new EqEditor.TextArea('input2'), true);
</script>
Copy

Makes the specified TextArea (or MathView) active, so that it receives input from the toolbar and the keyboard.

A static constructor that places the Equation Editor toolbar on the page and returns the new Toolbar object. This is a convenient alternative to 'new EqEditor.Toolbar', as it allows you to chain associated Toolbar commands, e.g.

<div id="toolbar"></div>
<div id="input"></div>
<script>
   EqEditor.Toolbar.link('toolbar')
  .addTextArea(new EqEditor.TextArea('input'), true);
</script>
Copy

You can use any of the standard toolbar designs: 'default', 'full', 'mini', 'chemistry', 'sidebar' and 'inactive'. e.g.

  EqEditor.Toolbar.link('toolbar','chemistry');
Copy

Alternatively you can select the panels you require, in any order, one inner array per row:

  EqEditor.Toolbar.link('toolbar', [["operators_core","greeklower","chemistry_arrows",
                                     "mhchem","mhchem_arrows","colors"]]);
Copy

The available panel names are: 'binary', 'accents', 'accents_ext', 'arrows', 'brackets', 'chemistry_arrows', 'chemistry_letters', 'colors', 'foreign', 'greeklower', 'greekupper', 'matrix', 'mhchem', 'mhchem_arrows', 'operators', 'operators_core', 'relations', 'spaces', 'style', 'subsupset', 'symbols'

Creates an instance of TextArea for LaTeX input and associates it with an HTML element. To provide some introductory text, use the placeholder attribute as illustrated in the example below. Any introductory text is removed as soon as the user starts typing.

<div id="input" placeholder="Write LaTeX here"></div>
<script>
var ta = new EqEditor.TextArea('input', true);
</script>
Copy

Adds history, with undo and redo, to the TextArea. This requires a History menu to provide the necessary controls.

Connects an Output component to the current TextArea. Every connected Output is refreshed whenever the equation changes. A mathview.MathView registers through this same call, so a WYSIWYG view can be kept in step with the markup.

Connects a Toolbar component to the current Textarea.

Provides a convenient method of executing any Output class function across all of the Output areas associated with the TextArea. This is particularly useful when you have several outputs and need them all to change together.

For example, say you want to change the format for all the outputs:

<select id="format" onchange="textarea.callOutputs('setFormat', this.value);">
	 <option value="svg">svg</option>
	 <option value="gif">gif</option>
	 <option value="png">png</option>
  <option value="pdf">pdf</option>
  <option value="emf">emf</option>
</select>
Copy

Clears the input box (TextArea), removing the equation and resetting the cursor.

Call if you are dynamically displaying the editor and select to 'close' a TextArea. This function will clean up any extra DOM elements.

This used to hide the suggestion list and stop there, leaving five listeners on the input element and, if the editor was closed mid-drag, one on window. Each of those closes over the TextArea, so nothing it held - the token array, the history, the Output and History menus it notifies - could be collected, and an editor opened and closed repeatedly (a dialog, a per-cell editor in a table) accumulated a copy of all of it every time. Closing twice is harmless: removeEventListener on a listener that isn't attached does nothing.

Moves keyboard focus into this TextArea. Part of the ToolbarTarget contract (see src/toolbar/toolbar.ts) so the Toolbar can refocus whichever target - a TextArea or a MathView - a keyboard-driven button activation should return focus to.

Returns the HTML element backing this TextArea. Typically you will then read its textContent to retrieve the LaTeX formula.

The following example illustrates how a button onclick action can retrieve the content of a TextArea.

<div id="input"></div>
<script>
textarea = new EqEditor.TextArea('input');
</script>
...
<button onclick="alert(textarea.getTextArea().textContent)" />
Copy

Insert commands into the active HTML element at the current cursor position. This function is usually called in response to a toolbar button press. The following example insert text for a fraction and places the cursor between the first curly braces:

<div id="input"></div>
<script>
var a = EqEditor.TextArea.link('input', true);
a.insert('\\frac{}{}', 6);
</script>
Copy

Returns true if the current TextArea is empty, false otherwise.

Generates the LaTeX for an array of the currently selected dimensions (see TextArea.curMatrixDims) and inserts it into the active TextArea.

Generates the LaTeX for a matrix of the currently selected dimensions (see TextArea.curMatrixDims) and inserts it into the active TextArea.

Notifies all connected History Menus of changes.

Notifies all connected Outputs of changes.

Pushes any text from the current TextArea to the History stack. Which allows further changes to be undone.

Reverts an undone change, i.e. redoes the most recently undone action.

Replaces the whole equation in one step, recording a single undo entry for it.

The maths view edits its own copy of the LaTeX and then pushes the result here. Doing that as a bare clear() + insert() was visible in the history: two entries per keystroke, the first of them empty. This is the same rewrite with the history told about it once.

Enables or disables auto-insertion of matching close brackets when an open bracket is typed.

Assigns the LaTeX commands that may be used within the formula. Any command breaking this condition is given the CSS class "CCrestricted", which by default shows it in red with a double underline. Override the CSS for "CCrestricted" to achieve alternative effects.

Assigns the variables that may be used within the formula. Any variable breaking this condition is given the CSS class "CCrestricted", which by default shows it in red with a double underline. Use TextArea.validate to test the equation as a whole.

The follow example allows variable 'bill' and any that start with 'j' and also end with 's':

textarea = EqEditor.TextArea.link('latexInput',true)
  		.addOutput(new EqEditor.Output('output'))
  		.setRestrictedVariables(['bill','j\\w+s'])
Copy

Restricts keyboard input. This is useful in assessment settings, where the equation must be built from a controlled set of toolbar buttons rather than typed freely.

There are three modes:

• 0 - allows all text and key operations (the default);
• 1 - allows the cursor, delete and space keys; all other input must come from a toolbar;
• 2 - all input must come from a toolbar.

Undoes the last action. Repeated calls unwind further changes to the input area.

Changes the dimensions of an existing selected matrix

Checks the equation to ensure it contains only the variables and commands permitted by TextArea.setRestrictedVariables and TextArea.setRestrictedCommands.

Static constructor.

Returns a new instance of TextArea linked to the specified HTML element. The advantage of this over the constructor with 'new' is that it allows you to chain additional requirements together, as shown in the example:

<div id="input"></div>
<script>
EqEditor.TextArea.link('input', true)
.addToolbar(new EqEditor.Toolbar('toolbar'), true)
</script>
Copy

Creates a WYSIWYG MathML view inside the given container element, e.g.

<div id="mathview"></div>
<script>
  var mv = new EqEditor.MathView('mathview');
  mv.addTextArea(new EqEditor.TextArea('input'));
</script>
Copy

Links this view to a TextArea that holds its LaTeX. An edit here refreshes that TextArea's content (see pushToLinkedTextArea); an edit there refreshes this view (see updateOutput, wired up automatically via TextArea.addOutput()).

Connects a Toolbar to this view, the same way TextArea.addToolbar() does - so the Toolbar's buttons insert into this view whenever it has focus.

Empties the view, removing the equation and resetting the cursor to the start.

Part of the Output-style contract TextArea.addOutput() expects; the actual TextArea object reference is supplied directly via addTextArea() instead, so there's nothing further to do with the id itself.

Moves keyboard focus into this view. Part of the ToolbarTarget contract (see src/toolbar/toolbar.ts) so the Toolbar can refocus whichever target a keyboard-driven button activation should return focus to.

Where the cursor is, as a character offset into the LaTeX getLatex() returns.

The same number the linked TextArea reports, because both panes count into the same string - so anything following the editor can ask either one. Provided for a view used on its own, with no markup pane to ask instead.

Returns the equation's current LaTeX. This is the value to read when submitting a form, or when handing the equation to a rendering service.

Splices txt into the equation at the cursor - what every "insert" toolbar button funnels through (see icons.json), whether that's a single command (\alpha), a full structure (\frac{}{}, \int_{}^{}{}), or plain text. Since the document is the LaTeX, this is a string splice and needs no parsing of the snippet at all; the cursor lands inside the snippet's first empty {} pair if it has one, matching the "ready to type" placement the same button gives in a TextArea.

Inserts an empty fraction, \frac{}{}, leaving the cursor in the numerator.

Inserts an integral with empty limits, \int_{}^{}.

Inserts an auto-sized bracket pair, \left({}\right).

Inserts an empty superscript, ^{}, leaving the cursor inside it.

Inserts an empty square root, \sqrt{}.

Delegates to the linked TextArea's own matrix-building logic rather than reimplementing it. curMatrixDims is relayed across since the TextArea's own method reads it from itself, not from whichever object happened to be the Toolbar's active target when it was set (see Toolbar's matrix grid UI, which writes directly to the active target's curMatrixDims). Unlike the previous version of this view, the resulting matrix now renders here as a real table rather than showing up as literal LaTeX - the converter has always understood matrices; it was this view that did not.

Delegates so any Output/History already linked to the TextArea still refreshes after a toolbar-driven edit here, same as if the user had typed directly into the TextArea.

Shows the equation as an inline one or as a display one, the same distinction output.Output.setInline makes for the exported formats.

The visible difference is display="block" on the <math> root: a display equation gets its own centred line, an inline one sits where it is put, on the baseline of whatever text surrounds it. Call it alongside Output.setInline() so what is on screen and what gets exported agree.

Display style is left on either way - full-size fraction numerators, and a large operator's limits above and below rather than beside. That is deliberate and it is about editing rather than presentation: in text style MathML drops an <mfrac>'s numerator and denominator a script level, so a fraction inside a fraction is drawn smaller than the one containing it, and the inner one is exactly what somebody is usually trying to click into.

mathview.setInline(true);
Copy

Replaces the equation wholesale and puts the cursor at the end. Use this to pre-load the view with an existing equation.

Re-renders this view from the linked TextArea's current LaTeX, and puts this view's cursor where that TextArea's is. Both are plain character offsets into the same string, so the "nearest matching position" translation an AST-based view needed here is now just an assignment. Skips an edit that's actually this view's own echo (see pushToLinkedTextArea / lastPushedLatex) rather than pointlessly re-rendering text already fully in sync.

Static constructor. Returns a new instance of MathView linked to the specified element, allowing chained setup, e.g.

<div id="mathview"></div>
<div id="input"></div>
<script>
  EqEditor.MathView.link('mathview')
    .addTextArea(EqEditor.TextArea.link('input'));
</script>
Copy

Creates an instance of the Output class, which links output from the Equation editor to an HTML element on the page. This is used to export LaTeX content from an associated TextArea in various forms for display or inclusion in other web tools. e.g.:

<div id="entry"></div>
<img id="output"/>
<script>
   EqEditor.TextArea.link('entry')
       .addOutput(new EqEditor.Output('output', 'url'));
</script>
Copy

The outputFormat sent to the exported area can be one of:

• wp - WordPress.
• phpBB - phpBB bulletin board.
• tw - TiddlyWiki.
• url - Unique web address of the rendered image.
• urlencoded - As url, but with additional encoding of special characters.
• pre - HTML pre element with its xml language set to latex. Used by some forums.
• doxygen - Doxygen format.
• html - HTML img element.
• latex - Raw LaTeX.

Connects an export area to this Output. The named element is filled with the equation in the requested format, and refreshed whenever the equation changes - which is how a page offers a "copy this into your forum post" box beside the preview.

Links this Output to a TextArea, so it displays the formatted equation for that text. You will not usually call this directly - api.TextArea.addOutput does it for you.

Downloads the current equation as a file in the Output's current image format.

Exports the current equation, returning a text string in the requested format.

Returns the equation in a compact form, removing all redundant spaces.

Returns the URL that renders the current equation.

Returns the supported export options, i.e. the formats accepted by Output.setFormat and Output.addExportArea.

Returns true if the equation is being rendered inline (vertically aligned with the surrounding text) rather than as a display equation.

Returns the supported background colours, as an array of {value, desc} pairs.

Returns the supported output DPI values.

Returns the supported export formats, as an array of {value, desc, group} entries suitable for populating a select element - the counterpart of Output.getSupportedFonts.

group names the optgroup an entry belongs under ("Formats" for markup you keep, "Platforms" for markup only one application understands). Entries arrive in the order they should be offered, with each group's members already adjacent, so a caller can build the menu in one pass without sorting.

Every entry is a valid argument to Output.exportAs and Output.setExportFormat. Building a menu from this rather than hard-coding one means a page picks up new formats when the API gains them, instead of silently offering an out-of-date list.

Returns the supported output fonts, as an array of {value, desc} pairs suitable for populating a select element.

Returns the supported font sizes, as an array of {value, desc} pairs.

Returns the supported image formats, i.e. ['gif', 'pdf', 'png', 'svg', 'emf'].

Sets the background colour of the rendered equation. Leave it empty for a transparent background, which is usually what you want when the equation sits on a coloured page.

   EqEditor.Output.link('output', 'url')
       .setBackground('red');
Copy

Sets the resolution of the rendered equation, in dots per inch. This is ignored for 'svg', which is resolution independent.

   EqEditor.Output.link('output', 'url')
       .setDpi('110');
Copy

Sets the export format of the Output, i.e. the way the LaTeX is written out for pasting into another system.

Sets the font used to render the equation. The rendering service currently supports: (default) - Latin Modern jvn - Verdana cmb - Computer Modern phv - Helvetica phn - Helvetica Neue tx - tx Sans Serif px - px Sans Serif cs - Comic Sans

   EqEditor.Output.link('output', 'url')
       .setFont('tx');
Copy

Sets the font size of the Output.

   EqEditor.Output.link('output', 'url')
       .setFontSize('LARGE');
Copy

Sets the image format of the Output, by changing the URL used to request the rendered equation. For example 'gif' requests 'https://latex.codecogs.com/gif.image?', whereas 'svg' requests 'https://latex.codecogs.com/svg.image?'.

   EqEditor.Output.link('output', 'url')
       .setFormat('pdf');
Copy

Sets the inline mode of the Output. An inline equation is vertically aligned to sit on the baseline of the surrounding text, rather than being rendered as a standalone display equation.

   EqEditor.Output.link('output', 'url')
       .setInline(true);
Copy

Sets the URL of the rendering service used to create the preview of the active equation. The default is 'https://latex.codecogs.com'; you would typically change this to point at your own installation of the rendering service.

<div id="entry"></div>
<img id="output"/>
<script>
   EqEditor.TextArea.link('entry')
       .addOutput(EqEditor.Output.link('output', 'url')
           .setRenderURL('https://latex.codecogs.com')
           .setFont('phv');
       );
</script>
Copy

Updates the Output to reflect new changes.

Converts a LaTeX string straight to presentation MathML, without needing an Output bound to a TextArea first.

Public and static because the editor is not the only thing that needs this: a host integration - a CKEditor or TinyMCE plugin storing the source LaTeX and regenerating its markup on the way out - has a string in hand and no editor in sight. Sharing this rather than each caller writing its own means every one of them produces the same markup.

Static constructor. Returns a new instance of Output linked to the specified HTML element. This approach is useful for chaining various output requirements together, e.g.

<div id="entry"></div>
<img id="output"/>
<script>
EqEditor.TextArea.link('entry')
 .addOutput(EqEditor.Output.link('output', 'url')
 .setFont('phv')
 .setFontSize('LARGE') 
);
</script>
Copy

Creates an instance of History and renders its buttons into the given element.

Connects the History buttons to the given TextArea. You will not usually call this directly - TextArea.addHistoryMenu does it for you.