docs/magicword.txt

   1 magicword.txt
   2
   3 Magic Words are some phrases used in the wikitext. They are used for two things:
   4 * Variables (like {{PAGENAME}}, {{SERVER}}, ...): part of wikitext, that looks
   5   like templates but that don't accept any parameter.
   6 * Parser functions (like {{fullurl:...}}, {{#special:...}}): behaves like
   7   functions and accepts parameters.
   8
   9 The localized arrays keys are the internal name, and the values are an array,
  10 whose include their case-sensitivity and their alias forms. The first form
  11 defined is used by the program, for example, when moving a page and its old name
  12 should include #REDIRECT.
  13
  14 They can be added in several arrays:
  15 * By adding a file to $wgExtensionMessagesFiles and defining there $magicWords.
  16   This array is associative with the language code in the first dimension key
  17   and then a "normal" array of magic words.
  18 * Localized arrays (languages/messages/LanguageXX.php) include their different
  19   names to be used by the users.
  20
  21 To add a new variable, you should use the "MagicWordwgVariableIDs" hook to add
  22 the internal name to the $magicWords array. You'll need to define the value of
  23 the variable with the "ParserGetVariableValueSwitch" hook.
  24
  25 For example to add a new variable:
  26
  27 Create a file called ExtensionName.i18n.magic.php with the following contents:
  28 ----
  29 <?php
  30
  31 $magicWords = [];
  32
  33 $magicWords['en'] = [
  34         // Case sensitive.
  35         'mag_custom' => [ 1, 'CUSTOM' ],
  36 ];
  37
  38 $magicWords['es'] = [
  39         'mag_custom' => [ 1, 'ADUANERO' ],
  40 ];
  41 ----
  42
  43 $wgExtensionMessagesFiles['ExtensionNameMagic'] = __DIR__ . '/ExtensionName.i18n.magic.php';
  44 $wgHooks['MagicWordwgVariableIDs'][] = 'wfAddCustomMagicWordID';
  45 $wgHooks['ParserGetVariableValueSwitch'][] = 'wfGetCustomMagicWordValue';
  46
  47 function wfAddCustomMagicWordID( &$magicWords ) {
  48         $magicWords[] = 'mag_custom';
  49         return true;
  50 }
  51
  52 function wfGetCustomMagicWordValue( &$parser, &$varCache, &$index, &$ret ){
  53         if( $index == 'mag_custom' ){
  54                 $ret = $varCache['mag_custom'] = "Custom value";
  55         }
  56         return true;
  57 }
  58
  59 And to add a new parser function:
  60
  61 Create a file called ExtensionName.i18n.magic.php with the following contents:
  62 ----
  63 <?php
  64
  65 $magicWords = [];
  66
  67 $magicWords['en'] = [
  68         // Case insensitive.
  69         'mag_custom' => [ 0, 'custom' ],
  70 ];
  71
  72 $magicWords['es'] = [
  73         'mag_custom' => [ 0, 'aduanero' ],
  74 ];
  75 ----
  76
  77 $wgExtensionMessagesFiles['ExtensionNameMagic'] = __DIR__ . '/ExtensionName.i18n.magic.php';
  78 $wgHooks['ParserFirstCallInit'][] = 'wfRegisterCustomMagicWord';
  79
  80 function wfRegisterCustomMagicWord( &$parser ){
  81         $parser->setFunctionHook( 'mag_custom', 'wfGetCustomMagicWordValue' );
  82         return true;
  83 }
  84
  85 function wfGetCustomMagicWordValue( &$parser, $var1, $var2 ){
  86         return "custom: var1 is $var1, var2 is $var2";
  87 }
  88
  89 Note: the 'ParserFirstCallInit' hook is only available since 1.12. To work with
  90 an older version, you'll need to use an extension function.
  91
  92 Online documentation (contains more informations):
  93 Magic words: https://www.mediawiki.org/wiki/Manual:Magic_words
  94 Variables: https://www.mediawiki.org/wiki/Manual:Variable
  95 Parser functions: https://www.mediawiki.org/wiki/Manual:Parser_functions