ResourceLoader/Developing with ResourceLoader
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 development (also known as "debug") mode.
Development 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 development and production modes. In day-to-day development, most developers will find it beneficial to use development mode most of the time, only validating their code's functionality in production mode before committing changes.
Contents |
[edit] Registering
- See also Manual:$wgResourceModules and ResourceLoader/Migration guide (developers)#Registering a module
[edit] CSS parsing
[edit] Annotations
- @embed
- @noflip
[edit] CSS Janus
[edit] Module structure
- Work in progress
- Top module
Two modules for most extensions. A module to be loaded from the <head> containing styles and/or scripts that need to run as soon as possible. This module should generally be a small as possible and be used to:
- Style output by PHP
- Insert or modify elements that change the location of anything above the "the fold" (such as inserting a banner that pushes the page down, or a sidebar widgets that pushes another sidebar portlet down, or a content action tab that causes a change in the position of other tabs)
- Bottom module
- Insert or modify elements that are not visible right away (e.g. binding autocompletion to a form element or inserting a small absolutely positioned widget)
- Anything else
[edit] Toggle debug mode
As with many other of MediaWiki, ResourceLoader is configured to run in production mode by default. To have ResourceLoader operate in development mode by default, set the $wgResourceLoaderDebug variable to true in LocalSettings.php. For example:
/* * By adding this to your LocalSettings.php file, MediaWiki will default to * development mode instead of production mode. */ $wgResourceLoaderDebug = true;
[edit] Switching modes per-request
ResourceLoader requests, such as those made to load.php, contain a debug parameter in their query string. This parameter controls whether ResourceLoader runs in production or development mode for that particular request. This parameter may also be used with MediaWiki page requests, allowing the default mode set by $wgResourceLoaderDebug to be overridden.
To force ResourceLoader to operate in production mode for a particular request, append debug=false to the query string. For example:
http://example.org/wiki/An_article?debug=false
To force ResourceLoader to operate in development mode for a particular request, append debug=true to the query string. For example:
http://example.org/w/index.php?title=An_article&action=edit&debug=true
[edit] Issues
- When developing with ResourceLoader debug on, the CSS will not be flipped for right-to-left (RTL) languages. So you should test RTL interface with debug off. (See Bug 30804 - RTL display is broken with ?debug=true.)
[edit] 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 since bug 25573 is fixed.
[edit] Good examples
The following is a list of MediaWiki extensions which take advantage of ResourceLoader functionality and are known to be a good example of ResourceLoader integration.
[edit] More info
- "Low Hanging Fruit vs. Micro-optimization – ResourceLoader" (OSCON 2011) by Trevor Parscal and Roan Kattouw (video · slides · slides+notes)
- "ResourceLoader 2.0" (Wikimania 2011) by Roan Kattouw and Timo Tijhof (slides · video)
- Migration guide for extension developers
- Vocabulary
| ResourceLoader | |
|---|---|
| Documentation | Migration guide (users) · Migration guide (developers) · Developing with ResourceLoader · Default modules · Vocabulary |
| Project information | Status updates · Version 1 Design Specification (tasks) · Version 2 Design Specification (tasks) · Requirements |
| Other | JavaScript Deprecations |
