Manuel:Mots Magiques

Les mots magiques sont une technique pour mapper une variété de chaînes de texte wiki à un ID unique associé à une fonction. Les variables et les fonctions d'analyse (fonctions parser) utilisent cette technique. Tout le texte mappé à cet ID sera remplacé par la valeur de retour de la fonction. Le mappage entre les chaînes de texte et l'ID est stocké dans la variable $magicWords dans un fichier qui peut être chargé en utilisant $wgExtensionMessagesFiles[] .

Les mots magiques par défaut sont implémentés dans CoreParserFunctions.php .

Comment fonctionnent les mots magiques

Chaque fois que MediaWiki trouve du texte entre doubles accolades ({{XXX ...}}), il doit décider si XXX est une variable, une fonction analyseur, ou un modèle. Pour ce faire, il se pose une série de questions :

1. Existe-t-il un ID de mot magique associé ? Dans une première étape de résolution du marquage de la forme {{XXX...}}, MediaWiki tente de traduire XXX en ID de mot magique.

La table de transaction est définie par $magicWords.

1. • Si aucun ID de mot magique n'est associé à XXX, XXX est supposé être un modèle.

   
   

2. Est-ce une variable ? Si un ID de mot magique est trouvé, MediaWiki vérifie ensuite l'existence de paramètres éventuels.
   • S'il ne trouve aucun paramètre, MediaWiki vérifie si l'ID du mot magique a été déclaré comme ID de variable. Pour vérifier cela, il récupère la liste des mots magiques en appelant MagicWord::getVariableIDs(). Cette méthode obtient sa liste d'IDs de variables à partir d'une liste codée en dur d'IDs de variables (voir Help:Variables ) et d'une liste d'IDs de variables personnalisée fournie par toutes les fonctions liées à l'accroche MagicWordwgVariableIDs .
     • Si l'ID du mot magique est classé comme une variable, MediaWiki appelle appelle la fonction ParserGetVariableValueSwitch pour trouver la valeur associée au nom de la variable.

   
   

3. Est-ce une fonction d'analyse ? S'il y a des paramètres ou si l'ID du mot magique est absent de la liste des IDs de mots magiques qui sont des variables, alors MediaWiki suppose que le mot magique est une fonction d'analyse ou un modèle. Si l'ID du mot magique est trouvé parmi la liste des fonctions d'analyse déclarée via un appel à $wgParser->setFunctionHook($magicWordId, $renderingFunctionName), il est traité comme une fonction d'analyse et interprété en utilisant la fonction appelée $renderingFunctionName. Sinon, on suppose qu'il s'agit d'un modèle.

Par convention :

• Les mots magiques qui sont des variables, sont mis en majuscules, sensibles à la casse et ne comportent pas de caractères espace.
• Les fonctions d'analyse sont préfixées par un signe de hachage (#) et insensibles à la casse; elles ne contiennent pas de caractères espace.

Ceci n'est qu'une convention et pas toujours appliquée de manière cohérente (pour des raisons historiques).

• Les variables ne comportent pas de caractères espace, mais certaines traductions de variables dans les autres langues peuvent en avoir.
• Les variables sont généralement en majuscules et sensibles à la casse, et certaines fonctions d'analyse utilisent également cette convention.
• Certaines fonctions d'analyse commencent par un croisillon (hash), mais pas toutes.

Là où c'est possible, suivez les conventions pour définir ou traduire les mots magiques. Les mots magiques ont une priorité supérieure à celle des modèles, donc tout mot magique défini bloquera l'utilisation de ce nom défini en tant que modèle.

Suivre les conventions évite de créer de plus en plus de collisions potentielles.

Définir des mots magiques

Pour que des mots deviennent réellement magiques, il faut définir deux choses :

• une correspondance entre le texte wiki et un ID de mot magique,
• une correspondance entre un ID de mot magique et une fonction PHP quelconque qui interprète ce mot magique.

Faire correspondre le wikicode aux IDs des mots magiques

La variable $magicWords est utilisée pour associer chaque ID de mot magique avec un tableau dépendant de la langue qui décrit toutes les chaînes textuelles correspondant à l'ID du mot magique. Important: ceci ne met à jour que la correspondance i18n dans le coeur, vous devez encore écrire le code pour que MediaWiki puisse utiliser ce mot magique. Assurez-vous également d'avoir initialisé $magicWords comme un tableau vide avant d'ajouter des valeurs spécifiques à la langue, sinon vous obtiendrez des erreurs quand vous essayerez de charger le mot magique et devrez reconstruire votre cache de traduction avant qu'il ne redevienne opérationnel.

Le premier élément de ce tableau est un drapeau entier qui indique si le mot magique est sensible à la casse ou pas. Les autres éléments sont une liste des textes qui doivent être associés à l'ID du mot magique. Si le drapeau de sensibilité à la casse est à 0, toute combinaison de casse des lettres composant le nom sera acceptée. S'il est à 1, seule la correspondance exacte des majuscules/minuscules sera associée à l'ID du mot magique. Ainsi, le format est $magicWords['en'] = [ 'InternalName' => [ 0, 'NameUserTypes', 'AdditionalAliasUserCanType' ] ];

Cette association est créée par $magicWords dans un fichier enregistré en utilisant $wgExtensionMessagesFiles[] .

Dans l'exemple ci-dessous, une installation du MediaWiki espagnol va associer l'ID de mot magique 'MAG_CUSTOM' avec « personalizado », « custom », « PERSONALIZADO », « CUSTOM » et toutes les autres variantes de la casse. Pour un MediaWiki anglophone, seul « custom » avec toutes ses variantes de casse sera associé à 'MAG_CUSTOM' :

Fichier Example.i18n.magic.php :

<?php

$magicWords = [];

$magicWords['en'] = [
	'MAG_CUSTOM' => [ 0, 'custom' ],
];

$magicWords['es'] = [
	'MAG_CUSTOM' => [ 0, 'personalizado' ],
];

En partie dans le fichier extension.json :

"ExtensionMessagesFiles": {
	"ExampleMagic": "Example.i18n.magic.php"
}

Notez que « ExampleMagic » est différent de la clé que vous utiliseriez pour un fichier d'internationalisation brut (normalement simplement le titre de l'extension, par exemple « Example »). « Magic » a été délibérément ajouté pour ne pas qu'ils se marchent dessus.

Dans le PHP en ligne

Vous pouvez associer les mots magiques en ligne en PHP plutôt que via un fichier i18n. Ceci est utile lors de la définition d'accroches (hooks) dans LocalSettings.php mais ne doit pas être fait dans les extensions.

MediaWiki\MediaWikiServices::getInstance()->getContentLanguage()->mMagicExtensions['wikicodeToHtml'] = ['MAG_CUSTOM', 'custom'];

Associer un ID de mot magique à une fonction PHP

Le mécanisme pour associer les identifiants des mots magiques aux fonctions de rendu dépend du fait que le mot magique sera utilisé comme une fonction parser ou comme une variable. Pour plus d'informations, veuillez consulter :

• Fonctions d'analyse
• Manual:Variables

Internationalisation

Voir la localisation pour l'aide.

Vous pouvez en savoir plus sur la définition et l'utilisation des mots magiques pour l'internationalisation sur l'API Messages, les Espaces de noms ; Évitez {{SITENAME}} dans les messages.

Sélecteur de comportement (mots magiques avec souligné double)

Les sélecteurs de comportement sont un type particulier de mot magique. Ils peuvent être reconnus par la double utilisation du caractère souligné (plutôt que les doubles accolades). Exemple : __NOTOC__

Ces mots magiques ne produisent généralement aucun contenu, mais modifient plutôt le comportement d'une page et/ou définissent une propriété de page. Ces mots magiques sont répertoriés dans MagicWordFactory::mDoubleUnderscoreIDs et aussi dans Aide:Mots magiques#Changements de comportement. L'effet de la plupart des changeurs de comportement standard est défini dans Parser::handleDoubleUnderscore() . Si aucun effet spécifique n'est défini, le mot magique définira simplement une propriété de page dans la table page_props. Ceci peut être vérifié ultérieurement en testant si $parser->getOutput()->getPageProperty( 'MAGIC_WORD' ) est nul ou correspond à une chaîne vide.

Sélecteurs de comportement personnalisés

Voici un exemple d'extension implémentant un commutateur de comportement personnalisé à __CUSTOM__

custom/extension.json - C'est un minimum, une extension réelle remplirait plus de champs.

{
	"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' );
		}
	}
}

Voir aussi

• Mots magiques - Liste de variables comme {{PAGENAME}} et {{SERVER}}
• Manual:MagicWord.php