Codex
|
Codex
 Vývojový systém pro Wikimedii s pokyny a sadou nástrojů (vývojové tokeny, komponenty a ikony) pro vytváření uživatelských rozhraní
|
Codex je oficiální vývojový systém pro Wikimedia. Poskytuje jednotnou sadu nástrojů, pokynů a komponent, které pomáhají vývojářům a designérům vytvářet konzistentní, přístupná a lokalizovaná uživatelská rozhraní napříč projekty Wikimedie.
Codex umožňuje přispěvatelům používat standardizované komponenty uživatelského rozhraní vytvořené s Vue.js nebo jen s CSS – jako jsou tlačítka, nabídky, dialogy a ikony. Zajišťuje konzistentní vzhled a chování našich produktů, aby odpovídaly vizuálnímu stylu a funkčním standardům Wikimedie. Podporuje vývojáře i designéry při vytváření uživatelsky přívětivých a snadno udržovatelných rozhraní.
Navštivte oficiální stránky s dokumentací, kde najdete podrobné informace o Codexu, včetně toho, jak jej používat mimo MediaWiki.
Codex je součástí MediaWiki od MediaWiki 1.39. Je také k dispozici jako sada balíčků npm. Systém je vyvíjen ve spolupráci s Wikimedia Foundation, Wikimedia Deutschland a dobrovolnými přispěvateli.
Zdrojový kód Codexu je hostován na Gerritu a jeho vývoj je sledován ve Phabricatoru. Můžete si prohlédnout úplný seznam změn a připojit se k naší skupině přispěvatelů na Telegramu.
Základní použití
Codex poskytuje řadu komponent, které mohou autoři vzhledů, rozšíření a uživatelských skriptů vkládat do svých vlastních uživatelských rozhraní: tlačítka, zaškrtávací políčka, přepínače, dialogy atd. Mnoho z těchto komponent lze značně přizpůsobit.
Rozšíření CodexExample pro MediaWiki
Codex/Steering Committee udržuje rozšíření CodexExample MediaWiki, které demonstruje, jak používat designové tokeny, komponenty a ikony z Codexu.
Toto rozšíření si můžete nainstalovat (vytvoří speciální stránku s názvem Special:CodexExample s živými ukázkami) nebo si můžete pro inspiraci prostudovat jeho zdrojový kód.
Více informací o instalaci a použití naleznete na stránce projektu README.md.
Použití s JavaScriptem
Komponenty Codexu jsou vytvářeny pomocí frameworku Vue.js JavaScript.
Pokud vyvíjíte aplikaci Vue v MediaWiki, je snadné načíst komponenty Codexu z ResourceLoader pomocí require().
Můžete načíst celý Codex najednou nebo jen omezenou podmnožinu komponent.
Načítání celé knihovny (doporučeno pro použití v uživatelských skriptech)
"ext.myExtension.foo": {
"dependencies": [ "@wikimedia/codex" ]
"packageFiles": [
"init.js",
"MyComponent.vue"
]
}
<!-- MyComponent.vue -->
<template>
<cdx-button @click="doSomething">Klikněte sem!</cdx-button>
</template>
<script>
const { CdxButton } = require( '@wikimedia/codex' );
module.exports = exports = {
name: "MyComponent",
components: {
CdxButton
},
methods: {
doSomething() {
//...
}
}
}
</script>
Načítání podmnožiny komponent Codexu (doporučeno pro vzhledy a rozšíření)
Deklarujte závislosti tak, aby se načetla pouze omezená sada komponent; viz sekce o pokročilém použití.
Použití bez JavaScriptu (komponenty Codexu pouze s CSS)
| Verze MediaWiki: | ≥ 1.42 |
Mnoho komponent Codexu také podporuje použití "pouze CSS". Tyto komponenty by měly vypadat vizuálně identicky jako jejich protějšky s podporou JS, ale budou nabízet omezenější chování.
Načítání stylů komponent
Styly omezené podmnožiny CSS komponent Codexu můžete načíst stejným způsobem jako u JS komponent výše.
Pokud potřebujete pouze styly, můžete při definici modulu přidat možnost "codexStyleOnly": "true".
"ext.myExtension.foo": {
"class": "MediaWiki\\ResourceLoader\\CodexModule",
"styles": "ext.myExtension.foo/styles.less",
"codexStyleOnly": "true",
"codexComponents": [
"CdxButton",
"CdxCard",
"CdxCheckbox",
"CdxProgressBar"
]
}
Poskytování značek komponent
Chcete-li používat komponenty Codexu pouze s CSS, stačí se ujistit, že jsou načteny příslušné styly, a poté na stránku přidat potřebné značky. Prozatím to budete muset udělat ručně. Příklad kódu naleznete v sekci "Použití pouze v CSS" na stránce dokumentace komponenty (zde je kód pro komponentu Button).
<div>
<button class="cdx-button cdx-button--action-default">
Výchozí tlačítko
</button>
</div>
<div>
<button class="cdx-button cdx-button--action-progressive">
Progresivní tlačítko
</button>
</div>
<div>
<button class="cdx-button cdx-button--action-destructive">
Destruktivní tlačítko
</button>
</div>
Používání Codexu v PHP
Codex PHP je knihovna pro tvorbu UI komponent pouze s CSS pomocí Codexu, vývojového systému Wikimedie. Viz dokumentace Codexu PHP.
Instalace
Nainstalujte si knihovnu Codex PHP pomocí Composer:
composer require wikimedia/codex
Příklad použití
Zde je příklad vytvoření komponenty Accordion v PHP:
$accordion = $codex
->accordion()
->setTitle( "Příklad akordu" )
->setDescription( "Toto je příklad akordu." )
->setContentHtml(
$codex
->htmlSnippet()
->setContent( "<p>Toto je obsah akordu.</p>" )
->build()
)
->setOpen( false )
->setAttributes( [
"class" => "foo",
"bar" => "baz",
] )
->build()
->getHtml();
echo $accordion;
Pokročilá využití
Použití omezené podmnožiny komponent
Modul ResourceLoader @wikimedia/codex poskytuje celou knihovnu Codexu – všechny komponenty, styly atd.
Pokud vyvíjíte skin nebo rozšíření a záleží vám na výkonu, měli byste zvážit použití funkce rozdělování kódu v Codexu.
ResourceLoader umožňuje zadat seznam komponent Codexu a načíst pouze JS/CSS pro tyto komponenty a jejich závislosti pomocí třídy CodexModule.
Registrace velkého množství modulů se důrazně nedoporučuje, i když nejsou ve výchozím nastavení načteny. Přidání každého modulu přidá k prvnímu načtení stránky 44 bajtů [1], takže denně se na servery Wikimedia přenese přibližně 40 GiB dat navíc.
Chcete-li tuto funkci použít, definujte vlastní modul ResourceLoader (obvykle se to dělá v skin.json nebo v extension.json) a zadejte seznam 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"
]
}
Tím se ve vašem adresáři resources vygeneruje virtuální soubor codex.js s potřebnými exporty.
Pak můžete z daného virtuálního souboru vyžádat požadované komponenty a kompozovatelné prvky:
// V resources/ext.myExtension/BlockForm.vue
const { CdxButton, CdxTextInput } = require( '../codex.js' );
Pokud potřebujete pouze komponenty s CSS a nechcete načítat JavaScript komponenty, můžete do definice modulu přidat hodnotu "codexStyleOnly": true.
Podobně, pokud potřebujete pouze soubory JavaScript a ne styly, můžete přidat "codexScriptOnly": "true".
Toto byste měli dělat pouze v případě, že styly vkládáte do jiného modulu, který slouží pouze ke stylům, jak je popsáno výše.
Podrobnější příklad použití Codexu v rozšíření MediaWiki naleznete v repozitáři CodexExample.
Používání ikon Codexu
Z důvodu výkonu neexistuje modul ResourceLoader s názvem codex-icons
{
"name": "icons.json",
"callback": "MediaWiki\\ResourceLoader\\CodexModule::getIcons",
"callbackParam": [
// Zde uveďte ikony, které váš modul potřebuje, např.:
"cdxIconArrowNext",
"cdxIconBold",
"cdxIconTrash"
]
}
Související stránky:
Přímé použití designových tokenů
Tokeny návrhu lze importovat do stylových listů Less jako proměnné. To může být užitečné, pokud vyvíjíte vlastní komponenty nebo styly a chcete je integrovat s Codexem.
Tokeny návrhu Codexu by měly být importovány ze souboru mediawiki.skin.variables.less.
@import 'mediawiki.skin.variables.less';
.my-feature {
background-color: @background-color-base;
color: @color-base;
}
Podívejte se na úplný seznam designových tokenů Codexu, rozdělených podle kategorií.
Codex mixinů LESS
Některé funkce Codexu jsou implementovány pomocí mixinů LESS. Například komponenta Link je spíše LESS mixin než komponenta Vue a použití ikon v komponentách pouze s CSS vyžaduje použití LESS mixinu (viz také dokumentace k používání komponent pouze s CSS).
Používání Codex mixinů LESS v MediaWiki a rozšířeních funguje velmi podobně jako používání designových tokenů: Jednoduše importujte mediawiki.skin.variables.less, čímž zpřístupníte všechny Codexové mixiny i designové tokeny.
@import 'mediawiki.skin.variables.less';
.my-feature {
a {
.cdx-mixin-link-base();
}
}
Používání Codexu v uživatelských skriptech
Codex je možné používat v uživatelských skriptech. Existují však určitá omezení, která vyžadují určitá alternativní řešení. Zde je několik věcí, které je třeba mít na paměti při používání Vue a Codexu v uživatelských skriptech:
- Žádná podpora pro komponenty typu
.vuev jednom souboru. Komponenty je nutné definovat v prostých souborech.js - Vše musí být uloženo v jednom souboru. Uživatelské skripty neposkytují dobrý způsob pro načítání vlastních modulů
- Definování šablon komponent pomocí literálů šablon ES6
- Upřednostňování globální registrace komponent pro komponenty Codexu
Načítání Vue/Codexu
Budete muset načíst Vue a Codex z ResourceLoaderu.
Nejlepší způsob, jak to udělat, je pomocí mw.loader.using; zbytek kódu userscriptu by měl být součástí callbacku nebo promise řetězce.
mw.loader.using( '@wikimedia/codex' ).then( function( require ) {
const Vue = require( 'vue' );
const Codex = require( '@wikimedia/codex' );
} );
Použití Vue.createMwApp
Jakmile načtete Vue a Codex, musíte definovat aplikaci Vue a připojit ji někam na stránku.
Přesné umístění se bude lišit v závislosti na tom, co se snažíte udělat.
K tomu můžete použít vlastní metodu createMwApp od MediaWiki.
mw.loader.using( '@wikimedia/codex' ).then( function( require ) {
//... vyžadují Vue a Codex, jak je uvedeno výše
// vytvořit element pro připojení aplikace Vue
const mountPoint = document.body.appendChild( document.createElement( 'div' ) );
// vytvořit aplikaci Vue a připojit ji k cílovému elementu
Vue.createMwApp( {
// data, vypočítané vlastnosti, metody atd. zde
} ).mount( mountPoint );
} );
Skutečné příklady
Níže uvedený odkaz ukazuje kompletní příklad uživatelského skriptu, který přidává odkaz na portlet na všechny stránky wiki, jenž po kliknutí spustí vlastní komponentu Codex Dialog. Neváhejte tento skript zkopírovat na svou vlastní uživatelskou stránku a použít jej jako výchozí bod.
https://en.wikipedia.org/wiki/User:EGardner_(WMF)/codex-hello-world.js
Zde je další skript používající Codex:
https://en.wikipedia.org/wiki/User:JSherman_(WMF)/revertrisk.js
Cyklus vydávání
Nové verze Codexu jsou vydávány ad hoc podle potřeby, nikoli podle konkrétního harmonogramu. Když je vytvořena nová verze, je do jádra MediaWiki také odeslána záplata, která tuto novou verzi používá. Protože se to děje v úterý, aktualizace jádra bude nasazena následující týden (při příštím spuštění nasazení).
Používání vlastní verze Codexu pro vývoj nebo testování
MediaWiki používá nejnovější verzi Codexu. Pokud potřebujete pro účely vývoje nebo testování použít jinou verzi, například k otestování interakce nesloučené záplaty v Codexu s MediaWiki, můžete MediaWiki nasměrovat na vaši vlastní verzi Codexu takto:
- Naklonujte Codex repozitář (pokud jste tak ještě neučinili) a podívejte se na změnu, kterou chcete otestovat.
- Spusťte příkazy
npm installanpm run build-allv kořenovém adresáři repozitáře Codex. - Umístěte
$wgCodexDevelopmentDirdo kořenového adresáře repozitáře Codex. Pokud jste například naklonovali repozitář Codex do nadřazeného adresáře adresáře MediaWiki, přidejte$wgCodexDevelopmentDir = MW_INSTALL_PATH . '../codex';doLocalSettings.php - Otestujte funkčnost spuštěním příkazu
mw.loader.load( '@wikimedia/codex' )v konzoli prohlížeče. Mělo by se zobrazit varování "Používáte lokální vývojovou verzi Codexu" a nemělo by se zobrazit žádné chyby.
Jakmile toto nastavíte, můžete ve svém klonu Codexu provádět další změny, ale abyste tyto změny projevili v MediaWiki, musíte pokaždé spustit příkaz npm run build-all.
Chcete-li zakázat vývojářský režim a vrátit se k používání nejnovější verze Codexu, zakomentujte řádek v souboru LocalSettings.php, který nastavuje $wgCodexDevelopmentDir.