CodexExample MediaWiki extension

The Design System Team maintains the CodexExample MediaWiki extension for demonstration purposes. 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.

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.

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

"ext.myExtension.foo": {
    "class": "MediaWiki\\ResourceLoader\\CodexModule",
	"packageFiles": [
		"init.js",
		"MyComponent.vue"
	],
    "codexComponents": [
        "CdxButton",
        "CdxCard",
        "CdxDialog"
    ]
}

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

Utilisation sans JavaScript (composants Codex uniquement CSS)

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.

"ext.myExtension.foo": {
	"class": "MediaWiki\\ResourceLoader\\CodexModule",
	"styles": "ext.myExtension.foo/styles.less",
	"codexStyleOnly": "true",
	"codexComponents": [
		"CdxButton",
		"CdxCard",
		"CdxCheckbox",
		"CdxProgressBar"
	]
}

<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.

composer require wikimedia/codex

$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;

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.

—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 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"
    ]
}

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();
    }
}

Using Codex in userscripts

It is possible to use Codex in userscripts. However, there are some limitations that will require certain workarounds. Here are a few considerations to keep in mind when using Vue and Codex in userscripts:

• No .vue single-file component support; you must define components in plain .js files
• Everything needs to live in one file; userscripts don't provide a good way to load custom modules
• Define component templates using ES6 template literals
• Prefer global component registration for Codex components

mw.loader.using( '@wikimedia/codex' ).then( function( require ) {
    const Vue = require( 'vue' );
    const Codex = require( '@wikimedia/codex' );
} );

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 );
} );