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.

= MediaWiki 1.17 =

High priority
...

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 jQuery snippets for a script that will work in both Vector and Monobook for 1.17.

Adding portlet links
The legacy function addPortlinkLink 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 addPortlinkLink function to support a few extra skins. This is now longer deleted. The function definition should be removed and calls adjusted to mw.util.addPortlinkLink.

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)

Ready, onload, hook
Check JavaScript deprecation overview for "addOnloadHook"

= MediaWiki 1.16 and before =

ImportScript
ImportScript 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 importStylesheet, importStylesheetURI and importScriptURI.

addPortletLink
addPortletLink 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. addPortetLink documentation (1.17+).

= 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 or the import* functions to load external resources. (importStylesheet, importScript, importStylesheetURI, importScriptURI).

Event binding
Binding events and callback functions is very tricky and it is hard to implement it in such as way that all browsers MediaWiki supports actually work with it. As a good practice it is recommended to use jQuery for event binding. See the JavaScript deprecation overview on "addHandler" for examples on more info for this.

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:

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

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 green.

Low priority

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