ResourceLoader/Migration guide (users)

Though time the core JavaScript and HTML output improves functionality, introduces new methods, deprecates or changes 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.)

= 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"

= 1.16 = ...

= 1.15 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.