The autoload plugin

If you are using jsMath on pages that are dynamically created, you may not know ahead of time whether jsMath will be needed on a particular page or not. Since jsMath.js is a large file, and downloading it can take a noticeable amount of time, you would not want to load jsMath.js if it is not going to be used. (Most browsers will cache JavaScript files, so only the first page the reader views will have the delay, but still, there is no need to cause the delay if the user is looking at a page with no math on it.)

The autoload plugin is designed to help you out in these situations. It will look through the web page to see if there are any instances of <SPAN> or <DIV> tags of class "math" that jsMath would process, and loads jsMath.js automatically if so, but does not load jsMath.js otherwise, effectively preventing the unwanted download for those cases where it was not needed.

If you are using easy/load.js to load jsMath, then you should set the autoload value to 1 to use autoload. This is the default setting.

If you want to use autoload by hand, add the lines

 <SCRIPT SRC="path-to-jsMath/plugins/autoload.js"></SCRIPT>
 <NOSCRIPT>
 <DIV STYLE="color:#CC0000; text-align:center">
 <B>Warning: <A HREF="http://www.math.union.edu/locate/jsMath">jsMath</A>
 requires JavaScript to process the mathematics on this page.<BR>
 If your browser supports JavaScript, be sure it is enabled.</B>
 </DIV>
 <HR>
 </NOSCRIPT>

at the bottom of the BODY of your document, before the call to jsMath.Process() or jsMath.ProcessBeforeShowing().

In this example, the autoload plugin is loaded in the BODY of the document, and it looks through the contents of the page automatically at the time it is called. It is also possible to load it in the document HEAD, but in this case, you will need to ask autoload to run later on. For example, you could put

 <SCRIPT SRC="path-to-jsMath/plugins/autoload.js"></SCRIPT>

in the document HEAD, and then at the bottom of the body, include

 <SCRIPT> jsMath.Autoload.Check() </SCRIPT>
 <NOSCRIPT>
 <DIV STYLE="color:#CC0000; text-align:center">
 <B>Warning: <A HREF="http://www.math.union.edu/locate/jsMath">jsMath</A>
 requires JavaScript to process the mathematics on this page.<BR>
 If your browser supports JavaScript, be sure it is enabled.</B>
 </DIV>
 <HR>
 </NOSCRIPT>

This will cause autoload to check for math in the document above the jsMath.Autoload.Check() call and load jsMath only if there is mathematics to be processed.

Note that in all the cases shown above, you still need to call jsMath.Process() or jsMath.ProcessBeforeShowing() in order to actually typeset the mathematics. The autoload plugin only loads jsMath; it doesn't run it.

One common way to use autoload is to use something like the following in the document HEAD:

 <SCRIPT SRC="path-to-jsMath/plugins/autoload.js"></SCRIPT>
 <SCRIPT>
 window.onload = function () {
 jsMath.Autoload.Check();
 jsMath.Process(document);
 }
 </SCRIPT>

which will load the plugin, then wait until the page is complete before checking for mathematics; if there is any, jsMath will be loaded and the document will be processed for mathematics. If not, the jsMath.Process() call will do nothing (so it is safe to include it even when jsMath isn't loaded).

Autloading the tex2math plugin

If you are also using the tex2math plugin, autoload can be requested to check for the math strings delimited by $...,ドル $$...$,ドル \(...\) and \[...\] in addition to (or in place of) looking for math SPAN's and DIV's. To do this, you set values in jsMath.Autoload before loading autoload.js, as in the following example:

 <SCRIPT>
 jsMath = {
 Autoload: {
 findTeXstrings: 0, // 1 to look for any tex-delimited math
 findLaTeXstrings: 0 // 1 to look for \(...\) and \[...\] only
 }
 }
 </SCRIPT>

You can set any (or all) of these values to control which tests are performed. If either of the TeX-string searches are performed, and strings are found, then the tex2math plugin is loaded automatically, so there is no need to load it separately. Note that there is no need to set both findTeXstrings and findLaTeXstrings, as the TeX string search includes the LaTeX strings (but not vice versa).

You can gain more precise control over what autoload looks for by setting the jsMath.Autoload.findCustomSettings variable:

 <SCRIPT>
 jsMath = {
 Autoload: {
 findCustomSettings: {
 processDoubleDollars: 1, // look for $$...$$
 processSingleDollars: 1, // look for $...$
 processSlashParens: 0, // look for \(...\)
 processSlashBrackets: 0, // look for \[...\]
 fixEscapedDollars: 1 // convert \$ to $
 }
 }
 }
 </SCRIPT>

Here, we look for $...$ and $$...$$ but not the LaTeX delimiters. See the tex2math plugin page for more details about these parameters.

It is also possible to specify custom strings to delimit mathematics, just as you can with the tex2math plugin. To specify these, use

 <SCRIPT>
 jsMath = {
 Autoload: {
 findCustomStrings: [begin-math, end-math,
 begin-display, end-display]
 }
 }
 </SCRIPT>

where begin-math and end-math are the strings that go around in-line mathematics, and begin-display and end-display are the strings that go around displayed mathematics. For example:

 <SCRIPT>
 jsMath = {
 Autoload: {
 findCustomStrings: ['%%','%%', '%%%', '%%%']
 }
 }
 </SCRIPT>

would make %%...%% indicate in-line math and %%%...%%% indicate displayed math equations. Note that the strings can not include HTML special characters like < or >, as these are already interpreted by the browser before autoload gets to look for them. So you can't use things that look like HTML tags for these, unfortunately.

In jsMath prior to version 3.3f required you to perform the tex2math calls yourself after autoload runs, and jsMath.Autoload.Run() was provided in order to make that easier. This is no longer necessary, and jsMath.Autoload.Run() is now depricated. Now autoload will perform the tex2math conversions automatically when it is loaded, so you no longer need to worry about calling tex2math when you use autoload.

Loading additional plugins and fonts

The value of jsMath.Autoload.needsJsMath is set to 1 if jsMath.js was loaded, and 0 if not, so you can use this variable to conditionally load additional plugins, fonts, etc. For example,

 <SCRIPT SRC="path-to-jsMath/plugins/autoload.js"></SCRIPT>
 <SCRIPT>
 if (jsMath.Autoload.needsJsMath) jsMath.Setup.Script("plugins/mimeTeX.js");
 jsMath.Process(document);
 </SCRIPT>

would load the mimeTeX plugin only if jsMath.js was loaded by the autoload plugin.

Alternatively, you can set the values of jsMath.Autoload.loadFonts and jsMath.Autoload.loadFiles to specify fonts and JavaScript files that should be loaded after jsMath.js is. These can be set either to the name of a single font or file, or to arrays of such names. For example,

 jsMath = {
 Autoload: {
 loadFonts: ["msam10","msbm10"],
 loadFiles: "plugins/mimeTeX.js"
 }
 }

would load the two AMS symbols fonts and the mimeTeX plugin whenever jsMath.js is loaded. Note that the file names are relative to the jsMath directory, unless they include an absolute path or URL. For instance

 jsMath = {
 Autoload: {
 loadFiles: ["/site/common.js","http://mysite.com/jsMath/local/macros.js"]
 }
 }

would load the first file from the root directory of the webserver hosting the current page, and the second from the specified website, but only if jsMath.js is loaded.

When jsMath.js is not loaded, autoload.js will define jsMath.Process(), jsMath.ProcessBeforeShowing(), jsMath.ConvertTeX() and jsMath.ConvertLaTeX() to be empty functions, so you can call them without having to worry about checking for jsMath.loaded first.

Defining custom macros

It is sometimes convenient to be able to defined your own macros for a page processed by jsMath. One way would be to load a separate JavaScript file that conatins jsMath.Macro() calls to define your macros, but that takes additional downloads and extra files. Alternatively, you can set the jsMath.Parser.prototype.macros array, but that is more complicated. The easiest way is to use the jsMath.Autoload.macros object to declare macros that you want to have defined automatically when jsMath is loaded. The entries in teh 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:

 <SCRIPT>
 jsMath.Autoload.macros = {
 RR: '{\\bf R}',
 bold: ['{\\bf #1}', 1]
 };
 </SCRIPT>

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

Searching only parts of the page

If you want autoload to search only a specific HTML element (like a specific DIV) for mathematics rather than the whole page (for example, to avoid having to search through sidebars and other navigational elements), you can set jsMath.Autoload.checkElement to the ID of the element to search, or to a reference to the element itself; if no element is specified, then the whole document is searched. (This mirrors the way that jsMath.Process() and jsMath.ProcessBeforeShowing() operate).

When you use the autoload plugin, there may be a delay at the bottom of the page while jsMath.js is loading. During this time, the rest of the page may be visible, so jsMath.ProcessBeforeShowing() may not have its desired effect.

If you are generating dynamic content on-the-fly (via JavaScript for example), then if the math content is not already in the page when autoload.js is loaded, it will not detect it, and so won't load jsMath.js for you. In these cases, you should not use autoload but should load jsMath.js in the usual way.

Using autoload with server-side includes

If your server is configured to allow server-side includes, you can cause autoload.js to be included directly into the web page rather than requiring the server to send the autoload.js file separately, causing a second file access. To do this, you need to first tell autoload where the jsMath files are (since it will not be able to look up the location from the SCRIPT tag as it usually does), and then include the autoload.js file;

 <SCRIPT>
 jsMath = {Autoload: {root: "path-to-jsMath"}};
 <!--#include virtual="path-to-jsMath/plugins/autoload.js" -->
 </SCRIPT>
 <NOSCRIPT>
 <DIV STYLE="color:#CC0000; text-align:center">
 <B>Warning: <A HREF="http://www.math.union.edu/locate/jsMath">jsMath</A>
 requires JavaScript to process the mathematics on this page.<BR>
 If your browser supports JavaScript, be sure it is enabled.</B>
 </DIV>
 <HR>
 </NOSCRIPT>

where path-to-jsMath is the URL for the jsMath directory. (This approach was suggested by Jan-Åke Larrson.)