Manual:How to make a MediaWiki skin/fr

Créer un habillage (skin) est un excellent moyen de se familiariser avec le fonctionnement interne de MediaWiki et de présenter 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 de plus avancé.

Bien que n'étant pas essentiel, les connaissances que vous auriez en LESS CSS pourraient vous aider. Ce tutoriel suppose que vous avez installé une version opérationnelle de MediaWiki, et que vous exécutez la version actuelle en développement; si ce n'est pas le cas, nous vous recommandons de faire la mise à jour d'abord.

Si vous avez un habillage existant qui utilise BaseTemplate PHP, ce guide n'est pas pour vous. Voir dans ce cas la Migration des habillages basés sur SkinTemplate vers SkinMustache.

Préparation
Le développement des habillages sera plus facile si vous êtes déjà familiarisé avec les modèles Mustache.

Au minimum vous devez connaître les notions de base de Mustache regroupées dans l'exemple ci-dessous :

L'habillage sert à mettre en forme le contenu visible à l'utilisateur - c'est à dire le HTML entre les balises BODY. Il n'a pas le droit de modifier quoi que ce soit dans la partie HEAD. Le code sera automatiquement généré pour l'habillage de sorte que celui-ci n'ait qu'à se préoccuper que de la mise en forme. Si vous devez modifier le HEAD, ceci ne concerne pas l'habillage et vous devez utiliser les accroches, les extensions ou les paramètres de configuration pour le faire ; voir la FAQ pour les meilleures pratiques.



Mise en route
Pour commencer à faire votre premier habillage, nous vous recommandons deux options.



Option 1 - fork de l'habillage Exemple
L'habillage Example de https://github.com/wikimedia/mediawiki-skins-Example fournit le squelette de l'implémentation d'un habillage. Clonez le dépôt dans le répertoire de vos habillages en vérifiant qu'il s'appelle Example puis ajoutez ceci à votre fichier LocalSettings.php :

Une fois cela fait, votre habillage doit être visible sur la page Special:Preferences de votre wiki.



Option 2 - Utiliser le laboratoire des habillages
L'outil skins lab vous permet de configurer un habillage avec du CSS de base et des modèles. Une fois que vous êtes à l'aise, vous pouvez cliquer sur le ZIP qui va compiler la structure de base de votre habillage. Heureusement le dépôt résultant est facile à explorer. Une fois l'archive ZIP téléchargée, placez-la dans le dossier de vos habillages MediaWiki et mettez à jour LocalSettings.php avec ceci :

Une fois cela réalisé, votre habillage doit être visible sur la page Special:Preferences de votre wiki.



Option 3 - A partir de la ligne de commande
Une fois l'archive ZIP téléchargée, placez-la dans le dossier de vos habillages MediaWiki et mettez à jour le fichier LocalSettings.php avec ceci :



Informer la communauté
Il est plus amusant de construire un habillage avec d'autres personnes et c'est aussi plus facile ! Une fois que vous commencez à avoir quelque chose d'utilisable, publiez-le sur GitHub ou. Une fois que le code est rendu public, [ créez une page pour l'habillage] (assurez-vous d'en avoir modifié le titre) pour informer les utilisateurs que vous êtes ouvert à la collaboration.

Le fait de configurer une page wiki a beaucoup d'autres avantages. Vous pourrez vous habituer aux rapports de bogue dans Phabricator ou aux problèmes GitHub et recevoir les correctifs des autres bénévoles de la communauté MediaWiki. Il devrait se trouver quelqu'un pour vous aider à définir la traduction.

Mustache
En version 1.35 nous avons ajouté la prise en charge de Mustache dans les habillages. Nous avons trouvé que l'utilisation de Mustache aide beaucoup au développement des habillages Minerva et Vector car elle vous permet de séparer les données de la présentation. Des parties de Mustache peuvent être employées pour réutiliser les modèles. Pour utiliser un Partial.mustache partiel dans MediaWiki, ajoutez-le simplement à votre répertoire de travail et référencez-le en utilisant dans le modèle maître 'skin.mustache'.

Les données envoyées aux modèles Mustache sont très souples. S'il manque quelque chose, vous pouvez utiliser PHP pour ajouter des données en étendant la fonction SkinMustache::getTemplateData.

L'habillage SkinJson peut être ajouté à une instance de développement MediaWiki pour inspecter les données disponibles pour les habillages. Notez que les tableaux sont préfixés par, les booléens par   et les objets par   pour vous aider à conceptualiser les données avec lesquelles vous travaillez.

La liste des données et les versions MediaWiki pour lesquelles elles sont disponibles sont documentées sur SkinMustache.php.



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-".

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

See Localisation for more information on why this is important.

Rendering template partials
Template partials can be used to render different parts of the skin and to avoid the problem with having a large unmaintainable skin.mustache file. In the following example, the skin renders the contents of the templates in the 3 files with the filenames Logo.mustache, Content.mustache and Footer.mustache. These files must exist in the same folder as the skin.mustache file or a subfolder of the directory containing skin.mustache.

Template partials are a great way to break up your skin to make it more readable. No template partials are predefined and available by default, however you can look at existing skins using SkinMustache for inspiration.

Read more about Mustache template partials.

Logo.mustache
Following code block is being used to show the site logo in the Example skin and you will also see the same if you create the skin from the SkinLabs.

From the code block mentioned above, the following line is responsible to show the logo `icon`:

This line assumes that, there is a key  in the array. So in your LocalSettings.php file, if there is a line similar as, then the logo/ icon image will be displayed. The default MediaWiki  exports a   key in the  array.

So to show the logo you need to update the LocalSettings.php and add a key.

Rendering menus with Mustache
All menus are structured in the same format (Manual:SkinMustache.php). A generic Menu.mustache template partial, added to the same folder as skin.mustache can therefore be used to generate a menu. However, when using this partial you'll need to tell it which menu to generate HTML for.

Inside skin.mustache the following would render the languages and views menu.

Rendering dropdown or sub-menus
Skin designers can also use the mustache syntax to create dropdown menus from the elements previously found in the sidebar of the Vector and MonoBook skins. This is a little trickier, however, but understanding the way the elements are stored can help.

The first sidebar element — typically containing the main page link and other MediaWiki links, is rendered via the  call. Subsequent menus, however, are stored in the  array, and can be rendered by calling this.

For example, one may use the following syntax: Which, when CSS is applied to hide "dropdown-content" until "mw-dropdown-title" is hovered over, thus creating a dropdown menu.

Disabling the table of contents
In 1.38, you can remove the table of contents from the article body and position it outside the content area. To disable the table of contents generation, add the following to skin.json:

The array-sections template key can be used for rendering the table of contents.

More examples
To see examples of template partials that can be used in your project, you can look through the examples in the Wikimedia skins labs.



Valeurs par défaut
A skin at minimum requires a single style ResourceLoader module defined in your skin's skin.json  file. It will look a bit like this:

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 an array of keys (opt-in policy) or in 1.36 an associative array (opt-out policy, recommended). 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.

Responsive skins / adding a meta viewport
If you are building a responsive skin, make sure to use the responsive skin option when declaring your skin in skin.json.

Making skins compatible with languages that are right-to-left (RTL)
The scripts of certain languages e.g. Hebrew are in right to left rather than left to right. This presents a problem for skin developers, where interfaces are flipped e.g. in Vector the sidebar is on the left rather than the right.

In MediaWiki it's also possible to use a different language for the skin and the content. For example, in Special:Preferences you can set your language to Hebrew while retaining the content in English.

Writing skins that work well in RTL is a large topic out of scope for this document, but if you need to test your skin in RTL you should update LocalSettings.php to change your content language:

As a skin developer you should keep in mind two things:
 * Any CSS written for your skin will be flipped automatically via the CSSJanus tool without any work required from you, however you may need to disable some of those transformations (see ResourceLoader/Architecture).
 * Any HTML you render that can be translated should be marked up with the dir HTML attribute]. For your convenience SkinMustache provides the html-user-language-attributes template variable which can be used like so:

for a user who who has set their language to Hebrew in preferences, produces the following HTML:

Images
You can extend with any data you choose to. This will allow site admins to configure images as they choose, but you must always conditionally render them.

In cases where images must be hardcoded for some reason., and cannot use a CSS background-image, or wgLogos for any reason you will need to extend the data sent to the template

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!

i18n
Messages defined in i18n/en.json can be passed directly to your Mustache template by inclusion in skin.json. Note, that you can use any messages defined inside MediaWiki core.

Extending data
The data available is documented on Manual:SkinMustache.php.

If you need to add additional data for rendering inside your skin's template that cannot be served by messages (as in the i18n section) e.g. raw HTML or complex data structures you must use a dedicated PHP class and extend the SkinMustache::getTemplateData method.



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:



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 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.



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.



Je souhaite modifier les éléments de HEAD dans la page HTML
Les développeurs d'habillages ne doivent pas se préoccuper de modifier quoi que se soit dans la section HEAD d'un document. Modifications of the HEAD are better served via extensions and configuration inside LocalSettings.php. For any questions please use the

Les liens suivants peuvent vous être utiles :





Je rédige une extension qui doit mettre en forme différemment en fonction de l'habillage
Les extensions peuvent utiliser les styles des habillages pour embarquer les styles spécifiques aux habillages en utilisant la clé skinStyles. Voir.



Construire des habillages pour MW 1.35
En 1.35, le support pour construire des habillages n'est pas aussi simple qu'en 1.36. Si vous souhaitez construire un habillage pour 1.35, en utilisant les template data fournies en 1.36, il vous faudra étendre la classe PHP SkinMustache. Un modèle pour l'habillage Example vous est fourni.



Vos commentaires sont importants
Si quelque chose n'est pas clair, nous aimerions vous l'expliquer, c'est pourquoi vos commentaires sont importants. Si vous rencontrez des problèmes, veuillez rédiger un rapport de bogue dans le projet d'architecture des habillages du noyau Mediawiki de Phabricator, et nous essayerons de trouver une solution élégante.

N'hésitez pas à poser vos questions sur la page de discussion. Il n'y a pas de question qui soit stupide.