jsMath (Authors)

Configuring jsMath

Most of the features of jsMath can be controlled through the jsMath/easy/load.js file. It contains settings (described below) that you can change to modify how jsMath operates. You load and run jsMath simply by adding the line

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

where path-to-jsMath is the URL for the jsMath folder on your server.

You can make copies of easy/load.js and have different settings in each copy, so you can use jsMath with different configurations by loading the appropriate copy of easy/load.js.

The Easy Loader Settings

The easy/load.js file contains a collection of values that you can set in order to control how jsMath operates. There are comments in the file to help you decide what settings to change, and they are explained more fully here:

root

This should be the URL for the jsMath directory on your server, or its location on your hard disk (if you are using jsMath locally rather than through a server). The URL can be of the form http://your-site/path-to-jsMath, or it can be an absolute path from the root of your server, e.g., /path-to-jsMath. It is possible to use a relative path, but that will be interpreted as relative to the page that loads easy/load.js, so all such pages would need to be at the same level of the web hierarchy. The URL must be in the same domain as the page that will be loading it (that is, jsMath and the HTML pages must both come from the same server, or at least servers in the same domain).

scale

This controls the scaling factor for the mathematics in comparison to the surrounding text. It is a percentage value, so 100 would be unscaled, and 120 would be scaled to 20 percent larger than normal. The math fonts often are a bit small compared to the standard font used in the browser, so you may want to use a size larger than 100. Also, since mathematics uses lots of super- and subscripts, if you are using small fonts on your pages, these can become difficult to read. Enlarging the scaling factor can help make super- and subscripts clearer. Usually, values between 120 and 133 are good choices.

autoload

This determines whether the autoload plugin is used or not. The autoload plugin checks the web page to see if there is any mathematics on the page before loading jsMath and only loads jsMath on pages that need it. Since jsMath is a large file (more than 100KB), this can substantially improve the load time for pages that don't have math on them. On the other hand, the autoload plugin is an additional download that has to be performed, and so that pages that do include mathematics will open slower, since both autoload and jsMath must be loaded. Since most browsers cache javascript files, this should only affect the first page downloaded from your site. There will still be a processing cost on each page, however, so if the majority of your pages include mathematics, you might consider turning off autoload to make your pages work faster.

processSlashParens

This controls whether the tex2math plugin is used to search for \(...\) within your web pages and convert them to <SPAN CLASS="math">...</SPAN> tags. This makes it more convenient to enter in-line mathematics for those used to typing LaTeX files. The default value is 1, meaning do search for these delimiters.

processSlashBrakets

This controls whether the tex2math plugin is used to search for \[...\] within your web pages and convert them to <DIV CLASS="math">...</DIV> tags. This makes it more convenient to enter displayed equations for those used to typing LaTeX files. The default is 1, meaning do search for these delimiters.

processDoubleDollars

This controls whether the tex2math plugin is used to search for $$...$$ within your web pages and convert them to <DIV CLASS="math">...</DIV> tags. This makes it more convenient to enter displayed equations for those used to typing plain TeX files. The default is 1, meaning do search for these delimiters.

processSingleDollars

This controls whether the tex2math plugin is used to search for $...$ within your web pages and convert them to <SPAN CLASS="math">...</SPAN> tags. This makes it more convenient to enter in-line mathematics for those used to typing plain TeX files. The default value is 0, meaning do not search for these delimiters. This is because dollar signs can appear in normal text where they would not indicate math mode, so you need to enable this specifically if you want to use single dollar signs for in-line math mode.

fixEscapedDollars

If you enable processSingleDollars, you may want to enable this setting as well. This controls whether the tex2math plugin is used to convert \$ to $ outside of math mode. That gives you the ability to "escape" a dollar sign, and prevent it from being used to initiate math mode, so it will appear as a normal dollar sign in the text of the file. The default is not to convert these.

doubleDollarsAreInLine

This controls whether tex2math will insert a SPAN rather than a DIV for $$...$$ within your pages. You could then use HTML by hand to distinguish between in-line and display math (for example, by putting displayed math within <CENTER>...</CENTER> tags).

allowDisableTag

This determines whether tex2math processing can be disabled by inserting a tag with ID="tex2math_off" on the web page. This makes it easy to control globally whether tex2math will process a page (and hence whether jsMath will be used). If your pages are generated by several people, however, as in a blog or bulletin-board system, a malicious user could disable mathematics for the whole page. You may wish to disable this setting if that is the case for your pages.

customDelimiters

This array holds four strings that are used to start and stop in-line and displayed mathematics. This way you can use any delimiters you want, rather than the TeX or LaTeX ones. Note, however, that these can not contain the HTML special characters <, >, or &. This is because those characters are used to indicate tags and entities within HTML, and since tex2math doesn't run until after the page has been interpreted by the browser, these character are no longer part of the text that is available to tex2math when it processes the page. In particular, that means you can't make delimiters that look like normal HTML tags.

The customDelimiters is commented out by default. If you want to use your own delimiters, uncomment the example and adjust the strings to suit your needs.

safeHBoxes

Since jsMath does not process text-mode TeX commands, formatting of tex within an \hbox{} must be handled by the use of HTML tags. But the tex2math plugin does not allow HTML tags within the mathematics, and that includes \hbox contents. So jsMath provides an alternative means of inserting tags in an \hbox via the @(...) sequence. If jsMath is used in a content-management system where untrusted users can enter mathematical formulas, then this poses a security risk as users would be able to enter arbitrary HTML into their postings. The safeHBoxes setting controls whether jsMath disables the @(...) mechanism or not. Setting this to 0 means users can enter arbitrary HTML tags into your pages. Leaving it as 1 means they will not be able to style the text within \hbox contents.

allowDoubleClicks

When the user double-clicks on an equation, jsMath will display a popup window that shows the original TeX code for that equation. You can disable that feature by setting allowDoubleClicks to 0.

showFontWarnings

JsMath works best and fastest when the user has installed the jsMath-TeX fonts on his or her computer. Without these, jsMath will use an image fallback mode that is slower, doesn't print as well, and doesn't resize if the user scales the page (the user would have to reload the page after changing sizes in order to get the correctly sized mathematics). If the user does not have these fonts installed, jsMath will issue a warning on the first page (containing mathematics) that is loaded from your site informing them that the TeX fonts will improve their experience of your site, and indicating how to get them.

Some page authers mistakenly think they are helping their readers by disabling this feature; in reality, however, you are guaranteeing that they will have a poorer experience at your site, since you have deprived them of the knowledge that there even is a font that they could download that would improve the speed and quality of the mathematics at your site. Since the warning is only issued once and it can be dismissed by the click of a button (and even can be prevented for up to five years using the control panel), there is no reason for you to turn off these informative messages.

method

This value controls which of the two methods of displaying mathematics jsMath should use. The default is to use "Process" (the jsMath.Process() function), which processes the mathematics asynchronously, so that the page will be displayed before the mathematics is typeset, and the user will see the equations turn into typeset math as jsMath processes them. JsMath also shows a progress message at the lower left of the screen while it is processing the mathematics on the page.

Setting this value to "ProcessBeforeShowing", however, will cause all the mathematics to be typeset before any of it is displayed. In most browsers, this will mean the page shows up with the mathematics already typeset, but there is a longer delay before the page appears (since jsMath must perform the typesetting before the page is displayed).

For pages with only a little mathematics, ProcesBeforeShowing may produce a more satisfying effect; but for pages with lots of mathematics, the user will probably not want to wait for all of it to be processed before being able to read any of the page. The Process setting allows the user to begin reading the page even while the mathematics lower down on the page is being typeset, and so it is the default setting.

loadFiles

This array can be used to list additional JavaScript files that should be loaded once jsMath has been initialized. This allows you to load jsMath extensions or plugins, or even your own JavaScript files that need to call jsMath functions. To load files, simply list them within the square brackets. For example:

     loadFiles: ["plugins/mimeTeX.js","extensions/AMSsymbols.js"],

would load the mimeTeX plugin and the AMSsymbols extension.

Files are loaded relative to the jsMath folder on the server, but you can also include absolute URLs to load extensions from anywhere on your server. The jsMath variable will be available when these are run, and so you can make a file that calls jsMath.Macro(), for example, to define macros that you may need on your page (see the documentation on defining macros for details.)

Note that several of the plugins need to be loaded before jsMath.js and so should not be added to the loadFile list. If you need to use those plugins, you will need to add a SCRIPT tag to your HTML file just before the one that loads easy/load.js.

loadFonts

This array can be used to list extra fonts that should be preloaded for use by jsMath. Note that you need to have installed these fonts on your server for this to work. (See the extra-fonts download page for a listing of the fonts available and instructions on installing them.) For example,

     loadFonts: ["cmmib10"],

would load the Computer Modern bold math italic font. See the documentation on adding fonts for details about how to access the font once it is loaded.

macros

This object can be used to declare macros to be defined automatically once jsMath has been loaded. The entries in the object are of the form

    name: value

where value is the replacement text for the macro \name. The value can also be [value,n] where value is the replacement text and n is the number of parameters for the macro.

Note that backslashes must be doubled in the replacement string, as in the following:

    macros: {
      RR: '{\\bf R}',
      bold: ['{\\bf #1}', 1]
    }

which define \RR to produce a bold-faced 'R', and \bold{...} to put its argument into bold face.

allowGlobal

JsMath has a "global mode" that allows it to cache the equations it has typeset to try to speed up processing of later pages. (See the Global Mode documentation for details.) This uses a frameset to give jsMath a persistent frame in which to hold the cached data, but that introduces a number of thorny issues for page authors. In particular, if your site already uses framesets, jsMath's frames could interfere with that. For this reason, you may want to disable jsMath's global mode, and can do so by setting allowGlobal to 0. This will disable the "Go Global" button on the jsMath control panel to prevent the user from entering global mode.

noImageFonts

If you have not loaded the jsMath image fonts onto your server (either because they take too much space, or because it is not possible for you to upload that many small files to the server), you should disable jsMath's image modes by setting noImageFonts to 1. This will prevent the user from selecting either of the image-based modes from the jsMath options panel, and will make the default fall-back method the unicode mode. Note, however, that unicode mode is not as effective as image mode, in most cases, and so the user's experience may be considerably poorer than if you had made the image fonts available.

Loading Extensions and Plugins

JsMath includes a number of extensions and plugins that modify the way that it operates. (See the author's documentation for details.) Most of these can be loaded by adding them to the loadFiles array as described above. You can even load your own JavaScript files that way as well.

All these files run after jsMath is loaded and initialized. Some plugins, however, must be loaded before jsMath.js is loaded, and so these can not be entered in the loadFile array. Instead, they must be loaded by a separate SCRIPT tag in your HTML file before the one that loads easy/load.js.

Unfortunately, it is not possible to include those files from within easy/load.js itself. One might think that adding additional document.write commands that insert more SCRIPT tags would work, but it turns out that this does not work as expected. The order in which such script tags are executed is browser dependent (MSIE does not always perform them in the order they are issued), so it is hard to guarantee that the scripts will load in the correct order.

(It would be possible, but awkward, to develop a feature-detection routine for this. If there is demand, however, I will work on it.)

Setting CSS Styles

Some features of jsMath can be controlled by CSS styles, for example, the size of the typeset mathematics, and the placement of displayed equations. There are several ways for you to customize these settings in your pages.

First, you could use STYLE tags within your pages themselves to set the styles, or could create a .css file and load that on each page. It is also possible, however, to have easy/load.js set the styles for you.

If you create a .css file, you can add a command like

    document.write('<STYLE SRC="path-to-CSS-file"></STYLE>');

to the bottom of easy/load.js, for example. Or you could use document.write to insert a STYLE block into your document directly.

Alternatively, you can set values in the jsMath.style array so that jsMath will create the stylesheet for you during its initialization process. For example,

    jsMath.style['div.typeset'] = "text-align:left; margin: 1em 0px 1em 1in";

would make displayed equations be left-justified at 1 inch from the left margin of the page. See the customizing jsMath section of the author's documentation for more details.

More Advanced Settings

JsMath uses the jsMath variable to store all of its data and code. You can override any of these values by setting the jsMath variable before jsMath.js is loaded. For example, the easy/load.js file sets jsMath.Easy so that jsMath has access to the configuration that you want to use.

Similarly, you can set other values in the jsMath variable to change jsMath's default behavior. The remainder of the author's documentation files describe how to do this, and often give examples of setting the jsMath variable by hand. Since easy/load.js already sets jsMath, you will need to be careful not to lose those settings by replacing jsMath with a new object.

Instead, you need to add to the existing jsMath object. You do this by setting jsMath.name rather than jsMath itself. For example, if the documentation suggests you use

    <SCRIPT> jsMath = {styles: {'div.typeset': 'text-align:left; margin: 1em 0px 1em 1in'}}  </SCRIPT>

then you should use

    jsMath.styles = {'div.typeset': 'text-align:left; margin: 1em 0px 1em 1in'};
or
    jsMath.style['div.typeset'] = 'text-align:left; margin: 1em 0px 1em 1in';

in easy/load.js instead.

You should only set jsMath.name once for any given name; if you set it more than once, only the last value will be in effect, as you will lose the earlier setting when the second assignment is made.

jsMath web pages Created: 22 Mar 2007 Last modified: Mar 28, 2010 3:12:00 PM Comments to: dpvc@union.edu

Controlling tex2math processing Browser Support for jsMath Information for jsMath Authors Getting Started with jsMath