Codex

Проекты Фонда Викимедиа Codex Дизайн-система для Викимедиа, включающая в себя рекомендации и набор инструментов (дизайн-токены, компоненты и иконки) для разработки пользовательских интерфейсов. Группа: Codex Steering Committee Члены команды: Derek Torsani, Roan Kattouw, Jan Drewniak Бэклог: #codex Обновления: CHANGELOG.md

Codex — официальная дизайн-система Wikimedia . Она предоставляет единый набор инструментов, рекомендаций и компонентов, которые помогают разработчикам и дизайнерам создавать согласованные, доступные и локализованные пользовательские интерфейсы для проектов Викимедиа.

Codex позволяет участникам использовать стандартизированные компоненты интерфейса, разработанные с использованием Vue.js и базового CSS , вроде кнопок, меню, диалогов и иконок, которые предназначены для удобства использования, доступности и совместимости. Она обеспечивает единообразный внешний вид и поведение наших продуктов, чтобы они соответствовали визуальному стилю и стандартам функциональности Викимедиа. Она поддерживает как разработчиков, так и дизайнеров в создании удобных и легко поддерживаемых интерфейсов.

Codex является рекомендованной дизайн-системой для пользовательского интерфейса, и она была включена в MediaWiki с версии MediaWiki 1.39 . Помимо этого она доступна в качестве набора npm-пакетов. Система совместно разрабатывается Wikimedia Foundation , Wikimedia Deutschland и волонтёрами.

Исходный код Codex размещён на Gerrit, а его разработка отслеживается в Phabricator. Вы можете ознакомиться с полным списком изменений и присоединиться к нашей группе в Telegram для вкладчиков, чтобы принять участие.

Базовое использование

Codex предоставляет различные «компоненты», которые авторы тем оформления, расширений и скриптов могут встроить в свои пользовательские интерфейсы: кнопки, флажки, переключатели, диалоговые окна и т. д. Многие из этих компонентов широко настраиваемы.

 См. полный список компонентов Codex (вместе с документацией и интерактивными демо).

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 Загрузчик ресурсов 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">Нажмите на меня!</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.

Использование без JavaScript (CSS-компоненты Codex)

Версия 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">
		Кнопка по умолчанию
	</button>
</div>
<div>
	<button class="cdx-button cdx-button--action-progressive">
		Прогрессивная кнопка
	</button>
</div>
<div>
	<button class="cdx-button cdx-button--action-destructive">
		Деструктивная кнопка
	</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( "Пример аккордеона" )
			->setDescription( "Это пример аккордеона" )
			->setContentHtml(
				$codex
					->htmlSnippet()
					->setContent( "<p>Это содержимое аккордеона</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. Затем вы можете запросить указанные вами компоненты и composable функции из этого виртуального файла:

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

Использование иконок Codex

Из соображений производительности модуля ResourceLoader под названием codex-icons, содержащего бы все значки из Codex, не существует. Такой модуль был бы громоздким и неэффективным, поскольку большинство пользователей Codex нуждаются лишь в нескольких из более чем 200 иконок. Вместо этого ResourceLoader предоставляет модулям способ встраивать только те иконки, которые им необходимы, аналогично описанному выше подходу с разделением кода.

{
    "name": "icons.json",
    "callback": "MediaWiki\\ResourceLoader\\CodexModule::getIcons",
    "callbackParam": [
        // Укажите иконки, которые необходимы вашему модулю, например:
        "cdxIconArrowNext",
        "cdxIconBold",
        "cdxIconTrash"
    ]
}

См. также:

• список всех иконок (имена и переменные)
• использование иконок во Vue

Использование дизайн-токенов напрямую

Дизайн-токены могут быть импортированны в таблицы стилей Less как переменные. Это может быть полезно, если вы создаёте свои компоненты или стили, и хотите чтобы они интегрировались с Codex.

Дизайн-токены Codex нужно импортировать из файла mediawiki.skin.variables.less.

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

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

Полный список дизайн-токенов Codex, разбитый по категориям, см. в Codex documentation#Design tokens.

Less-миксины Codex

Некоторые функции Codex реализуются с использованием миксинов Less. Например, компонент Link вляется больше Less-миксином, чем компонентом Vue, и использование иконок в компонентах только на CSS требует использования Less-миксина (см. также документацию по использованию компонентов только на CSS).

Использование миксинов Less c Codex в Mediawiki и расширениях работает очень схоже с использованием дизайн-токенов: просто импортируйте mediawiki.skin.variables.less, что сделает доступными все миксины Codex, а заодно и дизайн-токены.

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

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

Использование Codex в пользовательских скриптах

Использование Codex в пользовательских скриптах возможно, однако существуют некоторые ограничения, требующие определённых обходных решений. Вот несколько моментов, которые стоит учитывать при использовании Vue и Codex в пользовательских скриптах: 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:

• Однофайловые компоненты .vue не поддерживаются; вам нужно определять компоненты в базовых файлах .js
• Всё должно находится в одном файле; пользовательские скрипты не предоставляют оптимального способа загрузки кастомных модулей
• Определите шаблоны компонентов, используя шаблонные литералы ES6
• Предпочитайте глобальную регистрирацию для компонентов Codex

Загрузка Vue/Codex

Вам нужно будет загрузить Vue и Codex через ResourceLoader. Лучший способ сделать это — использовать mw.loader.using; остальной код вашего пользовательского скрипта должен быть размещён в callback-функции или цепочке промисов. The best way to do this is via mw.loader.using; the rest of your userscript code should live in a callback or promise chain.

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

Используйте Vue.createMwApp

Как только Vue и Codex будут загружены, вам нужно создать приложение Vue и смонтировать его куда-либо на странице. Его точное местоположение будет зависеть от того, что вы собираетесь делать. Для этого можно использовать специальный для MediaWiki метод createMwApp. 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 ) {
	//... загрузите Vue и Codex, как указано выше
	// создайте элемент, к которому будет смонтировано приложение Vue
	const mountPoint = document.body.appendChild( document.createElement( 'div' ) );
	// создайте Vue-приложение и смонтируйте его к целевому элементу
	Vue.createMwApp( {
		// данные, вычисляемые свойства, методы и прочее указываются здесь
	} ).mount( mountPoint );
} );

Реальные примеры

Ссылка ниже показывает полный пример пользовательского скрипта, добавляющего ссылку в портлет ко всем страницам вики, которая при клике вызывает кастомный компонент Dialog из Codex. Не стесняйтесь скопировать этот скрипт на свою страницу участника и использовать его как отправную точку.

https://en.wikipedia.org/wiki/User:EGardner_(WMF)/codex-hello-world.js

А вот другой скрипт, использующий Codex:

https://en.wikipedia.org/wiki/User:JSherman_(WMF)/revertrisk.js

Цикл релизов

Новая версия Codex выпускается каждый второй вторник. Когда создаётся новый релиз, в основное ядро MediaWiki также отправляется патч для использования этой новой версии. Поскольку это происходит по вторникам, обновление ядра будет развернуто на следующей неделе (в следующий раз, когда будет запущен deployment train).

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

Использование кастомной версии Codex для разработки или тестирования

MediaWiki использует последнюю версию Codex. Если вам нужно использовать другую версию для разработки или тестирования, например, чтобы опробовать, как патч, над которым ещё ведётся работа, в Codex взаимодействует с MediaWiki, вы можете указать движку на вашу собственную версию Codex следующим образом:

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. # Клонируйте репозиторий Codex (если ещё не сделали этого) и выберите изменения, которые хотите протестировать.
2. Запустите команду npm install и npm run build-all в корневой директории репозитория Codex.
3. Укажите $wgCodexDevelopmentDir на корневую директорию репозитория Codex. Например, если вы клонировали репозиторий Codex в родительскую директорию MediaWiki, добавьте $wgCodexDevelopmentDir = MW_INSTALL_PATH . '../codex'; в файл LocalSettings.php.
4. Проверьте, что всё работает, выполнив команду mw.loader.load( '@wikimedia/codex' ) в консоли браузера. Должно появиться предупреждение «You are using a local development version of Codex», и не должно возникать ошибок.
5. Run npm install and npm run build-all in the root directory of the Codex repository.
6. 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
7. 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.

Как только вы завершите настройку, вы сможете вносить дополнительные изменения в ваш клон Codex, но каждый раз необходимо будет запускать команду npm run build-all, чтобы изменения вступили в силу в MediaWiki.

Чтобы отключить режим разработки и вернуться к использованию последней версии Codex, закомментируйте строку в файле LocalSettings.php, которая устанавливает $wgCodexDevelopmentDir.