Manual:Developing extensions/fr

Extensions:

Extensions balise(en)

Fonctions parseur(en)

Hooks(en)

Pages spéciales(en)

Habillages(en)

Mots magiques(en)

API(en)

Chaque extension est normalement composée de 3 parties :

• la configuration
• l'exécution
• l'internationalisation

Organisation interne d'une extension

L'organisation interne d'une extension a changé au cours du temps. Initialement, elles étaient composées d'un seul fichier. Lorsque MediaWiki a évolué, cette organisation est devenue obselète. Au lieu de ceci, l'extension est généralement placée dans un dossier contenant un ou plusieurs fichiers correspodant aux trois parties : configuration, exécution et internationalisation.

• myextension/myextension.php - contient les instruction de configuration. (Note: Le fichier peut aussi s'appeler myextension/myextension.setup.php)

• myextension/myextension.body.php - contient le code d'exécution pour une extension simple. Pour des extensions plus complexes, il peut y avoir plusieurs fichiers et être placé dans un sous dossier nommé myextension/includes. Par exemple, voir Semantic MediaWiki

• myextension/myextension.i18n.php - contient l'internationalisation de l'extension

Écrire les instructions de configuration

Le but est d'écrire un fichier pour qu'ensuite l'utilisateur n'ait plus qu'à inclure celui-ci dans LocalSettings.php, comme ceci :

require_once( "$IP/extensions/myextension/myextension.php" );

Si vous voulez que votre extension soit configurable, vous devez définir et documenter quelques paramètres de configuration et l'utilisateur devrait avoir à écrire quelque chose comme ceci : (remplacer XXX par myextension)

$wgXXXConfigCeci=1;
$wgXXXConfigCela=false;
require_once( "$IP/extensions/XXX/XXX.php" );

Pour avoir cette simplicité, suivez ces instructions :

• définissez et/ou déclarez chaque paramètre de configuration ajouté par l'extension.
• préparez les classes pour le chargement automatique.
• déterminez les parties de la configuration qui doivent être exécutées immédiatement ou un peu plus tard après que le coeur de MediaWiki se soit initialisé et configuré.
• enregistrez chaque page spéciale, tag XML, fonction du parseur et variable utilisé par l'extension
• définissez les hooks (crochets) nécessaires pour votre extension.
• configuration et ajout du fichier d'internationalisation.

Faire une extension configurable

Si vous voulez que l'utilisateur puisse configurer l'extension, vous devrez donner une ou plusieurs variables de configuration. Il est généralement bien que ces variables aient un nom unique. Elles devraient également suivre les conventions de nommage de MediaWiki (par exemple les variables devraient commencer par $wg)

Par exemple, si votre extension est nommée "Simple extension qui ne fait rien", vous pourriez faire commencer le nom de chaque variable de configuration par $wgSeqnfr ou $wgSEQNFR. Il n'est généralement pas bien de prendre un nom d'une variable qui n'existe pas dans MediaWiki sans préfixe car une autre extension pourrait aussi l'utiliser. Il ne faut pas que l'utilisateur soit obligé de choisir entre deux extensions qui ne marchent pas ensemble à cause d'utiliser une variable du même nom.

Il est recommandé d'inclure une documentation sur l'utilisation de ces variables de configuration dans le documentation de l'extension.

Préparer les classes pour le chargement automatique

Si vous choisissez d'utiliser des classes pour votre extension, MediaWiki contient un mécanisme simplifié pour charger automatiquement le fichier source d'une classe quand celle-ci est requise. Dans la plupart des cas, cela doit vous éviter de devoir écrire votre propre méthode __autoload($classname).

Pour utiliser ce mécanisme, vous devez ajouter une entrée à la variable $wgAutoloadClasses. La clé du tableau doit être le nom de la classe et la valeur associée le fichier qui contient le code de cette classe. Ainsi par exemple (l'extension est nommée Foobar):

$wgAutoloadClasses['Foobar'] = dirname(__FILE__) . '/Foobar.body.php';

.

Pour des extensions complexes, quand il y a plusieurs fichiers :

$wgFoobarIncludes = dirname(__FILE__) . '/includes/';
$wgAutoloadClasses['SpecialFoobar'] 
  = $wgFoobarIncludes . 'SpecialFoobar.php'; #implémente la page spéciale
$wgAutoloadClasses['FoobarTag']
  = $wgFoobarIncludes . 'FoobarTag.php';   #implémente le tag <foobar>

Enregistrer l'extension

MediaWiki liste toutes les extensions qui sont installées sur la page Special:Version. Par exemple, vous pouvez voir toutes les extension utilisées ici sur Special:Version. C'est également bien d'être sur que toutes les extensions sont listées sur cette page. Pour ceci, vous pouvez ajouter une entrée à $wgExtensionCredits pour chaque page spéciale, tag XML, fonction du parseur ou variable. L'entrée peut être ajoutée de la manière suivante :

   $wgExtensionCredits['validextensionclass'][] = array(
       'name' => 'Example',
       'author' =>'John Doe', 
       'url' => 'http://www.mediawiki.org/wiki/User:JDoe', 
       'description' => 'This Extension is an example and performs no discernable function'
       );

validextensionclass doit être specialpage, parserhook, variable, other, comme spécifié sur Manual:$wgExtensionCredits.

En plus de l'enregistrement ci-dessus, chaque "hook" utilisé est également répertorié sur cette page. Pour des détails, voir la documentation spécifique à chaque type d'extension :

• Manual:Special pages
• Manual:Variable
• Manual:Parser functions
• Manual:Tag extensions

Retarder la configuration

LocalSettings.php est exécuté assez tôt dans le processus de MediaWiki et beaucoup de choses ne sont pas encore configurées. Ceci peut être un problème pour certaines extensions. MediaWiki laisse une chance pour executer les instructions avant ou après la configuration.

Pour pouvoir exécuter certaines commandes après la configuration de MediaWiki, il faut le faire en deux phases :

• définir une fonction de configuration
• la déclarer dans $wgExtensionFunctions pour qu'elle soit exécutée à la fin du processus de configuration.

Le code PHP devrait ressembler à ceci :

$wgExtensionFunctions[]='efFoobarSetup';
function efFoobarSetup() {
   #ici le code qui doit être exécuté à la fin
}

Écrire la partie d'exécution de l'extension

La technique d'écriture dépend de la partie de MediaWiki que vous voulez étendre :

• Wiki-syntaxe: Extensions qui étendent la syntaxe en ajoutant des tags XML, fonctions du parseur et variables. Cliquez sur les liens pour plus d'informations.
• Informations et administration: Extensions qui ajoutent une page spéciale pour l'administration et des informations. Pour plus d'informations, voir Manual:Special pages.
• Article automation and integrity: Extensions qui facilitent ou modifient l'intégration entre MediaWiki et la base de données. Ces extensions vont utiliser des hooks pour modifier le comportement lors de la création, modification, renommage et suppression d'articles. Voir Manual:Hooks pour plus d'informations.
• Apparence: Extensions qui modifient l'apparence avec des skins. Voir Manual:Skin et Manual:Skinning pour plus d'informations.
• Sécurité: Extensions qui limitent leur utilisation (ou celle du wiki) à certains utilisateur avec les permissions adéquates. Voir Manual:Preventing access pour plus d'informations. Certaines extensions utilisent un système externe d'autentifications, voir AuthPlugin. Pour celle qui limitent la lecture du wiki à certains groupes, voir Security issues with authorization extensions.

Voir aussi Extensions FAQ et Developer hub/fr

Internationaliser votre extension

Si vous voulez utiliser votre extension sur des wikis qui sont utilisés en plusieurs langues, il faut internationaliser l'extension. Ceci est assez simple à faire.

1. Pour chaque chaine renvoyée à l'utilisateur, définissez un message. MediaWiki supporte des paramètres dans les messages et doit être utilisé quand le message dépend de la valeur à l'exécution. Toujours utiliser un nom en minuscules.
2. Dans la configuration et l'implémentation, remplacer ces chaines par wfMsg($msgID, $param1, $param2, ...).
3. Mettre les messages dans le fichier d'internationalisation (myextension.i18n.php) . Ceci est généralement fait avec un tableau à deux dimensions dont la première clé est la langue et la seconde le nom du message, la valeur est le texte du message.

   <?php
   $allMessages = array(
   	'en' => array(
   		'sillysentence' => 'This sentence says nothing',
   		'answertoeverything' => 'Forty-two'
   	), 
   	'fr' => array(
   		'sillysentence' => 'Une phrase absurde',
   		'answertoeverything' => 'quarante-deux'
   	)
   );
   ?>
   

4. Dans la fonction de configuration, il faut les ajouter dans le coeur de MediaWiki. Ceci est généralement fait en incluant le fichier de localisation, naviguer dans le tableau et l'ajouter avec $wgMessageCache->addMesssages($aMessages, $lang) :

   require( dirname( __FILE__ ) . '/XXX.i18n.php' );
   foreach ( $allMessages as $lang => $langMessages ) {
       $wgMessageCache->addMessages( $langMessages, $lang );
   }
   

Pour plus d'informations, voir:

• Internationalisation
• Localization checks

Publier votre extension

Pour catégoriser et documenter votre extension, voyez Template:Extension. Pour ajouter votre extension sur ce wiki : Veuillez remplacer "MyExtension" avec le nom de l'extension (suivi de /fr pour la version française) :

MediaWiki est un projet open-source et les utilisateurs sont encouragés à faire leurs extensions MediaWiki^(en) sous une licence compatible approuvée GPLv2 Open Source Initiative (OSI) (y compris MIT, BSD, PD). Pour les extensions qui ont une licence compatible, vous pouvez demander un accès développeur^(en) sur les bases de connaissance MediaWiki pour les sources des extensions et obtenir un nouveau répertoire créé à votre attension. Vous pouvez aussi poster votre code directement sur la page de votre extension, bien que ce ne soit pas la méthode préférable.

Un développeur qui partage son code sur le wiki MediaWiki ou sur la base de connaissances des codes devrait s'attendre à :

Retour / Critique / Revues de code

Les revues et commentaires faits par d'autres développeurs sur des point comme l'utilisation de la structure, la sécurité, l'efficacité et l'utilité.

Ajustement de la part de développeurs

D'autres développeurs modifiant votre soumission afin de l'améliorer ou faire du nettoyage dans votre code pour qu'il satisfasse aux nouvelles méthodes et classes de structure, aux conventions de codage et aux traductions.

Accès amélioré pour les admins système des wiki

Si vous décidez de mettre votre code sur le wiki, un autre développeur peut décider de le déplacer vers la base de connaissance de code MediaWiki pour une maintenance plus facile. Vous pouvez alors demander un accès commit pour continuer à le maintenir.

Versions futures faites par d'autres développeurs

De nouvelles branches de votre codes créées par d'autres développeurs en tant que nouvelles versions de MediaWiki peuvent être publiées. Avec l'intégration de votre code dans d'autres extensions qui ont un objectif identique ou similaire - incorporant les meilleurs fonctionnalités de chaque extension.

Crédit

Le crédit de votre travail sera préservé dans les versions futures - y compris les extensions intégrées dans d'autres.

De même vous devriez créditer les développeurs de toute extension où vous avez emprunté du code - particulièrement lorsque vous effectuez une intégration.

Tout développeur qui ne se sent pas à l'aide quant à l'une de ces actions ne devrait pas héberger son code directement sur le wiki MediaWiki ou dans la base de connaissance. Vous êtes malgré tout encouragé à créer une page de résumé pour votre extension sur le wiki afin de permettre aux gens de connaître l'extension et qu'ils sachent où la télécharger. Vous pouvez aussi ajouter le modèle {{Extension exception}} sur votre extension afin de demander aux autres développeurs d'éviter de modifier votre code, bien qu'aucune garantie ne peut être donnée qu'une mise à jour ne soit pas faite si elle était nécessaire pour des raisons de sécurité et de compatibilité. Vous pouvez utiliser la page des problèmes courants si vous pensez qu'un autre développeur a violé l'esprit de ces application en éditant votre extension.

Techniques d'extension

Les extensions peuvent être catégorisées selon la technique utilisée. La plupart des extensions peuvent utiliser plusieurs techniques :

• Subclassing: Certaines extensions peuvent être des sous-classes de certaines classes de base de MediaWiki :
  • Pages spéciales - Sous-classes de SpecialPage pour générer du contenu qui est créé dynamiquement selon l'état du système, des paramètres donnés et requêtes sur la base de données. Elles peuvent être utilisées pour l'administration et l'information.
  • Skins - Les skins changent l'apparence de MediaWiki en modifiant le code qui génère la page en étant une sous-clase de SkinTemplate.
• Hooks: Une technique pour injecter un code PHP pendant l'exécution normale de MediaWiki. Elles peuvent être utilisées par le parseur, l'internationalisation et la maintenance.
• Tags - Tag du style XML qui sont associés à une fonction qui renvoie un code HTML. Le texte peut être formaté de n'importe quelle manière à l'intérieur et n'a pas besoin d'être affiché. Ces tags peuvent être utilisés pour générer du HTML qui contient des objets google, des formulaires, des flux RSS, ...
• Mots magiques: Une technique pour modifier des chaines de wiki-texte en association avec une fonction. Et les variables et les fonctions du parseur utilisent cette technique. Tout le texte va être remplacé par la valeur de retour de la fonction. La relation entre la fonction et le mot magique est définie par un tableau donné à une fonction qui utilise le hook LanguageGetMagic. Voir Manual:Magic words pour plus d'informations.
  • Variables - Les variables n'ont pas de paramètres et retournent une valeur fixée d'avance. Des chaines comme {{PAGENAME}} ou {{SITENAME}} sont des exemples de variables.
  • fonctions du parseur - {{functionname: argument 1 | argument 2 | argument 3...}}. Comme un tag mais renvoie du wikitext.