YK: Chapter 13: Display and customization

13 Display and customization

MediaWiki allows for a lot of customization of its look-and-feel, including changing the text of the interface itself. Such customization is available for both for administrators and users -- we’ll get to both in this chapter.

User preferences

Every logged-in user on a wiki can change many of their settings via the Special:Preferences page. This page is available conveniently through a link at the top of the page (in most skins), called “Preferences”. This page is split up into tabs, and lets you change a wide variety of settings: the skin you use (see the next section), your language of choice, your time zone, your preferred way to display the time, and a variety of other settings relating to the look-and-feel of the rest of MediaWiki’s functionality. You can choose which “gadgets” you want to use, out of the ones installed on this wiki (see here).

From this page, you can also make changes to your basic user account -- your password and email address. Users cannot change their username, though ­ usernames can’t be changed at all within core MediaWiki, though the Renameuser extension, which comes bundled in with MediaWiki, lets administrators do it.

Skins

In MediaWiki, a "skin" is the set of PHP and CSS files used to specify the display a wiki. MediaWiki, like any good content-management system, separates out the content of the display from its look. The files for all the skins are stored within the /skins directory. Each skin is represented by a file within that directory, and, in most cases, a sub-directory as well.

Every installation of MediaWiki has a default skin, that users see if they’re either not logged in or haven’t changed their settings. Additionally, users, if they’re logged in, can change the skin that they view the wiki with, by going to Special:Preferences, then going to the "Skins" tab ­ there they can select among any of the skins installed on that wiki. Unlike most good content-management systems, MediaWiki makes it rather difficult to create and maintain good skins. Part of the problem is that the set of functions that need to be defined and called by the skin keeps changing with new MediaWiki versions; although the rate of change seems to have subsided in more recent versions.

If you do want to create a custom skin, by the way, this is a good tutorial, by Daniel Friesen, that explains the basics:

http://blog.redwerks.org/2012/02/08/mediawiki-skinning-tutorial/

Before 2010, MediaWiki’s built-in skins were, all-in-all, underwhelming. The default skin until then, MonoBook, was criticized for its lackluster design and (to some) difficulty of navigation. But MonoBook itself shines in comparison with the older skins that were created for MediaWiki, a small and dwindling number of which remain bundled with the application. The Wikipedia Usability Initiative, which ran during all of 2010, took a methodical approach to the problem of the interface, hiring interface designers and, for the first time, doing large-scale usability testing. The most important result of the initiative was the creation of the current default skin, Vector. This is a clean, functional skin that has gotten high marks from users.

The current best place to find alternative MediaWiki skins, or at least to be inspired by the possibilities, is the “Gallery of user styles”, here:

https://www.mediawiki.org/wiki/Manual:Gallery_of_user_styles

At the moment, many or most of the skins listed there are out of date, though.

One notable skinning framework that has been gaining a lot interest recently is Bootstrap, which was originally created for Twitter. It makes modifications like changing around colors easy to do, and the skins it generates are responsive (see section below).There are a few different MediaWiki-based implementations for Bootstrap; the most commonly-used one at the moment is the “Bootstrap” extension:

https://www.mediawiki.org/wiki/Extension:Bootstrap

At least one skin, Chameleon, makes use of this extension already:

https://www.mediawiki.org/wiki/Skin:Chameleon

One interesting, unconventional usage of skins is as a way to turn a wiki into a more standard content-publishing system. The idea is that users who can edit the wiki (of whom there will be relatively few), and who are logged in, will see the wiki with a normal skin; while the majority of users/readers, who aren’t logged in, will see the wiki with a custom skin that doesn’t show the history and edit tabs, the standard sidebar, etc.: it’s a lightweight method of making a regular-looking website with the editing convenience of a wiki. The custom actions are usually still there, if users manually type in URLs that end with "action=history" and the like; but the absence of links on the screen will mean that the vast majority of users will never know that there’s a wiki behind the scenes, let alone see the history of page, the set of recent changes, etc. If you go with this approach, you would still most likely want to block non-logged-in users from being able to edit the wiki, but that’s easy to accomplish (see here).

Mobile display

Until 2012 or so, mobile support for websites meant one of two things: either dedicated mobile apps showing the website’s content, or a mobile-friendly version of the site, sometimes located at a subdomain like "m.". However, in 2012 the concept of responsive web design began to really catch on. The term (which was invented in 2010) refers to websites that, through a clever use of HTML and CSS, manage to look good in all screen browser widths. As the browser width shrinks, horizontal image sets become more vertical, formerly-visible menu options get hidden within dropdowns, and text widths of course become smaller.

There is already a framework for developing responsive MediaWiki skins: Bootstrap (see previous section). It could be that in the future, Bootstrap-based skins will become not just more popular, but the dominant form of display for MediaWiki.

Another responsive MediaWiki skin ­ that isn’t based on Bootstrap ­ is Refreshed, which looks great in both standard tablet and standard cell phone widths:

https://www.mediawiki.org/wiki/Skin:Refreshed

What about the old style of mobile support ­ native apps and device-specific display? For both of those, support is still at an early stage. There are a variety of apps for viewing Wikipedia for both iOS and Android, including an official one, Wikipedia Mobile, developed by the Wikimedia Foundation. However, there don’t appear to be any apps for viewing an arbitrary MediaWiki wiki.

On the other hand, there are ways to get a mobile-friendly display from within the browser itself. If you go to Wikipedia on a smart phone, you’ll see a minimized, easy-to-read display even without a Wikipedia app. That’s accomplished through the MobileFrontend extension:

https://www.mediawiki.org/wiki/Extension:MobileFrontend

This extension can be installed on any MediaWiki site. Unfortunately, it seems to require using a proxy server (like Varnish), which detects the device making each web request, and modifies the request accordingly if it’s a mobile device, so that MediaWiki can know to return a different display. This is a rather substantial amount of extra work. And the resulting display lacks some important functionality ­ most notably, there’s no way to edit the page.

There is a Wikimedia Foundation project, named “Athena”, that is meant to overhaul the display of MediaWiki, including the creation of a mobile-friendly skin, which may also end up being called “Athena”, and which could be responsive. It is a project without a clear end date, but you can see more about it here:

https://www.mediawiki.org/wiki/Athena

Ads

If you run a public wiki, you may want to to put ads on it. Ads can be a good fit for wikis, because wikis tend to hold targeted content, and appeal to a targeted community. That’s certainly the case if your wiki is about a high-ad-revenue topic like insurance, lawyers or mortgages, but it can be true even if your wiki is about, say, model airplanes ­ or even Greek philosophers.

In MediaWiki, ads are usually placed either at the top of the page, or in the sidebar, or in both places. The easiest way to add ads to the wiki is to simply add the code directly to the skin you’re using: once you’ve signed up with the ad service (assuming you’re using an ad service), and gotten the HTML/JavaScript code snippet(s) for your site, you can just add them to the relevant parts of the skin, and everything should work automatically. There are two downsides to this approach, though: it means you’ll have to re-add that code every time you upgrade MediaWiki (assuming that the upgrade involves a skin upgrade as well), and it means that ads will only show up in one skin, or at least only on the skins you add the ad code to.

There are several extensions that handle the display of ads. Oddly, there is no one definitive extension that’s easy to set up, and allows you to put horizontal banner ads at the top and bottom of the page, and a vertical one in the sidebar (ideally using Google AdSense, the most popular ad service. There are extensions that do subsets of this, though, and hopefully sometime soon an extension that handles all of it will come along. You can see the entire set of ad-displaying extensions here:

https://www.mediawiki.org/wiki/Category:Advertising_extensions

One notable extension in that group is AdManager, which allows setting of specific sidebar ads in specific pages, or groups of pages ­ it’s a more complex approach than that offered by the other ad extensions. You can read about it here:

https://www.mediawiki.org/wiki/Extension:AdManager

jQuery and ResourceLoader

MediaWiki has fairly sophisticated handling for JavaScript and CSS. Bundled within MediaWiki are the entire jQuery and jQuery UI JavaScript libraries; and MediaWiki has a component, ResourceLoader, that handles the display of JS and CSS intelligently. For MediaWiki developers, it’s very helpful to know about these components of MediaWiki, and they’re indispensable if your code contains any JavaScript or CSS. But even for MediaWiki administrators and users it can be helpful to know about them, so we’ll cover them in brief here.

jQuery is a third-party JavaScript library that simplifies a lot of typical JavaScript tasks considerably. Since its release in 2006, it has become, to some extent, a standard on the web. There are many other JS libraries available, but jQuery at the moment dominates the field: according to an ongoing survey at w3techs.com, jQuery is currently in use on an astounding 58% of all websites, and on 94% of websites that use any JavaScript library.

jQuery UI is a sibling library that adds to jQuery a large variety of standard interface utilities: drag-and-drop, animations, form inputs like date pickers, and so on. MediaWiki and some of its extensions make significant use of jQuery, and sometimes of jQuery UI as well ­ the Semantic Forms and Semantic Forms Inputs extensions (here and here) notably make significant use of jQuery UI.

ResourceLoader, or “the Resource Loader” as it’s sometimes known, is a component of MediaWiki that handles the addition of JavaScript and CSS onto the page. In regular web pages (and how it used to be in MediaWiki, until 2011), all the relevant JavaScript and CSS files are simply included on the page, usually on the top. But with ResourceLoader, MediaWiki and its extensions are meant to register all the JavaScript and CSS files they use, in the form of “modules”, and then ResourceLoader is responsible for placing the necessary JavaScript and CSS on the page. For both JavaScript and CSS, the content is displayed to the browser as one big file, and for JavaScript, the code is also minimized, or “minified”. In most cases, it’s also placed at the bottom of the page, instead of at the top. Because of the way browsers work, all of these changes make the display of pages significantly faster.

For the most part, the presence of ResourceLoader shouldn’t be noticed by users. The one exception to that is that, because by default the JavaScript and CSS is loaded at the end of the page instead of the beginning, users can sometimes see bare-looking text before formatting is applied to it. This sort of initial display is not unique to MediaWiki; it happens for every page where the JS and CSS are loaded last, and it’s referred to by web designers as a “flash of unstyled content”, or FOUC, which can be distracting to users. Specific modules can in fact be registered as being displayed on the top and not the bottom, and many already are, so this problem may go away entirely in the future.

A second version of ResourceLoader, ResourceLoader 2, is under development: its major planned new feature is the addition of JavaScript gadgets, defined using the Gadgets extension (see here), into the loading system. However, its development has been superseded by that of VisualEditor and other development priorities for the WMF, so there is no estimated completion date for the project.

You can read more about ResourceLoader, how it’s structured and its current development process, here:

https://www.mediawiki.org/wiki/ResourceLoader

MediaWiki: pages, and modifying the interface text

One relatively little-known feature of MediaWiki is the fact that you can modify the text of almost any part of the interface, directly through the wiki itself. You just need to find out the identifier of a particular piece of text (referred to in MediaWiki as a "message"), then go to the page named "MediaWiki:message-name". Take, for example, the "Summary" label that shows up at the bottom of the edit page. This turns out to be confusing for some users, who think that what they’re being asked to summarize is the entire page, not their most recent change. You may consider a label like "Description of edit" to be more useful. If you go to the page "MediaWiki:summary", and enter in the value "Description of edit", that’s how it will show up from then on to all users. To revert, you can simply delete the page.

Wikipedia itself contains some customizations. In MediaWiki the main tab for each page in the main namespace is called, by default, "Page". In the English-language Wikipedia, however, this tab instead appears as "Article". The name of the message holding that value is "nstab-main", and the content of the Wikipedia page "MediaWiki:Nstab-main", is the word "Article". (Looking at the page history, it appears that this value has been changed a number of times, most recently (at the time of this writing) on January 7, 2009.)

A downside of making such a modification is that it’s hard-coded to one language: if someone is viewing your wiki and has another language specified in their user preferences, they’ll normally see the entire interface in their language. But any messages that you modify will show up as that exact text to everyone, regardless of their language. (Whether it’s useful to view a wiki’s interface in one language if all the content is in another language, is a separate issue). But you can in fact set translations at the same time that you set a new value; that’s covered in the next section.

The most common usage of this functionality is to modify the sidebar. The sidebar, as odd as it sounds, is represented by a single "message". Here is the default value of the sidebar in the English language, in MediaWiki 1.22:

• navigation

• • mainpage|mainpage-description

• • portal-url|portal

• • currentevents-url|currentevents

• • recentchanges-url|recentchanges

• • randompage-url|randompage

• • helppage|help

• SEARCH

• TOOLBOX

• LANGUAGES

The last three lines are standard elements that have special handling, so their connection to the display is not obvious, but Figure 13.1 shows how that appears in the sidebar within the standard Vector skin (and with the Semantic MediaWiki extension installed, which adds the “Browse properties” link).

[]

Figure 13.1 Default sidebar display, in the Vector skin, with Semantic MediaWiki installed

The structure is fairly simple: a single asterisk indicates a section header, while two asterisks indicate an item within that section. Each item can be thought of as a MediaWiki link: it can either be a single string, in which case the link text and the linked page are the same, or it can be two strings separated by a pipe, with the first string as the page being linked to and the second, the link text. The only difference between the strings in the sidebar and regular MediaWiki links is that strings in the sidebar can be (and often are) language messages themselves. Note the "recentchanges" string in the sidebar, for instance: when displaying the sidebar, the system searches for a language value for "recentchanges" ­ it finds it ("Recent changes"), and substitutes that in. If no value had been found, the text "recentchanges" would simply have appeared as is.

Another popular usage of this functionality is to change the copyright text in the edit page, at MediaWiki:copyrightwarning. By default it looks like:

Please note that all contributions to Blik are considered to be released under the $2 (see $1 for details). If you do not want your writing to be edited mercilessly and redistributed at will, then do not submit it here.
You are also promising us that you wrote this yourself, or copied it from a public domain or similar free resource. Do not submit copyrighted work without permission!

Whenever you see values like $1, etc., it means that they’re placeholders to be filled in by the PHP code that displays those messages. In the case of the copyright warning, the values $1 and $2 are filled in with values derived from a combination of various global variables, settable in LocalSettings.php: $wgRightsPage, $wgRightsText and $wgRightsUrl.

How can you find out the name of a certain message? Fortunately, MediaWiki offers a clever way to do it ­ if you add "?uselang=qqx" to the URL of any page in the wiki (or "&uselang=qqx", if there was already a question mark in the URL), it will show the name of every message, in place of the value. So all you have to do to find the name of a message is go to a page that contains that message, add the "uselang=qqx" to the URL, and see what shows up in place of that message.

A special page, "Special:AllMessages", also exists, that shows the full set of message names and their values in the wiki’s current language.

Deleting a message page will revert that message back to its original value.

Customizing the site’s CSS and JavaScript

Some pages in the MediaWiki namespace are used for something other than defining interface text: adding additional JavaScript and CSS to the wiki’s pages. The most important of these are MediaWiki:Common.css and MediaWiki:Common.js. MediaWiki:Common.css contains CSS that is applied to every page in the wiki. Very often, this file is used to define ’prettytable’ and ’wikitable’, two CSS classes that are usually defined as synonyms of one another, used to make tables look nicer than the HTML default (MediaWiki skins rarely apply any special display to tables, for some reason.)

MediaWiki:Common.js, as you could guess, is meant to contain custom JavaScript that will be added to every page. It is often used to add additional functionality to help with the viewing or editing experience. The more standardized way to add such functionality is via the Gadgets extension (see here), although there you’re restricted to the gadgets that the administrator has selected for the wiki (this may change in the future).

In addition to Common.css and Common.js, there are pages that you can use to define custom JavaScript or CSS to be used only for one skin, or only for one user group. These follow a standard naming convention: to add CSS only for the MonoBook skin, for instance, you would add it to the page MediaWiki:monobook.css, while to add CSS only for the “bureaucrat” group, you would add it to the page MediaWiki:group-bureaucrat.css.

Site notice

You can set a message to be displayed at the top of every page; this is useful when you want to make a general announcement, such as that there will be an upcoming site outage, or that the wiki has some new feature, or that volunteers are needed for some task, etc. This can be done in a variety of ways:

Setting the global variable $wgSiteNotice in LocalSettings.php.

Modifying the page “MediaWiki:sitenotice”.

Modifying the page “MediaWiki:anonnotice” ­ this displays a notice only for anonymous, non-logged-in users.

Using the extension CentralNotice ­ this is a fairly heavy-duty extension, that allows for coordinating an entire “campaign” of banner ads and the like among a group of wikis; it is used by the Wikimedia Foundation during its annual fundraising drive:

https://www.mediawiki.org/wiki/Extension:CentralNotice

Using the extension DismissableSiteNotice ­ this extension displays a site notice that users can dismiss by clicking on a link, after which they won’t see it again:

https://www.mediawiki.org/wiki/Extension:DismissableSiteNotice

Language support

MediaWiki’s support for different written languages is a major point of pride; it appears to be unsurpassed by any other software. MediaWiki has been translated, at least to some extent, into over 400 languages, from Abkhazian to Zeeuws, including variants you might not think of as separate languages, such as Austrian German and Latin American Spanish. Its secret weapon in this effort is the excellent site Translatewiki.net (http://translatewiki.net), which itself runs on MediaWiki, and which serves as a platform for an army of volunteer translators around the world to translate every displayed piece of text in both MediaWiki and its extensions. You can see the impressive full list of languages at:

http://translatewiki.net/wiki/Special:SupportedLanguages

Translatewiki.net has taken on a life of its own, and is now used by additional, non-MediaWiki applications, including OpenLayers and Mifos.

MediaWiki’s messages are divided into two types: user messages and content messages. A user message is any piece of text that is simply displayed, and has no impact on the content of wiki pages, or their URLs. A content message, by contrast, is any piece of text that does show up in either page contents or URLs. You can see the difference in, for instance, the "Random page" link in the sidebar, which by default is defined by the text "randompage-url|randompage". Assuming the wiki is in English, the text reads "Random page", and points to the page "Special:Random". The link text is defined by the message "randompage", which is a user message, while the page name is defined by "randompage-url", which is a content message.

Every MediaWiki wiki has a default language, which is determined by the value of $wgLanguageCode in LocalSettings.php (this variable takes in the IETF language tag for the language, which is often, though not always, a two-letter abbreviation ­ see http://en.wikipedia.org/wiki/IETF_language_tag). This is the language used for both content messages and user messages, by default. A logged-in user, however, can choose to display user messages (though not content messages) in any other language, if they click on the "User preferences" link and change their language within the main "User profile" tab. So a user can view a wiki with content messages in one language and user messages in another.

All of these messages can be modified within the wiki, via pages in the "MediaWiki:" namespace, as described previously. But modifying a page like "MediaWiki:message-name" will actually override that message’s value in every language: if it’s a user message, that means that even if someone views your wiki in another language, they’ll still see that exact text you entered. You may not want that to happen; if not, you can set translations to only apply to one language, by using the structure "MediaWiki:message-name/language-code" instead. This will set the value for the language specified by that language code (again, usually a two-letter value). For instance, to change the sidebar only for Italian speakers, you would edit the page "MediaWiki:summary/it". Unfortunately, this can be done for every language except for the wiki’s main language: if your wiki is in English, changing the value of “MediaWiki:summary/en” will have no effect.

What about running multi-language wikis, though, where the page contents can themselves be in different languages? That is covered in the section "Multi-language wikis", here.