How to enhance wiki content with JavaScript: Difference between revisions

This is a draft mostly written in 2013. For current documentation on developing gadgets, refer to Manual:Interface/JavaScript, Extension:Gadgets, and Gadget kitchen. For current docs on how to use ResourceLoader, refer to ResourceLoader/Developing with ResourceLoader.

This is a guide for how, as contributors to a wiki, you can develop JavaScript to make a wiki page interactive.

Dynamic content

Wikitext is a powerful markup language, which allows end-users of the MediaWiki platform to build dynamic portals, forms, and interactive experiences directly into content pages without involvement from server administrators. Examples of primitivites that enable dynamic server-rendered content are: templates, magic words, parser functions, and Lua modules.

While the above capabilities make nearly everything possible that raw HTML, server-side PHP, or client-side JavaScript could do; we don't allow any of those directly on wiki pages as that would pose significant security risks and hamper long-term support and compatibility. Well-written content is expected to work indefinitely, whereas native extensions must follow release cycles of MediaWiki (Stable interface policy) or upstream PHP/Linux, etc.

As a security precaution to prevent attacks against the wiki, most HTML elements cannot be constructed via wikitext. Static content is generally supported both in wikitext syntax and through HTML-like syntax. Images and hyperlinks are possible via dedicated syntax that naturally disallows unsafe content.

This means that you cannot load Google AdSense banners, Facebook buttons, Disqus widgets, or embed any other scripts into wiki content. You should also never take input from wikitext or URL parameters such that arbitrary HTML or JavaScript can be formed or loaded as that would result in the same security vulnerabilities, which could e.g. result in security and privacy leaks (PII, reading habits, passwords, etc.).

Personal scripts

Individual editors can write customisations for themselves via Personal scripts under their user account. These can also be shared peer-to-peer with other users.

Default site scripts

Elected content administrators and on-wiki interface admins can develop JavaScript via site scripts such as Common.js or a Gadget. Both of these reside in the "MediaWiki" namespacec that is restricted to administrators.

Adding the HTML and JavaScript

Creating the script

jQuery is is bundled with MediaWiki core. You can write your script like this:

$(function () {
	var myPlace = document.getElementById('tpl-example-placeholder');
	myPlace.innerHTML = 'any HTML';
}());

$(function () {
	$('#mw-mywiki-example').html('any HTML');
}());

Separate script

If your script gets too long or you want to keep snippets from a third-party library separate, you can create a new file in the MediaWiki namespace (ending in .js), e.g. MediaWiki:Example.js. And then instruct MediaWiki to import that script. To do this, add an import script instruction to MediaWiki:Common.js:

importScript('MediaWiki:Example.js');

Enable on a wiki page

To display the widget on a wiki page, it is recommended to create a template in order to make it easy to re-use. For example, it could be called Template:Example.

Add the following code to the template. Make sure the ID matches the identifier you specified in your script earlier.

<div id="tpl-example-placeholder">...</div>

You can use any tags or attributes to style the template and the content being added. Just make sure that you keep the identifier the same.

Enable it on a page by including the template on any wiki page(s) you want the script to apply:

{{Example}}