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

This page is a translated version of the page Manual:Magic words and the translation is 89% complete.

Outdated translations are marked like this.

Расширения:

This manual is not intended for end users of MediaWiki. Looking for a list of magic words? See Справка:Волшебные слова . If you are looking for documentation to help you use MediaWiki, read the MediaWiki Handbook.

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.

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

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

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

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

Есть ли связанное ID волшебного слова? В качестве первого шага разбора разметки в виде {{XXX...}}, MediaWiki пытается перевести XXX в ID волшебного слова. Таблица переводов определяется в $magicWords.
- Если нет связанного с XXX ID волшебного слова, предполагается, что XXX — это шаблон.
Переменная ли это? Если найдено ID волшебного слова, MediaWiki далее проверяет есть ли у него какие-либо параметры.
- Если параметры не найдены, MediaWiki проверяет, объявлен ли идентификатор волшебного слова как идентификатор переменной. Чтобы проверить это, он извлекает список волшебных слов, обслуживаемых вызовом MagicWord::getVariableIDs(). Этот метод получает свой список идентификаторов переменных из жестко закодированного списка идентификаторов переменных (смотрите Help:Variables ) и из списка идентификаторов пользовательских переменных, предоставляемых всеми функциями, прикрепленными к ловушке MagicWordwgVariableIDs .
  - Если ID волшебного слова классифицирован как переменная, MediaWiki вызывает функцию ParserGetVariableValueSwitch , чтобы получить значение, связанное с именем переменной.
Функция парсера ли это? Если нет каких-либо параметров или если ID волшебного слова не найдено в списке переменных ID волшебных слов, тогда MediaWiki подразумевает что это волшебное слово функция парсера или шаблон. Если ID волшебного слова найден в списке функций парсера, объявленных через вызов $1, он рассматривается как функция парсера и отображается с использованием функции с именем $renderingFunctionName. В противном случае предполагается, что это шаблон.

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

When defining or translating magic words, adhere to established conventions.

По условным обозначениям:

Волшебные слова, называемые переменными, пишутся с заглавной буквы, чувствительны к регистру и не содержат пробелов.
Функции синтаксического анализа имеют префикс решётки (#), нечувствительны к регистру и не содержат пробелов.

Однако это условность, которая не применяется последовательно (по историческим причинам).

В переменных нет пробелов, но в некоторых переводах переменных на другие языки пробелы ДЕЙСТВИТЕЛЬНО присутствуют
Переменные обычно пишутся с заглавной буквы и чувствительны к регистру, но некоторые функции синтаксического анализатора также используют это соглашение.
Некоторые функции синтаксического анализатора начинаются со знака решетки, а некоторые нет.

По возможности вам следует следовать общепринятым правилам при определении или переводе волшебных слов. Волшебные слова имеют более высокий приоритет, чем шаблоны, поэтому любое определенное волшебное слово будет блокировать использование этого определенного имени в качестве шаблона.

Следование соглашениям позволяет избежать появления все новых и новых потенциальных коллизий.

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

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

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

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

Первый элемент этого массива это целочисленный флаг, указывающий, является ли волшебное чувствительным к регистру. Остальные элементы это список текста, который должен быть связан с 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 волшебного слова с функцией рендеринга зависит от того, будет ли волшебное слово использоваться как функция парсера или как переменная. Для получения более подробной информации смотрите:

Локализация

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

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

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

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

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

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

Вот пример расширения, реализующего настраиваемый переключатель поведения __CUSTOM__.

MyExt/extension.json - Это минимум, настоящее расширение заполнило бы больше полей.

{
	"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' ] );
		}
	}
}

Смотрите также

Справка:Волшебные слова - Список таких переменных как {{PAGENAME}} и {{SERVER}}
Manual:MagicWord.php