Codex

Groupe :	Design System Team
Début :	août 2021
Membres de l'équipe :	Anne Tomasevich, Bárbara Martínez Calvo, Chris Ciufo, Eric Gardner, Lauralyn Watson, Nat Baca, Roan Kattouw, Sarai Sánchez, Volker E.

This page is a translated version of the page Codex and the translation is 100% complete.

Codex est le système de conception de Wikimedia. Il comprend les jetons de conception pour stocker les valeurs stylistiques, les composants d'interface utilisateur construits en JavaScript (Vue.js) et ceux uniquement avec CSS, ainsi qu'une suite d'icônes. Ils sont tous conçus et construits pour prendre en charge par défaut largement l'internationalisation, l'utilisation globale et l'accessibilité web.

Cette page détaille comment utiliser Codex dans MediaWiki. Pour voir le code lui-même, aller sur Paquet logiciel Codex. Voir la documentation générale sur la façon d'utiliser Vue.js dans MediaWiki.

Les paquets Codex dans MediaWiki

Version actuelle

MediaWiki utilise actuellement la version 1.5.0 de Codex. De nouvelles versions sont publiées toutes les 2 semaines (voir le Calendrier des diffusions pour la cadence de sortie et toutes les versions).

Paquets

Les paquets suivants de Codex sont disponibles sur MediaWiki :

@wikimedia/codex-design-tokens — Ce paquet contient des jetons de conception dans divers formats, y compris les variables Less et JSON.
@wikimedia/codex — Ce paquet contient des composants d'interface utilisateur (UI) construits avec Vue 3 ou en tant que composants CSS uniquement.
@wikimedia/codex-icons — Ce paquet contient un ensemble d'icônes.

Il convient de noter qu'il existe actuellement un quatrième paquet — @wikimedia/codex-search. Il s'agit d'un sous-ensemble du paquet @wikimedia/codex, contenant seulement le composant TypeaheadSearch et ses styles. Avec la version 0.20.0 il est devenu obsolète et son code a été transformé et placé dans le paquet codex. Il a été créé seulement pour servir Vector 2022 et améliorer les performances, il ne doit être utilisé que là et va cesser d'exister au fur et à mesure que la division du code sera disponible.

Utilisation générale de Codex dans MediaWiki

Consultez l'extension CodexExample (MW 1.41+) pour un exemple d'utilisation de ses composants, des jetons de conception et des icônes dans une extension MediaWiki.

Les exemples de code du site web de documentation Codex ont tous, deux versions étiquetées « NPM » et « MediaWiki ». Dans le noyau, les habillages et les extensions MediaWiki, vous devez utiliser les versions « MediaWiki » de ces exemples; les exemples « NPM » ne conviendront pas parce que certains aspects fonctionnent un peu différemment dans MediaWiki. Lisez aussi les sections de cette page qui vont plus en détail sur la façon d'utiliser les jetons de conception, les composants et les icônes Codex dans MediaWiki.

Utiliser la version locale de Codex dans votre instance locale MediaWiki

Parfois, il peut être utile d'avoir votre version Codex dans votre instance locale de MediaWiki, afin de tester les nouvelles fonctionnalités ou les modifications de Codex qui n'ont pas encore été publiées ou incluses dans le noyau de MediaWIKI. Nous espérons éventuellement automatiser cela, mais jusqu'à ce que nous ayons cette capacité, vous pouvez le faire manuellement en copiant les fichiers 'dist' des paquets Codex dans le répertoire 'resources/lib' du noyau.

Construisez votre bibliothèque locale Codex en exécutant npm run build-all dans le répertoire racine de votre dépôt Codex.
Copiez les parties de Codex dont vous avez besoin dans votre dépôt du noyau MediaWiki. Tous les exemples ci-dessous supposent que vous utilisez un système de type Unix (par exemple: Linux ou macOS), que votre dépôt Codex et votre dépôt du noyau se trouvent dans le même répertoire, et que vous travaillez depuis le répertoire du noyau. Pour copier :
- Paquet @wikimedia/codex contenant les composants Codex : cp -r ../codex/packages/codex/dist/{codex*,mixins,modules} resources/lib/codex/
- Paquet @wikimedia/codex-design-tokens : cp ../codex/packages/codex-design-tokens/dist/*.less resources/lib/codex-design-tokens/
- Paquet @wikimedia/codex-icons : cp ../codex/packages/codex-icons/dist/{codex-icons.json,codex-icon-paths.less} resources/lib/codex-icons/

Utiliser les jetons de conception Codex

Les jetons de conception sont les plus petits éléments stylistiques de notre système de conception. Découvrez les jetons de conception de Codex dans la documentation officielle et consultez les démonstrations disponibles des jetons (par exemple, la démo des jetons de couleur).

Avantages des jetons de conception

Tous les aspects visuels du système de conception, tels que les couleurs, la typographie, l'espacement et les tailles sont définis à l'aide de jetons. Ils fournissent une source centrale de fiabilité pour ces éléments de conception, qui peuvent ensuite être utilisés sur plusieurs plateformes et applications, ici les habillages et les extensions MediaWiki. En utilisant des jetons de conception, les concepteurs et les développeurs peuvent assurer la cohérence de l'apparence et du comportement de leurs produits numériques. Par exemple, au lieu de coder en dur une valeur de couleur spécifique à plusieurs endroits d'un site web ou d'une application, un jeton de conception pour cette couleur peut être créé et réutilisé partout dans le système. Dans la phase finale de l'architecture des jetons, tous les jetons Codex doivent être utilisés exclusivement pour les propriétés de style dans le noyau, les habillages et les extensions MediaWiki. Une modification telle qu'un changement de couleur se reflètera facilement partout.

Les jetons de conception aident à standardiser le processus de conception et de développement, à accroître l'efficacité et à maintenir la cohérence visuelle tout au long des projets.

Utilisation des jetons de conception Codex dans MediaWiki et ses extensions

Vous pouvez utiliser les jetons de conception dans un fichier .less (ou dans un bloc <style lang="less"> d'un fichier .vue) en important mediawiki.skin.variables.less. MediaWiki utilise le système de variables d'habillage pour distribuer les jetons Codex.

Les valeurs de ces variables de jeton diffèrent selon l'habillage. Le thème par défaut de Codex est actuellement utilisé dans MinervaNeue, et une version modifiée du thème par default pour une taille de police de base plus petite (voir aussi la section sur les valeurs relatives ci-dessous) est utilisée dans Vector 2022 et l'ancien Vector. Tous les autres habillages utilisent actuellement des valeurs de retrait définis dans mediawiki.skin.defaults.less; ces valeurs sont encore en cours de développement. See How to make a MediaWiki skin for detailed information.

Exemple de fichier Less utilisant les jetons Codex de conception :

/* Dans 'extensions/MyExtension/resources/extension.stylesheet.less' */
@import 'mediawiki.skin.variables.less';

.my-extension-class {
    /* `@background-color-base` est l'un des jetons de conception fournis par Codex. */
    background-color: @background-color-base;
}

Notez que les exemples du site de documentation Codex importent les jetons à partir de '@wikimedia/codex-design-tokens/..., mais cela ne fonctionne pas dans MediaWiki. A la place, vous devez importer 'mediawiki.skin.variables.less' comme indiqué dans l'exemple ci-dessus.

Jetons à valeurs relatives

Les jetons qui expriment des distances utilisent généralement des valeurs absolues en px, tandis que les jetons qui expriment des tailles utilisent généralement des valeurs relatives en em. Les jetons à valeurs relatives sont conçus pour être utilisés dans un contexte où la taille de la police est celle de la police par défaut de l'habillage. Dans MinervaNeue, la taille de la police par défaut est de 16px; dans Vector 2022 et dans l'ancien Vector, elle est de 14px. Les jetons affectés de valeurs relatives sont initialisés de sorte à fournir la même valeur de pixels pour tous les habillages. Par exemple, dans MinervaNeue @size-icon-medium est fixé à 1.25em (qui est 20px à une taille de police de 16px), tandis que dans Vector 2022 et l'ancien Vector il est fixé à 1.42857em (qui est de 20px pour une taille de police de 14px).

Dans la plupart des cas, l'habillage définira la bonne taille de police pour vous, mais si vous rencontrez des problèmes avec des valeurs relatives produisant la mauvaise taille (généralement un nombre fractionnel de pixels plutôt qu'un nombre rond, par exemple 22,857px au lieu de 20px), vérifiez si la taille de police de l'élément parent est différente de la taille de la police de base de l'habillage.

Utiliser les composants de Codex Vue 3

Notez que cette section comprend également l'utilisation des composés Codex.

Pour commencer

Consultez les documents officiels pour en savoir plus sur les composants Vue 3 disponibles, y compris les démonstrations et les informations d'utilisation (voir par exemple la démo du composant Button). Make sure to use the MediaWiki-specific code samples, since usage differs slightly in and outside of MediaWiki.

Demander les composants Codex dans MediaWiki et les extensions

Codex est inclus dans MediaWiki. Il existe deux façons d'accéder aux composants Codex Vue dans votre module ResourceLoader : en incluant uniquement les composants dont vous avez besoin, ou en demandant l'intégralité de la bibliothèque des composants.

Sous-ensemble de composants

Il est recommandé de demander uniquement les composants nécessaires afin d'améliorer les performances. To see a working example of this system, reference the CodexExample extension.

First, make the following changes to your ResourceLoader module definition in extension.json or skin.json:

Set the class to MediaWiki\\ResourceLoader\\CodexModule.
Add a list of codexComponents, including all components and composables that you will be using.

"ext.myExtension.blockform": {
    "class": "MediaWiki\\ResourceLoader\\CodexModule",
    "codexComponents": [
        "CdxButton",
        "CdxCard",
        "CdxDialog",
        "CdxIcon",
        "CdxRadio",
        "CdxTextInput",
        "useModelWrapper"
    ],
    "packageFiles": [
        "init.js",
        "BlockForm.vue"
    ],
    "messages": [
		"block-target",
		"ipb-submit"
	]
}

This will generate a virtual file, codex.js, in your resources directory with the exports you need. Vous pouvez alors demander les composants et les composables que vous avez demandés à partir de ce fichier virtuel :

// In resources/ext.myExtension/BlockForm.vue
const { CdxButton, CdxTextInput } = require( '../codex.js' );

Note that if you only need the JavaScript files and not styles, you can add "codexScriptOnly": "true" to your module definition. You should only do this if you're putting the styles in another, style-only module using "codexStyleOnly": true.

Bibliothèque complète

Vous pouvez accéder à tous les composants Codex en plaçant le module @wikimedia/codex du RessourceLoader dans les dépendances de votre module.

Exemple de définition de module (dans le format extension.json) :

"ext.myExtension.blockform": {
	"dependencies": [
		"@wikimedia/codex"
	]
	"packageFiles": [
		"init.js",
		"BlockForm.vue"
	],
	"messages": [
		"block-target",
		"ipb-submit"
	]
}

Vous pouvez alors importer des composants et composés comme suit :

// In resources/ext.myExtension/BlockForm.vue
const { CdxButton, CdxTextInput } = require( '@wikimedia/codex' );

Utiliser les composants Codex dans MediaWiki et les extensions

Une fois que vous avez inclus les composants Codex comme une dépendance de votre module ResourceLoader et que vous les avez demandés dans votre fichier Vue, vous pouvez ensuite passer ces composants dans l'option components de votre composant, et les utiliser dans le modèle de ce dernier. Rappelez-vous que la syntaxe kebab est nécessaire dans les modèles , vous devez donc utiliser <cdx-button> pour CdxButton, <cdx-text-input> pour CdXTextInput, etc.

Exemples

Exemple d'un simple format de bloc utilisant les composants CdxButton et CdxTextInput de Codex :

<template>
    <div class="mw-block-form">
        {{ $i18n( 'block-target' ) }}
        <cdx-text-input v-model="username"></cdx-text-input>
        <cdx-button
            type="primary"
            action="destructive"
            :disabled="!isUsernameSet"
            @click="blockUser"
        >
            {{ $i18n( 'ipb-submit' ) }}
        </cdx-button>
    </div>
</template>

<script>
// This assumes you're using a subset of Codex components as described above.
const { CdxButton, CdxTextInput } = require( '../codex.js' );

// @vue/component
module.exports = exports = {
    components: {
        CdxButton,
        CdxTextInput
    },
    data: {
        username: ''
    },
    computed: {
        isUsernameSet() {
            return this.username !== '';
        }
    },
    methods: {
        blockUser() {
            // ...
        }
    }
};
</script>

Utiliser les icônes Codex

Pour commencer

Visitez le site officiel de documentation concernant les informations sur le système d'icônes et une liste de toutes les icônes.

Utiliser les icônes Codex dans MediaWiki et les extensions

Pour des raisons de performance, il n'y a pas de module ResourceLoader codex-icons contenant toutes les icônes de Codex. Un tel module serait énorme et coûteux, car la plupart des utilisateurs de Codex n'ont besoin que d'une poignée de ces 200 icônes. Au lieu de cela, ResourceLoader fournit un moyen pour les modules d'intégrer les icônes dont ils ont besoin, en définissant comme suit un fichier de paquet :

{
    "name": "icons.json",
    "callback": "MediaWiki\\ResourceLoader\\CodexModule::getIcons",
    "callbackParam": [
        // Lisez ici les icônes dont votre module a besoin, par exemple :
        "cdxIconArrowNext",
        "cdxIconBold",
        "cdxIconTrash"
    ]
}

Ces icônes peuvent ensuite être importées dans les fichiers .vue comme suit :

const { cdxIconArrowNext, cdxIconBold, cdxIconTrash } = require( './icons.json' );

Pour plus d'informations sur la façon d'utiliser ces icônes une fois qu'elles ont été importées, voir la documentation de Codex sur les icônes.

Exemples

Exemple du même bloc formaté comme ci-dessus, mais avec une icône ajoutée :

<template>
    <div class="mw-block-form">
        {{ $i18n( 'block-target' ) }}
        <cdx-text-input v-model="username"></cdx-text-input>
        <cdx-button
            type="primary"
            action="destructive"
            @click="blockUser"
        >
            <cdx-icon :icon="cdxIconBlock"></cdx-icon>
            {{ $i18n( 'ipb-submit' ) }}
        </cdx-button>
    </div>
</template>
<script>
    const { CdxButton, CdxTextInput } = require( '@wikimedia/codex' );
    const { cdxIconBlock } = require( './icons.json' );
</script>

Exemple de définition du module ResourceLoader :

"ext.myExtension.blockform": {
	"packageFiles": [
		"init.js",
		"BlockForm.vue",
		{
			"name": "icons.json",
			"callback": "MediaWiki\\ResourceLoader\\CodexModule::getIcons",
			"callbackParam": [
				"cdxIconBlock"
			]
		}
	],
	"messages": [
		"block-target",
		"ipb-submit"
	],
	"dependencies": [
		"@wikimedia/codex"
	]
}

Dans cet exemple, init.js est un fichier d'initialisation qui démarre le composant Vue.createMwApp(), comme documenté avec ici.

Utiliser les mixins Codex Less

Certaines fonctionnalités de Codex sont mises en œuvre à l'aide de mixins Less. Par exemple, le composant Link est un mixin Less plutôt qu'un composant Vue, et l'utilisation d'icônes dans les composants CSS seulement nécessite d'utiliser un mixin Less (voir aussi la documentation ci-dessous pour l'utilisation des composants CSS seulement ).

L'utilisation des mixins Codex Less dans MediaWiki et les extensions fonctionne de manière très similaire à l'utilisation des jetons de conception : il suffit d'importer 'mediawiki.skin.variables.less', ce qui rend tous les mixins Codex disponibles, ainsi que les jetons de conception.

Exemple de fichier Less utilisant un mixin :

/* Dans 'extensions/MyExtension/resources/extension.stylesheet.less' : */
@import 'mediawiki.skin.variables.less';

.my-extension-class {
    a {
        .cdx-mixin-link-base();
    }
}

Notez que les exemples du site de documentation de Codex importent les jetons de '@wikimedia/codex-design-tokens/...' et ensuite le mixin pertinent de '@wikimedia/codex/mixins/...'mais cela ne fonctionne pas dans MediaWiki. Au lieu de cela, vous devez importer 'mediawiki.skin.variables.less' comme indiqué dans l'exemple ci-dessus.

Utiliser le composants Codex uniquement CSS

Certains composants Codex ont des versions CSS seulement qui fonctionnent sans JavaScript. Vous pouvez vérifier qu'un composant possède une version CSS uniquement en recherchant ce composant dans la documentation de Codex, et voir s'il existe une section appelée version CSS uniquement. Par exemple, le composant Bouton possède une telle section. Cette section de documentation contient des exemples de l'apparence du HTML de ce composant.

Pour utiliser un composant CSS uniquement, procédez comme suit :

Générer le HTML du composant comme l'indique sa documentation
Charger le module ResourceLoader approprié contenant les styles de composants, en utilisant addModuleStyles(). This will either be the codex-styles module, which contains the styles for all Codex components, or your own ResourceLoader module with styles for a subset of Codex components (and, if needed, your own styles).

Demander les styles des composants Codex

Sous-ensemble de composants

Il est recommandé de ne demander que les composants dont vous avez besoin pour améliorer les performances. To see a working example of this system, reference the CodexExample extension.

Add a new style-only ResourceLoader module, or add to an existing one in extension.json or skin.json:

Set the class to MediaWiki\\ResourceLoader\\CodexModule.
Add a list of codexComponents, including all components that you will be using.
Add "codexStyleOnly": "true"

"ext.myExtension.styles": {
    "class": "MediaWiki\\ResourceLoader\\CodexModule",
    "codexComponents": [
        "CdxButton",
        "CdxTextInput"
    ],
    "codexStyleOnly": "true"
}

Then, in your PHP code, load the module using addModuleStyles().

$out->addModuleStyles( 'ext.myExtension.styles' );

Bibliothèque complète

You can access the styles for all Codex components by loading the codex-styles module in your PHP code:

$out->addModuleStyles( 'codex-styles' );

Utiliser les composants uniquement CSS de Codex

Exemple simple

Note that this example loads the entire codex-styles module for the sake of simplicity. Dans les cas réels où un seul composant est utilisé, vous devez charger un sous-ensemble du Codex comme expliqué ci-dessus.

// obtenir un objet OutputPage
$out = $this->getOutput();
// générer le HTML
$out->addHTML(
    '<button class="cdx-button cdx-button--action-progressive cdx-button--weight-primary">' .
    $this->msg( 'message-for-button-label' )->escaped() .
    '</button>'
);
// Charger le module des styles Codex.
$out->addModuleStyles( 'codex-styles' );

Exemple plus complexe

Dans SpecialFoo.php :

// obtenir un objet OutputPage
$out = $this->getOutput();
// générer le HTML
$out->addHTML( <<<HTML
    <div
        class="cdx-text-input cdx-text-input--has-start-icon"
    >
        <input class="cdx-text-input__input" type="text">
        <span
            class="cdx-text-input__icon cdx-text-input__start-icon mw-special-foo-input-icon"
        ></span>
    </div>
HTML
);
// Chargez le module des styles Codex et notre propre module de styles.
$out->addModuleStyles( [ 'codex-styles', 'ext.specialfoo.styles' ] );

Dans extension.json :

{
    "ResourceModules": {
        "ext.specialfoo.styles": {
            "class": "MediaWiki\\ResourceLoader\\CodexModule",
            "codexComponents": [
                "CdxTextInput"
            ],
            "codexStyleOnly": "true",
            "styles": [
                "SpecialFoo.less"
            ]
        }
    }
}

Dans SpecialFoo.less :

/* Importer tous les jetons de conception Codex et les mixins à l'aide de mediawiki.skin.variables.less. */
@import 'mediawiki.skin.variables.less';

.mw-special-foo {
    /* ... other styles ... */

    &-input-icon {
        .cdx-mixin-css-icon( @cdx-icon-search );
    }
}

Migrer de l'interface utilisateur MediaWiki vers Codex

Lorsque vous remplacez l'interface utilisateur obsolète MediaWiki UI par Codex, il est recommandé d'utiliser les composants CSS uniquement du paquet @wikimedia/codex, ou dans certains cas les jetons @wikimedia/codex-design-tokens et les mixins Less à la place.

Veuillez consulter l'article Migrer l'interface utilisateur MediaWiki pour les informations détaillées.

Fréquence de diffusion de Codex

Une nouvelle version de Codex est diffusée un mardi sur deux. Quand une nouvelle version est créée, un correctif du noyau MediaWiki est proposé pour utiliser cette nouvelle version. Comme cela est fait tous les mardis, la mise à jour du noyau sera déployée la semaine suivante (la prochaine fois que le train de déploiement est réactivé).

Vous pouvez voir tous les labels Codex sur Gerrit ou un calendrier des labels sur GitHub. Pour plus d'informations sur ce qui est contenu dans chaque version, voir le journal des modifications.

Voir aussi le Calendrier des versions de l'équipe des systèmes de conception