Attention

Version 3 is now the current version of MathJax. This document is for version 2.

The MathJax.Ajax Object

The MathJax.Ajax structure holds the data and functions for handling loading of external modules. Modules are loaded only once, even if called for in several places. The loading of files is asynchronous, and so the code that requests an external module will continue to run even when that module has not completed loading, so it is important to be aware of the timing issues this may cause. Similarly, creating or loading stylesheets is an asynchronous action. In particular, all actions that rely on the file or stylesheet having been loaded must be delayed until after the file has been downloaded completely. This is the reason for the large number of routines that take callback functions.

Any operation that could cause the loading of a file or stylesheet must be synchronized with the rest of the code via such callbacks. Since processing any mathematics might cause files to be loaded (e.g., little-used markup might be implemented in an extension that is loaded only when that markup is used), any code that dynamically typesets mathematics will need to be structured to use callbacks to guarantee that the mathematics has been completely processed before the code tries to use it. See the Synchronizing with MathJax documentation for details on how to do this properly.

Properties

timeout

Number of milliseconds to wait for a file to load before it is considered to have failed to load.

Default: 15 seconds

STATUS.OK

The value used to indicate that a file load has occurred successfully.

STATUS.ERROR

The value used to indicate that a file load has caused an error or a timeout to occur.

loaded

An object containing the names of the files that have been loaded (or requested) so far. MathJax.Ajax.loaded["file"] will be non-null when the file has been loaded, with the value being the MathJax.Ajax.STATUS value of the load attempt.

loading

An object containing the files that are currently loading, the callbacks that are to be run when they load or timeout, and additional internal data.

loadHooks

An object containing the load hooks for the various files, set up by the LoadHook() method, or by the MathJax.Hub.Register.LoadHook() method.

Methods

Require(file[, callback])

Loads the given file if it hasn’t been already. The file must be a JavaScript file or a CSS stylesheet; i.e., it must end in .js or .css. Alternatively, it can be an object with a single key:value pair where the key is one of js or css and the value is the file of that type to be loaded (this makes it possible to have the file be created by a CGI script, for example, or to use a data:: URL). The file must be relative to the MathJax home directory and can not contain ../ file path components.

When the file is completely loaded and run, the callback, if provided, will be executed passing it the status of the file load. If there was an error while loading the file, or if the file fails to load within the time limit given by MathJax.Ajax.timout, the status will be MathJax.Ajax.STATUS.ERROR otherwise it will be MathJax.Ajax.STATUS.OK. If the file is already loaded, the callback will be called immediately and the file will not be loaded again.

Parameters:

  • file — name of the file to be loaded

  • callback — the callback specification

Returns:

the callback object

Load(file[, callback])

Used internally to load a given file without checking if it already has been loaded, or where it is to be found.

Parameters:

  • file — name of the file to be loaded

  • callback — the callback specification

Returns:

the callback object

loadComplete(file)

Called from within the loaded files to inform MathJax that the file has been completely loaded and initialized. The file parameter is the name of the file that has been loaded. This routine will cause any callback functions registered for the file or included in the MathJax.Ajax.Require() calls to be executed, passing them the status of the load (MathJax.Ajax.STATUS.OK or MathJax.Ajax.STATUS.ERROR) as their last parameter.

Parameters:

  • file — name of the file that has been loaded

Returns:

null

loadTimeout(file)

Called when the timeout period is over and the file hasn’t loaded. This indicates an error condition, and the MathJax.Ajax.loadError() method will be executed, then the file’s callback will be run with MathJax.Ajax.STATUS.ERROR as its parameter.

Parameters:

  • file — name of the file that timed out

Returns:

null

loadError(file)

The default error handler called when a file fails to load. It puts a warning message into the MathJax message box on screen.

Parameters:

  • file — the name of the file that failed to load

Returns:

null

LoadHook(file, callback)

Registers a callback to be executed when the given file is loaded. The file load operation needs to be started when this method is called, so it can be used to register a hook for a file that may be loaded in the future.

Parameters:

  • file — the name of the file to wait for

  • callback — the callback specification

Returns:

the callback object

Preloading(file1[, file2...])

Used with combined configuration files to indicate what files are in the configuration file. Marks the files as loading (since there will never be an explicit Load() or Require() call for them), so that load-hooks and other load-related events can be properly processed when the loadComplete() occurs.

Parameters:

  • file1, file2, … — the names of the files in the combined file

Returns:

null

Styles(styles[, callback])

Creates a stylesheet from the given style data. styles can either be a string containing a stylesheet definition, or an object containing a CSS Style Object. For example:

MathJax.Ajax.Styles("body {font-family: serif; font-style: italic}");

and

MathJax.Ajax.Styles({
  body: {
    "font-family": "serif",
    "font-style":  "italic"
  }
});

both set the body font family and style.

The callback routine is called when the stylesheet has been created and is available for use.

Parameters:

  • styles — CSS style object for the styles to set

  • callback — the callback specification

Returns:

the callback object

Note

Internet Explorer has a limit of 32 dynamically created stylesheets, so it is best to combine your styles into one large group rather than making several smaller calls.

fileURL(file)

Returns a complete URL to a file (replacing [MathJax] with the actual root URL location).

Parameters:

  • file — the file name possibly including [MathJax]

Returns:

the full URL for the file