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.

Configuration structure

The toolbar widget is defined by a configuration object. You can look at the configuration for the default toolbar 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 by calling the .wikiEditor() function on the textarea. You will need to do this inside an $(document).ready(function() {}); call, though.

Adding things

// Check that the toolbar is available
if ( typeof $j != 'undefined' && typeof $j.fn.wikiEditor != 'undefined' ) {
	// Execute on load
	$j( function() {
		// General format: 
                // $j( '#wpTextbox1' ).wikiEditor( 'addToToolbar', { configuration object here } );

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


		// To add a group to an existing toolbar section:
		$j( '#wpTextbox1' ).wikiEditor( 'addToToolbar', {
			'section': 'emoticons',
			'groups': {
				'faces': {
					'label': 'Faces' // or use labelMsg for a localized label, see above
				}
			}
		} );

		// To add a button to an existing toolbar group:
		$j( '#wpTextbox1' ).wikiEditor( 'addToToolbar', {
			'section': 'emoticons',
			'group': 'faces',
			'tools': {
				'smile': {
					label: 'Smile!', // or use labelMsg for a localized label, see above
					type: 'button',
					icon: 'http://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
						}
					}
				}
			}
		} );

		// To add a booklet section:
		$j( '#wpTextbox1' ).wikiEditor( 'addToToolbar', {
			'sections': {
				'info': {
					'type': 'booklet',
					'label': 'Info'
				}
			}
		} );

		// To add a page to an existing booklet section
		$j( '#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;">' }
						}
					]
				}
			}
		} );

		// To add a special characters page
		$j( '#wpTextbox1' ).wikiEditor( 'addToToolbar', {
			'section': 'info',
			'pages': {
				'emoticons': {
					'layout': 'characters',
					'label': 'Emoticons',
					'characters': [ ':)', ':))', ':(', '<3', ';)' ]
				}
			}
		} );
	} );
}

Existing 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.

Removing things

TODO

Modifying things

Warning: Binding doesn't seem to work with $j() but does work if called with addOnloadHook.

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:

// Check that jQuery is defined

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

Example: adding localized icons

// Check that jQuery is available
if ( typeof $j != 'undefined' ) {
	$j( function() {
		$j( '#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'] = 'http://upload.wikimedia.org/wikipedia/commons/3/32/Toolbaricon_italic_L.png';
				section.groups.format.tools.italic.offset['sv'] = [2, -214];
			}
		} );
	} );
}