Manuel:Comment créer un habillage MediaWiki
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 :
{{ str }} <!-- renders escaped string -->
{{{ html-str }}} <!-- renders RAW HTML -->
<!-- accesses data inside an associative array of the form { 'key' => 'hello' } -->
{{#array-data}}
{{ key }} <!-- renders hello -->
{{/array-data}}
<!-- for boolean values -->
{{#is-talk-page}}
<!-- conditional rendering if is-talk-page is true -->
{{/is-talk-page}}
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 :
wfLoadSkin( 'Example' );
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 Télécharger 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 :
wfLoadSkin( 'FolderName' );
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
cd mediawiki/skins
npm install mediawiki-skins-cli
npx create-mw-skin SkinName
cd SkinName
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 :
wfLoadSkin( 'SkinName' );
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 Gerrit. 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 {{>Partial}} 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 array-, les booléens par is- et les objets par data- 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 msg-.
"example": {
"class": "SkinMustache",
"args": [ {
"name": "example",
"messages": [
"sitetitle",
"search",
"tagline",
"navigation-heading"
]
} ]
}
Dans l'exemple ci-dessous le message sitetitle peut être rendu dans un modèle Mustache en utilisant :
<p>{{msg-sitetitle}}</p>
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.
{{>subfolder/Logo}}
{{>Content}}
{{>Footer}}
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.
<!-- Logo.mustache -->
<div id="p-logo" class="mw-portlet" role="banner">
<a href="{{link-mainpage}}">
{{#data-logos}}
{{#icon}}<img src="{{.}}" width="40" height="40">{{/icon}}
{{#wordmark}}<img src="{{src}}" width="{{width}}" height="{{height}}">{{/wordmark}}
{{^wordmark}}<h1>{{msg-sitetitle}}</h1>{{/wordmark}}
{{/data-logos}}
</a>
</div>
Dans le bloc de code ci-dessus, la ligne suivante est responsable de l'affichage du logo 'icon' :
{{#icon}}<img src="{{.}}" width="40" height="40">{{/icon}}
Cette ligne suppose qu'il existe une clé icon dans le tableau $wgLogos.
Donc dans votre fichier LocalSettings.php, si vous voyez une ligne similaire à $wgLogos = [ 'icon' => "$wgResourceBasePath/resources/assets/wiki.png" ];, alors l'image du logo ou de l'icône sera affichée.
Le fichier LocalSettings.php par défaut de MediaWiki exporte une clé 1x dans la table $wgLogos.
Donc pour afficher le logo, vous devez mettre à jour LocalSettings.php et ajouter la clé icon.
resources/assets/wiki.png . Car il sera remis à sa valeur par défaut quand vous ferez la mise à jour de MediaWiki. La manière recommandée pour changer le logo est d'ajouter un fichier contenant l'image du nouveau logo et d'ajouter son chemin dans LocalSettings.php.
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.
<nav id="{{id}}" class="{{class}}" title="{{html-tooltip}}"
aria-labelledby="{{id}}-label">
<input type="checkbox" aria-labelledby="{{id}}-label" />
<h3 id="{{id}}-label" {{{html-user-language-attributes}}}>{{label}}</h3>
<div class="mw-portlet-body">
<ul {{{html-user-language-attributes}}}>
{{{html-items}}}
</ul>
{{{html-after-portal}}}
</div>
</nav>
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.
{{! Switch template context to data for all menus }}
{{#data-portlets}}
{{! Access the menu called "languages" }}
{{#data-languages}}
{{>Menu}}
{{/data-languages}}
{{! Access the menu called "views" }}
{{#data-views}}
{{>Menu}}
{{/data-views}}
{{/data-portlets}}
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 {{#data-portlets-sidebar.data-portlets-first}}.
Néanmoins les menus subséquents sont rangés dans le tableau {{#data-portlets-sidebar.array-portlets-rest}} et peuvent être générés en appelant ceci.
Vous pouvez utiliser par exemple la syntaxe suivante :
{{#data-portlets-sidebar.array-portlets-rest}}
<div class="mw-dropdown-title"><span>{{label}}</span>
<div class="dropdown-content">{{>Portlet}}</div></div>
{{/data-portlets-sidebar.array-portlets-rest}}
Qui, lorsque le CSS est appliqué pour masquer dropdown-content jusqu'à ce que mw-dropdown-title 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 :
{
"ValidSkinNames": {
"notocskin": {
"class": "SkinMustache",
"args": [
{
"name": "notocskin",
"toc": false
}
]
}
}
}
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.
Scripts et styles
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 :
"ResourceModules": {
"skins.example": {
"class": "ResourceLoaderSkinModule",
"features": { "normalize": true },
"styles": [ "resources/skins.example.less" ]
}
},
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 @import 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.
Variables des habillages MediaWiki
Les variables des habillages MediaWiki ont été initialement introduites avec MW 1.35, les développements récents les activent pour une large utilisation depuis MW 1.41.
La liste des valeurs disponibles est synchronisée sur les derniers jetons de conception (site de démonstration) Codex.
- Architecture d'implémentation rapide – Pour les concepteurs d'habillage, les variables d'habillage offrent un moyen de mettre rapidement en œuvre les choix de conception en définissant des valeurs dans une liste à plat. Grâce à elles, les concepteurs peuvent modifier des propriétés fondamentales telles que la typographie (famille des polices, taille des polices etc.), les couleurs, les points de rupture, les frontières, la taille, l'espacement ou les z-index. Cette simple liste est regroupée par propriétés CSS. Elle doit être située dans le dossier et le fichier resources/mediawiki.less/mediawiki.skin.variables.less pour être récupérée par le ResourceLoader. Le schéma de nommage suit la convention de nommage des variables MediaWiki.
- Valeurs par défaut neutres – Si un habillage ne spécifie pas certaines valeurs, le système utilisera automatiquement les paramètres par défaut de mediawiki.skin.defaults.less de MediaWiki. Ces valeurs représentent une apparence HTML de base.
- Personnalisation – Bien que vous ne puissiez pas modifier le nom des variables, vous pouvez en définir d'autres à l'intérieur de fichiers séparés et spécifiques à l'habillage. Dans chaque fichier Less, vous pouvez importer les valeurs de l'habillage en faisant simplement
@import 'mediawiki.skin.variables.less'; - Avantages de la centralisation – Toutes les définitions de variables pour le thème par défaut de Wikimedia et toutes le nommage sont centralisés afin de
- Établir une convention de nommage cohérente pour la clarté et l'uniformité
- S'assurer de la compatibilité entre les différentes habillages et les extensions
- Fournir des informations sur les lacunes ou les domaines d'amélioration potentiels en se basant sur des modèles d'utilisation communs
Les auteurs d'habillages sont encouragés à se familiariser avec ces mises à jour pour maximiser le potentiel de leur habillage.
Utilisation dans les fichiers Less du noyau, des habillages et des extensions
Pour utiliser les variables mediawiki.skin.variables.less ou les jetons de conception, vous devez inclure une déclaration d'import au début de votre fichier Less.
Exemple d'utilisation :
@import 'mediawiki.skin.variables.less';
/* Liens */
a {
color: @color-link;
}
a:visited {
color: @color-link--visited;
}
a:active {
color: @color-link--active;
}
Un détail important est que seules les variables spécifiées dans mediawiki.skin.defaults.less peuvent être réassignées avec des valeurs spécifiques aux habillages dans le fichier mediawiki.skin.variables.less de l'habillage.
Notez que les habillages Vector 2022, Vector legacy et MinervaNeue utilisent les deux thèmes Codex par défaut pour les interfaces utilisateur de Wikimedia , qui sont également représentés sur le site de documentation du Codex.
Plus de 45 différents habillages et extensions utilisent déjà les variables d'habillage dans MW 1.41.
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.
{
"ValidSkinNames": {
"my-responsive-skin": {
"class": "SkinMustache",
"args": [
{
"name": "my-responsive-skin",
"responsive": true
}
]
}
}
}
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 :
$wgLanguageCode = "he";
En tant que développeur d'habillages, vous devez avoir à l'esprit deux choses :
- Tous CSS écrit pour votre habillage sera permuté automatiquement par l'outil
CSSJanus sans que vous ayez à intervenir néanmoins vous avez la possibilité de désactiver certaines de ces transformations (voir Flipping).
- 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 :
<div
{{{html-user-language-attributes}}}
>
</div>
pour un utilisateur qui a indiqué l'hébreu dans ses préférences, le HTML produit est :
<div
dir="rtl" lang="he"
>
</div>
Images
Vous pouvez étendre Manuel:$wgLogos 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.
| skin.json | i18n/en.json | skin.mustache |
|---|---|---|
{
"ValidSkinNames": {
"mymustacheskin": {
"class": "SkinMustache",
"args": [
{
"name": "mymustacheskin",
"messages": [
"createaccount"
]
}
]
}
}
}
|
{
"@metadata": {
"authors": []
},
"skinname-mymustacheskin": "My Mustache Skin",
"mymustacheskin-hello": "Hello"
}
|
<div>
{{msg-mymustacheskin-hello}} <!-- prints hello in the current language -->
</div>
|
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.
<?php
class MySkin extends SkinMustache {
/**
* Etend la fonction getTemplateData pour ajouter une clé de modèle 'html-myskin-hello-world'
* qui peut être rendu dans skin.mustache en utilisant {{{html-myskin-hello-world}}}
*/
public function getTemplateData() {
$data = parent::getTemplateData();
$data['html-myskin-hello-world'] = '<strong>Hello world!</strong>'; // ou $this->msg('msg-key')->parse();
return $data;
}
}
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 fournie dans nos documents.
ResourceLoaderSkinModule d'exemple désactive la fonctionnalité du logo mais en active plusieurs autres :
{
"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
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 Manuel:$wgResourceModuleSkinStyles.
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.
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. Les modifications de HEAD sont mieux servies par les extensions et les paramètres de LocalSettings.php.
Les liens suivants peuvent vous être utiles :
- Manuel:$wgAppleTouchIcon
- Manuel:$wgFavicon
- Manual:Hooks/OutputPageBodyAttributes
- Manuel:$wgSkinMetaTags
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 Manuel:$wgResourceModuleSkinStyles.
Compatibilité de VisualEditor
Pour assurer la compatibilité de VisualEditor, voir ces directives.
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.