Příručka:Kouzelná slovíčka

This page is a translated version of the page Manual:Magic words and the translation is 100% complete.
Rozšíření MediaWiki

Magická slova (magic words) je technika pro mapování různých textových řetězců wiki na jediné ID, které je spojeno s funkcí. Tuto techniku používají jak proměnné, tak funkce analyzátoru. 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:

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

  2. 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é.

  3. 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 funkcí analyzátoru deklarovaných pomocí volání $wgParser->setFunctionHook($magicWordId, $renderingFunctionName), 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.
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í.


Definování kouzelných slov

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__

custom/extension.json - To je minimální, skutečné rozšíření by vyplnilo více polí.

{
	"name": "Custom",
	"type": "parserhook",
	"AutoloadClasses": {
		"MyHooks": "MyHooks.php"
	},
	"Hooks": {
		"GetDoubleUnderscoreIDs": [
			"MyHooks::onGetDoubleUnderscoreIDs"
		],
		"ParserAfterParse": [
			"MyHooks::onParserAfterParse"
		]
	},
	"ExtensionMessagesFiles": {
		"CustomMagic": "custom.i18n.php"
	},
	"manifest_version": 1
}

custom/custom.i18n.php

<?php
$magicWords = [];
$magicWords['en'] = [
	'MAG_CUSTOM' => [ 0, '__CUSTOM__' ],
];

custom/MyHooks.php

<?php
class MyHooks {
	public static function onGetDoubleUnderscoreIDs( &$ids ) {
		$ids[] = 'MAG_CUSTOM';
	}

	public static function onParserAfterParse( Parser $parser, &$text, StripState $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