Help:TemplateScripts

This is the central documentation for the TemplateScripts project.

TemplateScripts (formerly WikiWidgets) are JavaScript scripts that extend the functionality of wiki templates. Currently, TemplateScripts are enabled only in the Spanish Wikipedia, the English Wikiversity and the Spanish Wikiversity, but can be easily enabled in any wiki.

Installation

To enable TemplateScripts in your wiki, add the following code to MediaWiki:Common.js (and MediaWiki:Mobile.js):

// TemplateScripts are JavaScript scripts that extend the functionality of templates
var templatescripts = [];
$( '[data-templatescript]' ).each( function () {
	var script = $( this ).data( 'templatescript' );
	if ( script && !templatescripts.includes( script ) && /^[^&<>=%#]*$/.test( script ) ) {
		templatescripts.push( script );
		script = encodeURIComponent( script );
		mw.loader.load( '/wiki/MediaWiki:TemplateScript-' + script + '?action=raw&ctype=text/javascript' );
	}
} );

With this code, any element (for example a <div>, <span> or table) with the attribute data-templatescript="Example.js" will load the JavaScript found at MediaWiki:TemplateScript-Example.js

The code is quite simple so you can easily adapt it to the needs of your community. However, the restriction to the MediaWiki namespace is essential to prevent security risks, and the restriction to the "TemplateScript-" prefix is important to prevent this code from loading other scripts in the MediaWiki namespace that could cause trouble. Finally, the check to prevent the same script from loading more than once is important because otherwise some template scripts may load dozens or even hundreds of times per page, causing unnecessary load on the server.

After this code has been added, you can start creating or extending templates with custom JavaScript in the MediaWiki namespace. However, because only trusted users can edit the MediaWiki namespace, all JavaScript will have to go through some kind of review process to get there. Each wiki will have to figure out the best way to do it, respecting local practices and conventions, as well as global rules and policies.

Available template scripts

• Form - Create forms that inject content into other pages
• Sign - Easily sign in votes, polls and wikiprojects (live example)
• Vivarium (latin for 'place of life') - Creates an interactive version of Conway's Game of Life (live example)
• Formicarium (latin for 'place of ants') - Creates an interactive version of Langton's ant (live example)
• ExcerptTree - See and navigate excerpt trees (live example)
• Wikidebate - Tools for wikidebates (live example)

Development

To develop a new script, you can start by experimenting in your personal common.js. JavaScript that you put there will run only for you, but otherwise there will be little difference with a TemplateScript, you'll have access to the same libraries (for example jQuery, OOUI and mw.Api) and code will be executed at the same point (after the page loads). Once your code is stable, you can request a review and promotion to the MediaWiki namespace, where it can be loaded from any template and for every user.

Script possibilities

TemplateScripts opens the door to the huge potential of the JavaScript programming language. To list all possibilities is impossible, but here are a few teasers:

• Add HTML elements that templates normally don't permit, like <canvas> (example)
• Add HTML attributes that templates normally don't permit, like contenteditable (example)
• Call the Wikipedia API using the friendly mw.Api library (example)
• Modify HTML and CSS in advanced and dynamic ways, for example using jQuery
• Use data attributes to pass data to the script and do complex processing or advanced behavior switches (example)

Good script design guidelines

• You can design your script for your wiki only, but you can also try to generalize it to be usable by other wikis (example). If you do so, consider hosting it at Commons (example) and have other wikis load it from there (example).
• Versioning is key to keep track of which version of each script is being used in each wiki (example).
• Separation of concerns can be achieved by moving HTML to the template (example) and CSS to a separate stylesheet (example) that can then be loaded via TemplateStyles or from the template script (example).
• One template may load several template scripts, and one template script may load other template scripts too, so consider writing modular and reusable scripts. However, don't abuse dependencies since (in the current system) each script is an additional request.
• Encapsulate your code within a class to keep it tidy and avoid unnecessary naming conflicts (example).

See also

• Discussions: 1st (English Wikipedia), 2nd (Spanish Wikipedia), 3rd (English Wikipedia), 4th (Commons), 5th (Spanish Wikipedia), 6th (English Wikipedia)
• phab:T131436 - Experimental interface for embedding with partial security isolation. With further development, this will probably merge with TemplateScripts to provide infrastructure for scripts that are easier to review for security.
• Category:TemplateScripts - Files used by template scripts