Manuel:Variable

Cette page concerne la création de variables. Pour l'aide à propos de l'utilisation des variables par défaut, voir Aide:Mots magiques . Pour les variables globales PHP utilisées en interne dans MediaWiki, voir Manual:Wg variable .

Les Variables sont des morceaux de wikitexte qui ressemblent à des modèles mais n'ont pas de paramètres et ont reçu des valeurs codées en dur. Les balises wiki standard telles que {{PAGENAME}} ou {{SITENAME}} sont des exemples de variables. Vous pouvez également étendre le balisage wiki en définissant vos propres variables personnalisées.

Le terme est quelque peu impropre parce qu'il n'y a rien de variable dans une variable. Les utilisateurs finaux ne peuvent pas modifier la valeur d'une variable car elle est prédéterminée par un ensemble de code PHP qui calcule sa valeur. Le terme "variables vient de la source de leur valeur: une variable PHP ou quelque chose qui pourrait être affecté à une variable, par ex. une chaîne, un nombre, une expression ou une valeur de retour de fonction.

Définir des variables personnalisées

Les variables sont un cas particulier de mots magiques donc notre première étape sera de définir la variable comme un mot magique:

1. Choisissez un identifiant de mot magique pour votre variable. Il s'agit uniquement d'un identifiant interne qui est utilisé pour relier les différentes parties de la définition de la variable: les noms qui apparaissent dans le texte wiki et le code PHP qui attribue une valeur à la variable. Il est préférable de choisir un identifiant qui sera uniquement associé à votre extension et qui ne risque pas d'être confondu avec d'autres identifiants de mots magiques utilisés par d'autres extensions. Une stratégie courante consiste à utiliser quelque chose comme MAG_canonicalname où canonicalname est le nom sous lequel vous allez enregistrer votre extension (voir Registering custom variables au dessous de).
2. Définir les noms qui apparaîtront dans le texte wiki. Pour accomplir cela, vous devrez définir un tableau $magicWords dans un fichier. Voir Manuel:Mots Magiques pour plus d'informations. Vos noms peuvent être sensibles à la casse et dépendants de la langue.
3. Fournir du code PHP pour affecter une valeur à la variable. Pour ce faire, vous devrez définir et enregistrer une fonction hook avec ParserGetVariableValueSwitch .

Notez que la seule différence entre ce processus et le processus général de définition des mots magiques est la dernière étape: définir une fonction hook pour ParserGetVariableValueSwitch . Les fonctions d'analyseur ont une méthode différente pour associer un ID au code PHP. Voir Fonctions d'analyse pour plus d'informations.

Enregistrer des variables personnalisées

Ceci est un processus en deux étapes:

1. 'Définit la variable pour qu’elle soit incluse dans le code>Special:Version/code>. Cela nécessite d’ajouter un membre à $wgExtensionCredits . Pour plus d’informations, veuillez consulter 'Registering features with MediaWiki'.
2. 'Déclare le mot magique ID comme variable. ' Pour accomplir ceci nous écrivons et attribuons un crochet à MagicWordwgVariableIDs , le sujet de cet article.

cette accroche ne doit seulement être utilisée qu'avec des variables. Ne pas l'utiliser avec des fonctions d'analyse syntaxique !

Exemples

Remarque : si vous souhaitez utiliser cet exemple comme modèle de codage, veuillez remplacer le 'My' par quelque chose d’unique à votre projet afin qu’il y ait moins de risques de conflits de noms avec MediaWiki ou ses extensions. Par exemple, si votre extension a été nommée BigExtravagantStylingTool et que vous étiez raisonnablement sûr que personne d’autre n’avait une extension avec des constantes, des variables, des fonctions ou des classes commençant par 'BEST_', 'wgBEST', 'wfBEST', ou même 'BEST' vous pourriez vouloir remplacer 'My' par 'BEST'.

Fichier Example.i18n.magic.php

<?php
/**
 * Step 1: choose a magic word ID
 * Step 2: define some words to use in wiki markup
 */

$magicWords = [];

/** English (English) */
$magicWords['en'] = [
	// tell MediaWiki that all {{NiftyVar}}, {{NIFTYVAR}}, {{CoolVar}},
	// {{COOLVAR}} and all case variants found in wiki text should be mapped to
	// magic ID 'mycustomvar1' (0 means case-insensitive)
	'mycustomvar1' => [ 0, 'NiftyVar', 'CoolVar' ],
];

Fichier Example.php

<?php
/**
 * Step 3: Register the file with the magic words.
 */
$wgExtensionMessagesFiles['ExampleMagic'] = __DIR__ . '/Example.i18n.magic.php';

/**
 * Step 4: assign a value to our variable
 */
$wgHooks['ParserGetVariableValueSwitch'][] = 'wfMyAssignAValue';
function wfMyAssignAValue( &$parser, &$cache, &$magicWordId, &$ret ) {
	if ( $magicWordId === 'mycustomvar1' ) {
		// We found a value
		$ret = 'This is a really silly value';
	}
	// We must return true for two separate reasons:
	// 1. To permit further callbacks to run for this hook.
	//    They might override our value but that's life.
	//    Returning false would prevent these future callbacks from running.
	// 2. At the same time, "true" indicates we found a value.
	//    Returning false would set variable value to null.
	//
	// In other words, true means "we found a value AND other
	// callbacks will run," and false means "we didn't find a value
	// AND abort future callbacks." It's a shame these two meanings
	// are mixed in the same return value.  So as a rule, return
	// true whether we found a value or not.
	return true;
}

/**
 * Step 5: register the custom variable(s) so that it shows up in
 * Special:Version under the listing of custom variables.
 */
$wgExtensionCredits['variable'][] = [
	'name' => 'ExampleMagic',
	'author' => 'John Doe',
	'version' => '1.0',
	'description' => 'Provides a variable as an example and performs no discernible function',
	'url' => 'https://www.mediawiki.org/wiki/Extension:ExampleMagic',
];

/**
 * Step 6: register wiki markup words associated with
 *         MAG_NIFTYVAR as a variable and not some
 *         other type of magic word
 */
$wgHooks['MagicWordwgVariableIDs'][] = 'wfMyDeclareVarIds';
function wfMyDeclareVarIds( &$customVariableIds ) {
	// $customVariableIds is where MediaWiki wants to store its list of custom
	// variable IDs. We oblige by adding ours:
	$customVariableIds[] = 'mycustomvar1';
}

Pour plus d’informations

• Aide:Mots magiques - discute des mots magiques par défaut intégrés dans le paquet principal MediaWiki
• Manuel:Mots Magiques - examine les différents types de mots magiques et comment MediaWiki différencie les variables, les fonctions d’analyse et les modèles.
• Spécifications du langage Markup