TemplateScripts

From mediawiki.org
(Redirected from TemplateScript)

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

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
 * Documentation at https://www.mediawiki.org/wiki/TemplateScripts
 */
var templatescripts = [];
$( '#mw-content-text [data-templatescript]' ).each( function () {
	var script = $( this ).attr( 'data-templatescript' );
	if ( script && !templatescripts.includes( script ) && /^[^&<>=%#]*\.js$/.test( script ) ) {
		templatescripts.push( script );
		script = encodeURIComponent( script );
		mw.loader.load( '/w/index.php?title=MediaWiki:TemplateScript-' + script + '&action=raw&ctype=text/javascript' );
	}
} );

With this code, any HTML tag (for example a <div> or <span>) 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[edit]

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

TemplateScripts open the door to the huge potential of the JavaScript programming language. Possibilities are endless, 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[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 a central wiki like MediaWiki.org or Commons (example) and have other wikis load it from there (example). If you don't, then versioning can be useful to keep track of which version is being used in each wiki.
  • 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 itself (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 each one fires an additional web request.
  • Encapsulate your code within a class to keep it tidy and avoid unnecessary naming conflicts (example).

See also[edit]

Retrieved from "https://www.mediawiki.org/w/index.php?title=TemplateScripts&oldid=6422745"