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">Click me!</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' );

Uso sem JavaScript (componentes Codex somente 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">
		Default button
	</button>
</div>
<div>
	<button class="cdx-button cdx-button--action-progressive">
		Progressive button
	</button>
</div>
<div>
	<button class="cdx-button cdx-button--action-destructive">
		Destructive button
	</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( "Accordion Example" )
			->setDescription( "Este é um exemplo de accordion." )
			->setContentHtml(
				$codex
					->htmlSnippet()
					->setContent( "<p>Este é o conteúdo do accordion.</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. Você pode então exigir os componentes e elementos que podem ser compostos solicitados desse arquivo virtual:

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

Por motivos de desempenho, não existe um módulo ResourceLoader de codex-icons contendo todos os ícones do Codex. Tal módulo seria grande e um desperdício, já que a maioria dos usuários do Codex só precisa de alguns dos mais de 200 ícones. Em vez disso, o ResourceLoader fornece uma maneira para os módulos incorporarem os ícones necessários, semelhante à abordagem de divisão de código descrita acima.

{
    "name": "icons.json",
    "callback": "MediaWiki\\ResourceLoader\\CodexModule::getIcons",
    "callbackParam": [
        // Liste os ícones que seu módulo precisa aqui, por exemplo:
        "cdxIconArrowNext",
        "cdxIconBold",
        "cdxIconTrash"
    ]
}

See also:

• list of all icons (names and variants)
• using icons in Vue

Usando tokens de design diretamente

Design tokens can be imported into LESS stylesheets as variables. This may be useful if you are developing your own components or styles, and want them to integrate with Codex.

Codex design tokens should be imported from the mediawiki.skin.variables.less file.

@import 'mediawiki.skin.variables.less';

.my-feature {
    background-color: @background-color-base;
    color: @color-base;
}

Algumas funções do Codex são implementadas usando mixins do Less. Por exemplo, o Componente Link é um mixin do Less em vez de um componente Vue, e o uso de ícones em componentes somente CSS requer o uso do mixin (veja também abaixo a documentação para usando componentes somente CSS).

Usar mixins Less Codex no MediaWiki e extensões funciona de forma muito semelhante a usar tokens de design: basta importar mediawiki.skin.variables.less, o que disponibiliza todos os mixins do Codex, bem como os tokens de design.

@import 'mediawiki.skin.variables.less';

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