Extension:WikiEditor/Toolbar customization

This article explains the technical details of customizing the toolbar. It requires a basic level of understanding of JavaScript.

If you just need some quick working code that you can copy into your user JS, see the customizations library.

Scripts and gadgets
Before a script or gadget is able to manipulate the toolbar provided by WikiEditor, the following things must happen:


 * 1) Set the following in :
 * 2) * to allow users to setup their individual toolbar, or
 * 3) * to setup the toolbar site-wide
 * 4) The module "ext.wikiEditor" needs to be loaded which is usually done by invoking the WikiEditor extension.
 * 5) Add the following code to your User:YourUserName/common.js (or your MediaWiki:Common.js for a site-wide change) to customize the toolbar:

… and replace the line  by the code which defines each button added. Multiple snippets can be added by adding multiple separate  calls.

Extensions
Extensions wishing to customize the toolbar should first set up a module (with a dependency on ) and then add the following (e.g. in  ):

Configuration structure
The toolbar widget is defined by a jQuery plugin from module jquery.wikiEditor. You can look at the configuration for the default toolbar on module jquery.wikiEditor.toolbar.config to see how you can modify the toolbar.

You can modify the toolbar even after it's been built (see example above) by calling the  function on the textarea. You will need to do this inside an  call, as already mentioned.

action

 * type: one of "encapsulate", "replace", "callback", "dialog"
 * options: for "encapsulate" or "replace" types, carries options for jquery.textSelection module (pre, peri, post); regex, regexReplace
 * execute: for "callback" type, a callable function which will be passed the WikiEditor context
 * module: for "dialog" type, named reference to a WikiEditor add-in dialog module to open

Example:

Another example, using a callback function for the most flexibility in what should happen when the button is pressed:

button

 * type: "button"
 * icon or oouiIcon string required: short key name or URL to icon
 * label string: label string (use mw.message( key ).escaped for localization)
 * 

toggle
Toggles are like buttons but with a binary state. The button can be pressed (active) or non-pressed. (Since 1.32)
 * type: "toggle"
 * icon or oouiIcon string required: short key name or URL to icon
 * label string: label string (use mw.message( key ).escaped for localization)
 * 

You need to track the state yourself, the toggle button will not do it for you. After a callback, update the state, find the buttonelement and call  to make the button reflect the new state.

select
A dropdown menu with menuitems, each menuitem having its own action


 * type: "select"
 * icon or oouiIcon string required: short key name or URL to icon
 * label string: label string (use mw.message( key ).escaped for localization)
 * list object with dropdown menu items, each with their own label and 

element
Insert a raw DOM element. When you use this, you are responsible for everything (labels, event handling, accessiblity, etc.) but have the freedom to do whatever you want (dropdowns, buttons with visible labels, etc.).


 * type: "element"
 * element: either a htmlString, HTMLElement, Text, Array, jQuery object, a function returning any of the aforementioned, or a OO.ui.HTMLSnippet to be inserted.

For example, a button added to the secondary end of the toolbar that displays an alert when clicked:

booklet

 * type: "booklet"
 * label string: label string (use mw.message( key ).escaped for localization)
 * deferLoad boolean
 * pages object: map of name keys to further objects:
 * layout string required: 'table' or 'characters'
 * label string: label string (use mw.message( key ).escaped for localization)
 * headings string[]: array of objects? {text: mw.message( key ).escaped } ⁇
 * rows object[] optional?: array of objects? {'row key name': {message object?}}
 * characters object[] optional?: array of strings of little character bits for insertion, or objects specifying actions:
 * A string is interpreted as a character or string to insert at the cursor position.
 * An array with 2 strings will use the first string as the label, and the second string as the string to be inserted.
 * An object containing  and   properties will perform the action (used to split text to insert before and after the selection).

Default sections
The default WikiEditor toolbar has the following sections:
 * The main section which is always visible, with the groups format and insert.
 * The secondary is at the opposite end from the main section, and contains the default group that is empty by default.
 * The advanced section, with the groups heading, format, size, insert and search.
 * The characters section, with pages latin, latinextended, ipa, symbols, greek, cyrillic, arabic, hebrew, bangla, telugu, sinhala and gujarati
 * The help section, with pages format, link, heading, list, file, reference and discussion.

Adding things
The general format for adding things is as follows:

Some specific examples are displayed in the sections below.

Filter which namespaces should or should not generate added buttons

 * Ex. - To have a button generated only when editing any Talk: namespace page, add the highlighted line below.


 * Ex. - To have a button generated in all namespaces except the User: and Template: namespaces, add the highlighted line below.

Add a special characters page
Note that this only works after the 'characters' section has been built.

Add a whole new group with snippets, that insert text before and after the cursor position or selected text
Instead of a string, we can use an object in the array of characters, with a label and action, to provide the text to insert before and after the cursor or selected text.

Add characters to an existing special characters page
Additional characters can be injected during the building of the 'characters' section: There is also an API function, but it only works after the 'characters' section has been built:

Removing things
Use the  call to remove buttons from the toolbar. The following example removes the button for deprecated HTML element :

Modifying things
We don't really have a nice API to modify things, unfortunately. The best we have is a hook to change the configuration of a section just before it's being built:

Example: modifying button action
The solution below replaces the insertion of obsolete  tag with Big template, but could be used for any customisation of button actions in WikiEditor.

Determining when toolbar load is done
To be notified when the initial toolbar load is done, put:

This is in WikiEditor wmf/1.21wmf8 and later. For example, GuidedTour repositions absolutely positioned guiders (a type of tooltip) at this point.

This should be used carefully, because your script can be loaded later than the moment the event fires.

So it is better to use a hook (it will work also when you run this after the page is fully loaded).