Extension:WikiEditor/Toolbar customization

If you're just here to get some quick code that you can copypaste into your user JS and will just work out of the box, see the customizations library. The rest of this article explains the technical details of customizing the toolbar and requires a basic level of understanding of JavaScript.

Basic setup

Before a script is able to manipulate the toolbar provided by WikiEditor, two things must happen:

• The module "ext.wikiEditor.toolbar" needs to be loaded.
• The document needs to be read.

To customize the toolbar, put the following code in your User:YourUserName/common.js:

var customizeToolbar = function() {
	/* Your code goes here */
};

/* Check if view is in edit mode and that the required modules are available. Then, customize the toolbar . . . */
if ( $.inArray( mw.config.get( 'wgAction' ), ['edit', 'submit'] ) !== -1 ) {
	mw.loader.using( 'user.options', function () {
		if ( mw.user.options.get('usebetatoolbar') ) {
			mw.loader.using( 'ext.wikiEditor.toolbar', function () {
				$(document).ready( customizeToolbar );
			} );
		}
	} );
}

. . . and replace the line /* Your code goes here */ by the code which defines each button added. Multiple snippets can be added by simply pasting them below each other, inside of the function customizeToolbar.

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. Complete documentation is to be written shortly.

You can modify the toolbar even after it's been built (see example above) by calling the .wikiEditor() function on the textarea. You will need to do this inside an $(document).ready(function() {}); 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:

   'action': {
       'type': 'encapsulate',
           'options': {
               'pre': "",
               'periMsg': 'wikieditor-toolbar-tool-bold-example',
               'post': ""
           }
       }
   }

Another example from it.source, using callback:

     action: {
          type: 'callback',
               execute: function(context){
                      indentSelection();
               } 
     }

button

• type: "button"
• icon string required: short key name or URL to icon
• label string: non-localizable label string
• labelMsg string: key for localizable message string
• #action

booklet

• type: "booklet"
• label string: non-localizable label string
• labelMsg string: key for localizable message string
• deferLoad boolean
• pages object: map of name keys to further objects:
  • layout string required: 'table' or 'characters'
  • label string: non-localizable label string
  • labelMsg string: key for localizable message string
  • headings string[]: array of objects? {textMsg: key} ??
  • rows object[] optional?: array of objects? {'row key name': {message object?}}
  • characters string[] optional?: array of strings of little character bits for insertion (???!)

Q: How can we receive an event or callback when our booklet gets triggered?

Default sections

The default WikiEditor toolbar has the following sections:

• The main section which is always visible, with the groups format and insert.
• 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

When using the code below, remember it depends on the module "ext.wikiEditor.toolbar" and needs to wait until the page is loaded. To avoid executing it before everything is properly initialized, you should copy it inside of the function customizeToolbar defined above, or something equivalent.

The general format for adding things is as follows:

$( '#wpTextbox1' ).wikiEditor( 'addToToolbar', {
	// Configuration object here
} );

Some specific examples are displayed in the sections below.

Add a toolbar section

$( '#wpTextbox1' ).wikiEditor( 'addToToolbar', {
	'sections': {
		'emoticons': {
			'type': 'toolbar', // Can also be 'booklet'
			'label': 'Emoticons'
			// or 'labelMsg': 'section-emoticons-label' for a localized label
		}
	}
} );

Add a group to an existing toolbar section

$( '#wpTextbox1' ).wikiEditor( 'addToToolbar', {
	'section': 'emoticons',
	'groups': {
		'faces': {
			'label': 'Faces' // or use labelMsg for a localized label, see above
		}
	}
} );

Add a button to an existing toolbar group

$( '#wpTextbox1' ).wikiEditor( 'addToToolbar', {
	'section': 'emoticons',
	'group': 'faces',
	'tools': {
		'smile': {
			label: 'Smile!', // or use labelMsg for a localized label, see above
			type: 'button',
			icon: '//upload.wikimedia.org/wikipedia/commons/thumb/a/a4/Gnome-face-smile.svg/22px-Gnome-face-smile.svg.png',
			action: {
				type: 'encapsulate',
				options: {
					pre: ":)" // text to be inserted
				}
			}
		}
	}
} );

Add a booklet section

$( '#wpTextbox1' ).wikiEditor( 'addToToolbar', {
	'sections': {
		'info': {
			'type': 'booklet',
			'label': 'Info'
		}
	}
} );

Add a page to an existing booklet section

$( '#wpTextbox1' ).wikiEditor( 'addToToolbar', {
	'section': 'info',
	'pages': {
		'colors': {
			'layout': 'table',
			'label': 'Colors',
			'headings': [
				{ text: 'Name' }, // or use textMsg for localization, see also above
				{ text: 'Temperature' },
				{ text: 'Swatch' }
			],
			'rows': [
				{
					'name': { text: 'Red' },
					'temp': { text: 'Warm' },
					'swatch': { html: '<div style="width:10px;height:10px;background-color:red;">' }
				},
				{
					'name': { text: 'Blue' },
					'temp': { text: 'Cold' },
					'swatch': { html: '<div style="width:10px;height:10px;background-color:blue;">' }
				},
				{
					'name': { text: 'Silver' },
					'temp': { text: 'Neutral' },
					'swatch': { html: '<div style="width:10px;height:10px;background-color:silver;">' }
				}
			]
		}
	}
} );

Add a special characters page

$( '#wpTextbox1' ).wikiEditor( 'addToToolbar', {
	'section': 'characters',
	'pages': {
		'emoticons': {
			'layout': 'characters',
			'label': 'Emoticons',
			'characters': [ ':)', ':))', ':(', '<3', ';)' ]
		}
	}
} );

Note that this only works after the 'characters' section has been built.

Add characters to an existing special characters page

Additional characters can be injected during the building of the 'characters' section:

$(function() {
    $( '#wpTextbox1' ).on( 'wikiEditor-toolbar-buildSection-characters', function (event, section) {
        section.pages.symbols.characters.push('\u02be', '\u02bf');
    });
});

There is also an API function, but it only works after the 'characters' section has been built:

$( '#wpTextbox1' ).wikiEditor( 'addToToolbar', {
	'section': 'characters',
	'page': 'symbols',
	'characters': [ '\u02be', '\u02bf' ]
});

Removing things

Use the removeFromToolbar call to remove buttons from the toolbar. The following example removes the Search and Replace button:

/* Remove Search & Replace */
$( '#wpTextbox1' ).wikiEditor( 'removeFromToolbar', {
	'section': 'advanced',
	'group': 'search',
	'tool': 'replace'
});

Modifying things

Warning: Binding doesn't seem to work with $() but does work if called with addOnloadHook from module "mediawiki.legacy.wikibits" (make sure to add it to your script's dependencies).

A working example could be found at the bottom of ru:MediaWiki:ToolbarNew.js

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:

$( '#wpTextbox1' ).bind( 'wikiEditor-toolbar-buildSection-sectionname', function( event, section ) {
	// Do stuff with section
} );

Example: adding localized icons

$( '#wpTextbox1' ).bind( 'wikiEditor-toolbar-buildSection-main', function( event, section ) {
	// Add icons for bold (F) and italic (L) for Swedish (sv)
	// Don't overwrite them if they're already defined, so this hack can safely be removed once the
	// usability team incorporates these icons in the software
	if ( !( 'sv' in section.groups.format.tools.bold.icon ) ) {
		// There's already a bold F icon for German, use that one
		section.groups.format.tools.bold.icon['sv'] = 'format-bold-F.png';
		section.groups.format.tools.bold.offset['sv'] = [2, -214];
	}
	if ( !( 'sv' in section.groups.format.tools.italic.icon ) ) {
		// Use an icon from Commons for L
		section.groups.format.tools.italic.icon['sv'] = '//upload.wikimedia.org/wikipedia/commons/3/32/Toolbaricon_italic_L.png';
		section.groups.format.tools.italic.offset['sv'] = [2, -214];
	}
} );

Determining when toolbar load is done

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

$( '#wpTextbox1' ).on( 'wikiEditor-toolbar-doneInitialSections', function () {
    // Do something

This is in WikiEditor wmf/1.21wmf8 and later.