jsMath (Authors)

Adding jsMath to a BLOG or Bulletin-Board System

One of the challenges for programs that produce dynamic web content (that can include mathematics) is typesetting the mathematics that is entered by users of the system. JsMath has found a home in a number of bulletin-board and blog systems because its input format is TeX code, which is compact, reasonably straight-forward, and well known in the mathematics and scientific communities, and because it produces high-quality output without the need for plugins or other downloads on the part of the user, without special image-generation software or an installation of TeX on the server.

JsMath has been updated to make it even easier to incorporate it into blog and bulletin-board software (referred to in the future as BBS software). As of version 3.0, you no longer need to run part of jsMath in the document BODY, so it is now very straight-forward to include jsMath within pages that are generated automatically by a BBS system. It is most convenient if you can insert text either in the document HEAD, or at the top of the web page generated by the BBS, but it is possible to do it even if all you can do is insert text at the location of the mathematics within the page.

The easiest way to do this would be simply to insert a SCRIPT tag that loads the jsMath/easy/load.js file, and configure it to use tex2math to look for appropriate math delimiters within the body of the document. All the configuration can be done through the easy/load.js file, so you would only need to insert that one tag into the pages generated by the BBS program. So if you can insert

    <SCRIPT SRC="path-to-jsMath/easy/load.js"></SCRIPT>

to the HEAD or top of the BODY section of the page, that should be all that you need to do.

If you need a more complex setup, then there are three key steps that need to be performed: loading the jsMath.js file, inserting the SPAN and DIV tags for the mathematics, and calling the jsMath.Process() or jsMath.ProcessBeforeShowing() command.

When you can modify the HEAD or the top of the BODY

If you can insert arbitrary text in the document HEAD or at the top and bottom of the BODY, then add

    <SCRIPT>
      jsMath = {onload: function () {
        jsMath.Process(document);
      }};
      if (window.addEventListener) {window.addEventListener("load",jsMath.onload,false)}
      else if (window.attachEvent) {window.attachEvent("onload",jsMath.onload)}
      else {window.onload = jsMath.onload}
    </SCRIPT>
    <SCRIPT SRC="path-to-jsMath/jsMath.js"></SCRIPT>

there. It is best if this is at the top of the BODY, but will work fine in the HEAD as well. This takes care of two of the three issues: loading jsMath.js and calling jsMath.Process(). The only part remaining is to mark the mathematics for jsMath to process.

If your users can enter raw HTML commands, they could enter the SPAN or DIV tags by hand, though that is pretty tedious. If your BBS has a method for replacing special markup commands within the user's text by the corresponding HTML, you can use that to define more appropriate delimiters for your mathematics, and have these replaced buy the corresponding SPAN or DIV commands.

For example, you might want to use [math]...[/math] to indicate in-line math and [display]...[/display] to indicate displayed math equations. In that case, you would map '[math]' to '<SPAN CLASS="math">', '[/math]' to '</SPAN>', '[display]' to '<DIV CLASS="math">' and '[/display]' to '</DIV>'. How that is done will be dependent on the BBS system you are using; you'll have to look through its documentation for details.

It is best if the BBS system itself can make these substitutions, but if not, you can use the tex2math plugin to do the conversion for you. For example, you can insert

     <SCRIPT>
      jsMath = {onload: function () {
        jsMath.ConvertLaTeX(document);
        jsMath.Process(document);
      }};
      if (window.addEventListener) {window.addEventListener("load",jsMath.onload,false)}
      else if (window.attachEvent) {window.attachEvent("onload",jsMath.onload)}
      else {window.onload = jsMath.onload}
    </SCRIPT>
    <SCRIPT SRC="path-to-jsMath/jsMath.js"></SCRIPT>
    <SCRIPT> jsMath.Setup.Script("plugins/tex2math.js") </SCRIPT>

at the top of the BODY or in the HEAD section of the page. This will let your users indicate in-line math using \(...\) and display math using \[...\]. It is possible to have the tex2math plugin look for dollar signs as well as these LaTeX math indicators, or even use your own custom delimiters (like the ones suggested above). See the tex2math plugin documentation for more details. The down-side to using tex2math rather than having your BBS system insert the appropriate SPAN and DIV commands is that this will be slower for the user, and the initial mark-up will be displayed on screen before it is converted to mathematics, so the viewer will see the original form before the typeset mathematics appears. If you can add HTML markup at the bottom of the page, however, you can improve this. By putting the jsMath.ConvertLaTeX() command within the BODY of the page (rather than the onLoad handler), you can force the insertion of the SPAN and DIV tags to be performed before the page is displayed.

So if you put

    <SCRIPT SRC="path-to-jsMath/jsMath.js"></SCRIPT>
    <SCRIPT> jsMath.Setup.Script("plugins/tex2math.js") </SCRIPT>

at the top of the BODY or in the HEAD of the page and

    <SCRIPT>
      jsMath.ConvertLaTeX(document);
      jsMath.ProcessBeforeShowing(document);
    </SCRIPT>

at the bottom of the BODY, this will cause the mathematics on the page to be rendered before the page is displayed (at least in most browsers). The reason you might not want to do this, however, is because jsMath can be very slow, and if the page contains a lot of mathematics, your readers might give up waiting for the page to appear.

Loading jsMath only when it is needed

Note that the method described above will always cause jsMath.js to be loaded on every page of your site, even those that don't contain mathematics. Since jsMath.js is a large file (on the order of 110K), it is non-trivial to download it, and you might not want to have it sent to the user for every page when many might not include mathematics. Most likely, the jsMath.js file will be cached by the browser and sent only once, but that need not be the case, so this may be a concern for your BBS.

One solution it to take advantage of jsMath's autoload plugin. The basic setup would be something like the following:

    <SCRIPT>
      jsMath = {
        Autoload: {findLaTeXstrings: 1, delayCheck: 1},
        onload: function () {
          jsMath.Autoload.Check();
          jsMath.Process(document);
        }
      };
      if (window.addEventListener) {window.addEventListener("load",jsMath.onload,false)}
      else if (window.attachEvent) {window.attachEvent("onload",jsMath.onload)}
      else {window.onload = jsMath.onload}
    </SCRIPT>
    <SCRIPT SRC="path-to-jsMath/plugins/autoload.js"></SCRIPT>

This will ask the autoload plugin to look for the LaTeX math delimiters, \(...\) and \[...\] within the document, and if there are any, then it will load jsMath (and won't load jsMath otherwise). If jsMath was loaded, the jsMath.Autoload.Check() call will run the tex2math plugin to convert the LaTeX commands to jsMath SPAN and DIV tags, and then jsMath.Process() will typeset those. If jsMath wasn't needed, these commands will do nothing.

Note that if you use this method of loading jsMath, there can be a substantial pause once the page is loaded before the mathematics is processed. This is because the time-consuming loading of jsMath has been put off until the end of the page, so the user may have to wait for that once the page is displayed. If that download is slow, the user can be confused about why the mathematics is not showing properly; you may need to include a warning message somewhere indicating that that may happen. Once jsMath has been loaded for one page, however, the following pages should process at normal speed, since jsMath will be cached by the browser in most cases.

There are a number of options you can set for the autoload plugin; see the autoload plugin page for more details.

When you can only modify the text for the mathematics itself

If you can only insert text at the location of the mathematics itself, it is still possible to use jsMath. The issue here is that you don't want to load jsMath.js more than once. One way to do this would be to use

    <SCRIPT>
      if (!window.jsMath) {
        document.write('<SCRIPT SRC="path-to-jsMath/jsMath.js"><'+'/SCRIPT>');
      }
    </SCRIPT>
    <SPAN CLASS="math">

before the in-line mathematics and

    </SPAN>
    <SCRIPT> window.onload = function () {jsMath.Process(document)} </SCRIPT>

afterward, and similarly for the DIV blocks for displayed equations. This causes jsMath.js to be loaded and processed only once. Note the extra '+' within the </SCRIPT> tag; this is so that the </SCRIPT> within the document.write() will not end the <SCRIPT> in which the document.write appears.

You can include additional commands in the if-then statement that set defaults for jsMath, load plugins, and so on, if you wish. If this gets to be a lot of code, it might be more efficient to put it all into a separate .js file that you load instead of jsMath.js (and that itself loads jsMath.js).

jsMath web pages Created: 02 Aug 2005 Last modified: 13 Sep 2008 10:36:07 Comments to: dpvc@union.edu

Overriding jsMath Functions with Your Own Versions Browser Support for jsMath Information for jsMath Authors Loading jsMath in the Document HEAD