Příručka:Jak vytvořit vzhled MediaWiki
Vytvoření vzhledu je skvělý způsob, jak se seznámit s vnitřním fungováním MediaWiki a zahájit své příspěvky do hnutí Wikimedia! Pokud jste obeznámeni s předními technologiemi CSS, JavaScript a JSON, můžete si vytvořit vzhled MediaWiki! Není potřeba znát PHP, ale může vám pomoci, pokud chcete dělat něco pokročilého.
I když to není nezbytné, pomůže vám, pokud znáte LESS CSS. Tento průvodce předpokládá, že jste nainstalovali funkční verzi MediaWiki a používáte aktuální vývojovou verzi, pokud ne, doporučujeme to udělat jako první.
Pokud máte existující vzhled pomocí PHP BaseTemplate, tato příručka není pro vás. Místo toho si přečtěte Příručka:Jak vytvořit vzhled MediaWiki/Migraci vzhledů založených na SkinTemplate do SkinMustache.
Příprava
Vývoj vzhledu bude mnohem snazší, když budete znát šablony Moustache.
Minimálně byste měli být obeznámeni s následujícími základy Moustache popsanými v níže uvedeném příkladu:
{{ str }} <!-- renders escaped string -->
{{{ html-str }}} <!-- renders RAW HTML -->
<!-- accesses data inside an associative array of the form { 'key' => 'hello' } -->
{{#array-data}}
{{ key }} <!-- renders hello -->
{{/array-data}}
<!-- for boolean values -->
{{#is-talk-page}}
<!-- conditional rendering if is-talk-page is true -->
{{/is-talk-page}}
Vzhled je zodpovědný za vykreslení obsahu viditelného pro uživatele – HTML uvnitř tagu BODY. Je zakázáno upravovat cokoli uvnitř HEAD. Pro vzhled bude automaticky vygenerován kód, aby se vzhled mohl soustředit na prezentaci. Pokud potřebujete upravit HEAD, který je považován za mimo rozsah vzhledu, použijte k tomu háčky, rozšíření nebo konfiguraci viz FAQ, kde najdete osvědčené postupy, jak to udělat.
Začínáme
Chcete-li začít vytvářet svůj první vzhled, doporučujeme dvě možnosti.
Možnost 1 - Příklad vzhledu rozvětvením
Vzorové zobrazení https://github.com/wikimedia/mediawiki-skins-Example poskytuje jednoduchou implementaci vzhledu. Naklonujte úložiště do složky vzhledů a ujistěte se, že se tato složka jmenuje "Example" a přidejte do svých LocalSettings.php následující:
wfLoadSkin( 'Example' );
Pokud vše proběhlo podle plánu, měl by být váš vzhled dostupný na stránce Special:Preferences vaší wiki.
Možnost 2 – Použijte laboratoř vzhledů
Labolatorní nástroj zobrazení vám umožňuje nastavit vzhled pomocí základních CSS a šablon. Jakmile se budete cítit pohodlně, můžete kliknout na "stáhnout jako ZIP", čímž se sestaví potřebný základ pro váš vzhled. Doufejme, že se ve výsledném úložišti budete snadno orientovat. Až si stáhnete ZIP, umístěte jej do složky vzhledů MediaWiki a aktualizujte LocalSettings.php následujícím:
wfLoadSkin( 'FolderName' );
Pokud vše proběhlo podle plánu, měl by být váš vzhled dostupný na stránce Special:Preferences vaší wiki.
Možnost 3 - Z příkazového řádku
cd mediawiki/skins
npm install mediawiki-skins-cli
npx create-mw-skin SkinName
cd SkinName
Až si stáhnete ZIP, umístěte jej do složky vzhledů MediaWiki a aktualizujte LocalSettings.php pomocí následujícího:
wfLoadSkin( 'SkinName' );
Dejte lidem vědět!
Vytvoření vzhledu bude zábavnější s ostatními lidmi a také mnohem jednodušší! Jakmile budete mít něco použitelného, zvažte zveřejnění na GitHubu nebo Gerrit. Jakmile bude kód veřejně dostupný, měli byste vytvořit stránku vzhledu (nezapomeňte změnit název!), aby lidé věděli, že jste otevřeni spolupráci!
Nastavení wiki stránky má mnoho dalších výhod. Budete moci zpracovávat hlášení o chybách v Phabricator nebo GitHubu a přijímat záplaty od ostatních dobrovolníků z komunity MediaWiki. Někdo by vám také měl pomoci s nastavením překladu.
Mustache
Ve verzi 1.35 jsme přidali podporu pro Mustache ve vzhledech. Zjistili jsme, že použití Mustache je velmi užitečné při vývoji vzhledů Skin:Minerva a Skin:Vector, protože vám umožňuje oddělit data od prezentace. Části Mustache lze použít k opětovnému použití šablon. Chcete-li v MediaWiki použít částečný Partial.mustache, jednoduše je přidejte do složky, ve které pracujete, a odkazujte na ně pomocí {{>Partial}} v hlavní šabloně 'skin.mustache'.
Data odesílaná do šablon Mustache jsou poměrně flexibilní. Pokud něco chybí, můžete pomocí PHP přidat data rozšířením funkce SkinMustache::getTemplateData.
Vzhled SkinJson lze přidat do vývojové instance MediaWiki a zkontrolovat data dostupná pro vzhledy. Všimněte si, že pole mají předponu "array-", booleany mají předponu "is-" a objekty mají předponu "data-", což vám pomůže vytvořit představu o datech, se kterými pracujete.
Dostupné údaje a ve kterých verzích MediaWiki jsou k dispozici jsou zdokumentovány na SkinMustache.php.
Vytvoření přeložitelného vzhledu (i18n)
V skin.json pod ValidSkinNames můžete použít volbu `messages` k definování přeložitelných klíčů zpráv.
Tyto klíče by měly odpovídat záznamům ve složce i18n/en.json.
Jakmile se zaregistrujete pro vzhled, budou k dispozici ve vaší šabloně s předponou msg-.
"example": {
"class": "SkinMustache",
"args": [ {
"name": "example",
"messages": [
"sitetitle",
"search",
"tagline",
"navigation-heading"
]
} ]
}
Například v níže uvedeném příkladu lze zprávu "sitetitle" vykreslit v šabloně Mustache pomocí:
<p>{{msg-sitetitle}}</p>
Další informace o tom, proč je to důležité, najdete na stránce Lokalizace.
Části šablony vykreslení
Části šablony lze použít k vykreslení různých částí vzhledu a vyhnout se problému s velkým souborem skin.mustache, který nelze udržovat. V následujícím příkladu vzhled vykreslí obsah šablon ve 3 souborech s názvy Logo.mustache, Content.mustache a Footer.mustache. Tyto soubory musí existovat ve stejné složce jako soubor skin.mustache nebo podsložka adresáře obsahujícího skin.mustache.
{{>subfolder/Logo}}
{{>Content}}
{{>Footer}}
Části šablony jsou skvělým způsobem, jak rozdělit zobrazení, aby bylo čitelnější. Žádné části šablony nejsou předdefinovány a ve výchozím nastavení jsou dostupné, nicméně pro inspiraci se můžete podívat na existující vzhledy pomocí SkinMustache.
Přečtěte si více o částech šablony Moustache.
Logo.mustache
Následující blok kódu se používá k zobrazení loga webu ve vzhledu Example a totéž uvidíte, pokud vytvoříte vzhled ze SkinLabs.
<!-- Logo.mustache -->
<div id="p-logo" class="mw-portlet" role="banner">
<a href="{{link-mainpage}}">
{{#data-logos}}
{{#icon}}<img src="{{.}}" width="40" height="40">{{/icon}}
{{#wordmark}}<img src="{{src}}" width="{{width}}" height="{{height}}">{{/wordmark}}
{{^wordmark}}<h1>{{msg-sitetitle}}</h1>{{/wordmark}}
{{/data-logos}}
</a>
</div>
Z výše uvedeného bloku kódu je následující řádek zodpovědný za zobrazení loga `icon`:
{{#icon}}<img src="{{.}}" width="40" height="40">{{/icon}}
Tento řádek předpokládá, že v poli $wgLogos je klíč icon.
Pokud je tedy ve vašem souboru LocalSettings.php řádek podobný jako $wgLogos = [ 'icon' => "$wgResourceBasePath/resources/assets/wiki.png" ];, zobrazí se obrázek loga/ikony.
Výchozí MediaWiki LocalSettings.php exportuje klíč 1x v poli $wgLogos.
Chcete-li tedy zobrazit logo, musíte aktualizovat LocalSettings.php a přidat klíč icon.
resources/assets/wiki.png. Protože se změní na výchozí, když aktualizujete MediaWiki. Doporučený způsob, jak změnit logo, je přidat nový soubor obrázku loga a přidat tuto cestu k LocalSettings.php.
Všechny nabídky jsou strukturovány ve stejném formátu (PortletData). Obecnou částečnou šablonu Menu.mustache, přidanou do stejné složky jako skin.mustache, lze proto použít k vytvoření nabídky.
<nav id="{{id}}" class="{{class}}" title="{{html-tooltip}}"
aria-labelledby="{{id}}-label">
<input type="checkbox" aria-labelledby="{{id}}-label" />
<h3 id="{{id}}-label" {{{html-user-language-attributes}}}>{{label}}</h3>
<div class="mw-portlet-body">
<ul {{{html-user-language-attributes}}}>
{{{html-items}}}
</ul>
{{{html-after-portal}}}
</div>
</nav>
Při použití této části však budete muset sdělit, pro kterou nabídku má generovat HTML.
V skin.mustache by následující vykreslilo nabídku jazyků a zobrazení.
{{! Switch template context to data for all menus }}
{{#data-portlets}}
{{! Access the menu called "languages" }}
{{#data-languages}}
{{>Menu}}
{{/data-languages}}
{{! Access the menu called "views" }}
{{#data-views}}
{{>Menu}}
{{/data-views}}
{{/data-portlets}}
Rozbalovací nabídka nebo podnabídky vykreslování
Návrháři vzhledů mohou také použít syntaxi Mustache k vytvoření rozevíracích nabídek z prvků, které se dříve nacházely v postranním panelu vzhledů Vector a MonoBook. To je však trochu složitější, ale pochopení způsobu uložení prvků může pomoci.
První prvek postranního panelu – obvykle obsahující odkaz na hlavní stránku a další odkazy na MediaWiki, je vykreslen pomocí volání {{#data-portlets-sidebar.data-portlets-first}}.
Následující nabídky jsou však uloženy v poli {{#data-portlets-sidebar.array-portlets-rest}} a lze je vykreslit voláním tohoto.
Například lze použít následující syntaxi:
{{#data-portlets-sidebar.array-portlets-rest}}
<div class="mw-dropdown-title"><span>{{label}}</span>
<div class="dropdown-content">{{>Portlet}}</div></div>
{{/data-portlets-sidebar.array-portlets-rest}}
Což, když je CSS použito ke skrytí "dropdown-content", dokud nad "mw-dropdown-title" nepřejede kurzor, čímž se vytvoří rozbalovací nabídka.
Zakázání obsahu
V MW 1.38 můžete odstranit obsah z těla článku a umístit jej mimo oblast obsahu. Chcete-li zakázat generování obsahu, přidejte k skin.json následující:
{
"ValidSkinNames": {
"notocskin": {
"class": "SkinMustache",
"args": [
{
"name": "notocskin",
"toc": false
}
]
}
}
}
K vykreslení obsahu lze použít klíč šablony array-sections.
Další příklady
Chcete-li vidět příklady částí šablon, které lze použít ve vašem projektu, můžete si prohlédnout příklady v laboratoři vzhledů Wikimedie.
Skripty a styly
Výchozí
Minimální vzhled vyžaduje modul ResourceLoader s jedním stylem definovaný v souboru skin.json vašeho vzhledu. Bude to vypadat trochu takto:
"ResourceModules": {
"skins.example": {
"class": "ResourceLoaderSkinModule",
"features": { "normalize": true },
"styles": [ "resources/skins.example.less" ]
}
},
Klíč funkcí vám umožňuje používat užitečné výchozí hodnoty základu pro různé věci, včetně i18n a normalizace, které jsou zdokumentovány v dokumentaci jádra MediaWiki php. Funkcemi mohou být pole klíčů (zásady opt-in) nebo v MW 1.36 asociativní pole (zásady odhlášení, doporučeno). Pokud si nejste jisti, vynechejte klávesu funkcí a použijte doporučené výchozí hodnoty.
CSS / LESS
skin.json je manifestem všech aktiv, které vaše zobrazení používá.
Pod klávesou `ResourceModules` byste měli najít modul stylu pro váš vzhled uvedený pod `skins.example`.
Zde pod klíčem "styles" můžete přidat LESS nebo CSS souborů.
Budou načteny v pořadí, v jakém jsou uvedeny.
S LESS můžete použít @import výpisy ve stejné složce.
Více informací o tom, co je možné, naleznete v Developing_with_ResourceLoader.
Při používání obrázků byste měli být schopni používat relativní identifikátory URI pro přístup k obrázkům.
Proměnné vzhledu MediaWiki
Proměnné vzhledu MediaWiki byly původně představeny v MW 1.35, nedávný vývoj jim umožnil pracovat pro široké použití od MW 1.41.
Seznam dostupných hodnot je synchronizován s nejnovějšími Codex designové tokeny (demo stránky).
- Rychle proveďte návrh – Proměnné vzhledu nabízejí návrhářům vzhledu způsob, jak rychle implementovat volby návrhu nastavením hodnot v plochém seznamu. Jejich prostřednictvím mohou návrháři měnit základní vlastnosti, jako je typografie (rodina písem, velikost písma atd.), barvy, zarážky, okraje, velikosti, mezery nebo z-indexy. Tento jednoduchý seznam je seskupen podle vlastností CSS. Aby jej ResourceLoader vyzvedl, musí být umístěn ve složce a souboru resources/mediawiki.less/mediawiki.skin.variables.less. Schéma pojmenování se řídí konvencí pojmenování proměnných MediaWiki.
- Neutrální výchozí údaje – Pokud vzhled neurčuje určité hodnoty, systém automaticky použije výchozí hodnoty z vlastního mediawiki.skin.defaults.less od MediaWiki. Tyto hodnoty představují základní vzhled HTML.
- Přizpůsobení – I když nemůžete měnit názvy proměnných, můžete definovat další v samostatných souborech specifických pro vzhled. V každém souboru Less můžete importovat hodnoty vzhledu pouze o
@import 'mediawiki.skin.variables.less'; - Výhody centralizace – Všechny definice proměnných pro výchozí téma Wikimedie a všechna pojmenování jsou centralizována, aby to bylo možné
- Vytvoří se konzistentní konvence pojmenování pro jasnost a jednotnost
- Zajistí kompatibilitu mezi různými vzhledy a rozšířeními
- Poskytne přehled o potenciálních mezerách nebo oblastech zlepšení na základě běžných vzorců používání
Autoři vzhledů se vyzývají, aby se s těmito aktualizacemi seznámili, aby maximalizovali potenciál svých vzhledů.
Použití v jádru, vzhledech a rozšířeních Less souborů
Abyste mohli použít proměnné mediawiki.skin.variables.less neboli tokeny návrhu, musíte do souboru Less zahrnout příkaz importu.
Příklad použití:
@import 'mediawiki.skin.variables.less';
/* Odkazy */
a {
color: @color-link;
}
a:visited {
color: @color-link--visited;
}
a:active {
color: @color-link--active;
}
Důležitým detailem je, že pouze proměnné specifikované v mediawiki.skin.defaults.less mohou být znovu přiřazeny s hodnotami specifickými pro vzhled v souboru vzhledu mediawiki.skin.variables.less.
Všimněte si, že vzhledy Vector 2022, Vector legacy a MinervaNeue používají dvě výchozí témata Codexu pro uživatelská rozhraní Wikimedie, která jsou také zastoupena na stránce dokumentace Codexu.
Více než 45 různých vzhledů a rozšíření již používá proměnné vzhledu v MW 1.41.
Reagujicí vzhledy / přidání meta zobrazení
Pokud vytváříte responzivní vzhled, ujistěte se, že používáte volbu vzhledu responsive, když deklarujete svůj vzhled v skin.json.
{
"ValidSkinNames": {
"my-responsive-skin": {
"class": "SkinMustache",
"args": [
{
"name": "my-responsive-skin",
"responsive": true
}
]
}
}
}
Vytvoření kompatibility vzhledů s jazyky, které jsou zprava doleva (RTL)
Písma určitých jazyků, např. Hebrejština je spíše zprava doleva než zleva doprava. To představuje problém pro vývojáře vzhledů, kde jsou rozhraní převrácena, např. v Vector je postranní panel vlevo, nikoli vpravo.
V MediaWiki je také možné použít jiný jazyk pro vzhled a obsah. Například v Special:Preferences můžete nastavit svůj jazyk na hebrejštinu a zároveň zachovat obsah v angličtině.
Psaní vzhledů, které dobře fungují v RTL, je velké téma mimo rozsah tohoto dokumentu, ale pokud potřebujete otestovat svůj vzhled v RTL, měli byste aktualizovat LocalSettings.php, abyste změnili jazyk obsahu:
$wgLanguageCode = "he";
Jako vývojář vzhledu byste měli mít na paměti dvě věci:
- Jakýkoli CSS napsaný pro váš vzhled bude automaticky převrácen pomocí nástroje CSSJanus, aniž byste museli pracovat, ale možná budete muset některé z těchto transformací zakázat (viz Flipping).
- Jakýkoli HTML, který vykreslíte a který lze přeložit, by měl být označen dir atribut HTML]. Pro vaše pohodlí SkinMustache poskytuje proměnnou šablony html-user-language-attributes, kterou lze použít takto:
<div
{{{html-user-language-attributes}}}
>
</div>
pro uživatele, který si v předvolbách nastavil svůj jazyk na hebrejštinu, vytvoří následující HTML:
<div
dir="rtl" lang="he"
>
</div>
Obrázky
Příručka:$wgLogos můžete rozšířit o data, která si zvolíte. To umožní správcům webu konfigurovat obrázky podle vlastního výběru, ale musíte je vždy vykreslit podmíněně.
V případech, kdy musí být obrázky z nějakého důvodu pevně zakódovány a nelze použít obrázek na pozadí CSS nebo wgLogos, budete muset rozšířit data odeslaná do šablony
JavaScript
JavaScript kód ve vzhledech běží v prostředí, kde se můžete spolehnout na načtení objektů `mw` a `jQuery`. Doporučujeme použít ResourceLoader/Package_files, což vám umožní vyžadovat aktiva souboru.
Informace o dostupném rozhraní API a knihovnách naleznete v základní dokumentaci JS.
Pokročilejší
Pokročilejší informace budou poskytnuty na vyžádání. Pro urychlení přidávání dokumentace, položte, prosím, otázku na diskusní stránce!
i18n
Zprávy definované v i18n/en.json lze předat přímo do vaší šablony Mustache zahrnutím do skin.json. Všimněte si, že můžete použít jakékoli zprávy definované uvnitř jádra MediaWiki.
| skin.json | i18n/en.json | skin.mustache |
|---|---|---|
{
"ValidSkinNames": {
"mymustacheskin": {
"class": "SkinMustache",
"args": [
{
"name": "mymustacheskin",
"messages": [
"createaccount"
]
}
]
}
}
}
|
{
"@metadata": {
"authors": []
},
"skinname-mymustacheskin": "My Mustache Skin",
"mymustacheskin-hello": "Hello"
}
|
<div>
{{msg-mymustacheskin-hello}} <!-- prints hello in the current language -->
</div>
|
Rozšíření dat
Dostupné údaje jsou zdokumentovány na SkinMustache.php.
Pokud potřebujete přidat další data pro vykreslování do šablony vašeho vzhledu, která nemohou být obsluhována zprávami (jako v sekci i18n), např. raw HTML nebo složité datové struktury, musíte použít vyhrazenou třídu PHP a rozšířit metodu SkinMustache::getTemplateData.
<?php
class MySkin extends SkinMustache {
/**
* Rozšiřuje funkci getTemplateData o přidání klíče šablony 'html-myskin-hello-world'
* které lze vykreslit v skin.mustache pomocí {{{html-myskin-hello-world}}}
*/
public function getTemplateData() {
$data = parent::getTemplateData();
$data['html-myskin-hello-world'] = '<strong>Hello world!</strong>'; // nebo $this->msg('msg-key')->parse();
return $data;
}
}
Výchozí styl pomocí třídy ResourceLoaderSkinModule
Všechny vzhledy by měly definovat jednotný modul stylu s třídou ResourceLoaderSkinModule. Modul definuje různé výchozí styly, které se starají o vnitřnosti MediaWiki. Pokud chcete, můžete tyto funkce zakázat a poskytnout své vlastní styly. Definujte funkce jako prázdný objekt, abyste se připojili k doporučeným výchozím nastavením MediaWiki. seznam funkcí podpory je uveden v našich dokumentech.
Příklad ResourceLoaderSkinModule, který deaktivuje funkci loga, ale povolí několik dalších:
{
"skins.vector.styles": {
"class": "ResourceLoaderSkinModule",
"features": {
"normalize": true,
"elements": true,
"content": true,
"logo": false,
"interface": true,
"legacy": true
},
"targets": [
"desktop",
"mobile"
],
"styles": [ "resources/skins.vector.styles/skin.less" ]
}
}
}
Integrace s dalšími rozšířeními
Rozšíření by se měla integrovat s vámi, ne naopak! Zkuste při psaní vzhledu zapomenout na rozšíření. Vzhledy pro vývojáře rozšíření jsou poskytovány vývojářům rozšíření, aby zajistili nejlepší kompatibilitu. Úvodní šablony v Getting_started vykreslí všechny možné prvky uživatelského rozhraní. Pokud vynecháte určitá data, můžete přerušit podporu s rozšířeními.
U některých rozšíření možná budete chtít vyladit styly výchozích prvků uživatelského rozhraní, zejména Extension:Echo. K tomu budete muset přečíst Příručka:$wgResourceModuleSkinStyles.
Složení menu lze měnit pomocí háčků. Například ve Vectoru, háček SkinTemplateNavigation se používá k přemístění ikony hvězdičky hodinek. Nezapomeňte přitom zkontrolovat upravovaný, abyste se vyhnuli nežádoucím účinkům na jiné vzhledy.
Chci změnit prvky v záhlaví stránky HTML
Vývojáři vzhledů by se neměli zabývat úpravou čehokoli v HEAD dokumentu. Úpravy HEAD jsou lépe dostupné prostřednictvím rozšíření a konfigurace uvnitř LocalSettings.php.
Následující odkazy mohou být užitečné:
- Příručka:$wgAppleTouchIcon
- Příručka:$wgFavicon
- Manual:Hooks/OutputPageBodyAttributes
- Příručka:$wgSkinMetaTags
Píšu rozšíření, které se musí stylizovat jinak v závislosti na vzhledu
Rozšíření mohou využívat styly vzhledu k odesílání stylů specifických pro vzhled pomocí klíče skinStyles. Podívejte se na stránku Příručka:$wgResourceModuleSkinStyles.
Kompatibilita s VisualEditorem
Chcete-li zajistit kompatibilitu s VisualEditorem, přečtěte si tyto pokyny.
Vytváření vzhledů pro 1.35
V 1.35 nebyla podpora pro vytváření vzhledů tak přímočará jako v 1.36. Pokud si přejete sestavit vzhled pro 1.35 pomocí dat šablony poskytnutých v 1.36, budete muset rozšířit třídu PHP SkinMustache. Je poskytnuta polyfill pro ukázkový vzhled.
Vaše zpětná vazba je důležitá
Pokud něco není snadné, rádi bychom to usnadnili, takže vaše zpětná vazba je důležitá. Pokud narazíte na problémy, odešlete hlášení o chybě v projektu základní architektury vzhledu MediaWiki v Phabricatoru a my se pokusíme najít elegantní řešení.
Neváhejte, prosím, a položte otázku na diskusní stránce. Neexistuje nic jako hloupá otázka.