Manuel: Comment créer un habillage (skin) MediaWiki

From mediawiki.org
Jump to navigation Jump to search
This page is a translated version of the page Manual:How to make a MediaWiki skin and the translation is 59% complete.
Other languages:
English • ‎français • ‎русский • ‎עברית • ‎日本語

Créer un habillage est un excellent moyen de se familiariser avec le fonctionnement interne de MediaWiki et de lancer vos contributions au mouvement Wikimedia ! Si vous connaissez les technologies frontales de CSS, JavaScript et JSON, vous pouvez créer un habillage MediaWiki! Il n'est pas nécessaire de connaître PHP, mais cela peut vous aider si vous voulez faire quelque chose d'avancé.

While not essential, it will help if you are familiar with Mustache templates and LESS CSS. This tutorial assumes that you have installed a working version of MediaWiki, and are running the current development release, if not, it is recommended you do that first.

If you having an existing skin using the PHP BaseTemplate, this guide is not for you. Please see Manual:How to make a MediaWiki skin/Migrating SkinTemplate based skins to SkinMustache instead.

Mise en route

To begin making your first skin, we recommend two options.


Option 1 - Exemple de skin d'un fork

The Example skin https://github.com/wikimedia/mediawiki-skins-Example provides the bare bones implementation of a skin. Clone the repository in your skins folder making sure the folder is called "Example" and add the following to your LocalSettings.php:

wfLoadSkin( 'Example' );

If all has gone to plan your skin should be available on the Special:Preferences page of your wiki.

Option 2 - Utiliser le laboratoire d'habillages

The skins lab tool allows you to setup a skin with basic CSS and templates. Once you feel comfortable, you can click "download as ZIP" which will compile the necessary boiler plate for your skin. Hopefully the resulting repository is easy to navigate. When you have downloaded the ZIP place it in your MediaWiki skins folder and update LocalSettings.php with the following:

wfLoadSkin( 'FolderName' );

If all has gone to plan your skin should be available on the Special:Preferences page of your wiki.

Faites le savoir aux gens !

Making a skin will be more fun with other people and much easier too! Once you have got something usable, please consider publishing it to GitHub or Gerrit . Once the code is publicly available, you should create a skin page (make sure you change the title!) to let people know you are open for collaboration!

Setting up a wiki page has many other benefits. You'll be able to handle bug reports in Phabricator or GitHub issues and receive patches from other volunteers in the MediaWiki community. Somebody should also be able to help you setup translation.

Moustache

In 1.35 we added support for Mustache in skins. We found using Mustache to be very helpful in the development of the Skin:Minerva and Skin:Vector skins as it allows you to separate data from presentation. Mustache partials can be used to reuse templates. To use a partial Partial.mustache in MediaWiki, simply add them to the folder you are working in and reference them using {{>Partial}} in the master template `skin.mustache`.

The data sent to Mustache templates is relatively flexible. If something is missing, you can use PHP to add data by extending the SkinMustache::getTemplateData function.

The SkinJson skin can be added to a MediaWiki development instance, to inspect the data available to skins. Note that arrays are prefixed "array-", booleans are prefixed with "is-" and objects are prefixed "data-" to help you conceptualize the data you are working with.

Rendre votre habillage traduisible (i18n)

In skin.json under ValidSkinNames, you can use the `messages` option to define translateable message keys. These keys should correspond to entries inside the i18n/en.json folder. Once registered for the skin, these will be available in your template with a prefix "msg-".

    "example": {
                        "class": "SkinMustache",
                        "args": [ {
                                "name": "example",
                                "messages": [
                                        "sitetitle",
                                        "search",
                                        "tagline",
                                        "navigation-heading"
                                ]
                        } ]
                }

For example in the example below, the message "sitetitle" can be rendered in a Mustache template using

<p>{{msg-sitetitle}}</p>

See Localisation for more information on why this is important.

Scripts et styles

Valeurs par défaut

A skin at minimum requires a single style ResourceLoader module. It will look a bit like this:

       "ResourceModules": {
                "skins.example": {
                        "class": "ResourceLoaderSkinModule",
                        "features": [ "normalize" ],
                        "styles": [ "resources/skins.example.less" ]
                }
        },

The features key allows you to use useful boiler plate defaults for a variety of things including i18n and normalize which are documented in the MediaWiki core php documentation. Features can be a list of keys (opt-in policy) or in 1.36 an object (opt-out policy). If you are not sure, please omit the features key to use the recommended defaults.

CSS / LESS

The skin.json is a manifest of all the assets your skin uses. Under the `ResourceModules` key you should find the style module for your skin listed under `skins.example`. Here, under the "styles" key you can add LESS or CSS files. They will be loaded in the order they are listed. With LESS you can use @import statements in the same folder. More information about what's possible can be found in ResourceLoader/Developing_with_ResourceLoader.

When using images you should be able to use relative URIs to access the image assets.

JavaScript

JavaScript code in skins, runs in an environment where you can rely on the `mw` and `jQuery` objects having been loaded. We recommend using ResourceLoader/Package_files which will allow you to require file assets.

For information on the available API and libraries see core JS documentation.

Plus avancé

More advanced information will provided on an as requested basis. Please ask a question on the talk page to accelerate the addition of documentation!

Style par défaut via la classe ResourceLoaderSkinModule

All skins should define a single style module with the class ResourceLoaderSkinModule. The module defines various default styles to take care of MediaWiki internals. If you want, you can disable these features and provide your own styles. Define features as an empty object to tie yourself into the recommended MediaWiki defaults. A list of support features is provided in our docs.

Example ResourceLoaderSkinModule that disables the logo feature but enables several others:

{
    "skins.vector.styles": {
                        "class": "ResourceLoaderSkinModule",
                        "features": {
                                "normalize": true,
                                "elements": true,
                                "content": true,
                                "logo": false,
                                "interface": true,
                                "legacy": true
                        },
                        "targets": [
                                "desktop",
                                "mobile"
                        ],
                        "styles": [ "resources/skins.vector.styles/skin.less" ]
                }
    }
}

Intégration avec d'autres extensions

Extensions should integrate with you, not the other way round! Try to forget about extensions when writing your skin. User:Jdlrobson/Skins for extension developers is provided for extension developers to ensure they get the best compatibility. The starter templates in Manual:How_to_make_a_MediaWiki_skin#Getting_started will render all possible UI elements. If you omit certain pieces of data you may break support with extensions.

For certain extensions you may want to tweak the styles of the default UI elements, notably Extension:Echo. To do this you will need to read Manual:$wgResourceModuleSkinStyles.

Modification du contenu du menu

The composition of menus can be changed by using hooks. For example in Vector, the SkinTemplateNavigation hook is used to relocate the watch star icon. When doing this, remember to check the skin being operated on, to avoid side effects in other skins.

I am writing an extension that needs to style itself differently depending on the skin

Extensions can make use of skin styles to ship skin-specific styles using the skinStyles key. See Manual:$wgResourceModuleSkinStyles.

Building skins for 1.35

In 1.35 support for building skins was not as straightforward as in 1.36. If you wish to build a skin for 1.35, using template data provided in 1.36, you will need to extend the SkinMustache PHP class. A polyfill for the Example skin is provided.


Vos commentaires sont importants

If something is not easy, we'd like to make it easier, so your feedback is important. If you run into problems, then please file a bug report in the mediawiki core skin architecture project in Phabricator, and we'll try and find an elegant solution.

Please feel free to ask a question on the talk page. There is no such thing as a stupid question.