ResourceLoader/Core modules

This page intends to list, document, explain and give examples for all the libraries, plugins and scripts present in MediaWiki's [//gerrit.wikimedia.org/r/gitweb?p=mediawiki/core.git;a=tree;f=resources;hb=HEAD /resources] by default as of the current SVN HEAD.

The order of the modules should be kept similar to [//gerrit.wikimedia.org/r/gitweb?p=mediawiki/core.git;a=blob;f=resources/Resources.php;hb=HEAD their definition in Resources.php]. And the order of the headings within the modules either by order within the script file or by alphabet (whichever makes sense)

This may or may not correspond to the state in MediaWiki 1.17.

[//gerrit.wikimedia.org/r/gitweb?p=mediawiki/core.git;a=blob;f=resources/mediawiki/mediawiki.js;hb=HEAD mediaWiki]
This is the main JavaScript library. Defined in. Alias  is available everywhere and should be used.

[//gerrit.wikimedia.org/r/gitweb?p=mediawiki/core.git;a=blob;f=resources/mediawiki/mediawiki.js;hb=HEAD#l398 mediaWiki.config]

 * For a complete list of configuration values in, check out Manual:Interface/JavaScript.

An instance of the Map class that is global by default for backwards compatibility (in 1.17) and contains the wgVars such as wgSiteName, wgArticleId etc.

mw.config.get( 'wgIsMainPage' )
This variable is true if the current page is an action of the wiki's main page (eg. view, history, edit etc.) and null (inexistent) other wise.

[//gerrit.wikimedia.org/r/gitweb?p=mediawiki/core.git;a=blob;f=resources/mediawiki/mediawiki.js;hb=HEAD#l1109 mediaWiki.html]

 * mw.html.escape: Escape a string for HTML. Converts special characters to HTML entities.


 * mw.html.element: Creates an HTML string, with safe escaping.

[//gerrit.wikimedia.org/r/gitweb?p=mediawiki/core.git;a=blob;f=resources/mediawiki/mediawiki.js;hb=HEAD#l244 mediaWiki.message]
Returns a new instance of Message. is a shortcut to this.


 * key: Key of the message
 * parameter_1: (optional) this argument and any later ones will be passed to the Message constructor as the parameter array (to do replaces for $1, $2 etc.)

[//gerrit.wikimedia.org/r/gitweb?p=mediawiki/core.git;a=blob;f=resources/mediawiki/mediawiki.js;hb=HEAD#l295 mediaWiki.msg]
This is a shortcut for creating an instance of Message via  and returning

[//gerrit.wikimedia.org/r/gitweb?p=mediawiki/core.git;a=blob;f=resources/mediawiki/mediawiki.js;hb=HEAD#l315 mediaWiki.loader]
"" Note: mediaWiki.loader do not accept relative urls (see bug 34036) and differently from jQuery.getScript, it doesn't support callback functions (bug 25962).
 * mw.loader.addSource
 * mw.loader.getModuleNames
 * mw.loader.getState
 * mw.loader.getVersion</tt>
 * mw.loader.go</tt> No longer needed, mw.loader.load</tt> takes an array to load multiple modules in one request.
 * mw.loader.implement</tt>
 * mw.loader.load</tt> is the loader for modules and other sources. It can be called with one or more modules by name. It can also load an external script or style URI beginning with either "http://", "https://" or "//" and a mime-type in the second argument (either "text/css" or "text/javascript"). If no mime-type is provided, "text/javascript" is assumed. mw.loader.load creates an asynchronous request, so if you need to run code that depends on a module, use mw.loader.using instead.

""
 * mw.loader.register</tt>
 * mw.loader.state</tt>
 * mw.loader.using</tt> can be called with two or three arguments (dependencies, function to execute when modules are successfully loaded, function on error)
 * mw.loader.version</tt> Use mw.loader.getVersion</tt>.
 * mw.loader.work</tt>

[//gerrit.wikimedia.org/r/gitweb?p=mediawiki/core.git;a=blob;f=resources/mediawiki/mediawiki.js;hb=HEAD#l136 mediaWiki.Map]
A reusable class to store, get and set a set of variables. The core uses this for  and

When making an instance the function takes one parameter which affects whether the set will be made globally available (ie. as items of ) or local. By default this is false (not global) and will thus not not overwrite any global variables with the same name.


 * .values</tt>: An object containing all the variables. If 'global' was true during initialization, this is an alias to the  object.
 * .exists(key)</tt>: Function returns true if an entry with the key(s) exists, false otherwise
 * .get(key, fallback)</tt>: Returns the value of the key(s) or (optionally) the value of the second argument if the key does not exist (returns null if it doesn't exist and no fallback was provided)
 * .set(key, value)</tt>: Creates / Modifies one or multiple values

Examples

Address Book example

anonymous
Function returns boolean on whether the user is anonymous (true) or logged in (false).

name
Function returns the username or null if logged out.

options
Contains the preferences of the user, or the defaults when logged out. (mw.user.options</tt> is an instance of the mw.Map constructor)

sessionId
When called for the first time generates a sessionId and sets a domain-wide cookie and returns the sessionId. When it's set already (ie. after calling it, or when it was set earlier this session on another page) returns just the sessionId.

tokens
Is pre-populated with api tokens. Currently editToken and watchToken

See a live example from the [//gerrit.wikimedia.org/r/gitweb?p=mediawiki/core.git;a=blob;f=resources/mediawiki.action/mediawiki.action.watch.ajax.js;hb=HEAD&pathrev=88554#l117 mediawiki.action.watch.ajax.js] module.

[//gerrit.wikimedia.org/r/gitweb?p=mediawiki/core.git;a=blob;f=resources/mediawiki/mediawiki.log.js;hb=HEAD mediaWiki.log]
This script is loaded in debug-mode (can be enabled with debug=true in the URL) and is an alternative to calling console.log which would cause errors in browsers that don't have a console or don't have it enabled.

mw.log
Calling this either pushes the messages to console if its available and have a logging facility, or adds it to an #mw-log-console if not (the element is created on the first call) Note that different browsers and extensions may enable or disable different consoles and different logging facilities, and that they may or may not be visible even if they are used for logging purposes.

addCSS
Adds a  element to the HEAD and returns the CSSStyleSheet object.

The CSSStyleSheet object can be used to disable the css rules at any later time and re-enable them as well. This can be done through the 'disabled' attribute. When setting this to true, the rules no longer apply. When setting to false, the rules apply again.

See also W3 on CSSStyleSheet for more info.

addPortletLink
This function is ported from the legacy wikibits keeping it fully backwards compatible, with a few adjustments that support all core skins and with added support for a CSS-selector as.

Only the first three arguments are required.

In case you need to execute a custom function when the user clicks on a portlet, do not use ' ' for the href of the portlet. Instead, use the jQuery(...).click to specify the code which should be executed.

$content
A jQuery object for a page's content body regardless of the skin used. This is, for example, #bodyContent in the Vector-skin.

Here is a more advanced example involving loading in extra content with an AJAX request. Run this example on a page other than the main page.

getParamValue
This function returns the value of the specified URL parameter. By default it uses the current window's address. Optionally can be passed a custom location.

It returns  if is not present. Returns an empty string if it was an empty parameter (such as

jsMessage
This function is ported from the legacy wikibits keeping it fully backwards compatible, with a few adjustments and with added support to hide the message by calling with no arguments or when passing null.

rawurlencode
This function returns an encoded string in its raw form for use in urls.

For building query strings, you may want to use jQuery.param instead:

wikiUrlencode
This function returns an article/page name in its encoded form.

wikiGetlink
This function returns the address to a local wiki page.

wikiScript
This function returns the location of a script on the current wiki. Much like  in GlobalFunctions.php.

Parameters: <tt>str</tt> - Name of the script (eg. 'api'), defaults to 'index'.

[//gerrit.wikimedia.org/r/gitweb?p=mediawiki/core.git;a=blob;f=resources/mediawiki.api/mediawiki.api.js;hb=HEAD mediaWiki.Api]
Basic example

[//gerrit.wikimedia.org/r/gitweb?p=mediawiki/core.git;a=blob;f=resources/jquery/jquery.js;hb=HEAD jQuery]
jQuery 1.7.1 is loaded. More information about jQuery's presence in MediaWiki, see jQuery. For more about jQuery in general and all its core functions, refer to http://api.jquery.com/

[//gerrit.wikimedia.org/r/gitweb?p=mediawiki/core.git;a=blob;f=resources/jquery.ui/jquery.ui.core.js;hb=HEAD jQuery UI]
jQuery UI 1.8.17: http://jqueryui.com/demos/ The following components are included:
 * jquery.ui.accordion.js
 * jquery.ui.autocomplete.js
 * jquery.ui.button.js
 * jquery.ui.core.js
 * jquery.ui.datepicker.js
 * jquery.ui.dialog.js
 * jquery.ui.draggable.js
 * jquery.ui.droppable.js
 * jquery.ui.mouse.js
 * jquery.ui.position.js
 * jquery.ui.progressbar.js
 * jquery.ui.resizable.js
 * jquery.ui.selectable.js
 * jquery.ui.slider.js
 * jquery.ui.sortable.js
 * jquery.ui.tabs.js
 * jquery.ui.widget.js
 * i18n

[//gerrit.wikimedia.org/r/gitweb?p=mediawiki/core.git;a=blob;f=resources/jquery/jquery.async.js;hb=HEAD jQuery.async]

 * Plugin documentation

[//gerrit.wikimedia.org/r/gitweb?p=mediawiki/core.git;a=blob;f=resources/jquery/jquery.checkboxShiftClick.js;hb=HEAD jQuery.checkboxShiftClick]
This single-function plugin can be called to add this functionality to any number of checkboxes. By default (onload) it's applied to all  elements that have a type of checkbox, excluding any with a class of 'noshiftselect'. As it has a built-in prevention to avoid binding the CheckboxShiftClick twice to the same element you can simply run the line below under "Default" again at any time if you want to enable dynamically added checkboxes in the page to be shift-selectable as well. Or alternatively run it on the specific selector of choise (see second example below).

[//gerrit.wikimedia.org/r/gitweb?p=mediawiki/core.git;a=blob;f=resources/jquery/jquery.client.js;hb=HEAD jQuery.client]
A plugin that extracts information about the client's browser, layout engine and operating system. Use this instead of jQuery.browser, which is deprecated and will be removed from jQuery in the near future.

Profile
The profile function is the main function here and returns (and caches) all the information in an object in. All possible values (except for version numbers) are predefined. A typical return looks like this:

Here a few examples Check [//gerrit.wikimedia.org/r/gitweb?p=mediawiki/core.git;a=blob;f=resources/jquery/jquery.client.js;hb=HEAD jquery.client.js] for possible values of browser names, layout engines and platforms.

Test
...

[//gerrit.wikimedia.org/r/gitweb?p=mediawiki/core.git;a=blob;f=resources/jquery/jquery.collapsibleTabs.js;hb=HEAD jQuery.collapsibleTabs]
Used by the Vector extension.

[//gerrit.wikimedia.org/r/gitweb?p=mediawiki/core.git;a=blob;f=resources/jquery/jquery.colorUtil.js;hb=HEAD jQuery.colorUtil]

 * getRGB
 * colors
 * rgbToHsl
 * hslToRgb
 * getColorBrightness

[//gerrit.wikimedia.org/r/gitweb?p=mediawiki/core.git;a=blob;f=resources/jquery/jquery.cookie.js;hb=HEAD jQuery.cookie]
This plugin allows you to set, get and delete cookies.

When deleting a cookie, you must use the same path and domain used when the cookie was set.

[//gerrit.wikimedia.org/r/gitweb?p=mediawiki/core.git;a=blob;f=resources/jquery/jquery.json.js;hb=HEAD jQuery.json]
Provides JSON encoding to old browsers which do not support JSON.stringify:

[//gerrit.wikimedia.org/r/gitweb?p=mediawiki/core.git;a=blob;f=resources/jquery/jquery.makeCollapsible.js;hb=HEAD jQuery.makeCollapsible]

 * See also Manual:Collapsible elements.

Plugin makes all passed elements collapsible. It supports lots of variations such as:
 * Simple: Add " " to an element (a for example) with some content and save the page. The inner content of this element will be treated as collapsible content. Prepended to the element, before the collapsible content, is a toggle-link with a localized label (collapsible-expand, collapsible-collapse)
 * Initial state: Adding '" '" as additional class will cause the element to be initially collapsed when the page is loaded.
 * Custom label:HTML5 only Using the <tt>data-collapsetext</tt> and <tt>data-expandtext</tt> attributes one can define a custom text for the toggle labels added by the script. When added in wikitext these could populated by a localized message like:


 * Remote toggle: If you don't want the script to put the default toggle link (wether or not with a custom label) in your element, you can make one of your own. This could reside anywhere inside or outside the collapsible element. It's relationship to the collapsible element is detected by using the prefix  and   for the collapsible element and the togglelink respectively.

Example: Simple collapsible div or table

Input:

Output:

This is text is collapsible.

Example: Hide the collapsible element by default, the toggle element resides outside of it

For other live examples, see Test Wikipedia - Collapsing Testpage.

[//gerrit.wikimedia.org/r/gitweb?p=mediawiki/core.git;a=blob;f=resources/jquery/jquery.placeholder.js;hb=HEAD jQuery.placeholder]
This plugin adds support for placeholder texts in input fields for browsers that don't support the HTML5 attribute yet. If the attribute is not supported it's applied to all input elements with a 'placeholder' attribute, on-load.

It has a built-in check for browser support, but for efficiency it's best to do this check (also) wrapped around to call.

[//gerrit.wikimedia.org/r/gitweb?p=mediawiki/core.git;a=blob;f=resources/jquery/jquery.qunit.js;hb=HEAD jQuery QUnit]
Testing framework. See http://docs.jquery.com/QUnit.

[//gerrit.wikimedia.org/r/gitweb?p=mediawiki/core.git;a=blob;f=resources/jquery/jquery.qunit.completenessTest.js;hb=HEAD jQuery QUnit CompletenessTest]
Assesses the completeness (coverage) of test suites for object oriented javascript libraries. Written to be used in environments with jQuery and QUnit.

This is also [//gerrit.wikimedia.org/r/gitweb?p=mediawiki/core.git;a=blob;f=tests/qunit/data/testrunner.js;hb=HEAD#l44 used by MediaWiki core] when running the QUnit test suite with the  option enabled.

[//gerrit.wikimedia.org/r/gitweb?p=mediawiki/core.git;a=blob;f=resources/jquery/jquery.suggestions.js;hb=HEAD jQuery.suggestions]
There is also jquery.ui.autocomplete.js with similar functionality.

Real world examples: [//gerrit.wikimedia.org/r/gitweb?p=mediawiki/core.git;a=blob;f=resources/mediawiki.page/mediawiki.page.ajaxCategories.js;hb=HEAD ajaxCategories.js], [//gerrit.wikimedia.org/r/gitweb?p=mediawiki/extensions/Vector.git;a=blob;f=modules/ext.vector.simpleSearch.js;hb=HEAD ext.vector.simpleSearch.js]

Example shows suggestions for the summary-line:

[//gerrit.wikimedia.org/r/gitweb?p=mediawiki/core.git;a=blob;f=resources/jquery.tipsy/jquery.tipsy.js;hb=HEAD jQuery.tipsy]
Example page; JQuery project page

[//gerrit.wikimedia.org/r/gitweb?p=mediawiki/core.git;a=blob;f=resources/jquery/jquery.mwExtension.js;hb=HEAD#l5 jQuery Extension]
There are several methods added to the jQuery object for older browsers serving as backwards-compatibility for new native prototypes in newer browser. Also several other convenience functions have been created such as isEmpty and escapeRE. From MW 1.17 until 1.18, these methods and functions were part of the module "jquery.mwPrototypes". On MW 1.19, this was renamed to "jquery.mwExtension" (see 94227).
 * trimLeft: Trims whitespace from the left side of the string
 * trimRight: Trims whitespace from the right of the string
 * ucFirst: Returns the string with the first character capitalized
 * escapeRE: Returns a string for literal use in a regular expressions by escaping characters that have a special meaning in a regex.
 * isDomElement: Check whether a passed a variable is a direct link to an element.
 * isEmpty: This function checks if a variable is empty. Supports strings, booleans, arrays and objects. The string "0" is considered empty. A string containing only whitespace (ie. " ") is considered not empty.
 * compareArray: Compares two arrays and returns a boolean for whether they are in fact the same
 * compareObject: Compares two objects for it's properties and values (recursive)