### Navigation

- index
- next |
- previous |
- MathJax v2.0 documentation »
- The MathJax API »

# 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

### Navigation

- index
- next |
- previous |
- MathJax v2.0 documentation »
- The MathJax API »