:: Table of Contents

Equation Editor API

The Equation Editor API (Application Programming Interface) provides a mechanism to create custom equation editor and to seamlessly integrated the editor within any HTML web page. This page show the essential steps to creating an editor tool bar, customising the panels, and interfacing with content on your page.

Prerequisites

The following css and javascript must be loaded within the HTML page header:

  • https://latex.oncodecogs.com/css/equation-embed.css
  • https://latex.oncodecogs.com/js/eq_config.js
  • https://latex.oncodecogs.com/js/eq_editor-lite-19.js

Add to <head> :

<link rel="stylesheet" href="https://latex.oncodecogs.com/css/equation-embed.css"/>
<script src="https://latex.oncodecogs.com/js/eq_config.js"></script>
<script src="https://latex.oncodecogs.com/js/eq_editor-lite-19.js"></script>

Initialising the Editor

To place the Editor within a page you need the following minimum elements within your web-page:

  1. Define where the editor tool bar should appear, by creating an empty html element with an appropriate id, e.g.
    <div id="editor"></div>.
  2. Define where the user will be entering the LaTeX for an equation. This must allow input, so will typically be a textarea or editable div element, and as above it must be given a unique id. e.g.
    <textarea id="testbox"></textarea>
  3. To help the user visualise what they are creating its a good idea to show a preview of the equation. For most equation formats it is appropriate to use a img element again with a unique id, e.g.
    <img id="equation"/>
  4. Within a separate <script>...</script> block we now use functions defined by the API to link everything together:
    • First initiate the Equation Editor and direct it to put the toolbar in the <div id="editor"></div> created in the first step with the API functions, e.g.
      EqEditor.embed('editor','').
    • To this toolbar we add associations to both the input and preview elements using API functions EqEditor.add(...) together with the EqTextArea(...) object, e.g.
      EqEditor.add(new EqTextArea('equation', 'testbox'),false);

The complete example looks like:

Add to <body> :

<div id="editor"></div>
<textarea id="testbox"></textarea>
<img id="equation"/>

<script>
  EqEditor.embed('editor','');
  EqEditor.add(new EqTextArea('equation', 'testbox'),false);
</script>

EqEditor Class

The EqEditor class is the core to CodeCogs Equation Editor and links an instance of the toolbar to the <textarea> that are used to enter mathematical LaTeX code

Class Functions
  • EqEditor.embed(divID, SID, design, language)
  • EqEditor.add(EqTextArea, resize)
  • EqEditor.addText(document, textareaID, text)
  • EqEditor.setFormat(format)
  • EqEditor.moveto(divID)
  • EqEditor.insert(text,position,insertPosition)
  • EqTextArea EqEditor.getTextArea()

EqEditor.embed(divID, SID, design, language)

Places the Equation Editor toolbar on the page.

  • divID: the id of the the layer into which the editor is placed, e.g., <div id="editor"></div>.
  • SID [optional]: a unique code that identifies the user, allowing history and preferences to be remembered and saved. For this, we suggest choosing your email address and adding a random sequence of numbers to it for security reasons.
  • design [optional]: specifies the design of the editor to use. Parameters for design are covered separately here: design.
  • language [optional]: defines the spoken language using these codes:
    zh-cnCantonese
    nl-nlDutch (Nederlands)
    nl-beDutch Belgian
    en-usEnglish USA
    en-enEnglish British
    fr-frFrench (Fraçais)
    de-deGerman (Deutsch)
    el-elGreek (Έλληνας)
    lt-ltLitduanian (lietuvių kalba)
    hu-huHungarian (Magyar)
    it-itItalian (Italiano)
    ir-faPersian (Farsi)
    pl-plPolish (Polski)
    ro-roRomanian (Roman)
    ru-ruRusian (русский язык)
    es-esSpanish (Español)
    tr-trTurkish (Türkçe)
    uk-ukUkranian (українець)
    vi-viVietnamese

EqEditor.add(EqTextArea, resize)

Links the Equation Editor toolbar with one or more <textarea>'s, this allow the page to have any number of additional input areas connected to one toolbar. After defining each <textarea>, associate it with a toolbar using EqEditor.add(...).

  • EqTextArea: an instance of EqTextArea to be linked with the Equation Editor System.
  • resize [true:false]: resizes the textarea in proportion to the main window size.

Add to <body> :

<div id="toolbar"></div>
<textarea id="testbox" rows="3" cols="40"></textarea>
<img id="equation" />
<br/>
<textarea id="testbox2" rows="3" cols="40"></textarea>
<img id="equation2" />

<script>
  EqEditor.embed('toolbar');
  EqEditor.add(new EqTextArea('equation2', 'testbox2'),false);
  EqEditor.add(new EqTextArea('equation3', 'testbox3'),false);
</script>

EqEditor.addText(document, textareaID, text)

Adds the given text to the identified text area, at the current cursor position.

  • document: The target window frame. For the current page, use 'document'.
  • textareaID: The unique ID of the text area. e.g. <textarea id="testbox"></text>, into which the user writes the equation.
  • text: The text to be added to the current cursor position.

EqEditor.setFormat(format)

Change the output format of the preview equation

  • format: The output format. One of 'gif','png','pdf'

EqEditor.move(divID)

Although each page has a limit of one toolbar, this can be moved dynamically to any location.

  • divID: the id of the the layer into which the editor is placed, e.g., <div id="editor"></div>.

The following code illustrates how you might add a second <textarea> which, when selected, moves the toolbar above it:

<div id=""></div>
<textarea id="" onclick="EqEditor.moveto(toolbar2)"></textarea>

EqEditor.TextArea Class

Class Functions
  • contructor(textAreaId)
  • addToolbar(toolbar, reverse=true)
  • addOutput(output, reverse=true)
  • addHistoryMenu(history)
  • addExportArea(divElementId, type)
  • getTextArea():HTMLElement
  • insertText(text, newCaretPos, selectedInsertPos)

The EqTextArea object controls the behaviour of each <textarea> associated with the Editor toolbar. It also (optionally) allows rendering zones to be formed that display the content of the input textarea in a graphical form.

TextArea::Constructor(textareaID)

Initialised an instance of the EqTextArea, which associated the <textarea> with an equation preview

  • textareaID:string - unique ID for a textarea, e.g. <textarea id="latexInput"></textarea>, into which the user writes the equation.
toolbar = new EqEditor.Toolbar('toolbar');
textarea = new EqEditor.TextArea('latexInput');
toolbar.addTextArea(textarea);

TextArea::addToolbar(toolbar, reverse=true)

Connect a Toolbar to the TextArea.

  • toolbar - A toolbar object that is notified whenever this textArea receives focus. This causes buttons selected on the toolbar to be direct output to this associated textArea.
  • activate - Informs the toolbar to send commands to this textArea.
  • [EqTextArea].addOutput(output)

    Associate additional regions with a single <textarea>, enabling a LaTeX equation to be displayed or formated in various other ways. This is typically used to automatically export the equaton into other systems; perhaps another HTML page.

    • output: Output object into which the equation will be published.

    Add to <body> :

    <div id="editor"></div>
    <textarea id="testbox" rows="3" cols="40"></textarea>
    <img id="equation" />
    
    <h3>Selection of Export Areas</h3>
    <p>HTML:</p>
    <textarea id="exportarea1" rows="3" cols="40"></textarea>
    
    <p>HTML with hyperlink to edit equation, placed within a DIV layer:</p>
    <div id="exportarea2"></div>
    
    <p>Tidly Wiki</p>
    <textarea id="exportarea3" rows="3" cols="40"></textarea>
    
    <p>Equation URL, placed within an image element:</p>
    <img id="exportarea4"/>
    
    <p>Equation URL:</p>
    <textarea id="exportarea5" rows="3" cols="40"></textarea>
    <script>
        toolbar = new EqEditor.Toolbar('editor');
    
        textarea = new EqEditor.TextArea('testbox');
        toolbar.addTextArea(textarea);
    
        textarea.addOutput(new EqEditor.Output('exportarea1','html'));
        textarea.addOutput(new EqEditor.Output('exportarea3','tw'));
        textarea.addOutput(new EqEditor.Output('exportarea4','url'));
        textarea.addOutput(new EqEditor.Output('exportarea5','url'));
    </script>

    Which creates :

    string [EqTextArea].exportEquation(type)

    This function return the text from associated <textarea> in a formated form, according to the type.

    • type: The export type which is one of the following:
      latexRaw LaTeX markup, 1+sin(x)
      safeSafe LaTeX markup, 1&plus;&space;sin(x) - retains most of the equation in human readable form, but encoded spaces,plus and hash.
      encodedEncoded LaTeX markup, 1&plus;%20sin(x) - Uses the javascript escape function and converts '+' rto &plus;
      wpWordpress markup, [latex]1+sin(x)[/latex]
      phpBBphpBB markup, [tex]1+sin(x)[/tex]
      twTiddly Wiki, [img[http://latex.codecogs.com/gif.latex?1+sin(x)]]
      urlURL link to equation, http://latex.codecogs.com/gif.latex?1&plus;sin(x)
      urlencodedEncoded URL link to equation, http://latex.codecogs.com/gif.latex?1&plus;sin%28x%29
      preHTML code using pre-tags, <pre xml:lang="latex">1+sin(x)</pre>
      doxygenDOxygen markup, \f[1+sin(x)\f]
      htmleditHTML code for use on a webpage with link to edit equation, <a href="www.codecogs.com/eqnedit?latex=1+sin(x)"><img src="latex.codecogs.com?gif.latex=1+sin(x)" /></a>
      htmlHTML code for use on a webpage, <img src="latex.codecogs.com?gif.latex=1+sin(x)" />

    ExportButton subclass

    The Export Buttons functionality allows a javascript function to be called, with the content of the <textarea> passed as input. This would usually be used to insert an equation into another HTML editor (perhaps CKEditor etc.) so this response will almost always be triggered by a button (hence the name).

    EqEditor.ExportButton.add(EqTextArea, buttonID, exportFn, type)

    • EqTextArea: an instance of EqTextArea to be linked with the Equation Editor System,
    • buttonID: id of the button that triggers copying,
    • exportFn: javascript function called when button is pressed,
    • type: (see exportEquation)

    Add to <body> :

    <div id="toolbar"></div>
    <textarea id="testbox" rows="3" cols="40"></textarea>
    <img id="equation" />
    
    <p>
      <input id="copybutton" type="button" class="greybutton" value="Export Button 1" />
      <input id="copybutton2" type="button" class="greybutton" value="Export Button 2" />
    </p>
    
    <textarea id="buttonexport" rows="3" cols="40"></textarea>
    
    <script type="text/javascript">
      EqEditor.embed('toolbar');
      var a=new EqTextArea('equation', 'testbox');
      EqEditor.add(a,false);
    
      EqnExport=function(text) { EqEditor.addText(document, 'buttonexport', text); };
      EqEditor.ExportButton.add(a, 'copybutton', EqnExport, 'html');
    
      EqnExport2=function(text) { alert(text); };
      EqEditor.ExportButton.add(a, 'copybutton2', EqnExport2, 'html');
    </script>

    Which creates :

    Editor.js

    OpenLatexEditor (target, type, language, inline, latex, design):

    • target: the html id of the input box where the equation should be placed.
    • type: the output formatting for the equation:
      latex$1+sin(x)$ or \[1+sin(x)\]
      doxygen\f$1+sin(x)\f$ or \f[1+sin(x)\f]
      phpBB[tex]1+sin(x)[/tex]
      tw[img[https://latex.oncodecogs.com/png.image?1+sin(x)]]
      html<img src="https://latex.oncodecogs.com/png.latex?1+sin(x)" />
      pre<pre xml:lang="latex">1+sin(x)</pre>
    • language: the spoken language. If no language is specified, the system will use the browser language.
      zh-cnCantonese
      nl-nlDutch (Nederlands)
      nl-beDutch Belgian
      en-usEnglish USA
      en-enEnglish British
      fr-frFrench (Fraçais)
      de-deGerman (Deutsch)
      el-elGreek (Έλληνας)
      lt-ltLithuanian (lietuvių kalba)
      hu-huHungarian (Magyar)
      it-itItalian (Italiano)
      ir-faPersian (Farsi)
      pl-plPolish (Polski)
      ro-roRomanian (Roman)
      ru-ruRussian (русский язык)
      es-esSpanish (Español)
      tr-trTurkish (Türkçe)
      uk-ukUkrainian (українець)
      vi-viVietnamese
    • inline [true|false] (optional): pre-selects the 'inline' option within the editor.
    • latex (optional): loads the editor with initial latex code.
    • design (optional): loads the editor with a different design. See the design page for more information. If this parameter is not set, then the editor will start with previous loaded design.

    To support more languages, we need help from native speakers. The language template (English USA) is available at: Language Template. Instructions are at the top of the document, which you can submit to us at Email CodeCogs. Your help is greatly appreciated. Please add your name to the credits line within the translation file.

    Copied to clipboard