a30b328bd4
There's already a thing called magic words, and this is not it. These things are called variables. There are many usages of this term in the source. The term was introduced by Lee in 2002: originally OutputPage::replaceVariables() contained only this functionality. I introduced the term "magic word", meaning a localizable keyword. Localizable keywords are an abstraction not limited to this use case. "Magic variables" is a neologism, but I suppose it is permissible, since it disambiguates. Whereas calling a variable a magic word conflates rather than disambiguates. Fix terminology in magicword.md and update the examples. Change-Id: I621c888e3790a145ca9978f6b30ff1a8f685b64c
84 lines
2.4 KiB
Markdown
84 lines
2.4 KiB
Markdown
Magic Words
|
|
====================================
|
|
|
|
Magic words are localizable keywords used in wikitext. They are used for many
|
|
small fragments of text, including:
|
|
|
|
* The names of parser functions e.g. `{{urlencode:...}}`
|
|
* The names of variables, e.g. `{{CURRENTDAY}}`
|
|
* Double-underscore behavior switches, e.g. `__NOTOC__`
|
|
* Image link parameter names
|
|
|
|
Magic words have a synonym list, with the canonical English word always present,
|
|
and a case sensitivity flag. The MagicWord class provides facilities for
|
|
matching a magic word by converting it to a regex.
|
|
|
|
A magic word has a unique ID. Often, the ID is the canonical English synonym in
|
|
lowercase.
|
|
|
|
To add a magic word in an extension, add a file to the **ExtensionMessagesFiles**
|
|
attribute in extension.json,
|
|
and in that file, set a variable called **$magicWords**. This array is associative
|
|
with the language code in the first dimension key and an ID in the second key. The
|
|
third level array is numerically indexed: the element with key 0 contains the case
|
|
sensitivity flag, with 0 for case-insensitive and 1 for case-sensitive. The
|
|
subsequent elements of the array are the synonyms in the relevant language.
|
|
|
|
To add a magic word in core, add it to $magicWords in MessagesEn.php, following the
|
|
comment there.
|
|
|
|
For example, to add a new parser function in an extension: create a file called
|
|
**ExtensionName.i18n.magic.php** with the following contents:
|
|
|
|
```php
|
|
<?php
|
|
|
|
$magicWords = [];
|
|
|
|
$magicWords['en'] = [
|
|
// Case insensitive.
|
|
'mag_custom' => [ 0, 'custom' ],
|
|
];
|
|
|
|
$magicWords['es'] = [
|
|
'mag_custom' => [ 0, 'aduanero' ],
|
|
];
|
|
```
|
|
|
|
Then in extension.json:
|
|
|
|
```json
|
|
{
|
|
"ExtensionMessagesFiles": {
|
|
"ExtensionNameMagic": "ExtensionName.i18n.magic.php"
|
|
},
|
|
"Hooks": {
|
|
"ParserFirstCallInit": "MyExtensionHooks::onParserFirstCallInit"
|
|
}
|
|
}
|
|
```
|
|
|
|
It is important that the key "ExtensionNameMagic" is unique. It must not be used
|
|
by another extension.
|
|
|
|
And in the class file:
|
|
|
|
```php
|
|
<?php
|
|
|
|
class MyExtensionHooks {
|
|
public static function onParserFirstCallInit( $parser ) {
|
|
$parser->setFunctionHook( 'mag_custom', [ self::class, 'expandCustom' ] );
|
|
return true;
|
|
}
|
|
|
|
public static function expandCustom( $parser, $var1, $var2 ) {
|
|
return "custom: var1 is $var1, var2 is $var2";
|
|
}
|
|
}
|
|
```
|
|
|
|
- Online documentation (contains more informations):
|
|
- Magic words: <https://www.mediawiki.org/wiki/Manual:Magic_words>
|
|
- Variables: <https://www.mediawiki.org/wiki/Manual:Variable>
|
|
- Parser functions: <https://www.mediawiki.org/wiki/Manual:Parser_functions>
|