ResourceLoader/Migration guide (users)

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/Default modules.
 * See also ResourceLoader/JavaScript Deprecations 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.18 =

Protocol-relative urls

 * 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 http://example.org and https://example.org. 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  when on " https://example.org " will be automatically expanded by the browser to https://meta.wikimedia.org. This is much like (for example)  or , which are are automatically expanded to " http://mediawiki.org/w/foobar.jpg ".

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: because wgServer is now " ". Since a few years there has been another config variable, called " ". You should use that instead to differentiate wikis, like: If you must use wgServer, then simply change it to :

"Enabled by default" (Gadgets extension)
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 " " (or adding " " to en 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.

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.

mw.util.wikiScript
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 wiki-independent.

This is how it used to go in many gadgets.

Instead use something like one of the following:

= MediaWiki 1.17 =

Tabs (vector)
In 1.17 the HTML construction for the navigation tabs has changed from  to. 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 refer to Snippets/Main Page tab for a script that will work in both Vector and Monobook for 1.17.

Adding portlet links
The legacy function  has been rewritten in the mediaWiki JS Utility library as. 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  function to support a few extra skins. This is no longer needed. The function definition should be removed and calls adjusted to.

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

Client testing
Checking which browser, platform, layout engine etc. has should now be done with jQuery.client.
 * ,  etc. are deprecated
 * No need to  etc.

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

Instead use this:

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

Migrating user scripts
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  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
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</tt>.

In practice
Use mw.loader.using</tt> to declare any modules that you need before executing the contents of "function". You can pass multiple modules as an array of strings.

wg* Variables
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  object. Configuration is managed through an instance of  in. 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).

More info: ResourceLoader/Default modules

Ready, onload, hook
Check JavaScript deprecation overview for " ". Use  instead. Or  for short.

New CSS declarations in core

 * 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.
 * Links to redirects appear italicized on Special:AllPages, Special:PrefixIndex, Special:Watchlist/edit and in category listings
 * Source code

UsabilityInitiative no more
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": Should therefore be deleted entirely as the button no longer exists.

tags around .js / .css pages
It's no longer needed to wrap these pages in  or the like for the preview, since preview is now similar to the normal viewing of the page (ie. in a pre-tag).

= MediaWiki 1.16 and before =

ImportScript
The function  is now part of core. Wikis that have defined this function themselfs can now remove that and it will automatically use the core function now. This also goes for,   and.

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 visa 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
The function  is now part of core. Many wikis and gadgets have created functions like,  ,   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 developer of those functions have used the same argument order.
 * Note: Since then it has been deprecated and moved into the mediaWiki library as

appendCSS
appendCSS is now loaded on all pages by default in wikibits.js. Any definition for the function can be removed without having to change anything else.
 * Note: Since then it has been deprecated and moved into the mediaWiki library as

Wikitable
is now part of core. Although wikis should check if their version is the same (ie. different background color, or perhaps a different font-size), and if the same remove it from their .css pages.
 * Source code

mw-plusminus
,,   are now part of core as well.
 * Source code

External URLs
Icons for protocols like [ HTTP], IRC, etc. and file types like [ PDF] are now in-core.


 * Source code

ta[] Tooltip and Accesskeys
Scripts like  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). [//simple.wiktionary.org/w/index.php?title=MediaWiki:Monobook.js&diff=next&oldid=4974 example].

= Good practices = 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.

document.write
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, importStylesheetURI, importScriptURI , mw.loader.load).

Event binding
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
When working with regexes, user input and/or urls always encode and escape!


 * Regexes:
 * HTML:  (provided by default)
 * URL:  (for normal values),   for page titles, does not escape colons  and slashes (/). (provided by mediawiki.util</tt> module)

Prototyping
It is recommended not to use any kind of prototyping on native javascript constructors (ie. String.prototype.Foobar, Regex.quote, Array.prototype.inArray etc.). Instead extend the jQuery namespace:

Getting URL parameter values
Functions like getURLParamValue, getParamVal, getParamValue, etc. are very common accross wikis. Some are better than others (ie. what if a parameter appears twice ? (it should return the last one), does it ignore anything after the #tag ?)). As of 1.17  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:

Avoid use of !important
CSS stands for Cascading Style Sheets. Cascading means what comes later overwrites what came earlier. In most cases there is no need to use. See the following example: Text inside  will now be <strong style="color:green">green.

Keep gadgets central
Gadgets that are highly used across wiki (like Gadget-LiveClock.js) should be kept central (ie. Meta-Wiki or MediaWiki.org). 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. "").
 * Go to (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

 * UTCLiveClock
 * contribsrange
 * modrollback
 * ShortDiff
 * lastdiff Check Snippets/Last revision action
 * HotCat
 * WikiMiniAtlas
 * Navigation Popups (MediaWiki:Gadget-popups.js and MediaWiki:Gadget-popups.css respectively)

jQuery optimization

 * Optimization for jQuery
 * jQuery for Performance & Common mistakes
 * http://www.smashingmagazine.com/2008/09/16/jquery-examples-and-best-practices/

Use API instead of index.php
XML retrieved by invoking GET and POST methods on index.php is incompatible with HTML 5, which is the default as of 1.16 (but not on WMF wikis yet). You should update code to use api.php, JSON format and jQuery.ajax immediately.

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

Conventions

 * Manual:Coding conventions/JavaScript - keep if statements with brackets, use proper indention (block B in block A is indenter more, visualize the tree), etc.
 * Manual:Coding conventions/CSS - combine selectors, remove stuff now in core, etc.