User:V111P/js/addToolbarButtons

File:Advanced toolbar of vector skin.png

The Enhanced editing toolbar, with its Advanced section (the second row) open.

The classic toolbar.

addToolbarButtons.js simplifies adding buttons to the edit toolbar above the text area when editing the source of wiki pages.

The "Enhanced editing toolbar" (part of the WikiEditor MediaWiki extension) is now the default toolbar when editing the source code of articles, but some users are still using the original toolbar.

addToolbarButtons.js adds your buttons to whichever of the two toolbars appears above the text area when editing an article. (You can turn on and off the Enhanced editing toolbar from your preferences >> Editing tab >> Editor section >> "Enable enhanced editing toolbar" checkbox.) This script can not add buttons to the VisualEditor's toolbar.

Please comment on the talk page if you find this script useful and if you have any questions or suggestions. Also, please see my other useful scripts.

The source code of the script is here: User:V111P/js/addToolbarButtons.js

You can edit this page. If I don't like or understand something you wrote, I will correct it. ;)

How to use

If the script is already loaded (another script may have loaded it, so you should check), pass an object with the button's properties (described below) to the function mw.libs.addToolbarButtons().
To add multiple buttons at the same time, you can pass an array with property objects instead of a single property object.
If the script is not already loaded, add the object with the button's properties to the array window.toolbarButtonsToAdd instead. (If the array doesn't already exist, you need to create it first.) Then load addToolbarButtons.js with an Ajax call.
You can add the button objects to the array window.toolbarButtonsToAdd even if the script is already loaded. Then you need to call mw.libs.addToolbarButtons() with no arguments - this will add to the toolbar all buttons specified in the array window.toolbarButtonsToAdd so far (and will remove them from the array).

Here is an example of how to add a single button:

var addToolbarButtonsUrl = '//en.wikipedia.org/w/index.php?title='
	+ 'User:V111P/js/addToolbarButtons.js&action=raw&ctype=text/javascript';
// Backlink: [[User:V111P/js/addToolbarButtons.js]]


var myToolbarButton = {
	id: 'theUniqueIdOfYourButton',
	callback: function () {alert('hi');}
};


if (mw.libs.addToolbarButtons)
	mw.libs.addToolbarButtons(myToolbarButton);
else {
	var tbs = window.toolbarButtonsToAdd = window.toolbarButtonsToAdd || [];
	tbs.push(myToolbarButton);
	mw.loader.load(addToolbarButtonsUrl);
}

The button properties object

Only the id property is required, however you must also specify either a callback function or some text to insert (with at least one of the before, after and between properties). You can specify both a callback function and text to insert, but see Inserting and modifying text from your callback below.

File:White pog.svg

The default button image for the Enhanced toolbar

File:Button base.png

The default button image for the classic toolbar (used only if iconUrl is not set)

id (required) - must be a valid HTML DOM id and must be unique. If no id is specified or there is already another element on the page with that id, an error message will be printed in the console and no button will be added.
tooltip - a tooltip string
section - for the "Enhanced" toolbar only: "main" or "advanced". The default is "main". The buttons in "Main" are always shown. To see the buttons in the "Advanced" section, the user must click the "Advanced" link, which is right after all the buttons from the "Main" section.
group - for the "Enhanced" toolbar only. The groups in the "main" section are "format" and "insert". The groups in the "advanced" section are "heading", "format", "size", "insert" and "search". The default value is "insert".
before - text to be inserted before the selection/cursor.
after - text to be inserted after the selection/cursor.
between - text to be inserted at the cursor (between the strings specified with "before" and "after") if no text was selected before pressing the button. If there was some selected text, this property is not used. After it is inserted, the "between" text will be selected. This string is usually used to add a help message, such as "Type text here".
callback - the function to be called when the button is pressed. Must be an actual function object, not a string with the name of the function or anything else. Note that this callback function is called after the strings in "before", "after", and "between" are inserted in the text.
iconUrl - an image file url. See below how to choose an image from Commons and how to format its URL. The default image is an unlabeled round white button.
iconUrlClassic - an image file url. If this property is set, this image URL will be used for the classic toolbar instead of iconUrl. If it's not set, but iconUrl is, iconUrl's value will be used. If neither is set, an unlabeled square button will be used. You may want to have two separate images, because the default buttons on the classic toolbar look like buttons, while the images on the enhanced toolbar don't look like buttons (see the screenshots).

Examples

var button1 = {
	id: 'insertTemplateButton',
	tooltip: 'Insert a template',
	before: '{{',
	between: '<Template name>',
	after: '}}',
	callback: function (event) {
		if (window.console && console.log)
			console.log(this.id + ' button clicked');
	}, // you can remove this callback property, remember that it's not required
	iconUrl: '//upload.wikimedia.org/wikipedia/commons/'
		+ 'thumb/f/fb/Template_icon.svg/22px-Template_icon.svg.png',
	iconUrlClassic: '//upload.wikimedia.org/wikipedia/commons/9/97/Template_button.png'
};

var button2 = {
	id: 'removeEndOfLineSpacesButton',
	tooltip: 'Remove whitespace from end of lines',
	section: 'advanced',
	group: 'format',
	callback: function (event) {
		var ta = $('#wpTextbox1');
		ta.val(ta.val().replace(/\s+\n/g, '\n'));
	},
	iconUrl: '//upload.wikimedia.org/wikipedia/commons/'
		+ 'thumb/4/40/Edit-select-all.svg/22px-Edit-select-all.svg.png'
};

Inserting and modifying text from your callback

In your button object you can specify both a callback function and text to insert. In this case, the callback will be called after the text-to-insert is inserted. However, if for example you need to modify the currently selected text in the textarea directly from your callback function, you can use MediaWiki's textSelection jQuery plugin. Here is an example:

	mw.loader.using('jquery.textSelection'); // it's loaded by default, but just in case
	var textArea = $('#wpTextbox1');

	// The button's callback function
	function myCallback() {
		var sel = textArea.textSelection('getSelection');
		sel = sel.replace(/\r/g, ''); // IE before 9 doesn't remove the \r's

		// manipulate the text in the sel variable
		sel = sel.replace(/ /g, '_'); // for example. Replaces space with underscore

		// replace the selected text in the textarea with the new text
		textArea.textSelection('encapsulateSelection', {pre: sel, replace: true});
	}

Choosing and using an image from Commons

You can choose a button image from Commons, then its URL should start with //upload.wikimedia.org after you remove the http: or https: part (so that it can work with either protocol). But make sure to get the url of the actual image, not the image's wiki page. Click on the image on its wiki page to open the image itself, then copy the URL. If the image is in .svg format however, you will want to use a .png version of it, because Internet Explorer (as of version 10) will not resize the .svg image and only its upper-left corner will be shown to users of that browser. To get the .png version of a .svg image in Commons, click on the link "200px" below the image on its wiki page (next to the text This image rendered as PNG in other widths:), now get the URL, but edit the 200px part by changing it to 22px, because FireFox is not good at downsizing such images and the quality will be poor (as of version 24/Windows). Don't forget to remove the http:/https: part. Another problem is that old browsers don't support .png files. (Internet Explorer 10 in Browser/Document mode "IE7" doesn't display them. Instead you see a placeholder image indicating that an image is not being displayed there.)

To find an image, you may try searching for a keyword plus the word icon or button.

If you publish your script for others to use, you should give credit to the author of the image somewhere, such as on the help page for your script. This is required if the image is licensed under CC-BY or CC-BY-SA for example.

How to use

The button properties object

Examples

Inserting and modifying text from your callback

Choosing and using an image from Commons

See also