Manual:Skinning Part 3

From MediaWiki.org
Jump to: navigation, search

MediaWiki has a number of variances in what it displays depending on the page you are on. When finishing up your skin you should go around to the different parts of MediaWiki and ensure your skin looks correct in those cases.

  • Test the "Redirected from" line on a redirected page.
  • And test the redirect page itself.
  • View a page's permalink to ensure your skin works fine when viewing old revisions.
  • Test your wiki's skin on the edit, history, and diff pages.
  • Look at a deleted page to ensure the delete line is present.
  • Double check the styles on Special :Special Pages.
  • Test at least a few of the other special pages.
  • Test your skin's UI on pages as an anonymous user, a normal user, and as an administrator, each of which have different tabs.

In addition to these small things to test while building your skin there are a few major cases you should ensure function correctly when you've put your skin together.

Print mode[edit]

MediaWiki supports page printing with a print style sheet that removes most of the ui, this allows users to simply print any page on the wiki without any special printing mode. The 'printable' mode does little but disable screen style sheets and take the print style sheets and make them apply to the screen, it's only around for users who still think that they need a separate mode to print.

You've likely added new interface pieces with new classes not included in the common printing style sheet, hence you'll need to make some tweaks to ensure your skin looks correct while printing.

To tweak things in print mode the best method of doing so is to add a print style sheet. Go back to that resource loader array and add a new stylesheet with a 'print' media instead of 'screen'. From this style sheet you can set display: none; on the parts of your interface that still show up in print mode. You may also wish to give some things like the tagline a better print style as well.

Alternatively you can add class="no print" to the elements you need to hide from print mode.

Other languages[edit]

Use your internationalisation[edit]

MediaWiki has a great internationalisation (i18n) system. If you use it then your skin can be translated into other languages. Even if your wiki content is only in one language, visitors who prefer a different language can set it (for example in Preferences); and internationalizing means your skin can be used on more wikis. So, please make use of the i18n system for pieces of text in your skin. And by using the i18n system, you allow wiki admins to customize the messages shown by your skin.

To define a new i18n key for your skin just add it and its value in English to the i18n/en.json language file we created in part 2, then add it and some documentation to the i18n/qqq.json "language" file. This defines new messages in the i18n system. Keep in mind that these messages keys are global, so it's good practice to prefix any key you use with a ''skinnamekey- to avoid conflicts.

After you've defined a new message, class BaseTemplate provides a msg() method that gets the message for a key in the user's current language and outputs it, escaping it for HTML.

<?php $this->msg( 'msg-key' ); ?>

If you want to consider the message a block of wikitext to be parsed instead of output as is, you can use msgWiki():

<?php $this->msgWiki( 'msg-key' ); ?>

Keep in mind though that this invokes the parser and may not be cached so nicely, so overusing msgWiki() on a popular wiki can cause a performance hit, especially if you use anything advanced in the wikitext such as parser functions and other extensions.

Language variants[edit]

MediaWiki supports the concept of 'variants' for some languages. Some languages such as Kazakh and Serbian support multiple writing scripts. MediaWiki includes a language converter that automatically converts content between these scripts. When on a wiki using a language that supports variants MediaWiki includes tabs in the 'variants' category of tabs.

When you're done with the primary coding and styling of your skin you should consider testing to ensure you have variants tabs outputting correctly. You can do this by setting your development wiki's content to 'sr' or 'zh' temporarily.

Right-to-left (RTL) languages[edit]

Besides the many languages such as English which are written left-to-right (LTR), there are some languages that MediaWiki supports which are written right-to-left (RTL).

Even more importantly than language variants, you should probably test your skins compatibility with RTL languages. Because MediaWiki 1.18 includes better directionality support that allows the page language direction to be based on the user's language rather than the content language you can test simply by adding a uselang= parameter set to a RTL language to the query string, for example &uselang=fa (Persian) or &uselang=he (Hebrew).

To make support for RTL languages easy Resource Loader automatically flips many CSS properties automatically doing most of the work flipping the interface. There are however two cases where you may need to intervene and help directly to support RTL languages. Firstly Resource Loader will flip properties like margin-{left,right} and padding-{left,right}; however it will not flip left/right margins and padding in the combined margin and padding properties, so you may need to alter your CSS to use separate properties for left and right margins and padding. Secondly you may have some parts of the interface which may break when flipped and not work correctly in RTL, if you have a CSS property that is being flipped which needs to stay the same you can prefix it with /* @noflip */ to stop it from being flipped.

Accessibility[edit]

Another of MediaWiki's heavy focuses is accessibility. Accessibility is heavily considered whenever a new skin is added to core, however simply by not taking accessibility into account when you build a new skin you can easily ruin the accessibility of your wiki.

A full explanation on how to make a website / skin accessible is out of the scope of this tutorial. For in-depth information you should probably look at other things such as WebAIM's information and WAI. But I will cover skip links here.

Skip links — also known as jump links in parts of MediaWiki — are an accessibility pattern traditionally used to allow users without the use of a mouse to skip large blocks of navigation and go directly to the content instead of having to tab through or listen to them all before reaching the content.

You should consider reading up on the concept here: http://webaim.org/techniques/skipnav/

Traditionally they have been called "Skip" links and implemented as "Skip navigation" or "Skip to content". MediaWiki instead calls them "Jump" links and are implemented as "Jump to navigation". I don't know the origin of using jump instead of skip but it would likely be a good idea of keeping the pattern of creating "Skip ..." links when your navigation is first and your content comes later on the page, and "Jump ..." links when your content is the first thing on the page and your navigation comes later.

Skip links implementation is essentially the same as in a plain website. A div which you may or may-not hide containing a list of links pointing to ids you have in other spots in the markup to skip to that area.

While you're at it you may want to consider adding WAI-ARIA roles to your skin for the browsers that implement it.

Installing your skin[edit]

MediaWiki version: 1.25
Gerrit change 166705

(In case you didn't catch it from the very beginning of the tutorial.) To install your skin, load it from your wiki's LocalSettings.php (make sure to replace "FooBar" with your skin's name):

wfLoadSkin( "FooBar" );

In older MediaWiki versions, you have to explicitly load the skin's PHP file using require_once(). This is still supported in 1.25 onwards for backwards-compatibility.

require_once( "$IP/skins/FooBar/FooBar.php" );


MediaWiki version: 1.24
Gerrit change 135439

Before MediaWiki 1.25, there was an "auto-discovery" mechanism that detected skins in your wiki's "skins" folder and automatically loaded all skins from it; this functionality no longer exists.

To try out your skin you can:

  • change $wgDefaultSkin to make your new skin the default skin for all users of your wiki
  • go to Special:Preferences > Appearance while logged in and either change to the new skin or click its "Preview" link
  • add the ?useskin=foobar query string parameter to any wiki URL.

Further reading[edit]