Codex/fr

Projets de la Fondation Wikimedia 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 Groupe : Codex Steering Committee Membres de l'équipe : Derek Torsani, Roan Kattouw, Jan Drewniak Arriéré des tâches : #codex Mises à jour : CHANGELOG.md

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

For improved page load performance, limit loading to a subset of Codex components for skins and extensions. See § Using a limited subset of components

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 still under development and is not yet recommended for wide-spread use in MediaWiki core (T399523). Breaking changes may be introduced until a stable version is released.

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

Prioritize page load performance by using ResourceLoader to load only the necessary Codex components whenever possible.

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 to every initial page load, so about 40 GiB of extra transfer to Wikimedia servers per day.

—ResourceLoader

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 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, similaire à l'approche de division de code décrite ci-dessous.

{
    "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 :

• liste de toutes les icônes (noms et variantes)
• utilisation d'icônes dans Vue

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 .js simples
• 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

Once you've loaded Vue and Codex, you must define a Vue app and mount it somewhere on the page. The exact location will vary depending on what you are trying to do. You can use MediaWiki's custom createMwApp method for this.

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

The link below shows a complete example of a userscript which adds a portlet link to all Wiki pages that triggers a custom Codex Dialog component to launch when clicked. Feel free to copy this script to your own user page to use as a starting point.

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

Release cycle

A new version of Codex is released every other Tuesday. When a new release is created, a patch is also submitted to MediaWiki core to use that new release. Since this is done on Tuesdays, the update to core will be deployed the following week (the next time the deployment train runs).

Using a custom version of Codex for development or testing

MediaWiki uses the latest release of Codex. If you need to use a different version for development or testing purposes, for example to test how an unmerged patch in Codex interacts with MediaWiki, you can point MediaWiki to your own version of Codex as follows:

1. Clone the Codex repository (if you haven't already), and check out the change you want to test.
2. Run npm install and npm run build-all in the root directory of the Codex repository.
3. Point $wgCodexDevelopmentDir to the root directory of the Codex repository. For example, if you cloned the Codex repository in the parent directory of the MediaWiki directory, add $wgCodexDevelopmentDir = MW_INSTALL_PATH . '../codex'; to LocalSettings.php
4. Test that it works by running mw.loader.load( '@wikimedia/codex' ) in the browser console. This should trigger a warning saying "You are using a local development version of Codex", and should not trigger any errors.

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.