Руководство:Переменные

Эта страница о создании переменных. Как использовать переменные по умолчанию, см. Справка:Волшебные слова . О глобальных переменных PHP, используемых в MediaWiki, см. Manual:wg variable .

Переменные - это кусочки вики-текста, которые выглядят как шаблоны и имеют привязанные на уровне кода значения. Стандартная вики-разметка, такая как {{PAGENAME}} или {{SITENAME}} - примеры переменных. Вы также можете расширять вики-разметку определяя свои собственные переменные.

Данный термин является чем-то неправильным, потому что в переменной нет ничего переменного. Конечные пользователи не могут изменить значение переменной, поскольку оно предопределено пакетом кода PHP, который вычисляет ее значение. Термин «переменные» происходит от источника их значения в программировании: переменная в PHP или что-то, что может быть присвоено переменной, например, строка, число, выражение или возвращаемое значение функции.

Определение пользовательских переменных

Переменные - это особой случай магических слов, поэтому нашим первым шагом будет определение переменной как магического слова:

1. Выберите магический идентификатор(ID) слова для вводимой вами переменной. Это только внутренний идентификатор, который используется для связи различных частей определения переменной: имен, которые появляются в вики-тексте, и кода PHP, который будет назначать значение переменной. Лучше всего выбрать идентификатор, который будет однозначно связан с вашим расширением(шаблоном) и вряд ли будет перепутан с другими магическими идентификаторами слов, используемыми другими расширениями(шаблонами). Обычная стратегия - использовать что-то вроде MAG _ canonicalname, где canonicalname - это имя, под которым вы зарегистрируете свое расширение (см.Регистрация пользовательских переменных ниже).

This is only an internal identifier that is used to tie together the various parts of the variable definition: the names that appear in wiki text, and the PHP code that assigns a value to the variable. It is best to choose an ID that will be uniquely associated with your extension and is unlikely to be confused with other magic word IDs used by other extensions. A common strategy is to use something like MAG_canonicalname where canonicalname is the name under which you will register your extension (see Registering custom variables below).

1. Определите имена, которые будут отображаться в вики-тексте. Для этого вам нужно будет определить массив $magicWords в файле. Смотрите Руководство:Волшебные слова для получения дополнительной информации. Ваши имена могут быть чувствительны к регистру и языково-зависимыми.

1. Укажите код PHP для присвоения значения переменной. Для этого вам нужно определить и зарегистрировать функцию ловушки(хука) с помощью ParserGetVariableValueSwitch.

To accomplish this, you will need to define and register a hook function with ParserGetVariableValueSwitch .

Обратите внимание, что единственным отличием этого процесса (регистрации переменной) от общего процесса определения магических слов является последний шаг: определение функции ловушки(хука) для ParserGetVariableValueSwitch. Функции парсера имеют другой метод для привязки идентификатора к коду PHP. Смотрите Manual: Функции парсера для получения дополнительной информации. Parser functions have a different method for associating an ID with PHP code. See Руководство:Функции парсера for more information.

Регистрация пользовательских переменных

Данный процесс состоит из двух шагов:

1. Определите переменную, чтобы она была включена в Special:Version. Это требует добавления члена в $wgExtensionCredits . Для получения дополнительной информации смотрите: «Регистрация функций в MediaWiki».

1. Объявите ID магического слова как переменную. Для этого мы напишем и назначим ловушку(хук) для MagicWordwgVariableIDs, предмета этой статьи.

To accomplish this we write and assign a hook to MagicWordwgVariableIDs , the subject of this article.

Данный хук(ловушка) используется только только с переменными. Не используйте его для определения функций парсера!

Пример

Примечание: Если вы хотите использовать этот пример в качестве шаблона кодирования, замените 'My' чем-то уникальным для вашего проекта, чтобы снизить риск столкновения имен переменных с переменными из MediaWiki или любым из других расширений. Например, если ваше расширение было названо BigExtravagantStylingTool и вы были достаточно уверены, что никто не имеет расширения с константами, переменными, функциями или классами, начинающимися с 'BEST_', 'wgBEST', 'wfBEST' или даже «BEST», вы можете заменить «My» на «BEST».

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

<?php
/**
 * Step 1: choose a magic word ID
 * Step 2: define some words to use in wiki markup
 */

$magicWords = [];

/** English (English) */
$magicWords['en'] = [
	// tell MediaWiki that all {{NiftyVar}}, {{NIFTYVAR}}, {{CoolVar}},
	// {{COOLVAR}} and all case variants found in wiki text should be mapped to
	// magic ID 'mycustomvar1' (0 means case-insensitive)
	'mycustomvar1' => [ 0, 'NiftyVar', 'CoolVar' ],
];

Файл Example.php

<?php
/**
 * Step 3: Register the file with the magic words.
 */
$wgExtensionMessagesFiles['ExampleMagic'] = __DIR__ . '/Example.i18n.magic.php';

/**
 * Step 4: assign a value to our variable
 */
$wgHooks['ParserGetVariableValueSwitch'][] = 'wfMyAssignAValue';
function wfMyAssignAValue( &$parser, &$cache, &$magicWordId, &$ret ) {
	if ( $magicWordId === 'mycustomvar1' ) {
		// We found a value
		$ret = 'This is a really silly value';
	}
	// We must return true for two separate reasons:
	// 1. To permit further callbacks to run for this hook.
	//    They might override our value but that's life.
	//    Returning false would prevent these future callbacks from running.
	// 2. At the same time, "true" indicates we found a value.
	//    Returning false would set variable value to null.
	//
	// In other words, true means "we found a value AND other
	// callbacks will run," and false means "we didn't find a value
	// AND abort future callbacks." It's a shame these two meanings
	// are mixed in the same return value.  So as a rule, return
	// true whether we found a value or not.
	return true;
}

/**
 * Step 5: register the custom variable(s) so that it shows up in
 * Special:Version under the listing of custom variables.
 */
$wgExtensionCredits['variable'][] = [
	'name' => 'ExampleMagic',
	'author' => 'John Doe',
	'version' => '1.0',
	'description' => 'Provides a variable as an example and performs no discernible function',
	'url' => 'https://www.mediawiki.org/wiki/Extension:ExampleMagic',
];

/**
 * Step 6: register wiki markup words associated with
 *         MAG_NIFTYVAR as a variable and not some
 *         other type of magic word
 */
$wgHooks['MagicWordwgVariableIDs'][] = 'wfMyDeclareVarIds';
function wfMyDeclareVarIds( &$customVariableIds ) {
	// $customVariableIds is where MediaWiki wants to store its list of custom
	// variable IDs. We oblige by adding ours:
	$customVariableIds[] = 'mycustomvar1';
}

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

• Справка:Волшебные слова - список магических слов встроенных по умолчанию в основной (core) пакет MediaWiki.
• Руководство:Волшебные слова - рассмотрение различных видов магических слов и то, как MediaWiki различает переменные, функции парсера и шаблоны.
• Спец разметка