215 lines
7.5 KiB
ReStructuredText
215 lines
7.5 KiB
ReStructuredText
.. _api-ajax:
|
|
|
|
***********************
|
|
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 :ref:`Synchronizing with MathJax <synchronization>`
|
|
documentation for details on how to do this properly.
|
|
|
|
|
|
Properties
|
|
==========
|
|
|
|
.. describe:: timeout
|
|
|
|
Number of milliseconds to wait for a file to load before
|
|
it is considered to have failed to load.
|
|
|
|
*Default:* 15 seconds
|
|
|
|
.. describe:: STATUS.OK
|
|
|
|
The value used to indicate that a file load has occurred
|
|
successfully.
|
|
|
|
.. describe:: STATUS.ERROR
|
|
|
|
The value used to indicate that a file load has caused an error or
|
|
a timeout to occur.
|
|
|
|
.. describe:: 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.
|
|
|
|
.. describe:: 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.
|
|
|
|
.. describe:: loadHooks
|
|
|
|
An object containing the load hooks for the various files, set up by
|
|
the :meth:`LoadHook()` method, or by the
|
|
:meth:`MathJax.Hub.Register.LoadHook()` method.
|
|
|
|
|
|
Methods
|
|
=======
|
|
|
|
.. method:: 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
|
|
|
|
.. method:: 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
|
|
|
|
.. method:: 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 :meth:`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``
|
|
|
|
.. method:: loadTimeout(file)
|
|
|
|
Called when the timeout period is over and the file hasn't loaded.
|
|
This indicates an error condition, and the
|
|
:meth:`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``
|
|
|
|
.. method:: 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``
|
|
|
|
.. method:: 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
|
|
|
|
.. method:: 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 :meth:`Load()` or :meth:`Require()` call for
|
|
them), so that load-hooks and other load-related events can be
|
|
properly processed when the :meth:`loadComplete()` occurs.
|
|
|
|
:Parameters:
|
|
- **file1, file2, ...** --- the names of the files in the combined file
|
|
:Returns: ``null``
|
|
|
|
.. method:: 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 :ref:`CSS Style Object <css-style-objects>`.
|
|
For example:
|
|
|
|
.. code-block:: javascript
|
|
|
|
MathJax.Ajax.Styles("body {font-family: serif; font-style: italic}");
|
|
|
|
and
|
|
|
|
.. code-block:: javascript
|
|
|
|
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.
|
|
|
|
.. method:: 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
|