dev

CustomTools gives a method to add a button (or link) to different areas of the interface. It currently supports the following areas:

Note: Although you can use this script site-wide to add buttons and links to certain areas, some areas are only allowed for personal use (like adding buttons to the global navigation).

Installation

API

Custom tools are set up through an object with the following properties:

Property name Description Type Required? Notes
classes The classes to add to the button or link. String or an array of strings No
click A function to be called when you click the button. Function No
icon The name of an icon from WDSIcons. See also Fandom Design System. String Depending on the area. Never specify a size, only the icon's name. For example, use clock; never use clock-small.
link If you want it to link somewhere, set the URL in this property. String No If your URL starts with http://, https:// or //, it will be used as the URL. https://google.com will lead to that URL.


If your URL starts with /, it will be added after the wiki's base URL, keeping the language if any. In w:c:community, /f will set the link to https://community.fandom.com/f; in w:c:es.genshin-impact, /f will set the link to https://genshin-impact.fandom.com/es/f.
Otherwise, it will be used as a local link. Special:RecentChanges will lead to Special:RecentChanges. The value isn't escaped, so Page?action=edit will forward you to editing that page.

placement Where to add the button. The valid values are in the bullet list at the beginning of this page. String Yes Other values are ignored.
position Where to add the button in the container. By default, it is added at the beginning. Negative numbers count from the end, similar to Array.at. Number No 0 will add it at the beginning; 1 after the first item already there (if any); -1 at the end; -2 before the last item already there; and so on.
text What text to display. String No It varies depending on the location: it may be used as a button label, a tooltip or in the title attribute.


It behavior is altered by the i18n and system properties.

i18n If your script supports multiple languages using I18n-js, specify its name (e.g. CustomTools) so translations are fetched from the corresponding i18n JSON page.


The value of text will be used as the key.

String No
system If you want to use MediaWiki's system messages, set this property as true and the text value will be used to fetch instead that system message. Boolean No system: true and text: 'group-sysop' will display in the text field the value of that system message ("Administrators" in English, "Administradores" in Spanish, and so on).

Scripts

The script fires a hook dev.ct that makes available for you a function to setup any buttons and links you may want to add. 

mw.hook('dev.ct').add(function(addButtons) {
	// Add your buttons here calling addButtons.
});

importArticle({
	type: 'script',
	articles: [
		'u:dev:MediaWiki:CustomTools.js'
	]
});

The function expects either an array or a single object with the interface described at the beginning of API.

Example: Add a single button in the page-tools-left area, at the end.
mw.hook('dev.ct').add(function(addButtons) {
	addButtons({
		icon: 'eye',
		link: mw.config.get('wgPageName') + '?action=watch',
		placement: 'page-tools-left',
		position: -1,
		text: 'Add to watchlist'
	});
});

importArticle({
	type: 'script',
	articles: [
		'u:dev:MediaWiki:CustomTools.js'
	]
});
Example: This adds a button at the end of the page-tools-left area, and another one in the explore menu.
mw.hook('dev.ct').add(function(addButtons) {
	addButtons([
		{
			icon: 'eye',
			link: mw.config.get('wgPageName') + '?action=watch',
			placement: 'page-tools-left',
			position: -1,
			text: 'Add to watchlist'
		},
		{
			link: 'Special:Logs',
			placement: 'explore',
			position: -1,
			system: true,
			text: 'log'
		}
	]);
});

importArticle({
	type: 'script',
	articles: [
		'u:dev:MediaWiki:CustomTools.js'
	]
});

Personal use

You can use the hook described in scripts, or set a global window.CustomTools object or array of objects with the same structure that you would use as the function's parameter. 

window.CustomTools = [
	{
		icon: 'eye',
		link: mw.config.get('wgPageName') + '?action=watch',
		placement: 'page-tools-left',
		position: -1,
		text: 'Add to watchlist'
	},
	{
		link: 'Special:Logs',
		placement: 'explore',
		position: -1,
		system: true,
		text: 'log'
	}
];

importArticle({
	type: 'script',
	articles: [
		'u:dev:MediaWiki:CustomTools.js'
	]
});

Use this method only for personal scripts, never for scripts to be imported from dev or in your wiki's JS, since it might mess up with other user's personal custom tools.

User options

For advanced users, you can also set the configuration object through your user options: 

// Option A
mw.user.options.set('userjs-custom-tools', JSON.stringify([ /* ... */ ]));

// Option B
(new mw.Api()).saveOption('userjs-custom-tools', JSON.stringify([ /* ... */ ]));

It will be parsed and used for setup if it exists.

Text above can be found here (edit)