Over time, MediaWiki core JavaScript functions and HTML outputs have improved in functionality, introduced new methods, been deprecated, or changed in other ways.This document intends to highlight the most common problems that need to be fixed.

For an overview of the modules that are available in MediaWiki core, seeResourceLoader/Core modules.

Themediawiki.Uri module provides an API to create and manipulate MediaWiki URIs.This functionality already has browser's native support and the module has been deprecated. (T374314)

Thejquery.cookie module provides an API to read and write raw browser cookies via$.cookie.This functionality has been merged into themediawiki.cookie module.

Thejquery.cookie module name is now a deprecated alias formediawiki.cookie.The module name alias was removed in MediaWiki 1.42.

Both$.cookie andmw.cookie are now provided directly by themediawiki.cookie module.

Thejquery.hoverIntent module provides a helper method to run some code after an element was hovered for a minimum period of time.It does this by delaying your callback, such that very brief of accidental hovers don't cause a potentially "unintended" visual effect.This module is now deprecated (T311194).

There are two migration paths:

1. Use the built-in jQueryon() function instead (with eventsmouseenter andmouseleave), or
2. Re-create a similar effect usingsetTimeout.

Firstly, consider whether you still need the hoverIntent logic.When we introduced hoverIntent in 2010 (withMediaWiki 1.16), there are a number of notable differences compared to today.Mobile was much less significant for gadgets and user scripts, the design and behaviour expectations were different, and performance was balanced based on different trade-offs between CPU and network cost than today.Try converting to the built-inon() and interact with your gadget.

Documentation:

• https://api.jquery.com/on/

var$btn=$('.tpl-mybutton');// Old code (deprecated)$btn.hoverIntent(function(){$btn.addClass('tpl-my-button--active');},function(){$btn.removeClass('tpl-my-button--active');});// Old code (deprecated)$btn.hoverIntent({interval:300,over:function(){$btn.addClass('tpl-my-button--active');},out:function(){$btn.removeClass('tpl-my-button--active');}});// New code, with on()$btn.on('mouseenter',function(){$btn.addClass('tpl-my-button--active');}).on('mouseleave',function(){$btn.removeClass('tpl-my-button--active');});

Does it get better without the delay?If you prefer to keep the previous behaviour, you can create a similar delaying effect with asetTimeout call and two local varables:

varpending,done;$btn.on('mouseenter',function(){if(pending){return;}pending=setTimeout(function(){$btn.addClass('tpl-mybutton--active');done=true;},300);// delay}).on('mouseleave',function(){if(done){$btn.removeClass('tpl-mybutton--active');}clearTimeout(pending);pending=done=null;});

To compare the examples side-by-side refer tohttps://codepen.io/Krinkle/pen/VwGWgqN.

The "Publish changes" button is styled with OOUI since April 2017 (T111088, MediaWiki 1.39). This means the button label is bold by default. The following CSS can be safely removed. This button is sometimes labelled "Save changes" ($wgEditSubmitButtonLabelPublish).

#wpSave{font-weight:bold;}

Thejquery.jStorage module was deprecated in 2016 (MediaWiki 1.28).It has been removed in 2021 (MediaWiki 1.38).Use mw.storage from themediawiki.storage module instead (T143034).See also:mw.storage

// Old (deprecated)$.jStorage.set('mygadget-example',simple);// simple = 'Hello'$.jStorage.set('mygadget-example',object);// object = { sub: 'Hello' }simple=$.jStorage.get('mygadget-example');object=$.jStorage.get('mygadget-example');// New (replacement)mw.storage.set('mygadget-example',simple);// simple = 'Hello'mw.storage.setObject('mygadget-example',object);// object = { sub: 'Hello' }simple=mw.storage.get('mygadget-example');object=mw.storage.getObject('mygadget-example')

Gadgets could always have multiple files, but these were simply merged and executed as one script.MediaWiki 1.33 introduced the "Package files" feature, which allows for a more modular JavaScript design, with therequire() function andmodule.exports pattern to refer to additional files.Additionally, this allows you to include data from JSON files.This feature was limited to modules in MediaWiki core and extensions.

Since MediaWiki 1.38 this feature is also supported in ResourceLoaderWikiModule, andthe Gadgets extension was updated to make use of this through a new definition option called "package".

Administrators (eg.Interface administrator on WMF wikis) should take care when writing or reviewing JavaScript code that creates HTML based on text from JSON pages, to escape these to avoid security problems.

For example:

* mygadget[ResourceLoader|package]|mygadget-main.js|mygadget-Foo.js|mygadget-data.json|mygadget.css

Where MediaWiki:Gadget-mygadget-Foo.js exports:

functionFoo(config){// ...}Foo.prototype.format=function(){// ...};module.exports=Foo;

and MediaWiki:Gadget-mygadget-data.json:

{"setting":["value1","value2"],"flag":true}

FromMediaWiki:Gadget-mygadget-main.js you can then use:

varFoo=require('./mygadget-Foo.js');// class Foovarflag=require('./mygadget-data.json').flag;// true

Gadgets may also usemodule.exports in the main file to define a public interface that can be accessed by other gadgets withrequire( 'ext.gadget.mygadget' ), just like any other ResourceLoader module.

jQuery was upgraded to version 3 in MediaWiki 1.29 (released in 2017).In jQuery 3.0, several deprecated features were removed by upstream.We temporarily added these back through the jQuery Migrate layer to allow for a gradual transition (T280944).

In the developer console, you may find warnings like the following:

JQMIGRATE: jQuery.fn.size() is deprecated and removed; use the .length property.

JQMIGRATE: Attribute selector with '#' must be quoted

You may also find warnings that only say that something "is deprecated" without "and removed", such as:

JQMIGRATE: jQuery.fn.bind() is deprecated

Warnings that only say "deprecated" are for features thatwill continue to work even after the jQuery 3 migration layer is removed.

To understand how to update your code, use the following manuals:

• jQuery Migrate 3 warnings reference
• jQuery 3.0 Upgrade Guide
• jQuery 3.5 Upgrade Guide

The following three issues may be difficult to find and have some extra tips:

• HTML tags must be properly nested: This means you have used an invalid shortcut like<div/><p/>. In older jQuery versions, this invalid HTML was automatically corrected to <div>, followed by <p>. In jQuery 3 the browser standard behaviour is followed, which means this becomes a <p> inside a <div> like<div><p>..</p></div>. To preserve the old behaviour, explicitly open and close your HTML. Like<div> </div> <p> </p>.
• Cross-domain AJAX request with JSON-P: If you may cross-domain requests with$.ajax() or$.get() to APIs that returns executable JSON-P scripts (instead of plain JSON), then you must add the{ dataType: "script" } option. In previous versions, jQuery would guess between secure JSON and insecure JSON-P scripts.
• Calling .load() as event method: It is no longer possible to call$img.load(function). Use$img.on("load", function) instead.

As site administrator running MediaWiki 1.35.3 or later, you can choose to turn off migrate layer today already by setting$wgIncludejQueryMigrate tofalse.Turning off the migration layer improves page load performance, and helps you to verify whether your extensions and gadgets are ready for the upgrade.For example, if you have old code still using methods that were removed in jQuery 3, this may fail as follows.

Uncaught TypeError: $elem.size is not a function.

In MediaWiki 1.37, the migration layer will be off by default.A site administrator may temporarily turn it back on until problems like the above are resolved.

In MediaWiki 1.38, the migration layer will be permanently removed.

This version is not supported.

Theuser.tokens module has been merged into theuser.options module bundle.The old module name is now an alias and has been deprecated in MediaWiki 1.35.It will be removed in MediaWiki 1.36 sometime later in 2020. –T235457

To remain compatible, update dependency lists or loader statements from "user.tokens" to "user.options".

Themediawiki.notify module has been merged into the MediaWiki base environment.This module was responsible for providing themw.notify() function, which in turn lazy-loads the largermediawiki.notification module. –T233676

To remain compatible, simply remove "mediawiki.notify" from any dependency lists or loader statements.

jQuery UI has been deprecated for years, but remains available due to slow switching to alternatives.As a part ofon-going efforts to reduce bandwidth cost, the 27 deprecated jQuery UI modules have been collapsed into a single, still-deprecated mega-module (Gerrit,T219604).

To remain compatible, update dependency lists and loader statements from "jquery.ui.*" to "jquery.ui".

Thejquery.accessKeyLabel plugin has been available throughmediawiki.util since 2014 (MediaWiki 1.24).

Depending on it directly is no longer supported as of MediaWiki 1.34Update dependency lists and loader statements from "jquery.accessKeyLabel" to "mediawiki.util" to remain compatible.

Themediawiki.RegExp module has been available throughmediawiki.util since 2015 (MediaWiki 1.25). –T218339

Depending on it directly is no longer supported as of MediaWiki 1.34.Update dependency lists and loader statements from "mediawiki.RegExp" to "mediawiki.util" to remain compatible.

Themw.RegExp.escape() function has also been deprecated (although kept as alias, shipping with "mediawiki.util").Replace usage withmw.util.escapeRegExp().

Thejquery.tabIndex module existed to help compute a low or high tab index on focusable elements on a page.In most cases this code was redundant.Lines of code involvingfirstTabIndex() orlastTabIndex() are often best removed entirely.The module is deprecated in MediaWiki 1.34.

// Simply remove$thing.attr('tabindex',$(document).lastTabIndex()+1);

If the effect of this code is still wanted, it can be achieved in a simpler way without this JavaScript plugin.For example, to set a low tabindex, usetabindex="0".

// Remove$thing.attr('tabindex',$(document).firstTabIndex());// Add$thing.attr('tabindex','0');

Or, to set a high tabindex, usetabindex="999" instead, like so:

// Remove$thing.attr('tabindex',$(document).lastTabIndex()+1);// Add$thing.attr('tabindex','999');

If you do need the exact behaviour of the originallastTabIndex function, use the following:

// Remove$thing.attr('tabindex',$(document).lastTabIndex()+1);// AddvarlastIndex=Math.max.apply(null,$.map($('[tabindex]'),function(el){return+el.tabIndex;}));$thing.attr('tabindex',lastIndex+1);

TheeditToken key ofmw.user.tokens was deprecated in 2016 (MediaWiki 1.26).It has been removed in 2019 (MediaWiki 1.34). –T233442

ThecsrfToken key should be used instead. For example, changemw.user.tokens.get('editToken') tomw.user.tokens.get('csrfToken').

Note: Themw.Api class has not changed. Code likemw.Api.getToken('edit') will continue to work and should not be changed.

All submodulesmediawiki.api.* have been merged into the main modulemediawiki.api, so you only have to require the main module, and requiring submodules emits deprecation warnings. These submodules were kept as deprecated aliases tomediawiki.api, and removed in MediaWiki 1.33.

Methodmw.util.wikiGetlink(), which was deprecated since MediaWiki 1.23, has been removed.Usemw.util.getUrl() instead.

ThewgEnableAPI andwgEnableWriteAPI keys of mw.config are deprecated as of MediaWiki 1.32, and will be removed in MediaWiki 1.35 (change).

The value of these configuration keys is alwaystrue.Any check for them in JavaScript code is redundant and can be safely removed.

With this version, we have stopped JavaScript support for IE10.SeeCompatibility for details.

Deprecated in MediaWiki 1.29 (change), removed in MediaWiki 1.31.

The shim for the native placeholder attribute became obsolete as allsupported browsers for JavaScript support this natively.Simply remove the call to.placeholder().

The functionality was originally provided by a module calledjquery.mwPrototypes in MediaWiki 1.17 (r76320). This was renamed tojquery.mwExtension in MediaWiki 1.19 (r94227).

The module was deprecated in MediaWiki 1.26, and removed in MediaWiki 1.30.

• $.trimLeft,$.trimRight: These have native JavaScript methods available now.
• $.ucFirst: No replacement, rarely used. Simple enough to do in plain JavaScript asstr[0].toUpperCase + str.slice(1).
• $.escapeRE: Moved tomediawiki.RegExp; latermoved tomediawiki.util.
• $.isDomElement: No replacement, rarely used. Use duck-type checks like!!obj.nodeType instead.
• $.compareArray, $.compareObject, $.isEmpty: No replacement, rarely used.

JavaScript functions and variables part ofwikibits.js that had been deprecated since MediaWiki 1.17 or 1.18 have been removed:

User-Agent variables:is_gecko, is_chrome_mac, is_chrome, webkit_version, is_safari_win, is_safari, webkit_match, is_ff2, ff2_bugs, is_ff2_win, is_ff2_x11, opera95_bugs, opera7_bugs, opera6_bugs, is_opera_95, is_opera_preseven, is_opera, ie6_bugs, clientPC.

DOM manipulation:changeText, killEvt, addHandler, hookEvent, addClickHandler, removeHandler, getElementsByClassName, getInnerText.

Utilities:setupCheckboxShiftClick, addCheckboxClickHandlers, mwEditButtons, mwCustomEditButtons, injectSpinner, removeSpinner, escapeQuotes, escapeQuotesHTML, jsMsg, addPortletLink, appendCSS, tooltipAccessKeyPrefix, tooltipAccessKeyRegexp, updateTooltipAccessKeys.

Below is a table containing migration information for the wikibits functionality. Many of the replacements are part of themediawiki.util module, whichis not loaded by default. Please declare your dependency on this module if you refer tomw.util, as described inthe development guide.

$(function(){/* place code here to be executed after the page is loaded */});// or:functionLoadMyApp(){/* place code here to be executed after the page is loaded */}$(LoadMyApp);

/** * @param e {jQuery.Event} Cross-browser compatible/normalized event object */$('#mw-fooBar').click(function(e){e.preventDefault();/* do something else */});

// Full script urlmw.loader.load('https://www.mediawiki.org/w/index.php?title=MediaWiki:Gadget-UTCLiveClock.js&action=raw&ctype=text/javascript');// Local script urlmw.loader.load('/w/index.php?title=MediaWiki:Gadget-HotCat.js&action=raw&ctype=text/javascript');// Full stylesheet urlmw.loader.load('https://www.mediawiki.org/w/index.php?title=User:Example/custom-foo.css&action=raw&ctype=text/css','text/css');// Local stylesheetmw.loader.load('/w/index.php?title=User:Example/custom-foo.css&action=raw&ctype=text/css','text/css');

// Attach multiple events to an element and attach an anonymous function$('#fooBar').on('mouseenter mouseleave',function(){alert('#fooBar is moused!');});// Attach multiple events with different handlers to a single element$('#fooBar').on({click:function(){// do something on click},mouseenter:function(){// do something on mouseenter}});// Attach a handler to the click events of an earlier defined DOM element$(myElement).click(myFunction);

mw.loader.load('//meta.wikimedia.org/w/index.php?title=User:Krinkle/insertVectorButtons.js'+'&action=raw&ctype=text/javascript');functionkCustomMainInsertButton_config(){// {{Welcome}} ~~~~kCustomMainInsertButton('welcome',// Id'//commons.wikimedia.org/w/thumb.php?f=Nuvola_apps_edu_languages.svg&w=22',// File'Welcome',// tooltip'{\{Welcome}\}\~\~\~\~',// Open tag'',// Close tag''// sampleText);// {{subst:Test2}} ~~~~kCustomMainInsertButton('test2',// Id'//commons.wikimedia.org/w/thumb.php?f=Nuvola_apps_important.svg&w=22',// File'Test2',// tooltip'{\{subst:test2|',// Open tag'}\}\~\~\~\~',// Close tag''// sample text);}

// myElement.accessKey = 'x';// myElement.title = 'Example [x]';mw.loader.using('jquery.accessKeyLabel').then(function(){$(myElement).updateTooltipAccessKeys();});

// Set text of an earlier defined element$(myElement).text('New text!');// Set text for multiple elements at once$('.mw-userlink').text('Mr. Foobar');// Get the text of an element$(myElement).text();

jQuery(..).injectSpinner('some-id');jQuery.removeSpinner('some-id');

// Get everything with a classname$('.myclass');// Get all of element X (ie. table) with a classname$('table.wikitable');// Get all of something within another element$(myDomElement).find('.myclass');$(myDomElement).find('> .myclass');// only direct children// Get all class-elements that are direct children of an element$('#someElement .myclass');$('#someElement > .myclass');// only direct children

Since early 2011, gadgets with styles (both "only styles" and "styles and scripts") had their styles loaded twice.T42284 andchange 308096 fix this bug.

This bug was addressed by adding support in the Gadgets extension for the ResourceLoader "type" feature. This allows gadget developers to configure how the module should be loaded

• type=styles: Load module styles via<linkrel="stylesheet">, and completely omits loading any JavaScript files. (Loads styles early, applies styles before skin and page are ready, also works when JavaScript is disabled.)
• type=general: Load module scripts and/or styles viamw.loader.load(). (Applies styles after the skin and page are ready, right before JS execution, has better caching.)

Gadgets with only styles, internally gettype=styles by default. Gadgets with only scripts default totype=general.

Before MediaWiki 1.30, Gadgets with both scriptsand styles defaulted to loading both ways, thus loading the styles portion twice. Before that, we sent a warning in the browser console in a transition period that asked developers to set the desired type. After the transition period, we madetype=general the default for gadgets that have both scripts and styles.

To load styles through thetype=styles system, while also loading JavaScript files, two separate gadget definitions need to be specified.

If you see this warning, that means your gadget contains both scripts and styles. Here are two ways to fix the warning:

1. If the styles in your gadget are there to provide styling for things created by the gadget, add "type=general" to your gadget definition ("MediaWiki:Gadgets-definition").
2. Or – If the styles in your gadget are there to provide styling for things that are part of the skin or on the page, then these styles should not be together with the scripts in the same gadget. Convert the gadget to two separate gadgets. One gadget that is styles-only, and the other with the scripts. If the scripts gadget also has its own styles, then also set "type=general" on the original gadget (per point 1). If you want to keep presenting the modules as one gadget on the Preferences page, use#Gadget peers.

As you can see, in most cases the solution is "type=general." And in the future, this will become the default and we will not load styles twice. Right now, loading twice remains the default for compatibility with older gadgets covered by point 2 above. Changing these mixed gadgets to type=general now would cause some styles to load too late and cause a "flash of unstyled content".

For a long time, gadget authors have been interested in being able to provide a visual enhancement for all pages and also accompanying some scripting logic to apply related changes to interactive interfaces created by other modules. This requires the gadget to have both scripts and styles, but most of the styles are not required by the scripts – rather, the styles should apply directly to the page without waiting for JavaScript. So far this required either creating two gadgets (and requiring users to enable both), or creating a single gadget with the downside of the styles applying slightly after the page loads.

To accommodate the use case of a single gadget providing both page styles (which don't depend on JavaScript) and JavaScript code with its own styles, a new setting was introduced:peers. This is similar todependencies, except that where dependencies load before the main module (not before the page itself), peers will allow one to reference a separate gadget module that will be loaded regardless of whether JavaScript is enabled.

For example:

* example [ResourceLoader|dependencies=mediawiki.util|peers=example-pagestyles] | example.js | example.css* example-pagestyles [hidden] | example-pagestyles.css

This will register a gadget named "Example" in the preferences which, if enabled, will load example-pagestyles before the page renders. And, once JavaScript is available, the example module will also be loaded with its own dependencies, styles and scripts.

With this version, we have stopped JavaScript support for IE9 and other browsers that do not supportES5. SeeCompatibility for details.

The2006 wikitext editor was superseded byWikiEditor, which has been the default since 2010. The classic toolbar was loaded if you disabled the "Enable enhanced editing toolbar" user preference. The classic toolbar is now deprecated with console warnings as of April 2017 (T30856) in MediaWiki 1.29 (it was removed in October 2018 in MediaWiki 1.32). This means themediawiki.toolbar module no longer exists.

If you have code that added toolbar buttons for both editors, you can now safely remove all code formediawiki.toolbar. If you still have code formwCustomEditButtons (from before 2011, see#Toolbar), you can safely remove that too. To learn how to add buttons to the WikiEditor toolbar, refer toExtension:WikiEditor/Toolbar customization.

// Classic toolbarif(['edit','submit'].includes(mw.config.get('wgAction'))){mw.loader.using(['user.options','mediawiki.toolbar']).then(function(){if(!mw.user.options.get('usebetatoolbar')){mw.toolbar.addButtons(/* ... */);}});}// WikiEditor toolbarmw.hook('wikiEditor.toolbarReady').add(function($textarea){$textarea.wikiEditor('addToToolbar',{/* ... */});});

This version is not supported.

The$wgPreloadJavaScriptMwUtil option was removed. This option allowed third-party MediaWiki administrators to re-enable the unconditional preload ofmediawiki.util by default for all users (for backwards compatibility). It was disabled by default since MediaWiki 1.26, and has been disabled on Wikimedia wikis since 2014. Extensions, skins, gadgets and scripts that use themediawiki.util module must express a dependency on it.

The internal Wikimedia domain "bits.wikimedia.org" was deprecated sometime mid-2015. The following common paths should be migrated to avoid breakage once the domain is decommissioned (T107430).

• bits.wikimedia.org/:domain/load.php →https://:domain/w/load.php . Moved back to local domains, alongside/w/index.php and others.
• bits.wikimedia.org/static-current/* →https://:domain/static/current/: Moved to local domain, sharing a hostname-agonistic Varnish cache.
  • bits.wikimedia.org/skins/* →https://:domain/static/current/skins
• bits.wikimedia.org/static-1.xx-wmf.X/* →https://:domain/w/*: Specific versions can now be accessed through the regular script path. Wikimedia's multiversion entry point automatically serves the file from to the wikis' current MediaWiki version. (T99096)
  • bits.wikimedia.org/static-1.xx/skins/*→https://:domain/w/skins/*
  • bits.wikimedia.org/static-1.xx/extensions/*→https://:domain/w/extensions/*
  • bits.wikimedia.org/static-1.xx/resources/*→https://:domain/w/resources/*

Following the deactivation of JavaScript in Internet Explorer 6 and 7 in MediaWiki 1.24, JavaScript has been deactivated in Internet Explorer 8. SeeCompatibility for details.

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 changed 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 thetalk page, viaIRC, or on thewikitech-l mailing list. (T75810)

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, andnot 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 aswindow properties. For example:

// This is a local variablevarfoo;// This is a local functionfunctionbar(){..}// This is a global variable (accessible from other scripts, and from legacy event handlers, e.g.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.

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

Themw-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. [[phab:T28204]] */div.mw-geshidiv,div.mw-geshidivpre,span.mw-geshi,pre.source-css,pre.source-javascript,pre.source-lua{font-family:monospace,Courier!important;}

To inject JavaScript inline, useResourceLoader::makeInlineScript() to wrap the JavaScript code in an anonymous function that can access MediaWiki-related objects properly, andOutputPage::addScript() to add the results to the page source for execution.

For example:

$outputPage=RequestContext::getMain()->getOutput();$js='alert("hello world");';$wrappedJS=ResourceLoader::makeInlineScript($js);$outputPage->addScript($wrappedScript);

Thejquery.delayedBind JavaScript module, deprecated in MediaWiki 1.23, has been removed. Seephab:rMW8f2ebcbf6769.

Browser support for Internet Explorer 6 and 7 changed from Grade A to Grade C. This means JavaScript is no longer executed in these browser versions. SeeCompatibility for details.

This method has been deprecated in favour ofmw.notify.

The jsMessage message was designed to be a drop-in replacement fully compatible with the legacy wikibitsjsMsg function (deprecated since 1.17, removed in 1.29). The 2012 notification system on the other hand was designed with developer usability and security in mind.

For most cases, the new method is just as easy to use as the old one, and requires only a the same single parameter that represents the message. For example, with plain text:

// Deprecated (dependencies: mediawiki.util)varmsgText='Hello world';mw.util.jsMessage(msgText);// New, as of 2012 (dependencies: mediawiki.notify)varmsgText='Hello world';mw.notify(msgText);

And another example, with a DOM element, or a jQuery object:

// Deprecated (dependencies: mediawiki.util)var$myWidget=ExampleWidget.create({having:'2-buttons',toggle:'#sidebar'});mw.util.jsMessage($myWidget);// New, as of 2012 (dependencies: mediawiki.notify)var$myWidget=ExampleWidget.create({having:'2-buttons',toggle:'#sidebar'});mw.notify($myWidget);

If you're currently using raw HTML withmw.util.jsMessage(), the simplest way to migrate is to do what jsMessage used to do internally for you, which is to parse the HTML and place the node(s) in a jQuery object, as follows:

// Deprecated (dependencies: mediawiki.util)varmsgHtml='<form><button>Click me</button></form>';mw.util.jsMessage(msgHtml);// New, as of 2012 (dependencies: mediawiki.notify)varmsgHtml='<form><button>Click me</button></form>';var$msg=$($.parseHTML(msgHtml));mw.notify($msg);

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 onptwiki andsrwiki). 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).

As ofMediaWiki 1.19 a few bugs have been fixed with thewikitable class (seephab:T32485 andphab:T35434 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 foundhere. 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.

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.*/#fileimg{background:url("//upload.wikimedia.org/wikipedia/commons/5/5d/Checker-16x16.png")repeat;}

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

This change only applies to Wikimedia Foundation wikis.

As ofMediaWiki 1.18 there is native support for protocol-relative wiki installations. This means that a wiki could be accessible from bothhttp://example.org/ andhttps://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<imgsrc="//meta.wikimedia.org"/> when on "https://example.org" will be automatically expanded by the browser tohttps://meta.wikimedia.org./ This is much like (for example)<imgsrc="foobar.jpg"/> or<imgsrc="/w/foobar.jpg"/>, 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:

if(wgServer==='http://en.wikipedia.org'){// Doesn't work anymore!}

because wgServer is now "//en.wikipedia.org". 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!}

Alternatively, you can usewgServerName which is without the protocol or port:

if(mw.config.get('wgServerName')==='en.wikipedia.org'){// English Wikipedia!}

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 onSpecial:Preferences#mw-prefsection-gadgets.

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

See alsoExtension:Gadgets#Options.

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.

varfoo='bar';varapiUrl='//www.mediawiki.org/w/api.php?foo='+encodeURIComponent(foo)+'&baz=quux';$.ajax({url:apiUrl,...});

Instead use something like one of the following:

// Behold, mw.util.wikiScript!varfoo='bar';varapiUrl=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 :)varfoo='bar';varapiUrl=mw.util.wikiScript('api')+'?'+$.param({foo:foo,baz:'quux'});$.ajax({url:apiUrl,...});

You can even use thedata 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'},...});

See alsojQuery

As of1.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 ajax.googleapis.com), 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.

Global identifier "$j" has been deprecated. UsejQuery or$ instead.

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 useMediaWiki:Mainpage-nstab or refer toSnippets/Main Page tab for a script that will work in both Vector and Monobook for 1.17.

The legacy functionaddPortletLink has been rewritten asmw.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' (seedocumentation for details).

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

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

The legacy arraymwCustomEditButtons has been refactored into themw.toolbar library. The global array still exists in wikibits to avoid fatal errors but is no longer used due to race conditions. Note that (unlike mwCustomEditButtons) themw.toolbar.addButton API works also after the toolbar is visible. You can add late entries.

Note that mw.toolbar, just like the old mwCustomEditButtons array, is only for the classic toolbar. The current default wikitext editor is WikiEditor, which has its own API. SeeExtension:WikiEditor/Toolbar customization for more information.

The legacy functions such assajax_init_object have been deprecated. Instead,mw.Api from themediawiki.api module, orjQuery.ajax.

• mediawiki.api documentation
• jQuery.ajax documentation

Migration guide:

$('#mybox').load('/wiki/Template:ResourceLoader_navigation #bodyContent');$.get(mw.config.get('wgScript'),{title:'ResourceLoader',action:'raw'},function(data){/* Call was successful do something with "data" */});$.getJSON(mw.util.wikiScript('api'),{format:'json',action:'query',titles:'Main Page',prop:'info'},function(obj){/* API call was successful do something with obj */});

$.get(mw.util.wikiScript(),{action:'ajax',rs:'SomeExtensionFunction',rsargs:[arg1,arg2,arg3]// becomes &rsargs[]=arg1&rsargs[]=arg2...});

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

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

New inMediaWiki 1.17 is a user groups module that can automatically load scripts and styles from the MediaWiki namespace for a particular user group. For example, if the wiki has MediaWiki:Group-sysop.js, this script is automatically loaded for all users in that group.

This should replace customisations you may have for importing a page for sysops with importScript inside Common.js.

// Old - MediaWiki:Common.jsif(mw.config.get('wgUserGroups').includes('sysop')){importScript('MediaWiki:Sysop.js');// RemoveimportScript('MediaWiki:Sysop-something.js');// RemoveimportScript('MediaWiki:Shared-something.js');// Move to Group-sysop.js}// Old - MediaWiki:Sysop.js -> MediaWiki:Group-sysop.jsconsole.log('Hello sysop');// Old - MediaWiki:Sysop-something.js -> MediaWiki:Group-sysop.jsconsole.log('Hello sysop something');// New - MediaWiki:Common.js// (nothing here)// New - MediaWiki:Group-sysop.jsconsole.log('Hello sysop');console.log('Hello sysop something');importScript('MediaWiki:Shared-something.js');

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

importStylesheetURI(mw.config.get('wgExtensionAssetsPath')+'/Example/css/jquery-ui-1.7.2.css');$.getScript(mw.config.get('wgExtensionAssetsPath')+'/Example/js/jui.combined.min.js',function(){MyTool.init();});

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);});

When a script depends on another module, such asoojs ormediawiki.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. On-site modules, like gadgets, have a registry to declare these dependencies. For user scripts, one has to wrap code withmw.loader.using().

While this has been required since 2011, many scripts have continued to work without declaring their dependencies. Scripts may have worked before by accident as long as at least one user script (that used the same methods) did declare their dependencies and happened to load earlier.

With MediaWiki 1.19, page view performance has been optimised to use fewer modules by default. This makes it increasingly more important to declare the dependencies. Otherwise, your script may fail because any of the 1000+ modules you might refer to in your code would not be loaded yet. Loading everything all the time would be much too slow.

The only two base modules that are always present aremediawiki andjquery.

Usemw.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','oojs','jquery.cookie'],function(){/* some other script that uses $.cookie *//* some other script that uses mw.util and OO.EventEmitter() */});

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 themw object. Configuration is managed through an instance ofmw.Map inmw.config. It is also supporting the behaviour of more script executing in their own local/private scope as opposed to the global scope.

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

// One variableif(mw.config.get('wgCanonicalSpecialPageName')==='Search'){// Example for Special:Search}if(mw.config.get('wgGlobalGroups',[]).indexOf('global-rollbacker')!==-1){// Example for users in the global group "global-rollbacker".}// Multiple variablesvarconf=mw.config.get(['wgScript','wgAction']);if(conf.wgAction==='edit'){console.log('Example when editing a page',config.wgScript);}

More info:ResourceLoader/Default modules#mw.config

CheckJavaScript deprecation overview for "addOnloadHook". Use$( function ); instead, or$( fn ); for short.

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.

Links to redirects now appear italicized by default onSpecial:AllPages,Special:PrefixIndex,Special:Watchlist/edit and in category listings. Overrides like the following are redundant and can be safely removed.

.allpagesredirect,.redirect-in-category,.watchlistredir{font-style:italic;}

Perphab:T22276,input#wpSummary'swidth is now set in Vector as well (instead of just Monobook).

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 viaSpecial: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.

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

The old table sorter inwikibits.js was removed in favour ofjquery.tablesorter.

Variables such asts_alternate_row_colors, and functions likets_parseFloat andts_dateToSortKey no longer exist.

As of 2008, theimportScript function commonly defined by communities locally became a built-in part of MediaWiki ("wikibits.js"). Wikis that previously defined this function themselves, are able to remove that. The new built-in function is automatically used. The same also applies toimportStylesheet,importStylesheetURI andimportScriptURI.

Note thatimportStylesheetURI andimportScriptURI were subsequently deprecated in 2011 with MediaWiki 1.17, and disabled on mobile sites likehttps://en.m.wikipedia.org/. Usemw.loader.load instead.

As of 2008, the functionaddPortletLink is part of MediaWiki. Many wikis and gadgets have created functions likeaddLink,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 wasdeprecated in 2012 and moved to the mediawiki.util module asmw.util.addPortletLink()

As of 2008, the functionappendCSS 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 wasdeprecated in 2012 and moved to the mediawiki.util module asmw.util.addCSS()

This bugfix is obsolete as MediaWiki does this correctly by default. (example)

varhtmlE=document.documentElement;htmlE.setAttribute('lang',mw.config.get('wgUserLanguage'));

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

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

Alternative names for this feature, that were in popular use on Wikimedia Foundation wikis, include:.plainlinksneverexpand and.nounderlines. Replace any usage on wiki pages "plainlinks", and afterward these alternate styles may also be removed. For example, use search and query forinsource:plainlinksneverexpand.

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

Icons for protocols likeHTTP,IRC, etc. and file types likePDF are now supported by MediaWiki.

Scripts liketa['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 placeholderta = new Object(); was removed fromwikibits.js. Code trying to add members to it will likely emit an exception.

The below are additional advices not related to a particular MediaWiki release, but rather general best practices.

Do not use this method, as it can cause a page to become visually blanked. Instead, usejQuery to modify the document (adding elements, changing things etc.). To load external resources, use the import/loader functions instead.

Example: replace

document.write('<script type="text/javascript" src="'+'https://commons.wikimedia.org/w/index.php?title=MediaWiki:Gadget-HotCat.js'+'&action=raw&ctype=text/javascript"></script>');

with

mw.loader.load('https://commons.wikimedia.org/w/index.php?title=MediaWiki:Gadget-HotCat.js&action=raw&ctype=text/javascript');

Binding input events to callback functions can be hard to do in cross-browser compatible way for all browsers that MediaWiki supports.

It is recommended that you usejQuery for event binding. See theJavaScript deprecation overview on "addHandler" for examples.

When working with regular expressions, user input and/or urls must always be encoded or escaped.

• Regexes:mw.util.escapeRegExp (provided bymediawiki.util module).
• HTML:mw.html.escape (provided by default).
• URL:mw.util.wikiUrlencode for page titles,mw.util.rawurlencode for other values (provided bymediawiki.util module).

Do not extend native JavaScript constructors with non-standard methods (e.g.String.prototype.foobar,Regex.myMethod,Array.prototype.inArray etc.).

Such non-standard methods should be defined in your own namespace instead, for exampleMyThing.foobar, or using module.exports/require.

Before 2015, it was common for user scripts and gadgets to define fallback method for standard features of newer JavaScript engines. This is no longer needed in most cases, because theBase environment already ensures ES5 or later. This means ES5 methods such asString#trim andArray#forEach can be used directly.

Before MediaWiki 1.32, thees5-shim module was bundled with MediaWiki to automatically define polyfills if needed. It could be used like so:

// This using() command will immediately execute as "then()" in modern browsers.// In older browsers, it loads es5-shim.js first, and then executes your "then()".mw.loader.using('es5-shim').then(function(){console.log('    bar    '.trim());// "bar"['a','b'].forEach(function(val){/* .. */});});

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.17mw.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:

functiongetURLParamValue(p,url){returnmw.util.getParamValue(p,url);}

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<strongclass="my-element"> will now begreen.

Use Meta.wikimedia.org or MediaWiki.org to store Gadgets' code, then import it into various local mediawiki.

Interface administrators: To update a gadget on your wiki:

• CheckMediaWiki:Gadgets-definition on your wiki and find the gadget in question.
• The part after the pipe (|) is the scriptname (eg. "UTCLiveClock.js").
• Go toMediaWiki: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 outLiveClock on Simple Wikipedia.

Below is a list of gadgets that are :

• centrally stored
• compatible with 1.17
• work in Monobook and Vector
• can be loaded into any mediawiki, from WMF or external.

• UTCLiveClock

  mw.loader.load('https://www.mediawiki.org/w/index.php?title=MediaWiki:Gadget-UTCLiveClock.js&action=raw&ctype=text/javascript');

• contribsrange

  mw.loader.load('https://www.mediawiki.org/w/index.php?title=MediaWiki:Gadget-contribsrange.js&action=raw&ctype=text/javascript');

• modrollback

  mw.loader.load('https://www.mediawiki.org/w/index.php?title=MediaWiki:Gadget-modrollback.js&action=raw&ctype=text/javascript');

• ShortDiff

  mw.loader.load('https://meta.wikimedia.org/w/index.php?title=MediaWiki:Gadget-ShortDiff.js&action=raw&ctype=text/javascript');

• lastdiff CheckSnippets/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 https://commons.wikimedia.org/wiki/Help:Gadget-HotCat */mw.loader.load('https://commons.wikimedia.org/w/index.php?title=MediaWiki:Gadget-HotCat.js&action=raw&ctype=text/javascript');

• WikiMiniAtlas

/** * WikiMiniAtlas is a popup click and drag world map. * See [[meta:WikiMiniAtlas]] for more information. * Maintainers: [[w:User:Dschwen]] */mw.loader.load('https://meta.wikimedia.org/w/index.php?title=MediaWiki:Wikiminiatlas.js&action=raw&ctype=text/javascript');

• Navigation Popups (MediaWiki:Gadget-popups.js and MediaWiki:Gadget-popups.css respectively)

mw.loader.load('https://en.wikipedia.org/w/index.php?title=MediaWiki:Gadget-popups.js&action=raw&ctype=text/javascript');

@importurl('https://en.wikipedia.org/w/index.php?title=MediaWiki:Gadget-navpop.css&action=raw&ctype=text/css');

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

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 since17th of September, 2012). You should update code to useapi.php, JSON format and jQuery.ajax immediately. Use the ResourceLoader modules that do this for you to simplify interactng with the API, includingmediawiki.api.

A temporary fix for problems with DOM parsing of XML retrieved via AJAX: For example the methodgetElementById("foobar") on a XML object from Mozilla's DOMParser stopped to work as before. Replacing thegetElementById 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.

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

• w:de:Wikipedia:Technik/Skin/JS/Obsolet

• ResourceLoader