Namespace: mw, MediaWiki Frontend API, JSDoc

Base library for MediaWiki.

Exposed globally as mw, with mediaWiki as alias. mw code can be considered stable and follows the frontend stable interface policy.

Namespaces

Debug: Access the debug toolbar.
cldr: Namespace for CLDR-related utility methods.
errorLogger: Allows the logging of client errors for later inspections.
experiments: Provides an API for bucketing users in experiments.
html: HTML construction helper functions.
htmlform: Provides access to HTMLForm OOUI classes.
language: Methods for transforming message syntax.
loader: Client for ResourceLoader server end point.
log: Log debug messages and developer warnings to the browser console.
messagePoster: Library for posting messages to talk pages.
notification: Library for sending notifications to end users.
searchSuggest: Convenience library for making searches for titles that match a string.
tempUserCreated: Respond to the creation of a temporary user.
template: An extensible library for rendering templates in different template languages.
user: User library provided by 'mediawiki.user' ResourceLoader module.
util: Library providing useful common skin-agnostic utility functions.
widgets: OOUI widgets specific to MediaWiki.

Classes

Api: Interact with the MediaWiki API.
Feedback: Obtain feedback from users.
ForeignApi: Interact with the API of another MediaWiki site.
ForeignRest: Interact with the REST API of another MediaWiki site.
ForeignStructuredUpload: Upload to another MediaWiki site using structured metadata.
ForeignUpload: Upload to another MediaWiki site.
GallerySlideshow: Interface controls for the slideshow gallery.
Map: Collection of values by string keys.
Message: Describes a translateable text or HTML string.
Rest: Interact with the REST API.
Title: Library for constructing MediaWiki titles.
Upload: Upload to a wiki.
Uri: Create and manipulate MediaWiki URIs.

Properties

config :mw.Mapstatic #

Map of configuration values.

Check out the complete list of configuration values on mediawiki.org.

Type:

mw.Map

Source:

startup/mediawiki.js, line 249

Map of configuration values.

libs :Objectstatic #

Empty object for third-party libraries, for cases where you don't want to add a new global, or the global is bad and needs containment or wrapping.

Type:

Object

Source:

mediawiki.base/mediawiki.base.js, line 227

Empty object for third-party libraries, for cases where you don't want to add a new global, or the global is bad and needs containment or wrapping.

messages :mw.Mapstatic #

Store for messages.

Type:

mw.Map

Source:

startup/mediawiki.js, line 256

Store for messages.

storage :SafeStoragestatic #

Alias for module:mediawiki.storage.local.

Type:

SafeStorage

Properties:

Name	Type	Description
`session`	SafeStorage	Alias for `module:mediawiki.storage.session`.

Source:

mediawiki.storage/index.js, line 68

Alias for module:mediawiki.storage.local.

templates :mw.Mapstatic #

Store for templates associated with a module.

Type:

mw.Map

Source:

startup/mediawiki.js, line 263

Store for templates associated with a module.

Methods

UriRelative(documentLocation) → {mw.Uri}static #

A factory method to create an mw.Uri class with a default location to resolve relative URLs against (including protocol-relative URLs).

Parameters:

Name	Type	Description
`documentLocation`	string \| function	A full url, or function returning one. If passed a function, the return value may change over time and this will be honoured. (T74334)

Source:

mediawiki.Uri/Uri.js, line 66

Returns:

An mw.Uri class constructor

Type: mw.Uri

A factory method to create an mw.Uri class with a default location to resolve relative URLs against (including protocol-relative URLs).

confirmCloseWindow([options]) → {Object}static #

Prevent the closing of a window with a confirm message (the onbeforeunload event seems to work in most browsers).

Provided by the mediawiki.confirmCloseWindow module.

This supersedes any previous onbeforeunload handler. If there was a handler before, it is restored when you execute the returned release() function.

Example

mw.loader.using( 'mediawiki.confirmCloseWindow' ).then(() => {
    var allowCloseWindow = mw.confirmCloseWindow();
    // ... do stuff that can't be interrupted ...
    allowCloseWindow.release();

   // The second function returned is a trigger function to trigger the check and an alert
   // window manually, e.g.:

    var allowCloseWindow = mw.confirmCloseWindow();
    // ... do stuff that can't be interrupted ...
    if ( allowCloseWindow.trigger() ) {
        // don't do anything (e.g. destroy the input field)
    } else {
        // do whatever you wanted to do
    }
})

Parameters:

Name Type Attributes Description

options

Object

optional

Properties:

Name Type Attributes Description

namespace

string

optional

Optional jQuery event namespace, to allow loosely coupled external code to release your trigger. For example, the VisualEditor extension can use this remove the trigger registered by mediawiki.action.edit, without strong runtime coupling.

test

function

optional

Properties:

Name	Type	Attributes	Default	Description
`return`	boolean	optional	true	Whether to show the dialog to the user.

Source:

mediawiki.confirmCloseWindow.js, line 2

Returns:

An object of functions to work with this module

Type: Object

Prevent the closing of a window with a confirm message (the onbeforeunload event seems to work in most browsers).

deflate(data) → {string}static #

Convert a byte stream to base64 text. Before using load the mediawiki.deflate ResourceLoader module.

Example

return mw.loader.using( 'mediawiki.deflate' ).then( function () {
   return mw.deflate( html );
} );

Parameters:

Name	Type	Description
`data`	string

Source:

mediawiki.deflate/mw.deflate.js, line 14

Returns:

Type: string

Convert a byte stream to base64 text.

format(formatString, …parameters) → {string}static #

Format a string. Replace $1, $2 ... $N with positional arguments.

Used by mw.Message#parse.

Parameters:

Name	Type	Attributes	Description
`formatString`	string		Format string
`parameters`	Mixed	repeatable	Values for $N replacements

Since:

1.25

Source:

mediawiki.base/mediawiki.base.js, line 305

Returns:

Formatted string

Type: string

Format a string.

hook(name) → {Hook}static #

Create an instance of Hook.

Example

const hook = mw.hook( 'name' );
hook.add( () => alert( 'Hook was fired' ) );
hook.fire();

Parameters:

Name	Type	Description
`name`	string	Name of hook.

Source:

mediawiki.base/mediawiki.base.js, line 502

Returns:

Type: Hook

Create an instance of Hook.

inspect([…reports])static #

Generate and print reports.

When invoked without arguments, prints all available reports.

Parameters:

Name	Type	Attributes	Description
`reports`	string	optional repeatable	One or more of "size", "css", "store", or "time".

Source:

mediawiki.inspect.js, line 169

Generate and print reports.

log(…msg)static #

Write a verbose message to the browser's console in debug mode.

In ResourceLoader debug mode, this writes to the browser's console. In production mode, it is a no-op.

See mw.log for other logging methods.

Parameters:

Name	Type	Attributes	Description
`msg`	string	repeatable	Messages to output to console.

Source:

startup/mediawiki.js, line 145

Write a verbose message to the browser's console in debug mode.

message(key, …parameters) → {mw.Message}static #

Get a message object.

Shortcut for new mw.Message( mw.messages, key, parameters ).

Parameters:

Name	Type	Attributes	Description
`key`	string		Key of message to get
`parameters`	Mixed	repeatable	Values for $N replacements

Source:

mediawiki.base/mediawiki.base.js, line 327

See:

mw.Message

Returns:

Type: mw.Message

Get a message object.

msg(key, …parameters) → {string}static #

Get a message string using the (default) 'text' format.

Shortcut for mw.message( key, parameters... ).text().

Parameters:

Name	Type	Attributes	Description
`key`	string		Key of message to get
`parameters`	any	repeatable	Values for $N replacements

Source:

mediawiki.base/mediawiki.base.js, line 343

See:

mw.Message

Returns:

Type: string

Get a message string using the (default) 'text' format.

notify(message, [options]) → {jQuery.Promise}static #

Convenience method for loading and accessing the mw.notification module.

Parameters:

Name	Type	Attributes	Description
`message`	HTMLElement \| Array.<HTMLElement> \| jQuery \| mw.Message \| string
`options`	Object	optional	See mw.notification#defaults for the defaults.

Source:

mediawiki.base/mediawiki.base.js, line 359

Returns:

Type: jQuery.Promise

Convenience method for loading and accessing the mw.notification module.

now() → {number}static #

Get the current time, measured in milliseconds since January 1, 1970 (UTC).

On browsers that implement the Navigation Timing API, this function will produce floating-point values with microsecond precision that are guaranteed to be monotonic. On all other browsers, it will fall back to using Date.

Source:

startup/mediawiki.js, line 176

Returns:

Current time

Type: number

Get the current time, measured in milliseconds since January 1, 1970 (UTC).

requestIdleCallback(callback, [options])static #

Schedule a deferred task to run in the background.

This allows code to perform tasks in the main thread without impacting time-critical operations such as animations and response to input events.

Basic logic is as follows:

User input event should be acknowledged within 100ms per RAIL.
Idle work should be grouped in blocks of upto 50ms so that enough time remains for the event handler to execute and any rendering to take place.
Whenever a native event happens (e.g. user input), the deadline for any running idle callback drops to 0.
As long as the deadline is non-zero, other callbacks pending may be executed in the same idle period.

Parameters:

Name Type Attributes Description

callback function

options

Object

optional

Properties:

Name	Type	Attributes	Description
`timeout`	number	optional	If set, the callback will be scheduled for immediate execution after this amount of time (in milliseconds) if it didn't run by that time.

Source:

startup/mediawiki.requestIdleCallback.js, line 47

Schedule a deferred task to run in the background.

track(topic, [data])static #

Track an analytic event.

This method provides a generic means for MediaWiki JavaScript code to capture state information for analysis. Each logged event specifies a string topic name that describes the kind of event that it is. Topic names consist of dot-separated path components, arranged from most general to most specific. Each path component should have a clear and well-defined purpose.

Data handlers are registered via mw.trackSubscribe, and receive the full set of events that match their subscription, including buffered events that fired before the handler was subscribed.

Parameters:

Name	Type	Attributes	Description
`topic`	string		Topic name
`data`	Object \| number \| string	optional	Data describing the event.

Source:

mediawiki.base/mediawiki.base.js, line 384

Track an analytic event.

trackSubscribe(topic, callback)static #

Handlers will be called once for each tracked event, including for any buffered events that fired before the handler was subscribed. The callback is passed a topic string, and optional data argument(s).

Examples

// To monitor all topics for debugging
mw.trackSubscribe( '', console.log );

// To subscribe to any of `foo.*`, e.g. both `foo.bar` and `foo.quux`
mw.trackSubscribe( 'foo.', console.log );

Parameters:

Name Type Description

topic

string

Handle events whose name starts with this string prefix

callback

function

Handler to call for each matching tracked event

Properties:

Name	Type	Attributes	Description
`topic`	string
`data`	Object \| number \| string	optional

Source:

mediawiki.base/mediawiki.base.js, line 410

trackUnsubscribe(callback)static #

Stop handling events for a particular handler.

Parameters:

Name	Type	Description
`callback`	function

Source:

mediawiki.base/mediawiki.base.js, line 431

Stop handling events for a particular handler.