Chapter 12 Modules, gadgets and widgets
In MediaWiki, there is text created by users and code created by developers, but there is also the stuff that is in between: code that is entered into wiki pages and can then be run. There are three notable extensions, Scribunto, Gadgets and Widgets, that let users (usually only ones with special access) create relatively small snippets of code that can be used throughout the site. In Scribunto they are “modules”, written in Lua; in Gadgets they are “gadgets”, written in JavaScript; and in Widgets they are “widgets”, written in the templating language Smarty. Let's go through each of them in turn.
Scribunto
The Scribunto extension allows for creating “modules
”, written in the scripting language Lua,
which can include sophisticated logic and text processing. A module is a page in the “Module:” namespace.
To call a module, you use the parser function #invoke, in the manner:
{{#invoke:Module name|main|arguments}}
Let's look at a simple case of how it can be useful. On the English-language Wikipedia, there are thousands of module pages; among them is Module:Gallery, which lets you display a gallery of images in a more sophisticated manner (i.e., with more options) than the standard MediaWiki <gallery> tag (see here).
That page, like all other module pages, contains a set of Lua code; here is a snippet of it:
for i = 1, imageCount dolocal img = trim(args[i*2 - 1] or '')local caption = trim(args[i*2] or '')local alt = trim(args['alt' .. i] or '')if img ~= '' thentable.insert(gallery, img .. (alt ~= '' and ('|alt=' .. alt) or '') .. '|' .. caption )endendtbl:tag('div'):addClass('main'):tag('div'):wikitext(frame:extensionTag{ name = 'gallery', content = '\n' .. table.concat(gallery,'\n'), args = gargs})
The overall code takes a set of image names and creates an HTML table out of it, to be displayed. The exact details of this code are not important - and if you're not a programmer, that's fine too. But a few aspects of it should be noted:
- The set of images is passed in as a set of parameters (the “args” array), and the code loops through them. That means that there can be any number of arguments, i.e. images. That is in sharp contrast with templates, where each parameter has to be declared separately, so you can only approximate loops by having parameters like “p1”, “p2”, etc. – which is both awkward and sets a hard limit on the number of allowed parameters.
- The code, as complex as it looks, is quite a bit more readable than any equivalent template's wikitext would look. (There is not a single curly bracket here!)
The “Gallery” module is in turn called by the “Gallery” template, which is simply a “wrapper” around the module; its entire text reads:
{{#invoke:Gallery|gallery}}<noinclude>{{Documentation}}</noinclude>
This module is an extreme example: many other modules are only responsible for some complex bit of text handling, but this one takes over the entire handling of a template. But it's certainly a demonstration of the power of Lua modules, both in making less awkward syntax and in in increasing the power of templates.
You can read more about Scribunto, and Lua, here:
Gadgets
The Gadgets extension lets an administrator define pieces of JavaScript that users can then make use of, usually for help with editing or other wiki tasks. You can see the full list of gadgets installed on any wiki by going to that wiki's Special:Gadgets page, which lists all the gadgets and a brief description of each.
To install a gadget on a wiki, if it already exists on another wiki, go to that wiki's Special:Gadgets page, click on the gadget's “Export” link, and follow the instructions.
Any user can then use any installed gadget by going to the “Gadgets” tab within their Preferences page, checking the gadgets they want installed, and hitting “Save”.
There are many gadgets defined; two notable ones, both available on Wikipedia, are:
- Navigation popups – lets users see the top contents of a page, and a menu of action items for that page, when they hover over a link to it. (This functionality is also available via an extension, “Popups” (https://www.mediawiki.org/wiki/Extension:Popups).
- HotCat – provides autocompletion when adding or editing categories for a page.
You can read more about the Gadgets extension here:
Widgets
A wiki doesn't usually consist of text alone, and often it's helpful to embed outside media into the pages. MediaWiki itself doesn't allow for embedding HTML and JavaScript within pages, though (see here for more information), which means that audio and video players, and other content like RSS viewers, can't be added by default into MediaWiki. To get around this problem, a staggering array of extensions have been created, tasked with embedding specific players and widgets. Of the around 1,000 extensions listed on mediawiki.org, 44 are in the "Video player extensions" category; and around 12 exist for YouTube alone. Each one embeds into the wiki page some variation of the required HTML and JavaScript. However, the Widgets extension makes all of these unnecessary.
The Widgets extension is simple in concept: it allows for creating bits of custom HTML and JavaScript that can be embedded on a page. Each snippet of HTML and JavaScript, representing a single "widget", is stored directly within the wiki, in a page in the "Widget:" namespace.
Widgets can also store code, in the Smarty language – a PHP-based “template engine”. This lets widgets modify the output with parameters, and use “if” calls and the like.
Due to the obvious security danger of allowing free HTML and JavaScript in pages, editing in the “Widget:” namespace is restricted to users in the 'mediawikiwidgets' group.
There is no need to “re-invent the wheel”, and a large number of pre-defined widget pages already exist for the Widgets extension, and can be viewed at mediawikiwidgets.org. These represent video players, audio players, RSS readers, displays of information from individual websites like Facebook and Amazon, and others.
There, click on “View source”, copy the entire contents, and paste it to the page “Widget:YouTube” on your wiki. After that, embedding a video in a page is just a matter of adding something like:
{{#widget:YouTube|id=video ID}}
...to the page, where "video ID" is YouTube's own ID for the video, viewable in the URL. Each widget can define as many parameters as it wants; the YouTube widget defines only one, for the ID. There are other parameters that this widget could have had, though: YouTube allows for settings for its embedded videos such as the color of a border rectangle, for example. Part of the beauty of the Widgets extension is that you can modify a widget yourself, once it's on your wiki, in order to, among other things, add more parameters to it.
These widgets don't necessarily have to involve embedded media of any kind – after all, they're simply a mechanism for creating text based on a set of parameters. To some extent, Widgets is thus an alternative to the Scribunto extension – though Scribunto is recommended if there's any serious amount of logic being done in the code.