Localisation updates for magic, special pages aliases, skin names from Betawiki

[lhc/web/wiklou.git] / docs / magicword.txt

diff --git a/docs/magicword.txt b/docs/magicword.txt
index ee5a940..6ecdb56 100644 (file)
--- a/docs/magicword.txt
+++ b/docs/magicword.txt
@@ -1,40 +1,88 @@
 magicword.txt
 
-Magic Words are some phrases used in the wikitext. They are defined in several arrays:
-* $magicWords (includes/MagicWord.php) includes their internal names ('MAG_XXX').
-* $wgVariableIDs (includes/MagicWord.php) includes their IDs (MAG_XXX, which are constants),
-  after their internal names are used for "define()".
-* Localized arrays (languages/LanguageXX.php) include their different names to be used by the users.
+Magic Words are some phrases used in the wikitext. They are used for two things:
+* Variables (like {{PAGENAME}}, {{SERVER}}, ...): part of wikitext, that looks
+  like templates but that don't accept any parameter.
+* Parser functions (like {{fullurl:...}}, {{#special:...}}): behaves like 
+  functions and accepts parameters.
 
-The localized arrays keys are the internal IDs, and the values are an array, whose include their
-case-sensitivity and their alias forms. The first form defined is used by the program, for example,
-when moving a page and its old name should include #REDIRECT.
+The localized arrays keys are the internal name, and the values are an array, 
+whose include their case-sensitivity and their alias forms. The first form 
+defined is used by the program, for example, when moving a page and its old name
+should include #REDIRECT.
 
-Adding magic words should be done using several hooks:
-* "MagicWordMagicWords" should be used to add the internal name ('MAG_XXX') to $magicWords.
-* "MagicWordwgVariableIDs" should be used to add the ID (MAG_XXX constant) to $wgVariableIDs.
-* "AddMagicWordsXX" (XX is the language code, e.g. En or De) should be used to add the
-  different names of the magic word. Use both the localized name and the English name.
+They can be added in several arrays:
+* LanguageGetMagic hook, by adding a new key in $magicWords array. You can get
+  language code in the $lang parameter. Use both the localized name and the 
+  English name.
+* By adding a file to $wgExtensionMessagesFiles and defining there $magicWords.
+  This array is associative with the language code in the first dimension key
+  and then a "normal" array of magic words.
+* Localized arrays (languages/messages/LanguageXX.php) include their different 
+  names to be used by the users.
 
-For example:
+To add a new variable, you should use the "MagicWordwgVariableIDs" hook to add
+the internal name to the $magicWords array. You'll need to define the value of
+the variable with the "ParserGetVariableValueSwitch" hook.
+
+For example to add a new variable:
 
-$wgHooks['MagicWordMagicWords'][] = 'wfAddCustomMagicWord';
 $wgHooks['MagicWordwgVariableIDs'][] = 'wfAddCustomMagicWordID';
-$wgHooks['AddMagicWordsEn'][] = 'wfAddCustomMagicWordEn';
-$wgHooks['AddMagicWordsEs'][] = 'wfAddCustomMagicWordEs';
+$wgHooks['LanguageGetMagic'][] = 'wfAddCustomMagicWordLang';
+$wgHooks['ParserGetVariableValueSwitch'][] = 'wfGetCustomMagicWordValue';
 
-function wfAddCustomMagicWord( &$magicWords ) {
-       $magicWords[] = 'MAG_CUSTOM';
+function wfAddCustomMagicWordID( &$magicWords ) {
+       $magicWords[] = 'mag_custom';
+       return true;
 }
 
-function wfAddCustomMagicWordID( &$magicWords ) {
-       $magicWords[] = MAG_CUSTOM;
+function wfAddCustomMagicWordLang( &$magicWords, $langCode ) {
+       switch ( $langCode ) {
+               case 'es':
+                       $magicWords['mag_custom'] = array( 1, "ADUANERO", "CUSTOM" );
+                       break;
+               default:
+                       $magicWords['mag_custom'] = array( 1, "CUSTOM" );
+       }
+       return true;
 }
 
-function wfAddCustomMagicWordEn( &$magicWords ) {
-       $magicWords[MAG_CUSTOM] = array( 0, "#custom" );
+function wfGetCustomMagicWordValue( &$parser, &$varCache, &$index, &$ret ){
+       if( $index == 'mag_custom' ){
+               $ret = $varCache['mag_custom'] = "Custom value";
+       }
+       return true;
 }
 
-function wfAddCustomMagicWordEs( &$magicWords ) {
-       $magicWords[MAG_CUSTOM] = array( 0, "#aduanero", "#custom" );
+And to add a new parser function:
+
+$wgHooks['LanguageGetMagic'][] = 'wfAddCustomMagicWordLang';
+$wgHooks['ParserFirstCallInit'][] = 'wfRegisterCustomMagicWord';
+
+function wfAddCustomMagicWordLang( &$magicWords, $langCode ) {
+       switch ( $langCode ) {
+               case 'es':
+                       $magicWords['mag_custom'] = array( 0, "aduanero", "custom" );
+                       break;
+               default:
+                       $magicWords['mag_custom'] = array( 0, "custom" );
+       }
+       return true;
 }
+
+function wfRegisterCustomMagicWord( &$parser ){
+       $parser->setFunctionHook( 'mag_custom', 'wfGetCustomMagicWordValue' );
+       return true;
+}
+
+function wfGetCustomMagicWordValue( &$parser, $var1, $var2 ){
+       return "custom: var1 is $var1, var2 is $var2";
+}
+
+Note: the 'ParserFirstCallInit' hook is only aviable since 1.12. To work with
+an older version, you'll need to use an extension function.
+
+Online documentation (contains more informations):
+Magic words: http://www.mediawiki.org/wiki/Manual:Magic_words
+Variables: http://www.mediawiki.org/wiki/Manual:Variable
+Parser functions: http://www.mediawiki.org/wiki/Manual:Parser_functions
\ No newline at end of file