ResourceLoader/Developing with ResourceLoader

This is a high-level walkthrough of the PHP interface for ResourceLoader for understanding how to create and register ResourceLoader modules in MediaWiki core or an extension.

For more about how ResourceLoader is designed, its features and why it works the way it does, see ResourceLoader/Features.

Registering

See also Manual:$wgResourceModules

In order for all the ResourceLoader features to function properly it is required to register modules under a symbolic name. We do that by adding the module definition to the configuration variable $wgResourceModules in your extension.json file, or by adding to the array in ./resources/Resources.php (for MediaWiki core).

Below is an example for registering a module called ext.myExtension in MediaWiki 1.25 and later using extension.json (see also: Extension registration).

"ResourceModules": {
    "ext.myExtension": {
        "scripts": [
            "modules/ext.myExtension.core.js",
            "modules/ext.myExtension.foobar.js"
        ],
        "styles": "modules/ext.myExtension.css",
        "messages": [
            "myextension-hello-world",
            "myextension-goodbye-world"
        ],
        "dependencies": [
            "oojs"
        ]
    }
}

Example for MediaWiki 1.24 and earlier

$wgResourceModules['ext.myExtension'] = array(
	// JavaScript and CSS styles. To combine multiple files, just list them as an array.
	'scripts' => array( 'js/ext.myExtension.core.js', 'js/ext.myExtension.foobar.js' ),
	'styles' => 'css/ext.myExtension.css',
	
	// When your module is loaded, these messages will be available through mw.msg().
	// E.g. in JavaScript you can access them with mw.message( 'myextension-hello-world' ).text()
	'messages' => array( 'myextension-hello-world', 'myextension-goodbye-world' ),
	
	// If your scripts need code from other modules, list their identifiers as dependencies.
	// Note that 'mediawiki' and 'jquery' are always available and cannot
	// be explicitly depended on.
	'dependencies' => array( 'oojs' ),
	
	// You need to declare the base path of the file paths in 'scripts' and 'styles'
	'localBasePath' => __DIR__,
	// ... and the base from the browser as well. For extensions this is made easy,
	// you can use the 'remoteExtPath' property to declare it relative to where the wiki
	// has $wgExtensionAssetsPath configured:
	'remoteExtPath' => 'MyExtension',
);

naming: Because (in this example) ext.myExtension is a module provided by and related to an extension, the module name begins with "ext.".

composition: This defined module consists primarily of two scripts and a CSS file that goes with it. The module also declares that it wants to be able to use two translatable message-keys. Any messages declared here will be available through mw.msg() after your module has loaded. Tip: Pass single resources as a string. Pass multiple resources as an array of strings.

dependencies: The example script depends on the oojs module. Loading and execution of scripts is fully asynchronous, so it is important to declare your dependencies, to make sure that they are loaded and available before your scripts try to use or reference it.

There are a multitude of additional properties that a module can have, and these options are mostly intended to influence the delivery behavior.

Look at skinStyles and skinScripts if (part of) your code is skin specific.
Use skipFunction if you are adding polyfills that could be loaded conditionally.
When you need to include translations, you might want to check out languageScripts.
When you want your module to be loaded in mobile variants as well, use targets. (See also Writing a mobile friendly ResourceLoader module)

Loading modules

Server-side

see also Manual:OutputPage.php and ParserOutput

While building the page, add one or more modules to the page by calling the addModules method on the OutputPage or ParserOutput object and passing it one or more module names (such as "mediawiki.foo", "jquery.bar" or "ext.myExtension.quux")

$outputPage->addModules( 'example.fooBar' );

OutputPage adds the given module names to the load queue of the page. The client side loader requests all of the components for this module (scripts, styles, messages, dependencies, etc.) and execute them correctly. If your module contains styles that affect elements outputted by PHP as well as elements created dynamically, then you should split the module. One for styling/enhancing the output, and one for dynamic stuff. The first module should only have stylesheets and be loaded with addModuleStyles (see #CSS). The other module will simply be loaded asynchronously by the client, not blocking further parsing of the page.

$outputPage->addModules( [ 'ext.myExtension.foo', 'ext.myExtension.bar' ] );

To get a reference to OutputPage object from an extension, use the BeforePageDisplay hook.

CSS

If you have CSS that should be loaded before the page renders (and even when JavaScript is unavailable), queue it via OutputPage::addModuleStyles. This will make sure the module is loaded from a <link rel=stylesheet> tag.

This is in contrast with the preferred method OutputPage::addModules which loads modules as a complete package in a combined request (scripts, styles, messages) dynamically (from a lightweight client in JavaScript). This is the preferred method because it is more efficient (single request for all resources), supports dependency resolution, request batching, is highly cacheable (through access to the startup manifest with all version numbers it can dynamically generate permanently cacheable urls), and reduces cache fragmentation (modules previously loaded on other page views are loaded directly from Local Storage).

Since dependency changes can be deployed independently from caching the page, static loading with addModuleStyles cannot use dependencies. And since you can't dynamically access the latest version of the startup manifest from static HTML without JavaScript execution, it cannot have versions in the urls either and are therefore cached for a shorter time.

In practice you should only use OutputPage::addModuleStyles for stylesheets that are required for basic presentation of server-generated content (PHP output and the core Skin). Separate this CSS from modules with JavaScript and styling of dynamically-generated content.

JavaScript

JavaScript files are, like CSS files, also evaluated in the order they are defined in the scripts array.

In the following example, one would use the entry "scripts": [ "foo.js", "init.js" ] when registering the module.

// foo.js
var Foo = {
    sayHello: function ( $element ) {
        $element.append( '<p>Hello Module!</p>' );
    }
};
window.Foo = Foo;

// init.js
$( function () {
    // This code must not be executed before the document is loaded. 
    Foo.sayHello( $( '#hello' ) );
});

The page loading this module would somewhere use $this->getOutput()->addHTML( '<div id="hello"></div>' ); to output the element.

Passing information from PHP to Javascript

You will often find yourself having to pass information from the server side to the client-side run Javascript. Usually you will do this by using either HTML or the API. In a case where this is not possible, you can pass the information as a Javascript variable. For this, you make a call to addJsConfigVars() on the OutputPage or ParserOutput object. In rare cases where you need to add global configuration variables, you can use the ResourceLoaderGetConfigVars hook. Using ResourceLoaderGetConfigVars can add a lot of extra bytes to every single page, so try to avoid using it.

Client-side (dynamically)

Gadgets should list their dependencies through the "dependencies" options in their definition.

For user scripts, dependencies cannot be declared ahead of time (unlike gadgets). Instead, for user scripts, wrap the code in a mw.loader.using block, and specify the required modules. For example:

mw.loader.using( ['mediawiki.util','mediawiki.Title'] ).then( function () {
    /* This callback is invoked as soon as the modules are available. */
} );

This will guarantee that the specified modules are loaded. Don't worry about multiple (separate) scripts both asking the loader for the same module. ResourceLoader internally ensures nothing is loaded multiple times.

Conditional lazy loading

If you have a script that only needs another module in a certain scenario of the user interface, you can create small separate module (known as an "init module"), and from there use JavaScript to dynamically load the rest of the module.

Example:

var $sortableTables = $content.find( 'table.sortable' );
if ( $sortableTables.length ) {
    mw.loader.using( 'jquery.tablesorter' ).then( function () {
        $sortableTables.tablesorter();
    } );
}

Parallel execution

If you have multiple asynchronous tasks, it is best to run these tasks in parallel. Use jQuery.when to track multiple separate asynchronous tasks (known as a "Promise", or a "Deferred"). Below is an example of waiting for and AJAX request, and the loading of ResourceLoader modules, and the "document ready" status:

// Good: These three processes run in parallel
$.when(
  $.getJSON( '//api.example.org/foo' ),
  mw.loader.using( ['mediawiki.util', 'mediawiki.Title', 'jquery.cookie'] ),
  $.ready
).then( function ( fooData ) {
 // This runs when the ajax request is complete, the modules are loaded,
 // and the document is ready
 $( '#example' ).attr( 'href', mw.util.getUrl( fooData.page ) );
} );

// Bad: These are nested, one waiting before the other starts:
$( function () {
  mw.loader.using( ['mediawiki.util', 'mediawiki.Title', 'jquery.cookie'] ).then( function () {
    $.getJSON( '//api.example.org/foo' ).then( function ( fooData ) {
      $( '#example' ).attr( 'href', mw.util.getUrl( fooData.page ) );
    } );
  } );
} );

// Less bad: Preloading with load()
$( function () {
  mw.loader.load( ['mediawiki.util', 'mediawiki.Title', 'jquery.cookie'] );
  $.getJSON( '//api.example.org/foo' ).then( function ( fooData ) {
      mw.loader.using( ['mediawiki.util', 'mediawiki.Title', 'jquery.cookie'], function () {
        $( '#example' ).attr( 'href', mw.util.getUrl( fooData.page ) );
      } );
  } );
} );

CSS

Your styling resources can be either CSS or, since MediaWiki 1.22, LESS files. When writing styles we advise you to follow our conventions.

Media queries

You can use media queries when you define your modules, to specify when a CSS/Less file applies:

{	"styles": {
		"always.css": { "media": "screen" },
		"print.css": { "media": "print" },
		"high-resolution.css": { "media": "screen and ( min-width: 982px )" }
	}
}

In the above example, the always.css stylesheet will always apply to all screens, the print.css stylesheet applies on print (and in the "Printable version" mode), and the high-resolution.css stylesheet applies when the viewport width is at least 982 pixels. The contents of the corresponding CSS/Less file will then be wrapped in the defined media query:

/* Output of print.css by ResourceLoader */
@media print {
	/* Contents of print.css */
}

/* Output of high-resolution.css by ResourceLoader */
@media screen and ( min-width: 982px ) {
	/* Contents of high-resolution.css */
}

Annotations

The CSS preprocessors in ResourceLoader support several annotations that you can use to optimise your stylesheets.

@embed

See also ResourceLoader/Features#Embedding

If an image is specified with the CSS url() function and is small enough (up to 24kB) the annotation @embed can be used in a CSS comment. This instructs ResourceLoader to embed the image in the CSS output as a data URI. For example:

.mw-feedback-spinner {
    display: inline-block;
    /* @embed */
    background: url(mediawiki.feedback.spinner.gif);
    ...
}

If you view a ResourceLoader request for this module, you can see that ResourceLoader transformed this image file into an embedded data URL, with the external URL only as a fallback. Reformatted for clarity, the ResourceLoader response includes:

.mw-feedback-spinner{display:inline-block;
 background:url(data:image/gif;base64,R0lGODlhEgA...==);
 background:url(https://www.mediawiki.org/w/resources/src/mediawiki/mediawiki.feedback.spinner.gif?f41ed)!ie;
...
}

Browsers that support data URIs in CSS use the embedded image instead of making another network request.

MediaWiki version:

≥ 1.22

In MediaWiki 1.22 and newer you can also use a LESS mixin to specify an image, and the mixin function outputs the @embed directive for you. For example, the .background-image() mixin (in mixins.less in core) in your LESS file:

.mw-foo-bar {
    .background-image('images/icon-foo-bar.png');
    padding: 4px  0 3px 40px;
}

See also ResourceLoaderImage, which generates raster images and multiple colored icons from a single source SVG file.

@noflip

See also ResourceLoader/Features#Flipping

To disable the flipping functionality for one CSS declaration or on an entire ruleset, use the @noflip annotation:

For example:

/* @noflip */ 
.mw-portlet-item { 
    float: left; 
    line-height: 1.25; 
}

/* This one flips! */ 
.mw-portlet-item { 
    margin-top: 0.5em; 
    /* ... except this one: */ 
    /* @noflip */ 
    margin-left: 0.75em; 
    font-size: 0.75em; 
    white-space: nowrap; 
}

Debugging

Toggle debug mode

ResourceLoader supports complex client-side web applications in production and development environments. As these different environments have different needs, ResourceLoader offers two distinct modes: production mode and debug mode (also known as "development") mode.

Debug mode is designed to make development as easy as possible, prioritizing the ease of identifying and resolving problems in the software over performance. Production mode makes the opposite prioritization, emphasizing performance over ease of development.

It is important to test your code in both debug and production modes. In day-to-day development, most developers will find it beneficial to use debug mode most of the time, only validating their code's functionality in production mode before committing changes.

You can enable debug mode for all page views, or for a single page request (by appending ?debug=true to the URL); see ResourceLoader/Features#Debug mode for details on toggling it.

Server-side exceptions

ResourceLoader catches any errors thrown during module packaging (such as an error in a module definition or a missing file) in load.php requests. It outputs this error information in a JavaScript comment at the top of its response to that request, for example:

/**
 * exception 'MWException' with message 'ResourceLoaderFileModule::readStyleFile: style file not found: 
 * Problematic modules: {"skin.blueprint.styles":"error"}
 */

You can inspect the request in the network panel in the developer tools for most browsers, or you can copy the load.php URL and load it in a new browser window. Note that the HTTP request with a failing module still returns status 200 OK, it does not return an error.

You can also output errors to a server-side log file by setting up a log file ($wgDebugLogGroups ) in $wgDebugLogGroups['resourceloader']. They aren't added to the main debug log ($wgDebugLogFile ) since logging is disabled by default for requests to load.php (bug 47960).

Client-side errors

Unreviewed

JavaScript returned by ResourceLoader is executed in the browser, and can have run-time errors. Most browsers do not display these to the user, so you should leave your browser's JavaScript console open during development to notice them.

You can use ResourceLoader's mw.loader.getState() function to check the state of a module, for example enter mw.loader.getState( 'skins.vector.js' ) in your browser's JavaScript console. If it returns:

null: The module is not known to ResourceLoader. Check for typos, and verify whether the module registered and defined correctly.
registered: ResourceLoader knows about the module, but hasn't (yet) loaded it on the current page. Check your logic for adding the module, either server-side or client-side. You can force it to load by entering mw.loader.load( 'my-module-name' ).
error: Something went wrong, either server-side or during client-side execution, with this module or one of its dependencies. Check the browser console and Network inspector for error relating to a load.php request. Alternatively, consider reloading the the page in debug mode.
ready: The module loaded on the current page without errors.

Breaking cache

When making frequent changes to code and checking them in a browser, the caching mechanisms designed to improve the performance of web-browsing can quickly become inconvenient. When developing on a system which is not making use of a reverse proxy such as Squid or Varnish, you only need to force your browser to bypass its cache while refreshing. This can be achieved by pressing CTRL+F5 in Internet Explorer, or holding the shift key while clicking the browser's refresh button in most other browsers.

If you are developing behind a reverse proxy, you can either change the values of $wgResourceLoaderMaxage or use ?debug=true to bypass cache.