Manual:Palavras mágicas
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 mapeado para esse ID será substituído pelo valor de retorno da função.
O mapeamento entre as strings de texto e o ID é armazenado na variável $magicWords em um arquivo que pode ser carregado usando $wgExtensionMessagesFiles[].
As palavras mágicas padrão são implementadas em CoreParserFunctions.php.
Como funcionam as palavras mágicas
Sempre que o MediaWiki encontra texto entre chaves duplas ({{XXX ...}}) ele deve decidir se XXX é uma variável, uma função do analisador, ou um modelo. Para isso, ele faz uma série de perguntas:
- Tem um ID de palavra mágica associado? Como primeiro passo para resolver a marcação do formulário
{{XXX...}}, o MediaWiki tenta traduzir XXX para um ID de palavra mágica. A tabela de tradução é definida por $magicWords.- Se nenhum ID de palavra mágica estiver associado a XXX, presume-se que XXX seja um modelo.
- É uma variável? Se um ID de palavra mágica for encontrado, o MediaWiki verifica se tem algum parâmetro.
- Se nenhum parâmetro for encontrado, o MediaWiki verifica se o ID de palavra mágica foi declarado como um ID de variável. Para verificar isso, ele recupera a lista de palavras mágicas sendo servidas chamando
MagicWord::getVariableIDs(). Esse método obtém sua lista de IDs de variáveis de uma lista codificada de IDs de variáveis (consulte Help:Variables) e de uma lista de IDs de variáveis personalizadas fornecidas por todas as funções anexadas ao gancho MagicWordwgVariableIDs.- Se o ID de palavra mágica foi classificado como uma variável, o MediaWiki chama a função ParserGetVariableValueSwitch para obter o valor associado ao nome da variável.
- Se nenhum parâmetro for encontrado, o MediaWiki verifica se o ID de palavra mágica foi declarado como um ID de variável. Para verificar isso, ele recupera a lista de palavras mágicas sendo servidas chamando
- É uma função do analisador? Se houver algum parâmetro ou se o ID de palavra mágica não estiver na lista de IDs de palavras mágicas variáveis, então o MediaWiki assume que a palavra mágica é uma função do analisador ou um modelo. Se o ID de palavra mágica for encontrado na lista de funções do analisador declarada por meio de uma chamada para
$wgParser->setFunctionHook($magicWordId, $renderingFunctionName), ele será tratado como uma função do analisador e renderizado usando a função chamada$renderingFunctionName. Caso contrário, presume-se ser um 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 palavras mágicas
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 as palavras mágicas façam sua mágica, devemos definir duas coisas:
- um mapeamento entre o texto wiki e um ID de palavra mágica
- um mapeamento entre um ID de palavra mágica e alguma função do php que interprete a palavra mágica.
Mapeando texto wiki para IDs de palavras mágicas
A variável $magicWords é usada para associar cada ID de palavra mágica a um arranjo dependente da linguagem que descreve todas as strings de texto mapeadas para a ID de palavra mágica.
Importante: Isso apenas configura o mapeamento i18n de processo interno, você ainda precisa escrever outro código para fazer o MediaWiki usar a palavra mágica para qualquer coisa
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 deste arranjo é um sinalizador de inteiro que indica se a palavra mágica diferencia maiúsculas de minúsculas. Os elementos restantes são uma lista de texto que deve ser associada ao ID de palavra mágica. Se o sinalizador de diferenciação de maiúsculas e minúsculas for 0, qualquer variante de maiúsculas e minúsculas dos nomes no arranjo corresponderá. Se o sinalizador de diferenciação de maiúsculas e minúsculas for 1, apenas as correspondências exatas de maiúsculas e minúsculas serão associadas ao ID de palavra mágica.
Assim o formato é $magicWords['en'] = [ 'InternalName' => [ 0, 'NameUserTypes', 'AdditionalAliasUserCanType' ] ];
Esta associação é criada por $magicWords em um arquivo registrado usando $wgExtensionMessagesFiles[].
No exemplo abaixo, uma instalação do MediaWiki em espanhol associará o ID de palavra mágica "MAG_CUSTOM" com "personalizado", "custom", "PERSONALIZADO", "CUSTOM" e todas as outras variantes de maiúsculas e minúsculas. Em um MediaWiki em inglês, apenas "custom" em várias combinações de maiúsculas e minúsculas será mapeado para "MAG_CUSTOM":
Arquivo Example.i18n.magic.php:
<?php
$magicWords = [];
$magicWords['en'] = [
'MAG_CUSTOM' => [ 0, 'custom' ],
];
$magicWords['es'] = [
'MAG_CUSTOM' => [ 0, 'personalizado' ],
];
Em parte do arquivo extension.json:
"ExtensionMessagesFiles": {
"ExampleMagic": "Example.i18n.magic.php"
}
Observe que "ExampleMagic" é diferente da chave que você usaria para um arquivo de internacionalização simples (normalmente apenas o título da extensão, ou seja, "Example"). "Magic" foi acrescentado deliberadamente para que um não sobrescreva o outro.
Embutido no PHP
Você pode associar palavras mágicas embutindo-as no PHP em vez de através de um arquivo i18n.
Isso é útil ao definir ganchos em LocalSettings.php
MediaWiki\MediaWikiServices::getInstance()->getContentLanguage()->mMagicExtensions['wikicodeToHtml'] = ['MAG_CUSTOM', 'custom'];
Associando um ID de palavra mágica a uma função do PHP
O mecanismo para associar IDs de palavras mágicas com funções de renderização depende se a palavra mágica será usada como uma função do analisador ou uma variável. Para mais informações, consulte:
Localização
- Consulte Ajuda:Palavras mágicas#Localização para obter ajuda.
Você pode ler mais sobre definição e uso de palavras mágicas para localização em [[Manual:Messages API|Manual:IPA de mensagens]], Manual:Linguagem#Espaços de nomes; Evite {{SITENAME}} nas mensagens.
Modificadores de comportamento (palavras mágicas de sublinhado duplo)
Os modificadores de comportamento são um tipo especial de palavra mágica. Eles podem ser reconhecidos pelo uso de sublinhados duplos (em vez de chaves duplas).
Por exemplo:
__NOTOC__
Essas palavras mágicas normalmente não produzem nenhum conteúdo, mas alteram o comportamento de uma página e/ou definem uma propriedade de página.
Essas palavras mágicas estão listadas em MagicWordFactory::mDoubleUnderscoreIDs e também em Ajuda:Palavras mágicas#Comutadores de comportamento.
O efeito da maioria dos modificadores de comportamento padrões é definido em Parser::handleDoubleUnderscore().
Se nenhum efeito específico for definido, a palavra mágica simplesmente definirá uma propriedade de página na tabela page_props.
This can also be checked later by testing if $parser->getOutput()->getPageProperty( 'MAGIC_WORD' ) is null or the empty string
Comutador de comportamento personalizado
Para implementar um comutador de comportamento personalizado.
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' ] );
}
}
}
Consulte também
- Ajuda:Palavras mágicas - Lista de variáveis como {{PAGENAME}} e {{SERVER}}
- Manual:MagicWord.php