Manual:Palavras mágicas

From mediawiki.org
This page is a translated version of the page Manual:Magic words and the translation is 78% complete.
Outdated translations are marked like this.
Extensões do MediaWiki

Palavras mágicas são uma técnica para mapear uma variedade de strings de texto wiki para um único ID associado a uma função. Tanto as variáveis quanto as funções do analisador usam essa técnica. 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:

  1. 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.

  2. É 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 as funções associadas ao nome de evento ParserGetVariableValueSwitch até que seja encontrada uma que reconheça a palavra mágica e possa retornar seu valor.

  3. É 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.

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 space characters, 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 you should follow the conventions when defining or translating magic words. 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 adding more and more potential collisions.

Definindo palavras mágicas

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: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__. Example: __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.

custom/extension.json - This is minimal, a real extension would fill out more fields.

{
	"name": "Custom",
	"type": "parserhook",
	"AutoloadClasses": {
		"MyHooks": "MyHooks.php"
	},
	"Hooks": {
		"GetDoubleUnderscoreIDs": [
			"MyHooks::onGetDoubleUnderscoreIDs"
		],
		"ParserAfterParse": [
			"MyHooks::onParserAfterParse"
		]
	},
	"ExtensionMessagesFiles": {
		"CustomMagic": "custom.i18n.php"
	},
	"manifest_version": 1
}

custom/custom.i18n.php

<?php
$magicWords = [];
$magicWords['en'] = [
	'MAG_CUSTOM' => [ 0, '__CUSTOM__' ],
];

custom/MyHooks.php

<?php
class MyHooks {
	public static function onGetDoubleUnderscoreIDs( &$ids ) {
		$ids[] = 'MAG_CUSTOM';
	}

	public static function onParserAfterParse( Parser $parser, &$text, StripState $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