Руководство:Волшебные слова

This page is a translated version of the page Manual:Magic words and the translation is 82% complete.
Outdated translations are marked like this.
Расширения MediaWiki

Волшебные слова — это техника для соединения разнообразных текстовых цепочек к одному ID которое ассоциируется с этой функцией. И переменные, и функции парсера используют данную технику. Весь текст, прикрепленный к данному ID, будет заменен на возвращаемое значение функции. Сопоставление текстовых строк и идентификатора сохраняется в переменной $magicWords в файле, который можно загрузить с помощью $wgExtensionMessagesFiles[] .

Стандартные волшебные слова реализованы в CoreParserFunctions.php .

Как работают волшебные слова

Всякий раз, когда MediaWiki находит текст между двойными скобками ({{XXX ...}}), необходимо решить, является ли XXX переменной, функцией парсера или шаблоном. Чтобы сделать это, задается несколько вопросов:

  1. Есть ли связанное ID волшебного слова? В качестве первого шага разбора разметки в виде {{XXX...}}, MediaWiki пытается перевести XXX в ID волшебного слова. Таблица переводов определяется в $magicWords.
    • Если нет связанного с XXX ID волшебного слова, предполагается, что XXX — это шаблон.

  2. Переменная ли это? Если найдено ID волшебного слова, MediaWiki далее проверяет есть ли у него какие-либо параметры.
    • Если параметры не найдены, MediaWiki проверяет, объявлен ли идентификатор волшебного слова как идентификатор переменной. Чтобы проверить это, он получает список обслуживающих волшебных слов, вызывая MagicWord::getVariableIDs(). Этот метод получает свой список идентификаторов переменных из жестко закодированного списка идентификаторов переменных (см.Help:Variables ) и из списка идентификаторов пользовательских переменных, предоставляемых всеми функциями, прикрепленными к ловушке MagicWordwgVariableIDs .
      • Если ID волшебного слова было классифицировано как переменная, хуки MediaWiki будут вызывать функции, связанные с именем события ParserGetVariableValueSwitch , пока не будет найдена та, которая распознает волшебное слово и сможет вернуть его значение.

  3. Функция парсера ли это? Если нет каких-либо параметров или если ID волшебного слова не найдено в списке переменных ID волшебных слов, тогда MediaWiki подразумевает что это волшебное слово функция парсера или шаблон. Если ID волшебного слова найдено в списке функций парсера, который объявляется с помощью вызова $wgParser->setFunctionHook($magicWordId, $renderingFunctionName), то рассматривается как функция парсера и отображается с помощью функции под именем $renderingFunctionName. Иначе предполагается что это шаблон.

By convention:

  • The magic words called variables are capitalised, case-sensitive and do not have space characters.
  • Parserfunctions are prefixed with a hash sign ({{#), are case insensitive and do not include space characters.

This is however a convention and one not consistently applied (for historic reasons).

  • Variables do not have space characters, but some translations of variables in other languages DO have spaces
  • Variables generally are capitalised and case-sensitive, but some parser functions also use this convention.
  • Some parser functions start with a hash sign, but some do not.

Where possible you should follow the conventions when defining or translating magic words. Magic words are higher in priority than templates, so any magic word defined, will block the usage of that defined name as a template.

Following the conventions avoids adding more and more potential collisions.

Определение волшебных слов

Чтобы волшебные слова творили своё волшебство, мы должны определить две вещи:

  • соответствие вики-текста с идентификатором волшебного слова
  • соответствие идентификатора волшебного слова и какой-то php-функции, которая интерпретирует волшебное слово.

Проведение соответствия вики-текста с идентификатором волшебного слова

Переменная $magicWords используется для ассоциации всех идентификаторов магических слов с языково-зависимым массивом, который описывает все текстовые строки, которые связаны с идентификатором волшебного слова. Важно: Это только настраивает отображение интернационализации (i18n), но вам всё равно нужно написать другой код, чтобы MediaWiki использовал волшебное слово для чего угодно.

Первый элемент этого массива это целочисленный флаг, указывающий, является ли волшебное чувствительным к регистру. Остальные элементы это список текста, который должен быть связан с ID волшебного слова. Если флаг чувствительности к регистру равен 0, то любые варианты регистра в имени будут совпадать. Если флаг чувствительности к регистру равен 1, то только точные совпадения по регистру будут ассоциированы с ID волшебного слова. Таким образом формат выглядит как $magicWords['en'] = [ 'InternalName' => [ 0, 'NameUserTypes', 'AdditionalAliasUserCanType' ] ];

Такая ассоциация создается переменной $magicWords , в файле, зарегистрированном с помощью $wgExtensionMessagesFiles[] .

В приведенном ниже примере установка MediaWiki на испанском языке будет связывать идентификатор волшебного слова 'MAG_CUSTOM' с «personalizado», «custom», «PERSONALIZADO», «CUSTOM» и всеми другими вариантами регистра. В англоязычной MediaWiki только «custom» в различных комбинациях регистров будет отображаться в 'MAG_CUSTOM':

Файл Example.i18n.magic.php:

<?php

$magicWords = [];

$magicWords['en'] = [
	'MAG_CUSTOM' => [ 0, 'custom' ],
];

$magicWords['es'] = [
	'MAG_CUSTOM' => [ 0, 'personalizado' ],
];

В части файла extension.json:

"ExtensionMessagesFiles": {
	"ExampleMagic": "Example.i18n.magic.php"
}

Обратите внимание, что "ExampleMagic" отличается от ключа, который вы бы использовали для простого файла интернационализации (обычно это просто название расширения, то есть "Example"). "Magic" было добавлено ​​намеренно, чтобы одно не перезаписывало другое.

Во встроенном PHP

Вы можете связать волшебные слова прямо в PHP, а не через файл i18n. Это полезно при определении связок(хуков) в LocalSettings.php.

MediaWiki\MediaWikiServices::getInstance()->getContentLanguage()->mMagicExtensions['wikicodeToHtml'] = ['MAG_CUSTOM', 'custom'];

Ассоциация ID волшебного слова с PHP-функцией

Механизм ассоциации ID волшебного слова с функцией рендеринга зависит от того, будет ли волшебное слово использоваться как функция парсера или как переменная. Для получения более подробной информации смотрите:

Регистрация волшебных слов

В MediaWiki отсутствует явное требование регистрации ID волшебных слов. Достаточно зарегистрировать функцию парсера или переменные, которые их используют.

Локализация

Для справки смотрите Справка:Волшебные слова#Локализация.

Вы можете прочитать больше об определении и использовании волшебных слов для локализации на Manual:Messages API, Manual:Language#Namespaces; Avoid {{SITENAME}} in messages.

Переключатели поведения (волшебные слова с двойным подчеркиванием)

Переключатели поведения это особый тип волшебных слов. Их можно узнать по двойному подчеркиванию (вместо двойных скобок). Например, __NOTOC__. Example: __NOTOC__

Эти волшебные слова обычно не выводят какой-либо контент, а вместо этого изменяют поведение страницы и/или устанавливают свойство страницы. Эти волшебные слова перечислены в MagicWordFactory::mDoubleUnderscoreIDs, а также в Справка:волшебные слова#Переключатели поведения. Эффекты наиболее стандартных сценариев переключений описаны в Parser::handleDoubleUnderscore(). Если конкретный эффект не определен, волшебное слово просто установит свойство страницы в таблице page_props.

Поведение настраиваемого переключателя

Для применения поведения настраиваемого переключателя.

// __CUSTOM__ behavior switch in LocalSettings.php
$wgHooks['GetDoubleUnderscoreIDs'][] = function ( &$ids ) 
{ 
	$ids[] = 'custom';
	MediaWiki\MediaWikiServices::getInstance()->getContentLanguage()->mMagicExtensions['custom'] = ['custom', 'custom'];
};
$wgHooks['ParserAfterParse'][] = function ( Parser $parser, &$text, StripState $stripState )
{
	if(isset($parser->mDoubleUnderscores['custom']))
	{
		// Do behavior switching here ...
	}
};

Посмотрите также