Hooks

Registry and firing of events.

MediaWiki has various interface components that are extended, enhanced or manipulated in some other way by extensions, gadgets and even in core itself.

This framework helps streamlining the timing of when these other code paths fire their plugins (instead of using document-ready, which can and should be limited to firing only once).

Features like navigating to other wiki pages, previewing an edit and editing itself – without a refresh – can then retrigger these hooks accordingly to ensure everything still works as expected.

Example usage:

mw.hook( 'wikipage.content' ).add( fn ).remove( fn );
mw.hook( 'wikipage.content' ).fire( $content );

Handlers can be added and fired for arbitrary event names at any time. The same event can be fired multiple times. The last run of an event is memorized (similar to $(document).ready and $.Deferred().done). This means if an event is fired, and a handler added afterwards, the added function will be fired right away with the last given event data.

Like Deferreds and Promises, the mw.hook object is both detachable and chainable. Thus allowing flexible use and optimal maintainability and authority control. You can pass around the add and/or fire method to another piece of code without it having to know the event name (or mw.hook for that matter).

var h = mw.hook( 'bar.ready' );
new mw.Foo( .. ).fetch( { callback: h.fire } );

The function signature for hooks can be considered stable. See available global events below.

Events

'RcFilters.highlight.enable'() #

Fires when highlight feature is enabled.

Source:
Fires when highlight feature is enabled.

'RcFilters.popup.open'() #

Fires when the RCFilters tag multi selector menu is toggled.

Source:
Fires when the RCFilters tag multi selector menu is toggled.

'editRecovery.loadEnd'(editRecovery) #

Fired after EditRecovery has loaded any recovery data, added event handlers, etc.

Parameters:

Name Type Description
editRecovery Object
Properties:
Name Type Description
fieldChangeHandler function
Source:
Fired after EditRecovery has loaded any recovery data, added event handlers, etc.

'htmlform.enhance'(document) #

Fired on page load to enhance any HTML forms on the page.

Parameters:

Name Type Description
document jQuery
Source:
Fired on page load to enhance any HTML forms on the page.

'postEdit'(data) #

Fired after an edit was successfully saved.

Does not fire for null edits.

Code that fires the postEdit hook should first set wgRevisionId and wgCurRevisionId to the revision associated with the edit that triggered the postEdit hook, then fire the postEdit hook.

Example

mw.config.set( {
   wgCurRevisionId: data.newrevid,
   wgRevisionId: data.newrevid
} );
// Now fire the hook.
mw.hook( 'postEdit' ).fire();

Parameters:

Name Type Attributes Description
data Object optional

Optional data

Properties:
Name Type Attributes Default Description
message string | jQuery | Array optional

Message that listeners should use when displaying notifications. String for plain text, use array or jQuery object to pass actual nodes.
user string | mw.user optional
 mw.user

User that made the edit.
tempUserCreated boolean optional

Whether a temporary user account was created.
Source:
Fired after an edit was successfully saved.

'postEdit.afterRemoval'() #

After the listener for #postEdit removes the notification.

Deprecated:
  • Yes
Source:
After the listener for #postEdit removes the notification.

'skin.logout'(href) #

Fired when a trusted UI element to perform a logout has been activated.

This will end the user session, and either redirect to the given URL on success, or queue an error message via mw.notification.

Parameters:

Name Type Description
href string

Full URL
Source:
Fired when a trusted UI element to perform a logout has been activated.

'structuredChangeFilters.ui.initialized'() #

Fired when initialization of the filtering interface for changes list is complete.

Source:
Fired when initialization of the filtering interface for changes list is complete.

'util.addPortlet'(portlet, before) #

Fires when a portlet is successfully created.

Example

mw.hook( 'util.addPortlet' ).add( ( p ) => {
    p.style.border = 'solid 1px black';
} );

Parameters:

Name Type Description
portlet HTMLElement

the portlet that was created.
before string | null

the css selector used to append to the DOM.
Source:
Fires when a portlet is successfully created.

'util.addPortletLink'(item, information) #

Fires when a portlet link is successfully created.

Example

mw.hook( 'util.addPortletLink' ).add( ( link ) => {
    const span = $( '<span class="icon">' );
    link.appendChild( span );
} );

Parameters:

Name Type Description
item HTMLElement

the portlet link that was created.
information Object

about the item include id.
Source:
Fires when a portlet link is successfully created.

'wikipage.categories'($content) #

Fired when categories are being added to the DOM.

It is encouraged to fire it before the main DOM is changed (when $content is still detached). However, this order is not defined either way, so you should only rely on $content itself.

This includes the ready event on a page load (including post-edit loads) and when content has been previewed with LivePreview.

Parameters:

Name Type Description
$content jQuery

The most appropriate element containing the content, such as .catlinks
Source:
Fired when categories are being added to the DOM.

'wikipage.collapsibleContent'($collapsible) #

Fired after collapsible content has been initialized.

This gives an option to modify the collapsible behavior.

Parameters:

Name Type Description
$collapsible jQuery

An element that has been made collapsible
Source:
Fired after collapsible content has been initialized.

'wikipage.content'($content) #

Fired when wiki content has been added to the DOM.

This should only be fired after $content has been attached.

This includes the ready event on a page load (including post-edit loads) and when content has been previewed with LivePreview.

Parameters:

Name Type Description
$content jQuery

The most appropriate element containing the content, such as #mw-content-text (regular content root) or #wikiPreview (live preview root)
Source:
Fired when wiki content has been added to the DOM.

'wikipage.diff'($diff) #

Fired when the diff is added to a page containing a diff.

Similar to the wikipage.content hook $diff may still be detached when the hook is fired.

Parameters:

Name Type Description
$diff jQuery

The root element of the MediaWiki diff (table.diff).
Source:
Fired when the diff is added to a page containing a diff.

'wikipage.diff.diffTypeSwitch'(inlineToggleSwitch) #

Fired when the diff type switch is present so others can decide how to manipulate the DOM.

Parameters:

Name Type Description
inlineToggleSwitch OO.ui.ToggleSwitchWidget
Source:

Fired when the diff type switch is present so others can decide how to manipulate the DOM.

'wikipage.diff.wikitextDiffBody'($wikitextDiffBody) #

Fired when the wikitext DOM is updated so others can react accordingly.

Parameters:

Name Type Description
$wikitextDiffBody jQuery
Source:
Fired when the wikitext DOM is updated so others can react accordingly.

'wikipage.editform'($editForm) #

Fired when the editform is added to the edit page.

Similar to the wikipage.content hook, $editForm can still be detached when this hook is fired.

Parameters:

Name Type Description
$editForm jQuery

The most appropriate element containing the editform, usually #editform.
Source:
Fired when the editform is added to the edit page.

'wikipage.indicators'($content) #

Fired when a page's status indicators are being added to the DOM.

Parameters:

Name Type Description
$content jQuery

jQuery object with the elements of the indicators
Source:
See:
Fired when a page's status indicators are being added to the DOM.

'wikipage.tableOfContents'(sections) #

Fired when dynamic changes have been made to the table of contents.

Parameters:

Name Type Description
sections Array.<Object>

Metadata about each section, as returned by API:Parse.
Source:
Fired when dynamic changes have been made to the table of contents.

'wikipage.watchlistChange'(isWatched, expiry, expirySelected) #

Fires when the page watch status has changed.

Example

mw.hook( 'wikipage.watchlistChange' ).add( ( isWatched, expiry, expirySelected ) => {
    // Do things
} );

Parameters:

Name Type Description
isWatched boolean
expiry string

The expiry date if the page is being watched temporarily.
expirySelected string

The expiry length that was selected from a dropdown, e.g. '1 week'
Source:
Fires when the page watch status has changed.