Extension:WikiEditor/Toolbar customization

From MediaWiki.org
Jump to: navigation, search

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[edit | edit source]

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

  • $wgAllowUserJs = true; (or $wgUseSiteJs = true; depending on how the script will be executed) needs to be set in Localsettings.php
  • 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.user.options.get( 'showtoolbar' ) ) {
			$.when(
				mw.loader.using( 'ext.wikiEditor.toolbar' ),
				$.ready
			).then( customizeToolbar );
		}
	} );
}
// Add the customizations to LiquidThreads' edit toolbar, if available
mw.hook( 'ext.lqt.textareaCreated' ).add( 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[edit | edit source]

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[edit | edit source]

  • 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[edit | edit source]

  • 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[edit | edit source]

  • 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[edit | edit source]

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[edit | edit source]

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[edit | edit source]

$( '#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[edit | edit source]

$( '#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[edit | edit source]

$( '#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[edit | edit source]

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

Add a page to an existing booklet section[edit | edit source]

$( '#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[edit | edit source]

$( '#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[edit | edit source]

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[edit | edit source]

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[edit | edit source]

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' ).on( 'wikiEditor-toolbar-buildSection-sectionname', function( event, section ) {
	// Do stuff with section
} );

Example: adding localized icons[edit | edit source]

$( '#wpTextbox1' ).on( '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[edit | edit source]

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. For example, GuidedTour repositions absolutely positioned guiders (a type of tooltip) at this point.

See also[edit | edit source]