Expand all

mw.loader

Client for ResourceLoader server end point.

This client is in charge of maintaining the module registry and state machine, initiating network (batch) requests for loading modules, as well as dependency resolution and execution of source code.

Methods

addStyleTag(text, [nextNode]) → {HTMLStyleElement}static #

Create a new style element and add it to the DOM. Stable for use in gadgets.

Parameters:

Name Type Attributes Description
text string

CSS text
nextNode Node | null optional

The element where the style tag should be inserted before
Source:

Returns:

Reference to the created style element

Type
HTMLStyleElement
Create a new style element and add it to the DOM.

getModuleNames() → {Array.<string>}static #

Get the names of all registered ResourceLoader modules.

Source:

Returns:

Type
Array.<string>
Get the names of all registered ResourceLoader modules.

getScript(url) → {jQuery.Promise}static #

Load a script by URL.

Example

mw.loader.getScript(
    'https://example.org/x-1.0.0.js'
)
    .then( function () {
        // Script succeeded. You can use X now.
    }, function ( e ) {
        // Script failed. X is not avaiable
        mw.log.error( e.message ); // => "Failed to load script"
    } );
} );

Parameters:

Name Type Description
url string

Script URL
Source:

Returns:

Resolved when the script is loaded

Type
jQuery.Promise
Load a script by URL.

getState(module) → {string|null}static #

Get the state of a module.

Possible states for the public API:

  • registered: The module is available for loading but not yet requested.
  • loading, loaded, or executing: The module is currently being loaded.
  • ready: The module was successfully and fully loaded.
  • error: The module or one its dependencies has failed to load, e.g. due to uncaught error from the module's script files.
  • missing: The module was requested but is not defined according to the server.

Internal mw.loader state machine:

  • registered: The module is known to the system but not yet required. Meta data is stored by register(). Calls to that method are generated server-side by StartupModule.
  • loading: The module was required through mw.loader (either directly or as dependency of another module). The client will fetch module contents from mw.loader.store or from the server. The contents should later be received by implement().
  • loaded: The module has been received by implement(). Once the module has no more dependencies in-flight, the module will be executed, controlled via setAndPropagate() and doPropagation().
  • executing: The module is being executed (apply messages and stylesheets, execute scripts) by execute().
  • ready: The module has been successfully executed.
  • error: The module (or one of its dependencies) produced an uncaught error during execution.
  • missing: The module was registered client-side and requested, but the server denied knowledge of the module's existence.

Parameters:

Name Type Description
module string

Name of module
Source:

Returns:

The state, or null if the module (or its state) is not in the registry.

Type
string | null
Get the state of a module.

load(modules, [type])static #

Load an external script or one or more modules.

This method takes a list of unrelated modules. Use cases:

  • A web page will be composed of many different widgets. These widgets independently queue their ResourceLoader modules (OutputPage::addModules()). If any of them have problems, or are no longer known (e.g. cached HTML), the other modules should still be loaded.
  • This method is used for preloading, which must not throw. Later code that calls #using() will handle the error.

Parameters:

Name Type Attributes Default Description
modules string | Array

Either the name of a module, array of modules, or a URL of an external script or style
type string optional
 'text/javascript'

MIME type to use if calling with a URL of an external script or style; acceptable values are "text/css" and "text/javascript"; if no type is provided, text/javascript is assumed.
Source:

Throws:

If type is invalid

Type
Error
Load an external script or one or more modules.

using(dependencies, [ready], [error]) → {jQuery.Promise}static #

Execute a function after one or more modules are ready.

Use this method if you need to dynamically control which modules are loaded and/or when they loaded (instead of declaring them as dependencies directly on your module.)

This uses the same loader as for regular module dependencies. This means ResourceLoader will not re-download or re-execute a module for the second time if something else already needed it. And the same browser HTTP cache, and localStorage are checked before considering to fetch from the network. And any on-going requests from other dependencies or using() calls are also automatically re-used.

Example of inline dependency on OOjs:

mw.loader.using( 'oojs', function () {
    OO.compare( [ 1 ], [ 1 ] );
} );

Example of inline dependency obtained via require():

mw.loader.using( [ 'mediawiki.util' ], function ( require ) {
    var util = require( 'mediawiki.util' );
} );

Since MediaWiki 1.23 this returns a promise.

Since MediaWiki 1.28 the promise is resolved with a require function.

Parameters:

Name Type Attributes Description
dependencies string | Array

Module name or array of modules names the callback depends on to be ready before executing
ready function optional

Callback to execute when all dependencies are ready
error function optional

Callback to execute if one or more dependencies failed
Source:

Returns:

With a require function

Type
jQuery.Promise
Execute a function after one or more modules are ready.