Codex
|
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 traduites pour 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.
Voir le site de documentation officielle pour obtenir des détails complets sur Codex, y compris sur la façon de l'utiliser en dehors de MediaWiki.
Codex est le système de conception d'interface utilisateur recommandé fourni avec MediaWiki depuis MediaWiki 1.39. Il est également disponible sous forme d'ensemble de paquets npm. Le système est développé par Wikimedia Foundation en collaboration avec 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 suivre 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).
Extension MediaWiki CodexExample
Le Codex/Steering Committee maintient l'extension MediaWiki CodexExample qui montre comment utiliser les jetons de conception, les composants et les icônes de Codex.
Cette extension peut être installée (elle crée une page spéciale dédiée appelée Special:CodexExample avec des démonstrations en direct), où vous pouvez étudier son code source et vous en inspirer.
Voir la page du projet README.md pour plus d'informations sur l'installation et l'utilisation.
Utilisation avec JavaScript
Les composants Codex sont construits à l'aide de l'environnement JavaScript Vue.js.
Si vous développez une application Vue dans MediaWiki, il est facile de charger les composants Codex du ResourceLoader en utilisant require().
Vous pouvez charger simultanément la totalité de Codex, ou simplement un sous-ensemble limité de composants.
Charger toute la bibliothèque (recommandé pour les scripts utilisateur)
"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>
Charger un sous-ensemble de composants Codex (recommandé pour les habillages et les extensions)
Déclarer les dépendances pour ne charger qu'un ensemble limité de composants; voir la section sur l'utilisation avancée.
Utilisation sans JavaScript (composants Codex uniquement CSS)
| Version de MediaWiki : | ≥ 1.42 |
De nombreux composants Codex prennent également en charge l'utilisation de "CSS-only". Ces composants doivent apparaître visuellement identiques à leurs homologues JavaScript quand celui-ci est activé, mais ils offriront un comportement plus limité.
Chargement des styles de composants
Vous pouvez charger les styles d'un sous-ensemble limité de composants CSS Codex de la même manière que vous le feriez pour les composants JavaScript ci-dessus.
Si vous n'avez besoin que des styles, vous pouvez ajouter l'option "codexStyleOnly": "true" lorsque vous définissez votre module.
"ext.myExtension.foo": {
"class": "MediaWiki\\ResourceLoader\\CodexModule",
"styles": "ext.myExtension.foo/styles.less",
"codexStyleOnly": "true",
"codexComponents": [
"CdxButton",
"CdxCard",
"CdxCheckbox",
"CdxProgressBar"
]
}
Fournir le balisage des composants
Pour utiliser des composants Codex CSS-only, assurez-vous que les styles appropriés sont chargés, puis ajoutez le marquage nécessaire à votre page. Pour l'instant il faut faire cela manuellement. Vous trouverez des exemples de balisage dans la section « utilisation CSS-only » de la page de documentation des composants (exemple : balisage pour le composant Button).
<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>
Utiliser Codex dans PHP
Codex PHP est une bibliothèque pour construire les composants CSS-only de l'interface utilisateur avec Codex, le sysème de conception de Wikimedia; voir la documentation Codex PHP.
Installation
Installer la bibliothèque Codex PHP via Composer :
composer require wikimedia/codex
Exemple d'utilisation
Voici un exemple de création d'un composant Accordéon en 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;
Utilisation avancée
Utilisation d'un sous-ensemble limité de composants
Le module ResourceLoader @wikimedia/codex fournit la bibliothèque Codex entière – tous les composants, les styles, etc.
Si vous développez un habillage ou une extension et que les performances vous préoccupent, pensez à utiliser la fonctionnalité code-splitting de Codex.
ResourceLoader vous permet de spécifier une liste de composants Codex et de charger uniquement le JavaScript ou le CSS pour ces composants ainsi que leurs dépendances.
L'enregistrement de nombreux modules est fortement déconseillé, même s'ils ne sont pas chargés par défaut. L'ajout de chaque module augmente de 44 octets[1] le chargement initial de chaque page, soit environ un transfert supplémentaire de 40 Gio par jour pour les serveurs Wikimedia.
Pour utiliser cette fonctionnalité, définir un module personnalisé ResourceLoader (ce qui est généralement fait en skin.json ou extension.json) et spécifier une liste de 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"
]
}
Cela générera le fichier virtuel codex.js dans votre répertoire resources avec les exports nécessaires.
Vous pouvez alors demander les composants et les composables que vous avez demandés à partir de ce fichier virtuel :
// Dans resources/ext.myExtension/BlockForm.vue
const { CdxButton, CdxTextInput } = require( '../codex.js' );
Si vous avez besoin des composants CSS-only uniquement sans charger les composants JavaScript, vous pouvez ajouter "codexStyleOnly": true à la définition du module.
De même, si vous avez besoin des fichiers JavaScript uniquement et pas des styles, vous pouvez ajouter "codexScriptOnly": "true".
Vous ne devez faire cela que lorsque vous placez les styles dans un autre module (uniquement de style) comme décrit ci-dessus.
Voir le dépôt CodexExample pour les détails sur la manière d'utiliser Codex dans une extension MediaWiki.
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": [
// lister 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 les intégrer à 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;
}
Voir la liste complète des jetons de conception de Codex triée par catégorie.
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-only nécessite d'utiliser un mixin Less (voir aussi la documentation pour l'utilisation des composants CSS-only ).
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 du 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( {
// Placer ici les données, les propriétés calculées, les méthodes, etc.
} ).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 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
Les nouvelles versions du Codex sont publiées en fonction des besoins et non selon un calendrier précis. 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 habituellement 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 faire 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';dansLocalSettings.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 » mais ne devrait pas créer d'erreur.
Une fois cette configuration effectuée, vous pouvez apporter des modifications supplémentaires à votre clone de 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.