ResourceLoader/Migration guide (users)

Jump to: navigation, search
shortcut: RL/MGU

Through time the core JavaScript functions and HTML output improves functionality, introduces new methods, deprecates or changes in other aspects. This document intends to highlight the most common problems that need to be fixed.

  • For an overview of what is currently available in ResourceLoader, check out ResourceLoader/Modules.
  • See also ResourceLoader/Legacy JavaScript for a table with replacements for mediawiki.legacy functions (wikibits, ajax.js etc.).
  • Problems with gadgets? Check if it's listed below. If so, ask a sysop to update it on your wiki.
  • You can help with the migration on Wikimedia projects. See the 2011 Resource Walker, which also has useful tools to ease migration.

MediaWiki 1.26[edit | edit source]

Legacy gadgets[edit | edit source]

Gadgets are now required to use ResourceLoader. For many Gadgets, migrating to ResourceLoader will be as easy as adding [ResourceLoader] to its definition on MediaWiki:Gadgets-definition. If after adding that, the gadget is not working properly, consult the rest of this page to look for functionality that may have been removed since the gadget was last maintained. If you run into any issues or find features that don't work without a clear way of making it work, please reach out to MediaWiki developers and fellow gadget authors on the talk page, via IRC, or on the wikitech-l mailing list.

Global variables are not global[edit | edit source]

When ResourceLoader loads a gadget script, it is not executed in global context. This means that local variables you define in the script are actually local, and not assumed to be also global. They are local to the function your code is wrapped in. It's best to modularize your code to avoid using globals, see "Globals" in MediaWiki's JavaScript coding conventions. However, if you need to export a variable to the global scope, you can explicitly assign them as window properties. For example:

// This is a local variable
var foo;
// This is a local function
function bar() {

// This is a global variable (accessible from other scripts, and from legacy event handlers, e.g. onclick="javascript:Quux();"
window.Quux = function( width, height ) {

Code within your gadget can access foo and bar. Code outside the gadget (or code evaluated as separate programs, such as legacy onclick handlers), can only access Quux..

As of August 2015, ResourceLoader debug mode still executes scripts in global scope (phab:T64605), so your code may seem to work fine in debug mode but be broken in regular mode.

Font mw-geshi[edit | edit source]

The font-size of <syntaxhighlight> was often too small by default due to a font-family CSS bug. This was fixed in the MediaWiki 1.26 branch (see (phabricator:T28204).

The mw-geshi, source-css, source-javascript and related classes no longer exist. Related code such as the following can be safely removed:

/* Fix <syntaxhighlight> text size. [[Bugzilla:26204]] */ div, div pre,,
pre.source-javascript {
    font-family: monospace, Courier !important;

MediaWiki 1.20[edit | edit source]

New diff styles[edit | edit source]

This version introduces a new diff view, greatly improved in clarity especially for whitespace and other small changes and colour-blind users. If your wiki has custom CSS for the diffs, they may be in conflict with the new style (as happened on ptwiki and srwiki). You are recommended to remove the old code (or if still wanted by some users, update it to work with the new layout and create a gadget for it so that users can opt-in to it still).

MediaWiki 1.19[edit | edit source]

wikitable style updates[edit | edit source]

As of MediaWiki 1.19 a few bugs have been fixed with the wikitable class (see bugzilla:30485 and bugzilla:33434 for more info). If your wiki maintains a legacy synonym of this class (e.g. "prettytable") you need to update its CSS to match the current style in core.

The current style as of 1.19 can be found here. Copy those rules to your wiki and replace "wikitable" with the synonym (example for nl.wikipedia).

If your wiki doesn't keep something like this, then no update is necessary and everything should take care of itself.

File page checkered background[edit | edit source]

Checkered background

The checkered background often applied to transparent file namespace pages is now part of the software. Local rules like the following should be removed (because they are redundant, and actually cause an additional unnecessary HTTP request for the image)

/* Put a checker background at the image description page.
   Only visible if the image has transparent background.
#file img {
	background: url("//") repeat;

Trackbacks[edit | edit source]

Trackbacks were removed from MediaWiki core, so any styling targeting #mw_trackbacks can be removed.

MediaWiki 1.18[edit | edit source]

Protocol-relative urls[edit | edit source]

This change only applies to Wikimedia Foundation wikis.

As of MediaWiki 1.18 there is native support for protocol-relative wiki installations. This means that a wiki could be accessible from both and To make it possible to a share a common cache for as much as possible, we make use of a technique called protocol-relative urls. Although browsers have supports this for ages, script writers generally aren't very familiar with it until fairly recently. Briefly explained, this means that <img src="//" /> when on "" will be automatically expanded by the browser to This is much like (for example) <img src="foobar.jpg" /> or <img src="/w/foobar.jpg" />, which are are automatically expanded to "".

Depending on how the scripts were written this may require some changes to be made to your scripts. If you use the following method to detect whether the script is executed on a certain wiki, this change will break your script:

if ( wgServer === '' ) {
	// Doesn't work anymore!

because wgServer is now "//". For a few years there has been another config variable, called "wgDBname". You should use that instead to differentiate wikis, like:

if ( mw.config.get( 'wgDBname' ) === 'enwiki' ) {
	// English Wikipedia!

If you must use wgServer, then simply change it to:

if ( mw.config.get( 'wgServer' ) === '//' ) {
	// English Wikipedia!

"Enabled by default" (Gadgets extension)[edit | edit source]

As of the version of the Gadgets extension at the MW 1.18 branchpoint, there is a new feature that allows a gadget to be opt-out instead of opt-in based. By setting "[default]" (or adding "|default" to an existing section) the gadget will be enabled by default for everybody, unless a user has specifically opted out by unticking the checkbox on Special:Preferences#mw-prefsection-gadgets.

Note that this also loads it for all anonymous users. Gadgets that are only for logged-in users should be additionally restricted by, for example, requiring certain user rights.

See also Extension:Gadgets#Options.

mw.util.wikiScript[edit | edit source]

The actual paths have not changed, but getting the path to the API and index.php has become a lot easier. This also makes the code more portable as it has no hardcoded wiki-specific paths.

This is how it used to go in many gadgets.

var foo = 'bar';
var apiUrl = '//' + encodeURIComponent( foo ) + '&baz=quux';

$.ajax( { url: apiUrl, ... } );

Instead use something like one of the following:

// Behold, mw.util.wikiScript!
var foo = 'bar';
var apiUrl = mw.util.wikiScript( 'api' ) + '?foo=' + encodeURIComponent( foo ) + '&baz=quux';

$.ajax( {
	url: apiUrl,
} );

You may also want to use $.param to automatically escape and create things properly in the query string:

// $.param is also awesome. No need for encodeURIComponent that way :)
var foo = 'bar';
var apiUrl = mw.util.wikiScript( 'api' ) + '?' + $.param( {
	foo: foo,
	baz: 'quux'
} );

$.ajax( {
	url: apiUrl,
} );

You can even use the data option of $.ajax, that abstracts away the need to deal with the query string entirely:

// No longer needed to inject the '?' or '&' in the url
$.ajax( {
	url: mw.util.wikiScript( 'api' ),
	data: {
		foo: 'bar',
		baz: 'quux'
	}, ...
} );

MediaWiki 1.17[edit | edit source]

  • $j has been deprecated. Use jQuery or $ instead.

jQuery[edit | edit source]

See also jQuery

As of 1.17 the jQuery library is loaded by default on all MediaWiki pages. Each MediaWiki release will keep it up to date with the latest version of jQuery. If you used to load jQuery from within your script, (e.g. from, make sure you remove that. If you load jQuery more than once on a page, it overwrites the earlier version. Other scripts break because they may not work with an older version of jQuery.

Also, by overwriting the jQuery object, any plugins that were bound to that object are also lost.

Tabs (vector)[edit | edit source]

In 1.17 the HTML construction for the navigation tabs has changed from <li><a><span /></a></li> to <li><span><a /></span></li>. The most common situation in which this causes problems is where scripts assume the presence of the span element when, for example, customizing the tab for "Main Page". Before 1.17 this usually meant that wikis had a different implementation for Monobook and one for Vector (or only one for each and the other was distorted).

Please use MediaWiki:Mainpage-nstab or refer to Snippets/Main Page tab for a script that will work in both Vector and Monobook for 1.17.

Adding portlet links[edit | edit source]

The legacy function addPortletLink has been rewritten in the mediaWiki JS Utility library as mw.util.addPortletLink. The syntax and argument order is fully backwards compatible. The differences

  • Support for all core skins now
  • Support for simple id-selector as 'nextNode' (see documentation for details).

Some wikis may have re-defined / overwritten the addPortlinkLink function to support a few extra skins. This is no longer needed. The function definition should be removed and calls adjusted to mw.util.addPortletLink.

The legacy version of addPortlinkLink has been preserved as-is in case some edge cases would behave differently (for that reason the addPortlinkLink does not redirect to mw.util.addPortlinkLink)

Sajax[edit | edit source]

The legacy functions such as sajax_init_object have been deprecated. Instead, use $.ajax or mw.Api (from the mediawiki.api module).

Client testing[edit | edit source]

Checking which browser, platform, layout engine etc. has should now be done with jQuery.client.

  • is_safari, is_chrome etc. are deprecated
  • No need to navigator.userAgent.indexOf("MSIE 6")==-1 etc.

mw.loader[edit | edit source]

If you need certain scripts like jQuery UI's dialog or datepicker, instead of doing something like:

importStylesheetURI( mw.config.get( 'wgExtensionAssetsPath' ) + '/UsabilityInitiative/css/vector/jquery-ui-1.7.2.css' );

$.getScript( mw.config.get( 'wgExtensionAssetsPath' ) + '/UsabilityInitiative/js/js2stopgap/jui.combined.min.js', function () {
} );

Instead use this:

mw.loader.using( ['jquery.ui.dialog', 'jquery.ui.datepicker'], MyTool.init );

Or if you need to delay initialization until document.ready:

mw.loader.using( ['jquery.ui.dialog', 'jquery.ui.datepicker'], function () {
	$( document ).ready( MyTool.init );
} );

Migrating user scripts[edit | edit source]

There are a few old wikibits functions that don't have a simple drop-in replacement yet (such as importScript()). importScriptURI does have a simple successor: mw.loader.load. Recommendation: Keep using importScript the way you do, the way you know they work. They won't go away anytime soon, certainly not before there is a good replacement.

One should only use mw.loader.using for demonstration purposes or when writing site scripts/user scripts (which don't have a module registry for dependencies). In most cases, when dealing with ResourceLoader modules, there is a module registry which lists the scripts, styles, dependencies etc. that should be loaded. That way ResourceLoader knows about the modules contents ahead of time and can do all kinds of optimizations. For gadgets this registry is MediaWiki:Gadgets-definition.

Dependencies[edit | edit source]

When a script depends on another module, such as jquery.ui.dialog or mediawiki.util, you will need to declare this as a "dependency". This is because modules are loaded on-demand and asynchronously (in consecutive order: all at the same time), so a script needs to make sure a module has been loaded before it can use its methods. Native modules, like gadgets, have a registry to declare these dependencies, but user scripts do not. You will need to load those modules using mw.loader.using()

Note that this has been that way since day one that MediaWiki 1.17 was deployed. The only reason scripts appeared to work without declaring dependencies was that until now, it was more likely that – before your module loads –, another module has loaded which has the same dependencies as your module.

With MediaWiki 1.19, modules and scripts are loaded in a more efficient way, therefore it is important to declare your dependencies so that ResourceLoader will make sure to load those first. Otherwise, your script will fail because any of the 100+ modules you might refer to in your code may not be loaded yet, or are never loaded at all.

Two base modules are always loaded and need not be declared. These are mediawiki and jquery.

In practice[edit | edit source]

Use mw.loader.using() to declare any modules that you need before executing the contents of "function". You can pass multiple modules as an array of strings.

mw.loader.using( ['mediawiki.util', 'jquery.ui.dialog', 'jquery.cookie'], function () {

	/* some other script that uses $.cookie */

	/* some other script that uses mw.util and $foo.dialog() */

} );

Global wg variables[edit | edit source]

As of MediaWiki 1.17, the global config variables are deprecated. Rationale to clear the global namespace, working towards a reality where most of the core libraries will be object oriented as part of the mediaWiki object. Configuration is managed through an instance of mw.Map in mw.config. It is also supporting the behavior of more script executing in their own local/private scope as supposed to the global scope.

Legacy globals will be kept for backwards compatibly, but people should start migrating so that they may removed in a future version of MediaWiki (Bug 33837).

if ( mw.config.exists( 'wgGlobalGroups' ) {
	// do stuff

if ( mw.config.get( 'wgCanonicalSpecialPageName' ) === 'Search' ) {
	// do stuff

// Retrieve multiple variables for concise repeated access
var conf = mw.config.get( [
] );
if ( conf.wgAction === 'view' ) {
	// do stuff

More info: ResourceLoader/Default modules#mediaWiki.config

Ready, onload, hook[edit | edit source]

Check JavaScript deprecation overview for "addOnloadHook". Use jQuery( document ).ready( function ); instead, or $( fn ); for short.

New CSS declarations in core[edit | edit source]

Headings overflow hidden[edit | edit source]

overflow:hidden for any of h1, h2, h3, h4, h5 and/or h6 can be safely removed from stylesheets as this is now part of the core.

Italic redirects[edit | edit source]

Links to redirects appear italicized on Special:AllPages, Special:PrefixIndex, Special:Watchlist/edit and in category listings

.watchlistredir {
        font-style: italic;

wpSummary[edit | edit source]

Per bugzilla:20276, input#wpSummary's width is now set in Vector as well (instead of just Monobook).

UsabilityInitiative no more[edit | edit source]

As of 1.17 the functionality developed by the UsabilityInitiative has been extracted to stand-alone extensions. Buttons like "#pt-optin-try" no longer exist. You can enable/disable these functions like other extensions via Special:Preferences.

Scripts and styles doing things like "HideUsabilityOptIn":

#pt-optin-try {
	display: none !important;

should therefore be deleted entirely as the button no longer exists.

Preformatted JS/CSS pages[edit | edit source]

It's no longer useful to wrap these pages in /* <pre> */ or // <source lang="javascript"> etc. In newer versions of MediaWiki, these pages are rendered as code automatically (including syntax highlighting when available). See also bug 4801.

Table sorter[edit | edit source]

The old table sorter in wikibits.js was removed in favour of jquery.tablesorter.

Variables such as ts_alternate_row_colors, and functions like ts_parseFloat and ts_dateToSortKey no longer exist.

MediaWiki 1.16 and before[edit | edit source]

importScript[edit | edit source]

As of 2008, the function importScript is part of MediaWiki. Wikis that have defined this function themselves may remove that. It will automatically use the new function. This also goes for importStylesheet, importStylesheetURI and importScriptURI.

Make sure that before removing such local function though that the function signature is compatible with the core function and that there are no additional locally implemented arguments or features that core doesn't have (or vice versa). When in doubt, either keep it untouched or replace the function body with a compatibility call to the new core functionality (thus re-routing it instead of removing it entirely).

addPortletLink[edit | edit source]

As of 2008, the function addPortletLink is part of MediaWiki. Many wikis and gadgets have created functions like addLink, addLiLink, addlilink etc. these should be removed as they most likely don't support different skins (ie. only Monobook, not Vector or older skins). Be sure to check the syntax as there is no way of knowing the creator of those local functions used the same parameter order.

Note: The global function was deprecated in 2012 and moved to the mediawiki.util module as mw.util.addPortletLink()

appendCSS[edit | edit source]

As of 2008, the function appendCSS is part of MediaWiki. Wikis that have defined this function themselves may remove that. It will automatically use the new function.

Note: The global function was deprecated in 2012 and moved to the mediawiki.util module as mw.util.addCSS()

CSS declarations new in core[edit | edit source]

wikitable[edit | edit source]

The .wikitable CSS class is part of MediaWiki. Wikis that previously defined this class in their Common.css should remove it. Do check if the wiki has any customisations that should be retained (e.g. different background-color, or font-size).

plainlinks[edit | edit source]

The .plainlinks CSS class is part of MediaWiki. Wikis that previously defined this class in their Common.css should remove it.

Many wikis defined this functionality under a different name: .plainlinksneverexpand. Once any usage is replaced with "plainlinks", it may also be removed. (Search with insource:plainliksneverexpand.)

mw-plusminus[edit | edit source]

The CSS classes .mw-plusminus-pos, .mw-plusminus-null, and .mw-plusminus-neg are now implemented by MediaWiki.

External URLs[edit | edit source]

Icons for protocols like HTTP, IRC, etc. and file types like PDF are now supported by MediaWiki.

Tooltip and accesskeys[edit | edit source]

Scripts like ta['pt-userpage'] = new Array('.','My user page'); are ignored. It was deprecated in 2009. The function akeytt() no longer exists. Tooltips and accesskeys are now supported from core. The most common values that wikis used with ta[] are the same that have now been integrated into the core (ie. "." for "my user page"). They can still be modified, if really needed, by sysops in MediaWiki-messages (no need for JavaScript workarounds anymore).

As of MediaWiki 1.19 the global dummy placeholder ta = new Object(); was removed from wikibits.js. Code trying to add members to it will likely emit an exception.

Good practices[edit | edit source]

Anything not related to a particular MediaWiki version that should be noted as it is often done in a way that could or must be better.

Avoid document.write()[edit | edit source]

Do not use, will cause blank pages; instead, use jQuery to modify the document (adding elements, changing things etc.) and the import functions to load external resources. (importStylesheet, importScript, mw.loader.load, $.getScript).

Example: replace

document.write('<script type="text/javascript" src="'
             + ''
             + '&action=raw&ctype=text/javascript&dontcountme=s"></script>');


mw.loader.load( '//' );

Event binding[edit | edit source]

Binding events and callback functions is very tricky and it is hard to implement it in good cross-browser way that supports all browsers MediaWiki supports too.

As a good practice it is recommended to use jQuery methods for event binding. See the JavaScript deprecation overview on "addHandler" for examples on more info for this.

Encoding and escaping[edit | edit source]

When working with regexes, user input and/or urls always encode and escape!

Prototyping[edit | edit source]

Do not extend native JavaScript constructors with non-standard methods (e.g. String.prototype.foobar, Regex.myMethod, Array.prototype.inArray etc.). Depend on the es5-shim module to preload (in older browsers) standard polyfills for JavaScript 1.8 and ECMAScript 5 methods. See also Annotated ES5 specification and es5-shim.

// This loader() command immediate runs "done" in modern browsers,
// In order browsers it loads es5-shim.js first.
mw.loader.using( 'es5-shim').done( function () {
	console.log( '    bar    '.trim() ); // "bar"
	[ 'a', 'b' ].forEach( function ( val ) {
		/* .. */
	} );
} );

Getting URL parameter values[edit | edit source]

Functions like getURLParamValue, getParamVal, getParamValue, etc. are very common across wikis. Some are better than others (i.e. what if a parameter appears twice? (it should return the last one), does it ignore anything after the #tag?). As of 1.17 mw.util.getParamValue is available everywhere and takes these factors into account. Perform a full-text all-namespace search for these function names. If they are widely used perhaps make a note about it in the local village pump. Any site-wide scripts should be updated to use the mw.util function. If there are any serious problems with the local implementation (like not escaping the value for regex), it may be wise to redirect the function:

function getURLParamValue( p, url ) {
	return mw.util.getParamValue( p, url );

Avoid use of !important[edit | edit source]

CSS stands for Cascading Style Sheets. Cascading means what comes later overwrites what came earlier. In most cases there is no need to use !important. See the following example:

.my-element { color: blue; }
.my-element { color: green; }

Text inside <strong class="my-element"> will now be green.

Keep gadgets central[edit | edit source]

Gadgets that are highly used across wiki (like Gadget-LiveClock.js) should be kept central (ie. Meta-Wiki or The following is a list of gadgets that are centrally stored and

  • made compatible with 1.17
  • work in Monobook and Vector
  • wiki independent (ie. can be loaded on Commons, Wikipedia, Wiktionary or John Doe's Wiki without problems)

Sysops: To update a gadget on your wiki:

  • Check MediaWiki:Gadgets-definition on your wiki and find the gadget in question.
  • The part after the pipe (|) is the scriptname (eg. "UTCLiveClock.js").
  • Go to MediaWiki:Gadget-<scriptname> (eg. MediaWiki:Gadget-UTCLiveClock.js)
  • Remove everything and replace with the code in they grey area below the scriptname in the list. For an example on how this is done, check out LiveClock on Simple Wikipedia.

Gadgets[edit | edit source]

  • UTCLiveClock
  • contribsrange
  • modrollback
  • QPreview
  • ShortDiff
  • lastdiff Check Snippets/Last revision action
  • HotCat
 * This imports the latest version of HotCat from Commons.
 * HotCat is a gadget to make changes to categories much easier.
 * Full documentation can be found at [[commons:Help:Gadget-HotCat]]
mw.loader.load( '//' );
  • WikiMiniAtlas
 * WikiMiniAtlas is a popup click and drag world map.
 * See [[meta:WikiMiniAtlas]] for more information.
 * Maintainers: [[w:User:Dschwen]]
mw.loader.load( '//' );
  • Navigation Popups (MediaWiki:Gadget-popups.js and MediaWiki:Gadget-popups.css respectively)
mw.loader.load( '//' );
@import url( '//' );

jQuery optimization[edit | edit source]

Use API instead of index.php[edit | edit source]

XML retrieved by invoking GET and POST methods on index.php is incompatible with HTML 5, which is the default as of 1.16 (and WMF sites since 17th of September, 2012). You should update code to use api.php, JSON format and jQuery.ajax immediately. Use the ResourceLoader modules that do this for you to simplify interactng with the API, including mediawiki.api.

A temporary fix for problems with DOM parsing of XML retrieved via AJAX: For example the method getElementById("foobar") on a XML object from Mozilla's DOMParser stopped to work as before. Replacing the getElementById with $('#foobar', client.responseText).get(0) might work without many other changes to your code. Updating your script to the above mentioned methods is strongly recommended, however.

Conventions[edit | edit source]

See also[edit | edit source]

Documentation FeaturesResourceLoader/Features · VocabularyResourceLoader/Vocabulary · Migration guide (users)ResourceLoader/Migration guide (users) · Migration guide (developers)ResourceLoader/Migration guide for extension developers · Developing with ResourceLoaderResourceLoader/Developing with ResourceLoader · Core modulesResourceLoader/Modules · Mobile supportResourceLoader/Writing a MobileFrontend friendly ResourceLoader module
Project information Status updatesResourceLoader/status · Version 1 Design SpecificationResourceLoader/Version 1 Design Specification (tasksResourceLoader/V1 Task management) · Version 2 Design SpecificationResourceLoader/Version 2 Design Specification (tasksResourceLoader/V2 Task management) · RequirementsResourceLoader/Requirements
Other JavaScript DeprecationsResourceLoader/Legacy JavaScript