Placement is a library for script placement. It makes placement customization much easier, standardizes selectors, and creates the My Tools menu if necessary.
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'
};