TemplateScript

From Meta, a Wikimedia project coordination wiki
Jump to: navigation, search

TemplateScript is a powerful user script framework for adding custom one-click templates and scripts to your sidebar. Essentially:

  1. create templates (bits of text that can be inserted wherever you choose) or scripts (bits of JavaScript code that are executed);
  2. choose when they appear — always (even when reading), by namespace, action (like 'edit' or 'move'), or arbitrary conditions;
  3. click the sidebar link (or press the keyboard shortcut) to instantly insert your custom template or run your custom script.

It's compatible with all Wikimedia skins and common browsers.

Introduction[edit]

When you first install TemplateScript, you should see a new navigation box labeled 'TemplateScript' at the bottom of your sidebar. (This is the default — you can add as many new links or navigation boxes you want.)

TemplateScript initial menu.png

You can click the 'Regex editor' link to activate that example script. This tool lets you apply any number of regular expressions to the text, and save them for later use. For example, you could define a series of changes to close a request or update a template, then save those steps and apply them to any other page in two clicks. The regex editor looks like this:

Regex editor for TemplateScript.png

The regex editor is just an example of what you can do — TemplateScript is really meant for you to create your own scripts and templates. A template is really just a bit of text that gets added to the page when you click on it (you can choose where it gets added). A script is a bit of JavaScript that gets run when you click its link, so you can do anything (the regex editor is just a script). You can also assign keyboard shortcuts to templates or scripts to use them more quickly.

The easiest way to get started is to copy the 'welcome' example from the installation sample code, and change the name and text. To really delve in, you can read the documentation below.

Usage[edit]

Installation[edit]

  1. Copy the following code to your common.js page.
    /**
     * TemplateScript adds configurable templates and scripts to the sidebar, and adds an example regex editor.
     * @see https://meta.wikimedia.org/wiki/TemplateScript
     */
    // <pre>
    $.getScript('//tools.wmflabs.org/meta/scripts/pathoschild.templatescript.js', function() {
    	pathoschild.TemplateScript.Add([
    		{ name: 'welcome', template: '{{subst:welcome}} ~~~~', position: 'after', editSummary: 'welcome!', forNamespaces: 3, forActions: 'edit' },
    		// add your own templates or scripts here
    	]);
    });
    // </pre>
    
  2. Refresh your browser to reload the JavaScript. (In Chrome or Firefox, press [CTRL] and [R] at the same time.)

Creating templates[edit]

You define templates and scripts by passing a Template-like object to the pathoschild.TemplateScript.Add() function. Here's an example of several Template options. This will create a new sidebar box with the header "Being nice", with a link with the text "Welcome" — but only if you're editing a user's talk page (forNamespaces). When you click the link, it will insert "{{subst:welcome}} ~~~~" at the bottom of the edit box, and set the edit summary to "Welcome!".

pathoschild.TemplateScript.Add({
	category: 'Being nice',
	name: 'Welcome',
	template: '{{subst:welcome}} ~~~~',
	position: 'bottom',
	editSummary: 'Welcome!',
	forNamespaces: 3
});

You can also pass an array of templates to the function:

pathoschild.TemplateScript.Add([
	{
		category: 'Being nice',
		name: 'Welcome',
		template: '{{subst:welcome}} ~~~~',
		position: 'bottom',
		editSummary: 'Welcome!',
		forNamespaces: 3
	},
	{
		category: 'Being nice',
		name: 'Hi',
		template: '{{subst:hi}} ~~~~',
		position: 'bottom',
		editSummary: 'Hi!',
		forNamespaces: 3
	}
]);

If you need to repeat some values, you can use the alternative pathoschild.TemplateScript.AddWith() function that lets you specify common fields. For example, this code is equivalent to the last example:

pathoschild.TemplateScript.AddWith(
	{category:'Being nice', position:'bottom', forNamespaces:3},
	[
		{ name:'Welcome', template:'{{subst:welcome}} ~~~~', editSummary:'Welcome!' },
		{ name: 'Hi', template:'{{subst:hi}} ~~~~', editSummary:'Hi!' }
	]
);

See Template for a full list of options you can pass.

Template objects[edit]

Template
The pathoschild.TemplateScript.Template object contains all the options for a template or script. You must specify a name and template (or script), but all other fields are optional.
User interface and enabling:
option type default value purpose
name string (required) The name displayed as the sidebar link text.
enabled boolean true Whether this template is available.
category string 'TemplateScript' An arbitrary category name (for grouping templates into multiple sidebars), or null to use the default sidebar.
forActions string or string[] (all actions) The wgAction values for which the template is enabled.
forNamespaces int or int[] (all namespaces) The namespaces in which the template is enabled.
accessKey string none A keyboard shortcut that will instantly apply the template or script. This should be a single key like 'x' or '1', which will be combined with your browser's shortcut sequence (for example, in Chrome you'd press ALT+x). See w:Wikipedia:Keyboard shortcuts for your browser's keyboard shortcut sequence.
Behaviour:
option type default value purpose
template string null The text to insert into the main input box.
position string 'cursor'
or 'replace'
The position at which to insert the template. The default value is 'cursor' when editing a page, and 'replace' in all other cases.
isMinorEdit boolean false Whether to mark the edit as minor (if applicable).
editSummary string null The edit summary to use (if applicable).
editSummaryPosition string 'replace' The position at which to insert the edit summary.
headline string null The subject or headline to use (if applicable). This appears when editing a page with &section=new in the URL.
headlinePosition string 'replace' The position at which to insert the headline.
Scripting:
option type default value purpose
autoSubmit boolean false Whether to submit the form automatically after insertion.
script function null An arbitrary JavaScript function that is called after the template and edit summary are applied, but before autoSubmit. It is passed a reference to the Context object.
Position
The pathoschild.TemplateScript.Position values represent the insertion behaviour. These can be specified either as a constant (pathoschild.TemplateScript.Position.cursor) or by name ('cursor').
value meaning
before Insert before the text.
after Insert after the text.
cursor Insert the template at the current cursor position (replacing the selected text, if any).
replace Replace the current text entirely.
Context
The pathoschild.TemplateScript.Context object provides convenient access to properties about the current page. This is passed to Template scripts. (This object is populated by TemplateScript; changing the values yourself may cause unexpected behaviour.)
value type meaning
namespace int The number of the current namespace.
action string The current MediaWiki action.
singleton pathoschild.TemplateScript The TemplateScript instance for the page.
$target jQuery The primary input element (e.g., the edit textarea) for the current form.
$editSummary jQuery The edit summary input element (if relevant to the current form).

Examples[edit]

  • A simple template and a simple script:
    pathoschild.TemplateScript.Add([
    	{
    		name: 'header',
    		template: '{{header | some parameter = true }}',
    		position: 'before',
    		editSummary: 'added {{header}}',
    		forNamespaces: 0,
    		forActions: 'edit'
    	},
    	{
    		name: 'alert test',
    		script: function ($target) {
    			alert('The edit box says: "' + $target.val() + '".');
    		},
    		forActions: 'edit'
    	}
    ]);
    
  • A combination template and script:
    pathoschild.TemplateScript.Add({
    	name: 'current URL',
    	template: '<$URL>',
    	script: function (context) {
    		context.$target.val(context.$target.val().replace(/<\$URL>/g, location.href));
    	}
    });
    
  • A more comprehensive example, showing a full list of deletion templates for the English Wikisource, complete with logic to only show the relevant templates:
    /* editing pages */
    pathoschild.TemplateScript.AddWith(
    	{ forActions: 'edit' },
    	[
    		/* main namespace */
    		{
    			name: 'header',
    			template: '{{header\n | title    =\n | author   =\n | section  =\n | previous =\n | next     =\n | notes    =\n}}',
    			position: 'before',
    			forNamespaces: 0
    		},
     
    		/* talk namespace */
    		{
    			name: 'featured talk',
    			template: '{{featured talk\n | month   = {{subst:CURRENTMONTH}}\n | year    = {{subst:CURRENTYEAR}}\n | archive = {{subst:CURRENTYEAR}}/{{subst:CURRENTMONTH}}\n}}',
    			forNamespaces: 1
    		},
    		{
    			name: 'textinfo',
    			template: '{{textinfo\n| edition      =\n| source       =\n| contributors =\n| progress     =\n| notes        =\n| proofreaders =\n}}',
    			position: 'before',
    			editSummary: '{{textinfo}}',
    			forNamespaces: 1
    		},
     
    		/* author namespace */
    		{
    			name: 'author',
    			template: '{{author\n |name           =\n |last_initial   =\n |dates          =\n |description    =\n |image          =\n |wikipedia_link =\n |wikiquote_link =\n |commons_link   =\n}}',
    			forNamespaces: 102
    		}
    	]
    );
     
    /* deleting pages */
    pathoschild.TemplateScript.AddWith(
    	{ forActions: 'delete', category: 'Consensus' },
    	[
    		{
    			name: 'Copyvio discussion',
    			template: '[[WS:COPYVIO|Possible copyright violation]]',
    			category: 'Consensus'
    		},
    		{
    			name: 'Proposed',
    			template: '[[WS:DEL|Proposed deletion]]',
    			category: 'Consensus'
    		}
    	]
    );
    pathoschild.TemplateScript.AddWith(
    	{ forActions: 'delete', category: 'Speedy' },
    	[
    		{
    			name: 'G1 no meaningful',
    			template: '[[WS:CSD|Criteria for speedy deletion]] G1 ("No meaningful content or history.")'
    		}, {
    			name: 'G2 recreation',
    			template: '[[WS:CSD|Criteria for speedy deletion]] G2 ("Reposted content previously deleted...")'
    		}, {
    			name: 'G3 banned user',
    			template: '[[WS:CSD|Criteria for speedy deletion]] G3 ("content created and edited solely by a banned user after they were banned...")'
    		}, {
    			name: 'G4 redundant',
    			template: '[[WS:CSD|Criteria for speedy deletion]] G4 ("Two versions of the same text on different pages...")'
    		}, {
    			name: 'G5 beyond scope',
    			template: '[[WS:CSD|Criteria for speedy deletion]] G5 ("...clearly lies outside the [[WS:WWI|scope of Wikisource]]...")'
    		}, {
    			name: 'G6 copyvio',
    			template: '[[WS:CSD|Criteria for speedy deletion]] G6 ("...clear and proven copyright violation...")'
    		}, {
    			name: 'G6 re-copyvio',
    			template: '[[WS:CSD|Criteria for speedy deletion]] G6 ("...content previously deleted as a copyright violation...")'
    		}, {
    			name: 'G6 copyvio author',
    			template: '[[WS:CSD|Criteria for speedy deletion]] G6 ("...author pages for authors whose works are all copyrighted...")'
    		}, {
    			name: 'G7 author\'s request',
    			template: '[[WS:CSD|Criteria for speedy deletion]] G7 ("Deletion per request of the author...")'
    		}, {
    			name: 'A1 transwikied',
    			template: '[[WS:CSD|Criteria for speedy deletion]] A1 ("Articles [[m:transwiki|transwikied]] to another project...")'
    		}, {
    			name: 'A1 transwikied (commons)',
    			template: '[[WS:CSD|Criteria for speedy deletion]] A1 ("...images uploaded to the [[commons:|Wikimedia commons]] with the original contributor noted...")'
    		}, {
    			name: 'A2 non-notable',
    			template: '[[WS:CSD|Criteria for speedy deletion]] A2 ("...not significantly peer-reviewed or previously published in a significant edition or forum.")'
    		}, {
    			name: 'A3 no authorship info',
    			template: '[[WS:CSD|Criteria for speedy deletion]] A3 ("Works without authorship information...")'
    		}, {
    			name: 'M1 trivial',
    			template: '[[WS:CSD|Criteria for speedy deletion]] M1 ("...deletion as part of a page move or history merge, as long as the action requiring the deletion is uncontroversial.")'
    		}, {
    			name: 'M2 redirect (new)',
    			template: '[[WS:CSD|Criteria for speedy deletion]] M2 ("Unneeded redirects from page titles created within the last week...")'
    		}, {
    			name: 'M2 redirect (old)',
    			template: '[[WS:CSD|Criteria for speedy deletion]] M2 ("...[unneeded] redirects tagged with {{subst:dated soft redirect|"[[new title]]"}} for at least two months.")'
    		}, {
    			name: 'M2 redirect (broken)',
    			template: '[[WS:CSD|Criteria for speedy deletion]] M2 ("...Redirects to inexistant pages...)"'
    		}, {
    			name: 'M3 redirect (article to other ns)',
    			template: '[[WS:CSD|Criteria for speedy deletion]] M3 ("Internamespace redirects from the article namespace to any other namespace.")'
    		}, {
    			name: 'M4 talk page',
    			template: '[[WS:CSD|Criteria for speedy deletion]] M4 ("Unneeded talk: a discussion page for deleted or inexistant content.")'
    		}
    	]
    );
     
    /* various forms */
    pathoschild.TemplateScript.Add([
    	{
    		forActions: 'protect',
    		name: 'featured',
    		template: '[[WS:FT|Featured text]] (see the [[WS:PP|protection policy]])',
    		position: 'replace'
    	},
    	{
    		forActions: 'move',
    		name: 'standardized',
    		template: '[[WS:STYLE|Standardised]]',
    		position: 'replace'
    	}
    ]);
    

Troubleshooting[edit]

  1. Don't use $element.text() or $element.html() to edit input boxes.
    Always use $element.val() to change input box content. The $element.text() or $element.html() methods modify the element HTML directly, not the current value — these will cause the user's changes to be lost.

Regex editor[edit]

TemplateScript includes a default tool called the regex editor (see live example), which lets you define any number of custom regular expressions and apply them to the text. You can disable this feature by adding the following code before TemplateScript:

var pathoschild = pathoschild || {};
pathoschild.disableRegexEditor = true;


As a gadget or framework[edit]

TemplateScript is designed to work well as a gadget (or even multiple gadgets). You can simply call it many times the same way, and it will smartly extend the first instance. This also makes it very suitable as a framework for your own scripts — it will take care of creating a navigation box and links for you, and the user can enable many similar gadgets and have all their tools neatly organised together.

Here's how to initialise an example script created using TemplateScript:

/**
 * Amazing Gadget does some pretty cool stuff.
 * @see https://example.com/amazing-gadget
 */
$.getScript('//tools.wmflabs.org/meta/scripts/pathoschild.templatescript.js', function() {
	pathoschild.TemplateScript.Add([
		{ category: 'Amazing Gadget', name: 'Do cool stuff', script: function() { MyGadget.DoStuff(); } }
	]);
});

If you want your script to always be available (not only when editing or doing something), just leave out the options like forNamespace or forAction.

See also[edit]