Codex
 | Visitez le site de documentation officielle pour obtenir des détails complets sur le Codex, y compris sur la façon de l'utiliser en dehors de MediaWiki. |
|
Codex
 Système de conception pour les lignes directrices de Wikimedia avec un ensemble d'outils (jetons de conception, composants et icônes) pour créer des interfaces utilisateur
|
Codex est le système de conception de Wikimedia. Il fournit un ensemble unifié d'outils, de directives et de composants pour aider les développeurs et les concepteurs à créer des interfaces utilisateur cohérentes, accessibles et localisées dans tous les projets Wikimedia.
Codex permet aux contributeurs d'utiliser des composants d'interface utilisateur standardisés créés avec Vue.js et CSS, tels que des boutons, des menus, des boîtes de dialogue et des icônes, qui sont conçus pour être faciles à utiliser, accessibles et compatibles. Il garantit une apparence et un comportement cohérents pour nos produits, afin qu'ils soient conformes aux normes de style visuel et de fonctionnalité de Wikimedia. Il aide les développeurs et les concepteurs à créer des interfaces conviviales et faciles à maintenir.
Codex est le système de conception d'interface utilisateur recommandé, et est fourni avec MediaWiki depuis MediaWiki 1.39. Il est également disponible sous forme d'ensemble de paquets npm. Le système est développé en collaboration par Wikimedia Foundation, Wikimedia Deutschland et des contributeurs bénévoles.
Le code source de Codex est hébergé sur Gerrit et le développement est suivi dans Phabricator. Vous pouvez voir le journal des modifications complet et rejoindre notre groupe Telegram Contributeur pour discuter.
Utilisation de base
Codex fournit une variété de composants que les auteurs d'habillages, d'extensions, et de scripts utilisateur peuvent inclure dans leurs propres interfaces utilisateurs : boutons, cases à cocher, sélecteurs, dialogues, etc. Beaucoup de ces composants peuvent être largement personnalisés.
Consultez la liste complète des composants Codex (ainsi que la documentation et les démos interactives).CodexExample MediaWiki extension
The Codex Steering Committee maintains the CodexExample MediaWiki extension that demonstrates how to use design tokens, components, and icons from Codex.
This extension can be installed (it sets up a dedicated special page called Special:CodexExample with live demos), or you can study its source code for inspiration.
See the project README.md page for more information on installation and use.
Usage with JavaScript
Codex components are built using the Vue.js JavaScript framework.
If you are developing a Vue application in MediaWiki, then it's easy to load Codex components from ResourceLoader using require().
You can load all of Codex at once, or just a limited subset of components.
Loading the entire library (recommended for use in userscripts)
"ext.myExtension.foo": {
"dependencies": [ "@wikimedia/codex" ]
"packageFiles": [
"init.js",
"MyComponent.vue"
]
}
<!-- MyComponent.vue -->
<template>
<cdx-button @click="doSomething">Cliquez ici !</cdx-button>
</template>
<script>
const { CdxButton } = require( '@wikimedia/codex' );
module.exports = exports = {
name: "MyComponent",
components: {
CdxButton
},
methods: {
doSomething() {
//...
}
}
}
</script>
Loading a subset of Codex components (recommended for skins and extensions)
To only load a limited set of components, you can declare your dependencies in the following way below:
"ext.myExtension.foo": {
"class": "MediaWiki\\ResourceLoader\\CodexModule",
"packageFiles": [
"init.js",
"MyComponent.vue"
],
"codexComponents": [
"CdxButton",
"CdxCard",
"CdxDialog"
]
}
This will generate a virtual file, codex.js, in your resources directory with the exports you need.
You can then require the components you requested from that virtual file:
// In resources/ext.myExtension.foo/MyComponent.vue
const { CdxButton, CdxTextInput } = require( '../codex.js' );
See the CodexExample repository for more in-depth example of how to use Codex in a MediaWiki extension.
Utilisation sans JavaScript (composants Codex uniquement CSS)
| Version de MediaWiki : | ≥ 1.42 |
Many Codex components also support "CSS-only" usage. These components should appear visually identical to their JS-enabled counterparts, but they will offer more limited behavior.
Loading component styles
You can load the styles of a limited subset of Codex CSS components in the same way as you would for JS components, above.
If you only need the styles, you can add the "codexStyleOnly": "true" option when you define your module.
"ext.myExtension.foo": {
"class": "MediaWiki\\ResourceLoader\\CodexModule",
"styles": "ext.myExtension.foo/styles.less",
"codexStyleOnly": "true",
"codexComponents": [
"CdxButton",
"CdxCard",
"CdxCheckbox",
"CdxProgressBar"
]
}
Providing component markup
To use CSS-only Codex components, just ensure that the appropriate styles are loaded and then add the necessary markup to your page. For now, you'll have to do this by hand. You can find example markup in the "CSS-only usage" section on a component's documentation page (here is the markup for the Button component).
<div>
<button class="cdx-button cdx-button--action-default">
Bouton par défaut
</button>
</div>
<div>
<button class="cdx-button cdx-button--action-progressive">
Bouton progressif
</button>
</div>
<div>
<button class="cdx-button cdx-button--action-destructive">
Bouton destructeur
</button>
</div>
Using Codex in PHP
Codex PHP is a library for building CSS-only UI components using Codex, the Wikimedia design system, please see the Codex PHP documentation.
Installation
Install the Codex PHP library via Composer:
composer require wikimedia/codex
Example usage
Here’s an example of creating an Accordion component in PHP:
$accordion = $codex
->accordion()
->setTitle( "Exemple d'accordéon" )
->setDescription( "C'est un exemple d'accordéon." )
->setContentHtml(
$codex
->htmlSnippet()
->setContent( "<p>Voici le contenu de l'accordéon.</p>" )
->build()
)
->setOpen( false )
->setAttributes( [
"class" => "foo",
"bar" => "baz",
] )
->build()
->getHtml();
echo $accordion;
Advanced usage
Using a limited subset of components
The @wikimedia/codex ResourceLoader module provides the entire Codex library – all components, styles, etc.
If you are developing a skin or an extension and you care about performance, you should consider using Codex's code-splitting feature.
ResourceLoader allows you to specify a list of Codex components and load only the JS/CSS for those components plus their dependencies.
Registering many modules is highly discouraged, even if they are not loaded by default. The addition of each module adds 44 bytes[1] to every initial page load, so about 40 GiB of extra transfer to Wikimedia servers per day.
To use this feature, define a custom ResourceLoader module (this is typically done in skin.json or extension.json) and specify a list of codexComponents:
"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' );
If you only need CSS-only components and don't wish to load the component JavaScript, you can add "codexStyleOnly": true to the module definition.
Similarly, if you only need the JavaScript files and not styles, you can add "codexScriptOnly": "true".
You should only do this if you're putting the styles in another, style-only module as described above.
Utiliser les icônes Codex
Pour des raisons de performance, il n'y a pas de module ResourceLoader nommé codex-icons
{
"name": "icons.json",
"callback": "MediaWiki\\ResourceLoader\\CodexModule::getIcons",
"callbackParam": [
// Lisez ici les icônes dont votre module a besoin, par exemple :
"cdxIconArrowNext",
"cdxIconBold",
"cdxIconTrash"
]
}
Voir aussi :
Utiliser les jetons de conception directement
Les jetons de conception peuvent être importés dans les feuilles de style Less en tant que variables. Cela peut être utile si vous développez vos propres composants ou styles et que vous souhaitez qu'ils s'intégrent à Codex.
Les jetons de conception de codex doivent être importés depuis le fichier mediawiki.skin.variables.less.
@import 'mediawiki.skin.variables.less';
.my-feature {
background-color: @background-color-base;
color: @color-base;
}
Pour la liste complète des jetons de conception de Codex, trier par catégorie, voir ici.
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.
@import 'mediawiki.skin.variables.less';
.my-feature {
a {
.cdx-mixin-link-base();
}
}
Utiliser Codex dans des scripts utilisateurs
Il est possible d'utiliser Codex dans les scripts utilisateur. Cependant, certaines limitations nécessitent des solutions de contournement. Voici quelques points à prendre en compte lors de l'utilisation de Vue et Codex dans les scripts utilisateur :
- Pas de prise en charge des composants à fichier unique
.vue; vous devez définir les composants dans des fichiers.jssimples - Tout doit se trouver dans un seul fichier ; les scripts utilisateur ne constituent pas un bon moyen de charger des modules personnalisés
- Définissez les modèles de composants à l'aide des littéraux de modèle ES6
- Privilégiez l'enregistrement global des composants pour les composants Codex
Chargement de Vue/Codex
Vous devrez charger Vue et Codex à partir de ResourceLoader.
La meilleure façon de procéder est d'utiliser mw.loader.using ; le reste de votre code doit se trouver dans une chaîne de rappel ou de promesse.
mw.loader.using( '@wikimedia/codex' ).then( function( require ) {
const Vue = require( 'vue' );
const Codex = require( '@wikimedia/codex' );
} );
Utiliser Vue.createMwApp
Une fois que vous avez chargé Vue et Codex, vous devez définir une application Vue et la monter quelque part sur la page.
L'emplacement exact variera en fonction de ce que vous essayez de faire.
Vous pouvez utiliser la méthode personnalisée createMwApp de MediaWiki pour cela.
mw.loader.using( '@wikimedia/codex' ).then( function( require ) {
//... Nécessite Vue et Codex comme ci-dessus
// créer un élément pour installer l'application Vue
const mountPoint = document.body.appendChild( document.createElement( 'div' ) );
// créer une application Vue et l'installer à l'élément cible
Vue.createMwApp( {
// Les données, les accessoires informatiques, les méthodes, etc. vont ici
} ).mount( mountPoint );
} );
Exemples d’utilisation
Le lien ci-dessous montre un exemple complet de script utilisateur qui ajoute un lien portlet à toutes les pages Wiki et qui déclenche le lancement d'un composant Codex Dialog personnalisé lorsque l'on clique dessus. N'hésitez pas à copier ce script sur votre propre page utilisateur pour l'utiliser comme point de départ.
https://en.wikipedia.org/wiki/User:EGardner_(WMF)/codex-hello-world.js
Voici un nouveau script utilisant Codex :
https://en.wikipedia.org/wiki/User:JSherman_(WMF)/revertrisk.js
Cycle de publication
Une nouvelle version de Codex est publiée tous les mardis. Lorsqu'une nouvelle version est créée, un correctif est également soumis au noyau MediaWiki afin d'utiliser cette nouvelle version. Comme cela se fait le mardi, la mise à jour du noyau sera déployée la semaine suivante (lors du prochain déploiement).
Utilisation d'une version personnalisée de Codex pour le développement ou les tests
MediaWiki utilise la dernière version de Codex. Si vous avez besoin d'utiliser une version différente à des fins de développement ou de test, par exemple pour tester comment un correctif non fusionné dans Codex interagit avec MediaWiki, vous pouvez pointer MediaWiki vers votre propre version de Codex comme suit :
- Clonez le référentiel Codex (si ce n'est déjà fait) et vérifiez la modification que vous souhaitez tester.
- Exécutez
npm installetnpm run build-alldans le répertoire racine du référentiel Codex. - Pointez
$wgCodexDevelopmentDirvers le répertoire racine du dépôt Codex. Par exemple, si vous avez cloné le dépôt Codex dans le répertoire parent du répertoire MediaWiki, ajoutez$wgCodexDevelopmentDir = MW_INSTALL_PATH . '../codex';àLocalSettings.php. - Vérifiez que cela fonctionne en exécutant
mw.loader.load( '@wikimedia/codex' )dans la console du navigateur. Cela devrait déclencher un avertissement indiquant « Vous utilisez une version de développement locale de Codex », et ne devrait pas déclencher d'erreurs.
Une fois cette configuration effectuée, vous pouvez apporter des modifications supplémentaires à votre clone Codex, mais vous devez exécuter npm run build-all à chaque fois pour que ces modifications prennent effet dans MediaWiki.
Pour désactiver le mode développement et revenir à la dernière version de Codex, commentez la ligne dans LocalSettings.php qui définit $wgCodexDevelopmentDir.