Manual:Hooks/ParserGetVariableValueSwitch

From MediaWiki.org

function fnMyHook( &$parser, &$cache, &$magicWordId, &$ret ) { ... }

$wgHooks['ParserGetVariableValueSwitch'][] = 'fnMyHook';

[edit] 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 LanguageGetMagic. 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.

[edit] Usage

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. Otherwise it does nothing and returns false. Returning true tells MediaWiki to go onto the remaining hooks assigned to ParserGetVariableValueSwitch in hopes of finding a value for the magic word id.

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, &$cache, &$magicWordId, &$ret) {
  switch($magicWordId) {
  case MAG_MYVAR1:  
    $ret = "This is the value assigned to magic word id " . MAG_MYVAR1;
    break;
 
  case MAG_MYVAR2:
    $ret = "This is the value assigned to magic word id " . MAG_MYVAR2;
    break;
 
  case MAG_OUR_ORGANIZATION:
    $ret = "Cool non-profit";
    break;
 
  default:
    break;
  }
  // Permit future callbacks to run for this hook.
  // True value also indicates we found a value: two mixed meanings.
  return true; 
}

For more examples, please see:

• Manual:Hooks/MagicWordwgVariableIDs - discusses how the various hooks involved in defining a custom variable work together; also provides a coding example
• Extension:Variables - another coding example using this hook