Manual:Developing extensions/fr



Chaque extension se compose de trois parties :


 * 1) Installeur
 * 2) Exécution
 * 3) Emplacement

Une extension minimale se compose de trois fichiers, une pour chaque partie :


 * MyExtension/extension.json: Stocke les instructions de l'installateur. Le nom du fichier doit être "extension.json". (Pour les versions antérieures à MédiaWiki 1.25 les instructions d'installation se trouvent dans un fichier  nommé d'après l'extension. Beaucoup d'extensions ont encore des fonctionnalités rétro-compatibles dans ce fichier PHP.)
 * MyExtension/MyExtension_body.php: Stocke le code d'exécution pour l'extension. Le nom de fichier "MonExtension_body.php" est conventionnel mais non requis. Si votre extension est complexe et implique plusieurs fichiers PHP, vous devez suivre la convention de placer son code d'implémentation dans un sous-répertoire nommé  (bien que l'extension Exemple ne suive pas cette convention). Par exemple, regardez l'extension SemanticMediaWiki
 * MyExtension/i18n/*.json: Stocke l'information d'emplacement de l'extension.

Lorsque vous développez une extension, remplacez "MyExtension" ci-dessus par le nom de votre extension. Utilisez les noms UpperCamelCase pour son répertoire et son/ses fichiers PHP; ce sont les conventions générales de nommage des fichiers. (l' est un bon point d'entrée pour commencer les entensions. Vous pouvez aussi prendre en compte l'utilisation de MWStew pour le génération de votre extension boilerplate. Voir aussi le modèle cookiecutter pour les extensions MediaWiki sur GitHub).

Les trois parties d'une extension, la configuration, l'exécution, et l'internationalisation tout comme les types d'extensions, la licence et la publication de votre extension sont décrits dans les sections suivantes de cette page.

Configuration
Votre but en écrivant la partie de configuration est de consolider l'initialisation des paramètres pour que les utilisateurs qui installent votre extension n'aient rien à faire d'autre que d'inclure le fichier de configuration dans leur fichier, comme cela :

Si vous voulez rendre votre extension configurable par l'utilisateur, vous devez définir et documenter certains paramètres de configuration et le setup utilisateur devrait ressembler à ceci :

Pour atteindre cette simplicité, votre fichier setup doit effectuer un certain nombre de tâches (décrites en détails dans les sections suivantes) :


 * enregistrer tout pilote de média, fonction d'analyseur, page spéciale, balise XML personnalisée, et la variable utilisée par votre extension.
 * définir et/ou valider toutes les variables de configuration que vous avez définies pour votre extension.
 * préparer les classes utilisées par votre extension pour l'auto-chargement
 * déterminer quelles parties de votre installation doivent être faites immédiatement et quelles autres doivent être reportées après que le coeur de MediaWiki ait été initialisé et configuré.
 * définir toutes les accroches supplémentaires nécessaires à votre extension
 * créer ou vérifier toutes les nouvelles tables de la base de données, nécessaires à votre extension.
 * configurer l'internationalisation de votre extension

Enregistrement des fonctionalités avec MediaWiki
MediaWiki liste toutes les extensions qui ont été installées sur sa page de. A titre d'exemple, vous pouvez voir toutes les extensions installées sur ce wiki en Special:Version. Il est de bon ton de vérifier que votre extension est aussi affichée sur cette page. Pour faire cela, vous devrez ajouter une entrée à pour chaque pilote de média, fonction d'analyseur, page spéciale, balise XML personnalisée, et variable utilisée par votre extension. L'entrée ressemblera à quelque chose comme ceci :

Voir pour les détails complets de la signification de ces champs. Beaucoup de ces champs sont optionnels, mais il est encore bon de les remplir. La  fait référence à la version du schéma pour lequel le fichier  est écrit. Jusqu'à présent (janvier 2018) les versions disponibles sont la 1 et la 2. Voir ici pour la documentation concernant cette fonction.

En plus de l'enregistrement ci-dessus, vous devez également définir les accroches de votre fonction dans MediaWiki. Ce qui figure ci-dessus ne configure que la page Special:Version. La manière dont vous faites cela dépend du type de votre extension. Pour les détails, voyez la documentation de chaque type d'extension :

Rendre votre extension configurable par l'utilisateur
Si vous voulez que l'utilisateur puisse configurer votre extension, vous devrez fournir une ou plusieurs variables de configuration. C'est une bonne idée que de donner à ces variables un nom unique. Elles devront aussi suivre les conventions de nommage de MediaWiki (par exemple les variables globales doivent commencer par $wg).

Par exemple, si votre extension s'appelle "Very silly extension that does nothing", vous pourriez vouloir que le nom de vos variables de configuration commence par  ou. Ce que vous choisissez n'a réellement pas d'importance tant que personne du coeur de MediaWiki ne commence ses variables de cette manière et vous avez fait un travail raisonnable en vérifiant que personne parmi les extensions publiées n'avait fait commencer ses variables de la sorte. Les utilisateurs n'hésiteront pas à choisir entre votre extension et d'autres extensions car vous avez choisi des noms de variables qui se chevauchent.

Une bonne idée aussi est d'inclure la documentation détaillée de toutes les variables de configuration dans vos informations d'installation.

Voici un exemple de boiler plate qui peut être utilisé pour commencer :

Remarquez que après l'appel à  la variable globale   n'existe pas. Si vous initialisez la variable, par exemple dans  alors la valeur donnée dans ne sera pas utilisée.

Préparer des classes pour l'auto-chargement
Si vous choisissez des classes pour implémenter votre extension, Mediawiki fournit un mécanisme simplifié pour aider PHP à trouver le fichier source dans lequel se trouve votre classe. Dans la plupart des cas cela évite d'écrire votre propore méthode d'.

Pour utiliser le mécanisme d'auto-chargement de MediaWiki, ajoutez les entrées dan sle champ. La clé de chaque entrée est le nom de la classe; la valeur est le fichier qui héberge la définition de la classe. Pour une extension simple ne comportant qu'une seule classe, on donne souvent à la classe le nom de l'extension et donc la section d'auto-chargement pourrait ressembler à ceci (avec une extension appelée MyExtension):

Le nom de fichier est relatif au répertoire dans lequel se trouve le fichier extension.json.

Définir des accroches supplémentaires
Voir.

Ajouter des tables dans la base de données
Si votre extension a besoin d'ajouter ses propres tables de base de données, utilisez l'accroche. Voir la page du manuel pour davantage d'informations sur l'utilisation.

Configurer l'internationalisation
Voir:
 * Internationalisation (sommaire)
 * Internationalisation (détaillé)
 * Namespaces

Ajouter des journaux
Sur MediaWiki, toutes les actions des utilisateurs sur le wiki sont tracées pour la transparence et la collaboration. Voir pour savoir comment le faire.

Execution
La technique pour l'écriture de la portion d'implémentation dépend de la partie du système Mediawiki que vous souhaitez étendre :
 * Balisage Wiki : Les extensions qui étendent le marquage du wiki contiendront typiquement du code qui definit et implémente les balises XML personnalisées, les fonctions d'analyseur et les variables.
 * Rapports et administration : Les extensions qui ajoutent des rapports et des possibilités administratives habituellement le font en ajoutant des pages spéciales. Pour davantage d'informations, voir.
 * Automatisation des articles et intégrité : Les extensions qui améliorent l'intégration entre MediaWiki et sa base de données arrière, ou qui vérifient les acticles pour les fonctions d'intégrité, vont typiquement ajouter des fonctions à l'une des multiples accroches qui concernent les processus de création, de modification, de renommage, et de la supression des articles. Pour plus d'informations concernant ces accroches et sur la manière d'y attacher votre code, veuillez voir.
 * Habillage et convivialité : Les extensions qui apportent un nouvel aspect et comportement à MediaWiki sont embarquées dans les skins. Pour davantage d'information sur la manière d'écrire vos propres habillages, voir et.
 * Sécurité: Les extensions qui limitent leur utilisation à certains utilisateurs doivent s'intégrer au système des droits propre à MediaWiki. Pour en connaître plus sur ce système, veuillez voir . Certaines extensions aussi laissent Mediawiki utiliser des mécanismes d'autentification externes. Pour davantage d'informations, voir . De plus, si votre extension tente de limiter le nombre de lecteurs de certains articles, veuillez consulter les pièges décrits dans.

Voir aussi ,

Localisation
Si vous voulez que votre extension soit utilisable sur les wikis qui ont des lecteurs en plusieurs langues, vous devez ajouter une prise en charge de l'internationalisation à votre extension.

Enregistrer les messages dans .json
Enregistrer les définitions de messages dans un fichier d'internationalisation JSON, un par clé de langue dans laquelle votre extension a été traduite. Les messages sont enregistrés avec une clé de message et le message lui-même, en utilisant le format standard JSON. Chaque identifiant de message doit être en minuscules et ne doit pas contenir d'espaces. Un exemple que vous pouvez trouver par exemple dans l'extension MobileFrontend. Voici un exemple de fichier JSON minimal (dans ce cas en.json:

en.json

Enregistrer la documentation des messages dans qqq.json
La documentation concernant les clés des messages peut être mise dans le fichier JSON pour le pseudo language avec le code qqq. Une documentation de l'exemple ci-dessus peut-être :

qqq.json:

Definir des messages

 * Attribuez à chaque message un identificateur de message unique, en minuscules, et sans espaces ; par exemple :uploadwizard-desc
 * Pour toute chaîne de caractères à afficher à l'utilisateur, veuillez définir un message.
 * MediaWiki supporte les messages paramètrés et cette fonction doit être utilisée quand un message dépend des informations générées au moment de l'exécution. Les paramètres de substitution sont spécifiés par $n, où n représente l'index du paramètre; par exemple

Définir la documentation du message
Chaque message que vous définissez doit avoir une entrée de documentation du message associée Message documentation; dans qqq.json par exemple

Charger le fichier d'internationalisation
Dans votre routine d'installation, définissez l'emplacement de vos fichiers de messages (par exemple dans le répertoire i18n/):

Utilisation de wfMessage dans PHP
Dans votre code d'installation et d'implémentation, remplacez chaque utilisation littérale du message par un appel à. Dans les classes qui implémentent (tout comme dans quelques autres telles que les sous-classes de SpecialPage), vous pouvez utiliser   à la place. Exemple:

Utiliser mw.message sous JavaScript
Il est aussi possible d'utiliser les fonctions i18n dans JavaScript. Voir pour les détails.

Types d'extensions
Les extensions peuvent être catégorisées sur la base des techniques de programmation utilisées pour implémenter leurs actions. Les extensions les plus complexes utilisent plus d'une des techniques suivantes :
 * Sous-classement: MediaWiki s'attend à ce que certains types d'extensions soient implémentés en tant que sous-classes d'une classe de base fournie par MediaWiki:
 *  – Les sous-classes de la classe sont utilisées pour construire des pages dont le contenu est généré dynamiquement en utilisant une combinaison de l'état actuel du système, des paramètres d'entrée de l'utilisateur, et des requêtes à la base de données. A la fois, des rapports et des formulaires de saisie de données peuvent être générés. Ils sont utilisés à la fois pour des raisons statistiques et administratives.
 *  – Les habillages modifient l'aspect et le comportement de Mediawiki en modifiant le code qui génère les pages en sous-classant la classe Mediawiki.
 *  – Une technique pout injecter du code php personnalisé aux points-clés du traitement MediaWiki. Elles sont largement utilisées par l'analyseur de MediaWiki, son moteur d'internationalisation, son système de gestion des extensions, et son système de maintenance des pages.
 *  – Balises de style XML qui sont associées à une fonction PHP génèrant du code HTML. Vous n'avez pas besoin de vous limiter au formatage du texte à l'intérieur des balises. Vous n'avez même pas besoin de l'afficher. Plusieurs extensions de balises utilisent le texte comme paramètre ce qui guide la génération du HTML pour inclure les objets Google, les formulaires d'entrée de données, les flux RSS, et les extraits des articles wiki sélectionnés.
 *  – Une technique pour faire correspondre une variété de chaînes de caractères wiki à un ID unique qui est lié à une fonction. A la fois les variables et les fonctions analyseur utilisent cette technique. Tout texte associé à cet identifiant sera remplacé par la valeur retournée par la fonction. La correspondance entre les chaînes de texte et l'identifiant est stockée dans le tableau $magicWords. L'interprétation de l'identifiant est un processus un peu plus complexe – voir  pour plus d'information.
 *  – Les variables sont quelque part comme un abus de langage. Il existe des morceaux de texte wiki qui ressemblent à des modèles mais qui n'ont pas de paramètre et qui ont reçu des valeurs en dur. Le marquage standard de wiki tel que ou  sont des exemples de variables. ils tirent leur nom du source de leur valeur: une variable PHP ou quelque chose qui pourrait être assigné à une variable, par exemple une chaîne, un nombre, une expression, ou la valeur de retour d'une fonction.
 *  – .  De même manière que les extensions de balises, les fonctions d'analyseur traitent les paramètres et retournent une valeur. A l'inverse des extensions de balises, le résultat des fonctions d'analyseur est du texte wiki.
 *  – vous pouvez ajouter des modules personnalisés à l'API d'action de MediaWiki, appelables par JavaScript, les robots ou les clients tiers.
 *  – If you need to store data in formats other than wikitext, JSON, etc. then you can create a new.

Support des autres versions du coeur
Il existe deux conventions largement répandues pour supporter les versions plus anciennes du coeur MediaWiki :

La maintenance de l'extension doit déclarer avec le paramètre de  du modèle de l'extension quelle convention elle suit.
 * Maître: la branche maître (master branch) de l'extension est compatible avec autant d'anciennnes versions du coeur que possible. Ceci résulte en un fardeau de maintenance (les développements à compatibilité ascendante doivent être conservés longtemps, et les modifications de l'extension doivent être testées avec plusieurs versions de MediaWiki), mais les sites qui utilisent les anciennes versions de MediaWiki bénéficient des fonctions ajoutées récemment par l'extension.
 * Branches de version: les branches de version (release branches) de l'extension sont compatibles avec les branches correspondantes du coeur, c'est à dire que les sites qui utilisent MediaWiki doivent utiliser la branche  de l'extension. (Pour les extensions hébergées sous gerrit, ces branches sont automatiquement créées quand les nouvelles versions de MediaWiki sont diffusées.) Ceci résulte dans un code plus propre et un développement plus rapide mais les utilisateurs sur les versions anciennes des coeurs ne bénéficient pas des correstions de bogues et des nouvelles fonctions à moins qu'elles ne soient rétro-reportées manuellement.

Publication
Pour autocatégoriser et pour standardiser la documentation de votre extension existante, veuillez voir. Pour ajouter votre nouvelle extension à ce Wiki:

Deploiement et enregistrement
Si vous pensez déployer votre extension sur les sites Wikimedia (en incluant éventuellement Wikipedia), un examen supplémentaire est justifié en termes de performances et de sécurité. Consulter.

Si votre extension ajoute des espaces de noms, vous pouvez enregistrer ses espaces de noms par défaut; de manière équivalente, si elle ajoute des tables de bases de données ou des champs, vous pouvez les enregistrer sur.

Veuillez être conscient que la relecture et le déploiement des nouvelles extensions sur les sites Wikimedia peuvent être extrêmement lents, et dans certains cas ont pris plus de deux ans.

Documentation d'aide
Vous devez fournir la documentation d'aide dans le domaine publique pour les fonctions offertes par votre extension. est un bon exemple. Vous devez donner aux utilisateurs un lien vers la documentation à l'aide de la fonction.

Fournir du support / collaborer
Les développeurs d'extensions doivent ouvrir un compte sur de Wikimedia, et demander un nouveau projet pour l'extension. Cela fournit un espace public où les utilisateurs peuvent soumettre les problèmes et les suggestions, et vous pouvez collaborer avec les utilisateurs et les autres développeurs pour trier les bogues et planifier les fonctionnalités de votre extension.

Voir aussi

 * – implémente quelques exemples de fonctionnalités avec une documentation en ligne complète
 * – une extension Boilerplate fonctionnelle, utile comme point de départ pour votre propre extension
 * Lisez l'extension Example, basez votre propre code sur l'extension BoilerPlate.
 * cookiecutter-mediawiki-extension – un modèle pour l'outil python cookiecutter pour générer une extension standard (avec variables, etc.)
 * Vous permet d'avancer rapidement avec votre propre extension. Peut aussi générer l'extension BoilerPlate.
 * - copier le code spécifique à partir d'eux
 * – explique comment votre extension peut fournir une API aux clients
 * Meilleures pratiques pour les extensions
 * Meilleures pratiques pour les extensions
 * Meilleures pratiques pour les extensions
 * Meilleures pratiques pour les extensions
 * Meilleures pratiques pour les extensions