Manual:Palabras máxicas
Magic words are strings of text that MediaWiki links to specific functions or return values, such as current date and time, page titles, site information, and more. They can be thought of as special commands or variables that allow dynamic content generation and interaction with the MediaWiki software during page rendering.
From a technical standpoint, magic words map a range of wiki text strings to a unique internal identifier (ID), which is then associated with a particular function. This ID directs MediaWiki to execute a corresponding operation or return a specific value. Both variables (which output dynamic values) and parser functions (which perform operations or conditional logic) make use of this mapping technique.
Todo o texto catalogado à certa identidade será substituído polo valor de regreso da función.
A representación das expresións e cada identidade é almacenada na variábel $magicWords nun arquivo que pode ser cargado utilizándose $wgExtensionMessagesFiles[].
As palabras máxicas estándares son implementadas en CoreParserFunctions.php.
Como funcionan as palabras máxicas
Sempre que MediaWiki atopa un texto entre chaves duplas ({{XXX ...}}), debe decidir se XXX é unha variábel, unha función sintáctica ou un modelo. Para facer isto, faise unha serie a preguntas:
- Hai unha palabra máxica asociada a unha ID? O primeiro paso ao resolver marcación do padrón
{{XXX...}}, MediaWiki intenta traducir XXX a ID (identidade) coma palabra máxica. A táboa de tradución é definida por $magicWords.- Se ningunha identidade de palabra máxica é asociada con XXX, supónse que XXX é un modelo.
- É unha variábel? Se a identidade dunha palabra máxica é atopada, axiña MediaWiki verifica se posúe algún parámetro.
- Se ningún parámetro é atopado, MediaWiki verifica se a a identidade da palabra máxica foi definida como identidade de variábel. Para facer isto, recupérasa a lista de palabras máxicas que atenden chamando
MagicWord::getVariableIDs(). Este método acada a súa lista de identidades de variábeis dunha lista codificada de identidades de variábeis (véxase Help:Variables) e dunha lista personalizada de variábeis, que é proporcionada por todas as funcións enlazadas no gancho MagicWordwgVariableIDs.- Se a identidade da palabra máxica foi clasificada coma variábel, MediaWiki chama as funcións asociadas co nome do evento ParserGetVariableValueSwitch ata que sexa atopado un que corresponda á palabra máxica e poida devolver o seu valor.
- Se ningún parámetro é atopado, MediaWiki verifica se a a identidade da palabra máxica foi definida como identidade de variábel. Para facer isto, recupérasa a lista de palabras máxicas que atenden chamando
- É unha función sintáctica? Se hai algún parámetro ou se a ID da palabra máxica non for atopada na lista de palabras máxicas variables, entón MediaWiki supón que a palabra máxica é unha función sintáctica ou modelo. Se a identidade da palabra máxica é atopada na lista de funcións sintácticas declaradas mediante unha chamada de
$wgParser->setFunctionHook($magicWordId, $renderingFunctionName), ela é tratado coma función sintáctica e executada utilizándose a función$renderingFunctionName. Doutra banda, suponse que é un modelo. If the magic word ID is found in the list of declared parser functions, it is treated as a parser function and rendered using the function named$renderingFunctionName. Otherwise, it is presumed to be a template.
Definindo palabras máxicas
By convention:
- The magic words called variables are capitalised, case-sensitive and do not have space characters.
- Parserfunctions are prefixed with a hash sign (#), are case insensitive and do not include space characters.
This is however a convention and one not consistently applied (for historic reasons).
- Variables do not have spaces in English, but some translations of variables in other languages do have spaces.
- Variables generally are capitalised and case-sensitive, but some parser functions also use this convention.
- Some parser functions start with a hash sign, but some do not.
Where possible the conventions for defining or translating magic words should be followed. Magic words are higher in priority than templates, so any magic word defined, will block the usage of that defined name as a template.
Following the conventions avoids creating additional potential naming collisions.Para que palabras máxicas fagan a súa meigaría, débese definir dúas cousas:
- unha correspondencia entre texto wiki e unha identidade de palabra máxica
- unha correspondencia entre unha identidade de palabra máxica e algunha función php que interpreta a palabra máxica.
- a mapping between wiki text and a magic word ID
- a mapping between a magic word ID and some PHP function that interprets the magic word.
Catalogando expresións wiki coma ID de palabra máxica
A variábel $magicWords é utilizada para asociar cada palabra máxica cunha matriz dependente de lingua que describe todas as expresións que son catalogadas á identidade da palabra máxica.
Important: This only sets up the back end i18n mapping, you still have to write other code to make MediaWiki use the magic word for anything.
Also, make sure that you initialize $magicWords as an empty array before adding language-specific values or you will get errors when trying to load the magic word and will need to rebuild your localization cache before it will work.
O primeiro elemento desta matriz é unha sinatura que indica se a palabra máxica é sensible a maiúsculas e minúsculas. Os elementos restantes son unha lista de texto que debería ser asociado coa identidade da palabra máxica. Se a sinatura de sensibilidade for 0, calquera variación nos nomes listados na matriz combinará. Se a sinatura de sensibilidade for 1, soamente combinacións exactas serán asociadas á identidade da palabra máxica.
Thus the format is $magicWords['en'] = [ 'InternalName' => [ 0, 'NameUserTypes', 'AdditionalAliasUserCanType' ] ];
Esta asociación é creada por $magicWords nun arquivo rexsitrado con $wgExtensionMessagesFiles[].
No exemplo abaixo, unha instalación española de MediaWiki asociará a identidade da palabra máxica 'MAG_CUSTOM' con "#personalizado", "#custom", "#PERSONALIZADO", "#CUSTOM" e en tódalas outras variantes pertinentes. En MediaWiki en inglés, soamente "#custom" nas diversas combinacións será catalogado coma 'MAG_CUSTOM': In an English MediaWiki only "custom" in various case combinations will be mapped to 'MAG_CUSTOM':
Ficheiro Example.i18n.magic.php:
<?php
$magicWords = [];
$magicWords['en'] = [
'MAG_CUSTOM' => [ 0, 'custom' ],
];
$magicWords['es'] = [
'MAG_CUSTOM' => [ 0, 'personalizado' ],
];
In part of the extension.json file:
"ExtensionMessagesFiles": {
"ExampleMagic": "Example.i18n.magic.php"
}
Note que "ExampleMagic" é un tanto diferente da clave que sería utilizada para un ficheiro de internacionalización sinxelo (normalmente apenas a extensión, p. ex. "Exemple"). "Magic" foi engadida deliberadamente, destarte, un non sobrescribe o outro.
In inline PHP
You can associate magic words inline in PHP rather than through a i18n file.
This is useful when defining hooks in LocalSettings.php but should not be done in extensions.
MediaWiki\MediaWikiServices::getInstance()->getContentLanguage()->mMagicExtensions['wikicodeToHtml'] = ['MAG_CUSTOM', 'custom'];
Asociando unha ID de palabra máxica a unha función PHP
O mecanismo para asociar o ID de palabra máxica con funcións de execución depende de que se a palabra máxica será utilizada como unha función sintáctica ou unha variábel. Para máis información, véxase:
Localización
- Véxase Help:Magic words#Localisation, para axuda.
Pódese ler máis de definición e uso de palabras máxicas para localización en Localisation#PLURAL and GENDER support in JavaScript, Localisation#Localizing namespaces and special page aliases, Localisation#Switches in messages…; Localisation#Be aware of PLURAL use on all numbers, Localisation#Users have grammatical genders, Avoid {{SITENAME}} in messages.
Cambio de acción (palabras máxicas con subliñado duplo)
Os cambios de acción son un tipo especial de palabra máxica. Poden ser recoñecidos polo uso de subliñados duplos (máis que chaves duplas). Por exemplo, __NOTOC__.
Example:
__NOTOC__
Estas palabras máxicas non retornan tipicamente ningunha saída de contido, senón que cambian o comportamento dunha páxina e/ou lle definen unha propiedade.
Estas palabras máxicas son listadas en MagicWordFactory::mDoubleUnderscoreIDs e tamén en Help:Magic words#Behavior switches.
O efecto de cada und os cambios é definido en Parser::handleDoubleUnderscore().
Se ningún efecto específico é definido, a palabra máxica definirá unha propiedade de páxina na táboa page_props.
This can also be checked later by testing if $parser->getOutput()->getPageProperty( 'MAGIC_WORD' ) is null or the empty string
Custom behavior switch
Here is an example extension implementing a custom __CUSTOM__ behaviour switch
MyExt/extension.json - This is minimal, a real extension would fill out more fields.
{
"name": "MyExt",
"type": "parserhook",
"AutoloadNamespaces": {
"MediaWiki\\Extension\\MyExt\\": "includes/"
},
"Hooks": {
"GetDoubleUnderscoreIDs": "main",
"ParserAfterParse": "main"
},
"HookHandlers": {
"main": {
"class": "MediaWiki\\Extension\\MyExt\\Hooks",
"services": [ "MainConfig" ]
}
},
"ExtensionMessagesFiles": {
"MyExtMagic": "custom.i18n.magic.php"
},
"manifest_version": 2
}
MyExt/MyExt.i18n.magic.php
<?php
$magicWords = [];
$magicWords['en'] = [
'MAG_CUSTOM' => [ 0, '__CUSTOM__' ],
];
MyExt/includes/Hooks.php
<?php
namespace MediaWiki\Extension\MyExt;
class Hooks implements GetDoubleUnderscoreIDsHook, ParserAfterParseHook {
public function onGetDoubleUnderscoreIDs( &$ids ) {
$ids[] = 'MAG_CUSTOM';
}
public function onParserAfterParse( $parser, &$text, $stripState ) {
if ( $parser->getOutput()->getPageProperty( 'MAG_CUSTOM' ) !== null ) {
// Do behavior switching here ...
// e.g. If you wanted to add some JS, you would do $parser->getOutput()->addModules( [ 'moduleName' ] );
}
}
}
Véxase tamén
- Axuda:Palabras máxicas - Listaxe de variábeis coma {{PAGENAME}} e {{SERVER}}
- Manual:MagicWord.php