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)
Dans skin.json sous ValidSkinNames, vous pouvez utiliser l'option 'messages' pour définir des clés de messages traductibles. Ces clés doivent correspondre aux entrées du répertoire i18n/en.json. Une fois enregistrées pour l'habillage, elles seront disponibles dans votre modèle avec le préfixe.

Dans l'exemple ci-dessous le message sitetitle peut être rendu dans un modèle Mustache en utilisant :

Voir l'Internationalisation pour d'autres informations sur l'importance de cela.



Générer des parties de modèle
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.

Les partiels de modèle sont un moyen très pratique pour segmenter votre habillage afin de le rendre plus lisible. No template partials are predefined and available by default, however you can look at existing skins using SkinMustache for inspiration.

Voir les autres informations sur les Partiels du modèle Mustache.

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.

Dans le bloc de code ci-dessus, la ligne suivante est responsable de l'affichage du logo 'icon' :

Cette ligne suppose qu'il existe une clé  dans le tableau. 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.

Donc pour afficher le logo, vous devez mettre à jour LocalSettings.php et ajouter la clé.



Générer des menus avec Mustache
Tous les menus sont structurés dans le même format PortletData. 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.



Générer des menus déroulants ou des sous-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. Néanmoins les menus subséquents sont rangés dans le tableau  et peuvent être générés en appelant ceci.

Vous pouvez utiliser par exemple la syntaxe suivante : Which, when CSS is applied to hide "dropdown-content" until "mw-dropdown-title" is hovered over, thus creating a dropdown menu. 

Désactiver la table des matières
In MW 1.38, you can remove the table of contents from the article body and position it outside the content area. Pour désactiver la génération de la table des matières, ajoutez à skin.json ceci :

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



Autres exemples
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. Ce qui devrait ressembler à quelque chose comme :

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 MW 1.36 an associative array (opt-out policy, recommended). Si vous n'êtes pas certain, n'utilisez pas les clés des fonctionnalités pour utiliser les valeurs recommandées par défaut.

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. Ils seront chargés dans l'ordre où ils sont listés. Avec LESS vous pouvez utiliser des déclarations @import dans le même répertoire. More information about what's possible can be found in Developing_with_ResourceLoader.

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



Habillages dynamiques / ajout d'un port de visualisation des données meta
If you are building a responsive skin, make sure to use the responsive skin option when declaring your skin in skin.json.



Rendre les habillages compatibles avec les langues qui se lisent de droite à gauche (RTL)
L'écriture de certaines langues comme l'hébreu par exemple, se présente de la droite vers la gauche plutôt que de la gauche vers la droite. Ce qui pose problème pour les développeurs d'habillages, où les interfaces sont permutés par exemple dans Vector la barre latérale est sur la gauche plutôt que sur la droite.

Dans MediaWiki il est également possible d'utiliser une langue différente pour l'habillage et une autre pour le contenu. Par exemple dans Special:Preferences vous pouvez définir votre langue comme étant l'hébreu alors que le contenu peut être présenté en anglais.

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:

En tant que développeur d'habillages, vous devez avoir à l'esprit deux choses :
 * 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 Flipping).
 * 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
Vous pouvez étendre avec les données que vous souhaitez. 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.



Etendre les données
Les données disponibles sont documentées sur 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.

<span id="Default_styling_via_the_ResourceLoaderSkinModule_class">

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. Si vous le souhaitez, vous pouvez désactiver ces fonctionnalités et fournir vos propres styles. Define features as an empty object to tie yourself into the recommended MediaWiki defaults. La liste des fonctionnalités supportées est présentée dans nos documents.

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

<span id="Integrating_with_other_extensions">

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. Skins for extension developers is provided for extension developers to ensure they get the best compatibility. The starter templates in Getting_started will render all possible UI elements. Si vous oubliez certaines partie d'information vous pouvez casser la compatibilité avec les extensions.

For certain extensions you may want to tweak the styles of the default UI elements, notably Extension:Echo. Pour faire cela, il vous est demandé de lire.

<span id="Changing_menu_content">

Modification du contenu du menu
La composition des menus peut être modifiée en utilisant les accroches. Par exemple pour Vector, l'accroche SkinTemplateNavigation est utilisée pour relocaliser l'icône étoile de suivi. En faisant cela, vérifiez d'avoir bien coché l'habillage courant sur lequel vous travaillez, pour éviter les effets de bord sur les autres habillages.

<span id="I_want_to_change_elements_in_the_head_of_the_HTML_page">

Je souhaite modifier les éléments de HEAD dans la page HTML
Les développeurs de l'habillage ne doivent rien modifier dans la section HEAD du 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 :



<span id="I_am_writing_an_extension_that_needs_to_style_itself_differently_depending_on_the_skin">

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.

<span id="Building_skins_for_1.35">

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.

<span id="Your_feedback_is_important">

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.