Manual:Variable

From MediaWiki.org
Jump to: navigation, search

Other languages:
تۆرکجه • ‎Deutsch • ‎English • ‎español • ‎français • ‎italiano • ‎日本語 • ‎polski • ‎português • ‎português do Brasil • ‎русский
This page is about creating variables. For help using default variables, see Help:Magic wordsHelp:Magic words. For PHP global variables used internally in MediaWiki, see Manual:wg variable.
Gnome-preferences-other.svg Extensions:Manual:Extensions DevelopmentManual:Developing extensions Tag extensionsManual:Tag extensions Parser functionsManual:Parser functions HooksManual:Hooks Special pagesManual:Special pages SkinsManual:Skins Magic wordsManual:Magic words APIAPI:Extensions

Variables are bits of wikitext that look like templates but have no parameters and have been assigned hard-coded values. Standard wiki markup such as {{PAGENAME}}Help:Magic words or {{SITENAME}}Help:Magic words are examples of variables. You can also extend wiki markup by defining your own custom variables.

The term is something of a misnomer because there is nothing variable about a variable. End users cannot change the value of a variable because it is predetermined by a bundle of PHP code that calculates its value. The term "variables" comes from the source of their value: a PHP variable or something that could be assigned to a variable, e.g. a string, a number, an expression, or a function return value.

Defining custom variables[edit]

Variables are a special case of magic words so our first step will be to define the variable as a magic word:

  1. Choose a magic word ID for your variable. 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).
  2. Define the names that will appear in wiki text. To accomplish this, you will need to define and register https://www.mediawiki.org/wiki/Manual:Magic_wordsWords in a file through https://www.mediawiki.org/wiki/Manual:Magic_words. Your names can be case sensitive and language dependent. See Manual:Magic wordsManual:Magic words for more information.
  3. Provide PHP code to assign a value to the variable. To accomplish this, you will need to define and register a hook function with ParserGetVariableValueSwitch.

Note that the only difference between this process and the general process for defining magic words is the last step: defining a hook function for ParserGetVariableValueSwitch. Parser functions have a different method for associating an ID with PHP code. See Manual:Parser functions for more information.

Registering custom variables[edit]

This is a two step process:

  1. Define the variable so that it gets included in Special:Version. This requires adding a member to $wgExtensionCreditsManual:$wgExtensionCredits. For more information, please see Registering features with MediaWiki.
  2. Declare the magic word ID as a variable. To accomplish this we write and assign a hook to MagicWordwgVariableIDs, the subject of this article.
    this hook is only for use with variables. Do not use it to define parser functions!

Example[edit]

Note: if you wish to use this example as a coding template, please replace 'My' with something unique to your project so that there is less risk of name clashes with MediaWiki or any of its extensions. For example, if your extension was named BigExtravagantStylingTool and you were reasonably sure that no-one else had an extension with constants, variables, functions, or classes beginning 'BEST_', 'wgBEST', 'wfBEST', or even 'BEST' you might want to replace 'My' with 'BEST'.

File 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' ),
);

File 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;
}

For more information[edit]