Příručka:Kouzelná slovíčka
Magic words are strings of text that MediaWiki links to specific functions or return values, such as current date and time, page titles, site information, and more. They can be thought of as special commands or variables that allow dynamic content generation and interaction with the MediaWiki software during page rendering.
From a technical standpoint, magic words map a range of wiki text strings to a unique internal identifier (ID), which is then associated with a particular function. This ID directs MediaWiki to execute a corresponding operation or return a specific value. Both variables (which output dynamic values) and parser functions (which perform operations or conditional logic) make use of this mapping technique.
Veškerý text namapovaný na toto ID bude nahrazen návratovou hodnotou funkce.
Mapování mezi textovými řetězci a ID je uloženo v proměnné $magicWords v souboru, který lze načíst pomocí $wgExtensionMessagesFiles[].
Výchozí magická slova jsou implementována v CoreParserFunctions.php.
Jak fungují kouzelná slůvka
Kdykoli MediaWiki najde text mezi dvojitými složenými závorkami ({{XXX ...}}), musí rozhodnout, zda XXX je proměnná, funkce analyzátoru nebo šablona. Za tímto účelem položí řadu otázek:
- Má přidružené ID kouzelného slova? Jako první krok při řešení označení tvaru
{{XXX...}}se MediaWiki pokouší přeložit XXX na ID kouzelného slova. Překladovou tabulku definuje $magicWords.- Pokud není k XXX přidruženo žádné ID magického slova, předpokládá se, že XXX je šablona.
- Je to proměnná? Pokud je nalezeno ID kouzelného slova, MediaWiki dále zkontroluje, zda má nějaké parametry.
- Pokud nejsou nalezeny žádné parametry, MediaWiki zkontroluje, zda bylo ID kouzelného slova deklarováno jako ID proměnné. Pro kontrolu načte seznam magických slov sloužících voláním
MagicWord::getVariableIDs(). Tato metoda získává svůj seznam ID proměnných z pevně zakódovaného seznamu ID proměnných (viz Help:Variables) a ze seznamu ID uživatelských proměnných poskytovaných všemi funkcemi připojenými k háčku MagicWordwgVariableIDs.- Pokud bylo kouzelné slovo ID klasifikováno jako proměnná, MediaWiki zavolá funkci ParserGetVariableValueSwitch, aby získala hodnotu spojenou s názvem proměnné.
- Pokud nejsou nalezeny žádné parametry, MediaWiki zkontroluje, zda bylo ID kouzelného slova deklarováno jako ID proměnné. Pro kontrolu načte seznam magických slov sloužících voláním
- Je to funkce analyzátoru? Pokud existují nějaké parametry nebo pokud ID kouzelného slova chybí v seznamu ID proměnných kouzelných slov, pak MediaWiki předpokládá, že kouzelné slovo je funkce analyzátoru nebo šablona. Pokud je ID magického slova nalezeno v seznamu deklarovaných funkcí analyzátoru, je považováno za funkci analyzátoru a je vykresleno pomocí funkce s názvem
$renderingFunctionName. V opačném případě se předpokládá, že se jedná o šablonu.
Definování kouzelných slov
Podle konvence:
- Kouzelná slova nazývaná proměnné jsou velkými písmeny, rozlišují se malá a velká písmena a neobsahují mezery.
- Funkce parseru jsou opatřeny předponou se znakem hash (#), nerozlišují malá a velká písmena a neobsahují mezery.
Toto je však konvence, která se důsledně nepoužívá (z historických důvodů).
- Proměnné nemají mezery, ale některé překlady proměnných v jiných jazycích mezery mají
- Proměnné jsou obecně velká a rozlišují se velká a malá písmena, ale některé funkce analyzátoru také používají tuto konvenci.
- Některé funkce analyzátoru začínají znakem hash, ale některé ne.
Pokud je to možné, měli byste při definování nebo překladu kouzelných slovíček dodržovat konvence. Magická slova mají vyšší prioritu než šablony, takže jakékoli definované magické slovo zablokuje použití tohoto definovaného názvu jako šablony.
Dodržováním konvencí se vyhnete přidávání dalších a dalších potenciálních kolizí.Aby kouzelná slova udělala své kouzlo, musíme definovat dvě věci:
- mapování mezi textem wiki a ID kouzelného slova
- mapování mezi ID magického slova a nějakou funkcí PHP, která interpretuje magické slovo.
Mapování textu wiki na ID kouzelných slov
Proměnná $magicWords se používá k přiřazení každého ID kouzelného slova k poli závislému na jazyce, které popisuje všechny textové řetězce mapované na ID kouzelného slova.
Důležité: Tím se nastaví pouze mapování back-end i18n, stále musíte napsat jiný kód, aby MediaWiki použila magické slovo pro cokoli.
Před přidáním hodnot specifických pro jazyk se také ujistěte, že jste inicializovali $magicWords jako prázdné pole, jinak se při pokusu o načtení kouzelného slova zobrazí chyba a bude nutné znovu vytvořit mezipaměť lokalizace, než bude fungovat.
Prvním prvkem tohoto pole je celočíselný příznak udávající, zda magické slovo rozlišuje velká a malá písmena. Zbývající prvky jsou seznam textu, který by měl být spojen s ID magického slova. Pokud je příznak rozlišující malá a velká písmena 0, bude se shodovat jakákoli varianta názvů v poli. Je-li příznak rozlišující malá a velká písmena 1, budou s ID magického slova spojeny pouze přesné shody velkých a malých písmen.
Formát je tedy $magicWords['en'] = [ 'InternalName' => [ 0, 'NameUserTypes', 'AdditionalAliasUserCanType' ] ];
Toto přidružení vytváří $magicWords v souboru registrovaném pomocí $wgExtensionMessagesFiles[].
V níže uvedeném příkladu španělská instalace MediaWiki spojí magické slovo ID 'MAG_CUSTOM' s "personalizado", "custom", "PERSONALIZADO", "CUSTOM" a všemi ostatními variantami případu. V anglické MediaWiki bude na 'MAG_CUSTOM' mapováno pouze "custom" v různých kombinacích případů:
Soubor Example.i18n.magic.php:
<?php
$magicWords = [];
$magicWords['en'] = [
'MAG_CUSTOM' => [ 0, 'custom' ],
];
$magicWords['es'] = [
'MAG_CUSTOM' => [ 0, 'personalizado' ],
];
V části souboru extension.json:
"ExtensionMessagesFiles": {
"ExampleMagic": "Example.i18n.magic.php"
}
Všimněte si, že "ExampleMagic" se liší od klíče, který byste použili pro prostý internacionalizační soubor (obvykle pouze název přípony, tj. "Example"). "Magic" bylo přidáno záměrně, aby jedno nepřepisovalo druhé.
Inline PHP
Kouzelná slova můžete přidružit inline v PHP spíše než prostřednictvím souboru i18n.
To je užitečné při definování háčků v LocalSettings.php, ale nemělo by se to dělat v rozšířeních.
MediaWiki\MediaWikiServices::getInstance()->getContentLanguage()->mMagicExtensions['wikicodeToHtml'] = ['MAG_CUSTOM', 'custom'];
Přiřazení ID kouzelného slova k funkci PHP
Mechanismus pro přiřazování ID kouzelných slov k funkcím vykreslování závisí na tom, zda bude kouzelné slovo použito jako funkce analyzátoru nebo proměnná. Další informace naleznete na adrese:
Lokalizace
- Nápovědu viz Nápověda:Kouzelná slovíčka#Lokalizace.
Více o definici a použití kouzelných slov pro lokalizaci si můžete přečíst na stránkách Příručka:Zprávy API, Příručka:Jazyk#Jmenné prostory; Vyhněte se {{SITENAME}} ve zprávách.
Přepínače chování (dvojité podtržení kouzelných slov)
Přepínače chování jsou zvláštním typem kouzelných slov. Lze je rozpoznat podle použití dvojitého podtržítka (spíše než dvojitých složených závorek).
Příklad:
__NOTOC__
Tato kouzelná slova obvykle nevydávají žádný obsah, ale místo toho mění chování stránky a/nebo nastavují vlastnost stránky.
Tato magická slova jsou uvedena v MagicWordFactory::mDoubleUnderscoreIDs a také na stránce Nápověda:Kouzelná slova#Přepínače chování.
Účinek většiny standardních přepínačů chování je definován v Parser::handleDoubleUnderscore().
Pokud není definován žádný konkrétní efekt, kouzelné slovo jednoduše nastaví vlastnost stránky v tabulce page_props.
To lze také zkontrolovat později testováním, zda je $parser->getOutput()->getPageProperty( 'MAGIC_WORD' ) null nebo prázdný řetězec
Přepínač vlastního chování
Zde je příklad rozšíření implementující vlastní přepínač chování __CUSTOM__
MyExt/extension.json - to je minimální, skutečné rozšíření by vyplnilo více polí.
{
"name": "MyExt",
"type": "parserhook",
"AutoloadNamespaces": {
"MediaWiki\\Extension\\MyExt\\": "includes/"
},
"Hooks": {
"GetDoubleUnderscoreIDs": "main",
"ParserAfterParse": "main"
},
"HookHandlers": {
"main": {
"class": "MediaWiki\\Extension\\MyExt\\Hooks",
"services": [ "MainConfig" ]
}
},
"ExtensionMessagesFiles": {
"MyExtMagic": "custom.i18n.magic.php"
},
"manifest_version": 2
}
MyExt/MyExt.i18n.magic.php
<?php
$magicWords = [];
$magicWords['en'] = [
'MAG_CUSTOM' => [ 0, '__CUSTOM__' ],
];
MyExt/includes/Hooks.php
<?php
namespace MediaWiki\Extension\MyExt;
class Hooks implements GetDoubleUnderscoreIDsHook, ParserAfterParseHook {
public function onGetDoubleUnderscoreIDs( &$ids ) {
$ids[] = 'MAG_CUSTOM';
}
public function onParserAfterParse( $parser, &$text, $stripState ) {
if ( $parser->getOutput()->getPageProperty( 'MAG_CUSTOM' ) !== null ) {
// Do behavior switching here ...
// e.g. If you wanted to add some JS, you would do $parser->getOutput()->addModules( [ 'moduleName' ] );
}
}
}
Související odkazy
- Nápověda:Kouzelná slova - seznam proměnných jako {{PAGENAME}} a {{SERVER}}
- Manual:MagicWord.php