Help:TemplateScripts

From Wikimedia Commons, the free media repository
Jump to navigation Jump to search

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

Installation[edit]

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
$( '[data-templatescript]' ).each( function () {
	var script = $( this ).data( 'templatescript' );
	if ( script && /^[^&<>=%#]*$/.test( 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.

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

So far there are only few template scripts available:

Development[edit]

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 and mw.Api) and restrictions. 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[edit]

TemplateScripts open the door to the huge potential of the JavaScript programming language. To list all possibilities is impossible, but here are a few ideas that may serve as 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 the jQuery library
  • Use data attributes to pass data to the script and do complex processing or advanced behavior switches (example)

Good script design guidelines[edit]

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

  • Discussions: first (English Wikipedia), second (Spanish Wikipedia), third (English Wikipedia), fourth (Commons)
  • phab:T131436 - Experimental interface for embedding with partial security isolation. With further development, this will probably merge with WikiWidgets to provide infrastructure for widgets that are easier to review for security.
  • Category:TemplateScripts - Files used by template scripts