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 le 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 ::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
Des sections de modèle peuvent être utilisées pour générer les différentes parties de l'habillage et pour éviter le problème d'avoir un long fichier skin.mustache qui devient non maintenable. Dans l'exemple suivant, l'habillage met en forme le contenu des modèles dans les trois fichiers ayant pour noms Logo.mustache, Content.mustache et Footer.mustache. Ces fichiers doivent exister dans le même répertoire que celui du fichier skin.mustache ou dans un sous-répertoire du répertoire contenant skin.mustache.

Les parties de modèle sont un moyen très pratique pour segmenter votre habillage afin de le rendre plus lisible. Il n'y a pas de parties de modèle prédéfinies et disponibles par défaut, néanmoins vous pouvez regarder les habillages existants utilisant SkinMustache et vous en inspirer.

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

Logo.mustache
Le bloc de code suivant va être utilisé pour afficher le logo du site dans l'habillage Example et vous verrez aussi la même chose si vous créez l'habillage à partir de 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. Donc dans votre fichier LocalSettings.php, si vous voyez une ligne similaire à, alors l'image du logo ou de l'icône sera affichée. Le fichier  par défaut de MediaWiki exporte une clé   dans la table.

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. Un modèle partiel générique Menu.mustache, ajouté dans le même dossier que skin.mustache peut par conséquent être utilisé pour générer un menu. Mais si vous utilisez ce partiel, vous devrez lui indiquer pour quel menu il doit générer le HTML.

Dans skin.mustache le code suivant permet de restituer les langues et afficher les menus.



Générer des menus déroulants ou des sous-menus
Les concepteurs d'habillages peuvent aussi utiliser la syntaxe mustache pour créer des menus déroulants à partir des éléments trouvés précédemment dans la barre latérale des habillages Vector et MonoBook. C'est un peu acrobatique mais si vous comprenez la manière dont les éléments sont stockés, cela peut vous aider.

Le premier élément de la barre latérale — typiquement il contient le lien vers la page d'accueil ainsi que d'autres liens MediaWiki; est rendu via l'appel de. 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 : Qui, lorsque le CSS est appliqué pour masquer  jusqu'à ce que   soit survolé, créant ainsi un menu déroulant. 

Désactiver la table des matières
Dans MW 1.38, vous pouvez sortir la table des matières hors de l'article et la positionner en dehors de la zone du contenu. Pour désactiver la génération de la table des matières, ajoutez à skin.json ceci :

La clé du modèle array-sections peut être utilisée pour mettre en forme la table des matières.



Autres exemples
Pour consulter les exemples des partiels de modèles pouvant être utilisés dans votre projet, voir le laboratoire des habillages de Wikimedia.



Valeurs par défaut
Au minimum un habillage nécessite un unique module ResourceLoader de style dans le fichier skin.json de votre habillage. Ce qui devrait ressembler à quelque chose comme :

Ces clés des fonctionnalités vous permettent d'utiliser pleinement l'ensemble des valeurs définies par défaut pour une variété d'éléments y compris le i18n et la normalisation décrits dans la documentation PHP du noyau MediaWiki. Les fonctionnalités peuvent être fournies sous la forme d'un tableau de clés (règles d'abonnement) ou en MW 1.36 comme un tableau associatif (règles de désabonnement, ce qui est recommandé). 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
Le skin.json est un manifeste de tous les actifs que votre habillage utilise. Sous la clé 'ResourceModules' vous devez trouver le module de style pour votre habillage listé sous 'skins.example'. Ici, sous la clé 'styles' vous pouvez ajouter les fichiers LESS ou CSS. Ils seront chargés dans l'ordre où ils sont listés. Avec LESS vous pouvez utiliser des déclarations dans le même répertoire. D'autres informations à propos de ce qu'il est possible de faire peuvent être consultées sur Développer avec le ResourceLoader.

Lorsque vous manipulez les images, vous pouvez utiliser des URIs relatives pour accéder aux caractéristiques de l'image.

MediaWiki Skin Variables
MediaWiki skin variables have been around since MW 1.35, recent development enabled them to work for broader use.


 *  For skin designers  - Skin variables offer a way to quickly implement design choices by setting values in a flat list. This straightforward list is grouped by CSS properties. It must be located in folder and file 'resources/mediawiki.less/mediawiki.skin.variables.less' in order to be picked up by ResourceLoader. The naming scheme follows the MediaWiki variables naming convention.
 *  Defaults  - If a skin doesn't specify certain values, the system will automatically use the defaults from MediaWiki's own 'mediawiki.skin.defaults.less'.
 *  Customization  - While you can't modify the variable names, you could define additional ones in separate skin specific files. In every Less file, you can import the skin's values by only
 *  Centralization Benefits  - All the variables definition for the Wikimedia default theme and all the naming is centralized in order to
 * Establish a consistent naming convention for clarity and uniformity
 * Ensure compatibility across various skins and extensions
 * Provide insights into potential gaps or areas of improvement based on common usage patterns

Skin authors are encouraged to familiarize themselves with these updates to maximize the potential of their skins.

Over 35 different skins and extensions use the skin variables in MW 1.41 already.



Habillages dynamiques / ajout d'un port de visualisation des données meta
Si vous construisez un habillage réactif, assurez-vous d'utiliser l'option d'habillage responsive lorsque vous déclarez votre habillage dans 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.

Ecrire des habillages qui fonctionnent bien en RTL, c'est un vaste sujet dont l'objectif sort de ce document, mais si vous avez besoin de tester votre habillage en RTL vous devez mettre à jour LocalSettings.php pour modifier la langue de votre contenu :

En tant que développeur d'habillages, vous devez avoir à l'esprit deux choses :

CSSJanus sans que vous ayez à intervenir néanmoins vous avez la possibilité de désactiver certaines de ces transformations (voir Flipping).
 * Tous CSS écrit pour votre habillage sera permuté automatiquement par l'outil
 * Tout HTML que vous affichez et qui peut être traduit doit être marqué avec l'atttribut HTML dir]. Par facilité SkinMustache fournit la variable du modèle html-user-language-attributes qui peut être utilisée ainsi :

pour un utilisateur qui a indiqué l'hébreu dans ses préférences, le HTML produit est :

Images
Vous pouvez étendre avec les données que vous souhaitez. Cela va permettre aux administrateurs de site de configurer les images au fur et à mesure de leur sélection, mais la mise en forme conditionnelle est à votre charge.

Dans le cas où des images doivent être codées en dur, et que vous ne pouvez pas utiliser un CSS pour l'image de fond ni wgLogos pour certaines raisons, vous devrez étendre les données fournies au modèle.

JavaScript
Le code JavaScript dans les habillages, s'exécute dans un environnement où vous pouvez vous appuyer sur les objets 'mw' et 'jQuery' (à charger auparavent). Nous vous recommandons d'utiliser ResourceLoader/Package_files, ce qui vous permettra de demander les ressources des fichiers.

Pour les informations concernant l'API disponible et les bibliothèques voir la documentation JS du noyau.



Plus avancé
D'autres informations plus avancées seront fournies en fonction des demandes. Veuillez poser votre question sur la page de discussion pour accélérer l'ajout de documentation !

i18n
Les messages définis dans i18n/en.json peuvent être passés directement à votre modèle Mustache par l'inclusion dans skin.json. Notez que vous pouvez utiliser tout message défini dans le noyau de MediaWiki.



Etendre les données
Les données disponibles sont documentées sur SkinMustache.php.

Si vous devez ajouter des données supplémentaires pour le rendu à l'intérieur du modèle de votre habillage et qui ne peuvent pas être fournies par les messages (comme dans la section i18n) c'est à dire du HTML brut ou des structures complexes de données, vous devez utiliser une classe PHP dédiée et étendre la méthode SkinMustache::getTemplateData.

<span id="Default_styling_via_the_ResourceLoaderSkinModule_class">

Style par défaut via la classe ResourceLoaderSkinModule
Tous les habillages doivent définir un module unique de style avec la classe ResourceLoaderSkinModule. Le module définit différents styles par défaut qui prennent en compte le fonctionnement interne de MediaWiki. Si vous le souhaitez, vous pouvez désactiver ces fonctionnalités et fournir vos propres styles. Définir les fonctionnalités en tant qu'objet vide pour vous lier aux valeurs par défaut recommandées de MediaWiki. La liste des fonctionnalités supportées est présentée dans nos documents.

ResourceLoaderSkinModule d'exemple désactive la fonctionnalité du logo mais en active plusieurs autres :

<span id="Integrating_with_other_extensions">

Intégration avec d'autres extensions
Les extensions doivent s'intégrer avec vous, et non l'inverse ! Essayez d'oublier les extensions lors de l'écriture de votre habillage. Les habillages pour les développeurs d'extensions leur sont fournis pour s'assurer d'avoir la meilleure compatibilité. Les modèles pour débuter de la section d'introduction présentent tous les éléments possibles de l'interface utilisateur. Si vous oubliez certaines partie d'information vous pouvez casser la compatibilité avec les extensions.

Pour certaines extensions vous pouvez modifier les styles des éléments par défaut de l'interface utilisateur, notamment avec l'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.

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.