Manual:Palabras mágicas
Las palabras mágicas son cadenas de texto que MediaWiki vincula a funciones específicas o valores de retorno, como fecha y hora actuales, títulos de páginas, información del sitio y más. Se pueden considerar como comandos o variables especiales que permiten la generación de contenido dinámico e interacción con el software de MediaWiki durante el renderización de páginas.
Desde un punto de vista técnico, las palabras mágicas mapean una gama de cadenas de texto wiki a un identificador interno único (ID), que luego se asocia con una función particular. Este ID le indica a MediaWiki que ejecute una operación correspondiente o que devuelva un valor específico. Tanto las variables (que generan valores dinámicos) como las funciones de análisis sintáctico (que realizan operaciones o lógica condicional) utilizan esta técnica de mapeo.
Todo el texto asignado a esa ID será reemplazado por el valor de retorno de la función.
El mapeo entre las cadenas de texto y la ID se almacena en la variable $magicWords en un archivo que se puede cargar usando $wgExtensionMessagesFiles[].
Las palabras mágicas predeterminadas están implementadas en CoreParserFunctions.php.
Cómo funcionan las palabras mágicas
Dondequiera que MediaWiki encuentre texto entre dobles llaves ({{XXX ...}}) decide si XXX corresponde a una variable, una función del analizador sintáctico, o una plantilla. Para hacerlo, se hace las siguientes preguntas:
- ¿El texto está asociado a un ID de palabra mágica? Es el primer paso para resolver la forma de marcado
{{XXX...}}, Mediawiki intenta traducir XXX al ID de una palabra mágica. La traducción se realiza de acuerdo a la tabla de $magicWords.- Si no hay ningún ID de palabra mágica asociado con "XXX", se asume que "XXX" es una plantilla.
- ¿Es una variable? En caso de que sí se encuentre el ID de una palabra mágica, MediaWiki procede a comprobar si tiene algún parámetro.
- Si no se encuentra ningún parámetro, MediaWiki comprueba si el ID de la palabra mágica ha sido declarado como ID de variable. Para comprobar esto, recupera la lista de las palabras mágicas en uso llamando a
MagicWord::getVariableIDs(). Este método obtiene su lista de identificadores de variables de una lista en código duro (véase Help:Variables) y de una lista de identificadores de variables personalizadas proporcionada por todas las funciones conectadas al hook MagicWordwgVariableIDs.- Si la ID de la palabra mágica ha sido clasificada como variable, MediaWiki llama a la función ParserGetVariableValueSwitch para obtener el valor asociado con el nombre de la variable.
- Si no se encuentra ningún parámetro, MediaWiki comprueba si el ID de la palabra mágica ha sido declarado como ID de variable. Para comprobar esto, recupera la lista de las palabras mágicas en uso llamando a
- ¿Es una función de análisis? Si hay algún parámetro o si el ID de la palabra mágica falta en la lista de ID de palabras mágicas variables, entonces MediaWiki asume que la palabra mágica es una función de análisis o una plantilla. Si la palabra mágica ID se encuentra en la lista de funciones de parser declaradas, se trata como una función de parser y se representa utilizando la función llamada
$renderingFunctionName. De lo contrario, se presume que es una plantilla.
Definir palabras mágicas
Por convención:
- Las palabras mágicas llamadas variables son capitalizadas, sensibles a los casos y no tienen caracteres espaciales.
- Las funciones de parser están prefijadas con un signo hash (#), son insensibles a los casos y no incluyen caracteres espaciales.
Sin embargo, se trata de una convención y no se aplica de manera consistente (por razones históricas).
- Las variables no tienen espacios en inglés, pero algunas traducciones de variables en otros idiomas sí tienen espacios.
- Las variables generalmente son capitalizadas y sensibles a los casos, pero algunas funciones de parser también utilizan esta convención.
- Algunas funciones de parser comienzan con un signo hash, pero algunas no.
Cuando sea posible, se deben seguir las convenciones para definir o traducir palabras mágicas. Las palabras mágicas tienen mayor prioridad que las plantillas, por lo que cualquier palabra mágica definida, bloqueará el uso de ese nombre definido como plantilla.
Siguiendo las convenciones evita crear posibles colisiones de nombres adicionales.Para que las palabras mágicas hagan su magia debemos definir dos cosas:
- Un mapeo entre el texto wiki y el ID de una palabra mágica.
- Un mapeo entre el ID de una palabra mágica y alguna función PHP que interprete la palabra mágica.
Mapeo de wikitexto a palabra mágica IDs
La variable $magicWords se utiliza para asociar cada ID de palabra mágica con una matriz dependiente del idioma que describe todas las cadenas de texto que se cartografiaron con el ID de palabra Mágica.
Importante: Esto solo establece el mapeo de backend i18n, todavía tienes que escribir otro código para que MediaWiki use la palabra mágica para cualquier cosa.
Además, asegúrese de que inicie $magicWords como una matriz vacía antes de agregar valores específicos del idioma o obtendrá errores al tratar de cargar la palabra mágica y tendrá que reconstruir su caché de localización antes de que funcione.
El primer elemento de esta matriz es una bandera de números enteros que indica si la palabra mágica es o no sensible al caso. Los elementos restantes son una lista de texto que debe estar asociado con la palabra mágica ID. Si la bandera sensible al caso es 0, cualquier variante del caso de los nombres en la matriz coincidirá. Si la bandera sensible al caso es 1, solo coincidencias exactas de casos se asociarán con la palabra mágica ID.
Por lo tanto el formato es $magicWords['en'] = [ 'InternalName' => [ 0, 'NameUserTypes', 'AdditionalAliasUserCanType' ] ];
$magicWords crea esta asociación en un fichero registrado usando $wgExtensionMessagesFiles[].
En el ejemplo siguiente, una instalación de MediaWiki en español asociará la palabra mágica ID 'MAG_CUSTOM' con "personalizado", "custom", "PERSONALIZADO", "CUSTOM" y todas las otras variantes de casos. En un MediaWiki en inglés, solo las combinaciones "custom" en varios casos se asignarán a "MAG_CUSTOM":
Archivo Example.i18n.magic.php:
<?php
$magicWords = [];
$magicWords['en'] = [
'MAG_CUSTOM' => [ 0, 'custom' ],
];
$magicWords['es'] = [
'MAG_CUSTOM' => [ 0, 'personalizado' ],
];
En parte del archivo extension.json:
"ExtensionMessagesFiles": {
"ExampleMagic": "Example.i18n.magic.php"
}
Tenga en cuenta que "ExampleMagic" es diferente a la clave que usaría para un archivo de internacionalización simple (normalmente solo el título de la extensión, es decir, "Example"). "Magia" ha sido añadida deliberadamente para que uno no sobreescriba al otro.
En línea
Puedes asociar palabras mágicas en línea en PHP en lugar de a través de un archivo i18n.
Esto es útil para definir ganchos en LocalSettings.php pero no debe hacerse en extensiones.
MediaWiki\MediaWikiServices::getInstance()->getContentLanguage()->mMagicExtensions['wikicodeToHtml'] = ['MAG_CUSTOM', 'custom'];
Asociación de un ID de palabra mágica con una función PHP
El mecanismo para asociar los identificadores de palabras mágicas con las funciones de representación depende de si la palabra mágica se utilizará como una función de análisis o una variable. Para obtener más información, consulte:
Localización
- Consulte Ayuda:Palabras mágicas#Localización para obtener ayuda.
Puede leer más sobre la definición y el uso de palabras mágicas para la localización en Manual:Messages API, Manual:Language#Namespaces; Evite {{SITENAME}} en los mensajes .
Cambios de comportamiento (palabras mágicas con doble guión bajo)
Los interruptores de comportamiento son un tipo especial de palabra mágica. Se pueden reconocer por su uso de doble subcorrección (en lugar de doble aparador).
Ejemplo:
__NOTOC__
Estas palabras mágicas normalmente no producen ningún contenido, sino que cambian el comportamiento de una página y/o establecen una propiedad de página.
Estas palabras mágicas se enumeran en MagicWordFactory::mDoubleUnderscoreIDs y también en Ayuda:Palabras mágicas#Interruptores de comportamiento.
El efecto de la mayoría de los interruptores de comportamiento estándar se define en Parser::handleDoubleUnderscore().
Si no se define ningún efecto específico, la palabra mágica simplemente establecerá una propiedad de página en la tabla de page_props.
Esto también se puede comprobar más adelante probando si $parser->getOutput()->getPageProperty( 'MAGIC_WORD' ) es nulo o la cadena vacía
Cambio de comportamiento personalizado
Aquí hay un ejemplo de extensión que implementa un cambio de comportamiento personalizado __CUSTOM__
MyExt/extension.json - Esto es mínimo, una extensión real llenaría más campos.
{
"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éase también
- Ayuda:Palabras mágicas - Lista de variables como {{PAGENAME}} y {{SERVER}}
- Manual:MagicWord.php