Codex/Migrating from MediaWiki UI
< Codex
From MediaWiki 1.41 on, it is recommended to use markup for Codex CSS-only components instead of MediaWiki UI markup. This page aims to explain how to handle migrations.
Introduction to Codex CSS-only components[edit]
Codex provides CSS-only components for consumers who are concerned about using Vue.js and Codex library. They provide a lightweight mechanism to render basic components such as buttons, checkboxes, input, icons and radio elements.
The most recent information on CSS components can be found in the official Codex documentation. For example see the CSS-only-version of the button component as an example.
How to migrate to Codex from mediawiki.ui modules[edit]
Migrating away from MediaWiki ui markup requires 2 changes:
- You should remove the ResourceLoader module from the page, and instead load either codex-styles OR codex-search-styles. The former loads all styles for all Codex components and the latter loads a subset of styles for commonly used components.
- It is important to chose the appropriate module:
- Currently in performance sensitive pages e.g. articles we recommend using codex-search-styles. This stylesheet is loaded by default on the Minerva and Vector 2022 skins.
- If the page is not performance sensitive, for example it is a special page, or a page primarily for logged in editors, particularly pages which load Vue.js and Codex at some point in the page life cycle, use the full codex-styles module.
- If in doubt, use codex-search-styles.
- It is important to chose the appropriate module:
- You should change the HTML markup per the sections below.
Migrating HTML from mediawiki.ui modules to Codex modules[edit]
| Component | MediaWiki UI markup | Codex equivalent markup |
|---|---|---|
| Icon | <span class="mw-ui-icon mw-ui-icon-bookmark"></span>
|
<span class="my-feature-class--bookmark"></span>
@import "mediawiki.skin.variables.less";
.my-feature-class {
&--bookmark {
.cdx-mixin-css-icon( @cdx-icon-bookmark );
}
}
|
| Button | <button class="mw-ui-button">
Click me
</button>
|
<button class="cdx-button">
Click me
</button>
|
| Icon button | <button class="mw-ui-button mw-ui-icon-element" aria-label="Back">
<span class="mw-ui-icon mw-ui-icon-arrow-previous"></span>
</button>
|
<button class="cdx-button cdx-button--icon-only" aria-label="Back">
<span class="cdx-button__icon my-feature-class--arrow-previous"></span>
</button>
@import "mediawiki.skin.variables.less";
.my-feature-class {
&--arrow-previous {
.cdx-mixin-css-icon( @cdx-icon-arrow-previous, @param-is-button-icon: true );
}
}
|
| Input | <input class="captcha-word mw-ui-input" placeholder="Enter captcha">
|
<div class="cdx-text-input">
<input class="captcha-word cdx-text-input__input" placeholder="Enter captcha">
</div>
|
| Checkbox | <div class="mw-ui-checkbox">
<input name="wpRemember" type="checkbox" value="1" id="wpRemember" tabindex="3" class="mw-userlogin-rememberme">
<label for="wpRemember">Keep me logged in (for up to 365 days)</label>
</div>
|
<div class="cdx-checkbox">
<input name="wpRemember" type="checkbox" value="1" id="wpRemember" tabindex="3" class="mw-userlogin-rememberme cdx-checkbox__input">
<span class="cdx-checkbox__icon"> </span>
<label for="wpRemember" class="cdx-checkbox__label">Keep me logged in (for up to 365 days)</label>
</div>
|
| Radio | <span class="mw-ui-radio">
<input
id="radio-css-only-1"
type="radio"
name="radio-css-only"
/>
<label for="radio-css-only-1">
Radio 1
</label>
</span>
|
<span class="cdx-radio">
<!-- <input> element with id, type, name, and any other necessary
attributes. The actual input is visually hidden. -->
<input
id="radio-css-only-1"
class="cdx-radio__input"
type="radio"
name="radio-css-only"
/>
<!-- Empty span that will be styled to look like a radio input. -->
<span class="cdx-radio__icon"></span>
<!-- Label with `for` attribute matching the input's id. -->
<label class="cdx-radio__label" for="radio-css-only-1">
Radio 1
</label>
</span>
|
Component modifiers[edit]
Many components can be modified. This lookup table should help you map MediaWiki UI modifiers to Codex equivalents.
| Modifier class in MediaWiki UI | Modifier class in Codex |
|---|---|
mw-ui-quiet
|
cdx-button--weight-quiet
|
mw-ui-progressive
|
cdx-button--action-progressive
|
mw-ui-destructive
|
cdx-button--action-destructive
|