Usage

Importing

To import and use the Placement library inside your script, use the following:

mw.hook('dev.placement').add(function (placement) {
    // your code here
});
importArticle({
    type: 'script',
    article: 'u:dev:MediaWiki:Placement.js'
});

Methods

The library exports an object (window.dev.placement.loader) with the following properties:

• element
  • Returns a standardized element specified by the function parameter.
  • Accepted input values are listed below.
    • editdropdown - edit dropdown menu.
    • globalnav - global navigation user dropdown.
    • toolbar - bottom toolbar.
    • tools - My Tools menu; creates if it does not exist.
    • wikinav - community header dropdown.
• custom
  • Returns a custom element name specified by the function parameter.
• type
  • Returns a type specified by the function parameter, which typically either appends or prepends the button to the already specified element.
• script
  • Specifies the script's name for customization purposes.
  • Is required and should be placed before other invocations of the placement object.
• util
  • All-in-one method for using Placement; accepts an object with four required parameters (element, type, script, and content). If the content is an object, the script will automatically attempt to make it use UI-js.

Examples

Prepends link to My Tools menu

mw.hook('dev.placement').add(function (placement) {
    placement.script('ToolsMenuLink');
    $(placement.element('tools'))[placement.type('prepend')](
        $('<li>').append(
            $('<a>', {
                text: 'hello'
            })
        )
    );
});

Inserts link after custom element

mw.hook('dev.placement').add(function (placement) {
    placement.script('CustomExampleLink');
    $('<li>').append(
        $('<a>', {
            text: 'hello'
        })
    )[placement.type('insertAfter')](placement.custom('.global-navigation__bottom .wds-list li:nth-child(2)'));
});

Prepends link to My Tools menu using util

mw.hook('dev.placement').add(function (placement) {
    placement.util({
        script: 'ToolsMenuLink',
        element: 'tools',
        type: 'prepend',
        content: $('<li>').append(
            $('<a>', {
                text: 'hello'
            })
        )
    });
});

Customization

To customize a script's placement, first make sure that it uses this script. Then, start by exposing the global object.

window.dev = window.dev || {};
window.dev.placement = window.dev.placement || {};

Then specify your configuration, using element to determine where the script should be placed and type to change how the script is added (e.g. appended/prepended). The element parameter supports all excepted values for placement.element(), which are listed here, as well as custom selectors.

window.dev.placement['ScriptName'] = {
    element: 'tools',
    type: 'prepend'
};

For example, to move AjaxBatchDelete to the bottom of the edit dropdown, use the following:

window.dev = window.dev || {};
window.dev.placement = window.dev.placement || {};
window.dev.placement['AjaxBatchDelete'] = {
    element: 'editdropdown',
    type: 'append'
};