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

From MediaWiki.org
Jump to navigation Jump to search
This page is a translated version of the page Manual:Variable and the translation is 100% complete.

Other languages:
English • ‎español • ‎français • ‎polski • ‎русский • ‎تۆرکجه • ‎日本語
Эта страница о создании переменных. Как использовать переменные по умолчанию, см. Справка:Волшебные слова . О глобальных переменных PHP, используемых в MediaWiki, см. Manual:wg variable.
OOjs UI icon puzzle-ltr.svg Расширения: Разработка Теги расширений Руководство:Функции парсера Прерывания Служебные страницы Стили оформления (skins) Руководство:Волшебные слова API Content models

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

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

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

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

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

Обратите внимание, что единственным отличием этого процесса (регистрации переменной) от общего процесса определения магических слов является последний шаг: определение функции ловушки(хука) для ParserGetVariableValueSwitch. Функции парсера имеют другой метод для привязки идентификатора к коду PHP. Смотрите Manual: Функции парсера для получения дополнительной информации.

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

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

  1. Определите переменную, чтобы она была включена в Special:Version. Это требует добавления члена в $wgExtensionCredits . Для получения дополнительной информации смотрите: «Регистрация функций в MediaWiki».
  2. Объявите ID магического слова как переменную. Для этого мы напишем и назначим ловушку(хук) для MagicWordwgVariableIDs, предмета этой статьи.
    Данный хук(ловушка) используется только только с переменными. Не используйте его для определения функций парсера!

Пример

Примечание: Если вы хотите использовать этот пример в качестве шаблона кодирования, замените '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 = array();

/** English (English) */
$magicWords['en'] = array(
	// 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' => array( 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'][] = array(
	'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';

	// must do this or you will silence every MagicWordwgVariableIds hook
	// registered after this!
	return true;
}

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