Manual:Hooks/ParserGetVariableValueSwitch

ParserGetVariableValueSwitch
Available from version 1.6.1 Assigns a value to a user defined variable
Define function:	public static function onParserGetVariableValueSwitch( $parser, &$variableCache, $magicWordId, &$ret, $frame ) { ... }
Attach hook:	In extension.json: { "Hooks": { "ParserGetVariableValueSwitch": "MediaWiki\\Extension\\MyExtension\\Hooks::onParserGetVariableValueSwitch" } }
Called from:	File(s): Parser.php
Interface:	ParserGetVariableValueSwitchHook.php

For more information about attaching hooks, see Manual:Hooks .
For examples of extensions using this hook, see Category:ParserGetVariableValueSwitch extensions.

Details

ParserGetVariableValueSwitch is the hook responsible for assigning a value to custom variables. Whenever the parser sees a string like {{XXX}}, it assumes that it represents one of three possible kinds of wiki markup: a template, a variable, or a parser function. If XXX is registered as a variable name, the parser runs the hooks assigned to ParserGetVariableValueSwitch until it finds one that can return a value for the variable.

To register XXX as a variable name, you must associate the string 'XXX' with a magic word id via $magicWords. A magic word id is just an internal identifier that groups together all wiki text names for a variable. To make this particular magic word id act like a variable (rather than a parser function or template), you also must add its associated magic word id to the list of custom variable ids via a MagicWordwgVariableIDs hook.

Usage

In MediaWiki 1.35, $magicWordId is no longer passed by reference.

ParserGetVariableValueSwitch is passed the magic word id in $magicWordId. If the hook knows how to assign a value to that particular id, it should assign the value to $ret and return true. Never return false since this will lead to aborting all further calls to this hook.

Because the hook will be passed both ids it knows and those it doesn't, it should check the id before assigning any value to it. This is normally done in a switch statement, as illustrated in the example below:

#-----------------------------------------------------
# Register the hook function so MediaWiki can call it
#-----------------------------------------------------
$wgHooks['ParserGetVariableValueSwitch'][] = 'wfMyAssignAValueToAVariable';


#----------------------------------------------------
# Define the hook function
#----------------------------------------------------
function wfMyAssignAValueToAVariable($parser, &$variableCache, &$magicWordId, &$ret, $frame) {
  switch($magicWordId) {
  case 'MAG_MYVAR1':  
    $ret = 'My first variable';
    break;

  case 'MAG_MYVAR2':
    $ret = 'My second variable';
    break;

  case 'MAG_OUR_ORGANIZATION':
    $ret = "Cool non-profit";
    break;

  default:
    break;
  }
  // Permit future callbacks to run for this hook.
  // never return false since this will prevent further callbacks AND indicate we found no value!
  $variableCache[$magicWordId] = $ret; // Optional, to cache the value and avoid repeated calls.
  return true; 
}

Details

Usage

See also