Extension:TemplateData

**Manuel des extensions MediaWiki**
TemplateData; État de la version : stable
Implémentation	Balise, API
Description	Permet d'enregistrer, de retrouver et de visualiser des informations à propos des templates
Auteur(s)	Timo Tijhof, Moriel Schottlender, James Forrester, Trevor Parscal, Bartosz Dziewoński, Marielle Volz, ...
Dernière version	0.1.2 (Mises à jour constantes)
Politique de compatibilité	Versions ponctuelles alignées avec MediaWiki. Le master n'est pas compatible arrière.
MediaWiki	>= 1.43
PHP	5.4+
Modifie la base; de données	Non
Licence	Licence publique générale GNU v2.0 ou supérieur
Téléchargement	Télécharger l'extension ; Git [?]: Télécharger la branche master de Git; parcourir le dépôt (Phabricator · GitHub); historique des validations (commits); contributeurs du dépôt (GitHub); relecture du code;
	Paramètres $wgTemplateDataUseGUI;
	Balises ‎<templatedata>
	Accroches utilisées EditPage::showEditForm:fields; EditPage::showEditForm:initial; MultiContentSave; OutputPageBeforeHTML; ParserFetchTemplateData; ParserFirstCallInit; ResourceLoaderRegisterModules;
Téléchargements trimestriels	277 (Ranked 19th)
Utilisé par les wikis publics	6,971 (Ranked 24th)
	Traduire l’extension TemplateData sur translatewiki.net si elle y est disponible
Problèmes	Tâches ouvertes · Signaler un bogue

This page is a translated version of the page Extension:TemplateData and the translation is 100% complete.

Cette extension est fournie avec MediaWiki 1.35 et supérieur. Ainsi vous n'avez pas besoin de télécharger à nouveau. Néanmoins, vous devez encore suivre les autres instructions fournies.

L'extension TemplateData introduit une balise ‎<templatedata> et une API qui ensemble permettent aux contributeurs de spécifier comment les modèles et leurs paramètres doivent être utilisés. Cette information est disponible sous forme de table synthétique bien formatée pour les utilisateurs finaux, et sous forme d'API JSON permettant aux autres systèmes (comme VisualEditor ) de construire des interfaces pour travailler avec les modèles. Voir Aide:TemplateData pour une aide plus approfondie.

Installation

Téléchargez et placez le(s) fichier(s) dans un répertoire appelé TemplateData dans votre dossier extensions/.
Les développeurs et les contributeurs au code doivent à la place installer l'extension à partir de Git en utilisant:cd extensions/ git clone https://gerrit.wikimedia.org/r/mediawiki/extensions/TemplateData
Ajoutez le code suivant à la fin de votre fichier LocalSettings.php :
```
wfLoadExtension( 'TemplateData' );
```
Fait – Accédez à Special:Version sur votre wiki pour vérifier que l'extension a bien été installée.

Modification des données

L'extension TemplateData fonctionne grâce à une balise ‎<templatedata> définie dans le wikicode d'une page de modèle (en option, il peut être transclus à partir d'une page différente également). Il est conçu pour être compatible avec l'affichage commun que beaucoup de wikis utilisent, en faisant la transclusion de la documentation du modèle à partir d'une page séparée (mais ceci n'est pas nécessaire). Le contenu de cette balise ‎<templatedata> doit être du JSON valide qui utilise le format décrit ci-dessous; notez que toutes les descriptions doivent être en texte brut (il n'est pas permis de mettre du wikicode à l'intérieur des données du modèle).

Quand un bloc ‎<templatedata> est inclus dans une page, l'extension TemplateData réalise les contrôles suivants lorsque la page est sauvegardée :

Le contenu doit être du JSON valide;
Chaque élément de la structure JSON doit être du type attendu tel que spécifié ci-dessous (c'est à dire un objet, un tableau, ou une primitive); et
pour les éléments qui ont une liste spécifique de valeurs possibles (par exemple : le type d'un paramètre), la valeur dans l'objet JSON doit correspondre à l'une de ces valeurs.

Dès qu'un de ces contrôles échoue, le serveur n'est pas autorisé à sauvegarder et un message d'erreur est affiché au-dessus de la page de modification.

Pour les éléments à valeur automatique (autovalue), T4700 empêche subst: de travailler dans tout modèle ajouté à l'intérieur d'une balise, y compris les balises ‎<ref> et ‎<gallery>. Le bloc TemplateData s'enregistre bien mais le wikicode résultant ne sera pas analysé correctement lorsque le modèle sera utilisé.

Evitez d'utiliser {{#tag:templatedata}} car il empêche le fonctionnement de l'éditeur de données du modèle.

Format

Ci-dessous vous avez une version visualisée des données JSON telle qu'elles sont définies sur la page du modèle entourées des balises ‎<templatedata>‎</templatedata>. La spécification du format est disponible dans le dépôt TemplateData . Référez-vous à Specification.md pour la dernière version.

Objet TemplateData

L'objet TemplateData est un élément racine JSON encapsulé dans un élément ‎<templatedata> sur la page du modèle.

Clé	Type	Description
`description`	InterfaceText ou `null`	Une brève description du modèle. Ceci doit être du texte brut. Une fois rempli, ce texte peut être affiché comme légende lorsque vous modifiez un modèle unique et peut se trouver dans les résultats de recherche lorsque vous en sélectionnez un parmis plusieurs. La valeur par défaut est `null`. → For more details see: description
`params`	Objet contenant des objets Param	Un objet qui fait correspondre chaque nom de paramètre du modèle à son objet Param associé; celui-ci décrivant les propriétés du paramètre. → For more details see: params
`paramOrder`	Tableau de chaînes des noms de paramètre	Ordre logique dans lequel les paramètres doivent être affichés. Tableau de clés uniques des paramètres. Chaque chaîne doit être une clé valide dans l'objet `params`. → For more details see: paramOrder
`sets`	Tableau d' objets Set	Un tableau contenant les spécifications des ensembles (set). Un ensemble est un groupe de paramètres devant être utilisés en même temps. La valeur par défault est []. Notez que la fonctionnalité `sets` est encore en développement.
`format`	chaîne, soit `inline` ou `block`	Indique comment sera présenté le wikicode. La valeur par défaut est `inline`. Voir les formats personnalisés pour les autres formats.
`maps`	Objet contenant des objets Maps	Un objet qui fait correspondre le nom simplifié d'un consommateur-tiers des données du modèle (par exemple Citoid, Special:MyLanguage/Wikidata, etc.), à un objet qui associe à son tour le nom d'un paramètre de consommateur à un ou plusieurs noms correspondant de paramètres du modèle.

Objet Param

Clé Type Valeur par défaut Description

label

InterfaceText

null

Un nom (très) court pour le paramètre. Essayez de rester en-dessous de 20 caractères.

→ For more details see: label

description

InterfaceText

null

Une brève description du paramètre, pour que les utilisateurs sachent lequel choisir dans une liste d'options.

→ For more details see: description

required

booléen

false

Indique si le paramètre est nécessaire pour que le modèle fonctionne (true si ce paramètre doit être spécifié).

→ For more details see: required

suggested

booléen

false

Indique si le paramètre est suggéré pour que le modèle soit utile (true si ce paramètre devrait être spécifié).

→ For more details see: suggested

deprecated

booléen ou chaîne

false

Indique un paramètre obsolète. La valeur peut être une chaîne d'instructions qui renseignent l'utilisateur sur ce qu'il peut faire à la place, ou être simplement true.

→ For more details see: deprecated

aliases

Tableau de chaînes

[]

Liste d'alias. Un alias est un autre nom que l'on attribue au paramètre et que l'on peut utiliser en remplacement (et non pas en plus) du nom initial. Les alias ne sont pas documentés dans un objet Parameter séparé. S'ils ont besoin de plus d'information, leur propre propriété doit être marquée « obsolète ».

→ For more details see: aliases

default

InterfaceText

null

Valeur par défaut utilisée par le modèle si aucune valeur n'est assignée au paramètre, ou sa description.

→ For more details see: default

autovalue

chaîne

null

Une valeur par défaut générée dynamiquement en wikicode, comme par exemple la date du jour ou le nom du contributeur; cela impliquera souvent la substitution du wikicode, comme dans {{subst:CURRENTYEAR}}.

→ For more details see: autovalue

example

InterfaceText

null

Un texte d'exemple pour le paramètre, pour aider les utilisateurs à utiliser la bonne valeur.

→ For more details see: example

type

chaîne

"unknown"

Type de paramètre, pour les indications (logicielles) de type. Une valeur parmis :

Valeur de chaîne	Type de Parameter
"unknown"	Type supposé s'il n'est pas indiqué → For more details see: value ‘unknown’
"number"	Toute valeur numérique (sans le séparateur décimal - point ou virgule - ni celui des milliers) → For more details see: value ‘number’
"string"	Toute valeur textuelle. Peut contenir des passages à la ligne. → For more details see: value ‘string’
"line"	Champ texte court – utilisé pour les noms, les libellés, et autres champs courts de formulaire. Ceci suppose que le texte ne comporte pas de passages à la ligne. → For more details see: value ‘line’
"boolean"	Une valeur booléenne ('1' pour true, '0' pour false et '' pour inconnue), voir la logique ternaire. → For more details see: value ‘boolean’
"date"	Une date dans le format ISO 8601, par exemple "2014-05-09" ou "2014-05-09T16:01:12Z" → For more details see: value ‘date’
"url"	Une URL, avec son protocole, par exemple "http://www.example.org", "https://example.org", ou "//example.org". → For more details see: value ‘url’
"wiki-page-name"	Un nom de page MediaWiki valide pour le wiki actuel. Ne doit pas exister, mais sinon cela doit être un nom de page valide à créer éventuellement. → For more details see: value ‘wiki-page-name’
"wiki-file-name"	Un nom valide de fichier MediaWiki pour le wiki actuel. Ne doit pas exister, mais sinon cela doit être un nom de fichier valide à téléverser éventuellement. Ne doit pas inclure l'espace de noms (par exemple « Foo.svg » et non pas « File:Foo.svg » ni « Bild:Foo.svg » ). → For more details see: value ‘wiki-file-name’
"wiki-template-name"	Un nom de modèle MediaWiki valide pour le wiki actuel. → For more details see: value ‘wiki-template-name’
"wiki-user-name"	Un nom d'utilisateur MediaWiki valide pour le wiki actuel. Ne doit pas exister, mais sinon cela doit être un nom d'utlisateur à créer éventuellement. Ne doit pas inclure l'espace de noms (par exemple « Foo » mais pas « User:Foo » ni « Usario:Foo » ). → For more details see: value ‘wiki-user-name’
"content"	Contennu de la page en wikicode, tel que le style du texte, les liens, les images, etc. → For more details see: value ‘content’
"unbalanced-wikitext"	Wikicode brut qui ne doit pas être traité comme contenu intègre car il n'est pas appairé (il manque une des deux balises) – c'est le cas par exemple, des modèles qui concatènent des morceaux de wikicode pour en faire un plus gros, tel que `{{echo\|before=<u>\|after=</u>}}` → For more details see: value ‘unbalanced-wikitext’

→ For more details see: type

inherits

chaîne

aucun
substitué

La clé du nom d'un autre paramètre (doit être une clé valide dans l'objet params). L'objet Parameter actuel va hériter des propriétés de l'objet Parameter spécifié, et les propriétés locales viendront réécraser les propriétés héritées.

→ For more details see: inherits

suggestedvalues

Tableau de chaînes de caractères

[]

Propriété optionnelle de paramètre. Crée une liste de valeurs de paramètres pour aider les utilisateurs à sélectionner la valeur souhaitée. Pour que les valeurs suggérées soient affichées sous forme de liste déroulante dans l'Editeur Visuel, le type du paramètre doit être l'une des valeurs suivantes : content (contenu), line (ligne), string (chaîne de caractères), number (nombre), unknown (inconnu) ou unbalanced wikitext (wikicode non fermé).

→ For more details see: suggestedvalues

Objet Set

Clé	Objet ou type primitif	Description
`label`	InterfaceText	Un nom (très) court pour le paramètre de type ensemble (set). Essayez de rester en-dessous de 20 caractères.
`params`	tableau de chaînes	Un ou plusieurs noms de paramètres à inclure dans l'ensemble (chacun devant être une clé valide dans l'objet `params`). Un paramètre peut faire partie de plusieurs ensembles. Chaque paramètre n'appartient pas forcément à un ensemble.

Structure de Maps

Maps est une structure de donnée unique qui se décompose en plusieurs sous-niveaux. Le second niveau est communément appelé un objet map.

Clé	Type	Valeur par défaut	Description
nom du consommateur	objet	{}	Un objet qui fait correspondre un nom de consommateur à un objet map qui à son tour fait correspondre un nom de paramètre consommateur, à un ou plusieurs noms de paramètres de modèle correspondant. Les noms des paramètres du modèle peuvent être écrits soit comme une chaîne (un nom), soit un tableau de chaînes (plusieurs noms), ou soit comme un tableau de tableaux de chaînes (plusieurs ensembles de noms); chacune de ces chaînes doit être une clé valide dans l'objet `params` n'importe où dans le même TemplateData du modèle. Un paramètre de modèle spécifique peut figurer dans plusieurs tables de correspondance, et peut être utilisé dans les valeurs de plusieurs clés d'une même table de correspondance, mais tous les paramètres de modèle ne doivent pas forcément être déclarés dans une table de correspondance. Un exemple écourté de Template:Cite_news#TemplateData de la Wikipedia anglophone illustrant la structure des objets map. { "proveit": { "main": "title", "textarea": [ "quote" ] }, "citoid": { "title": "title", "url": "url", "publisher": "publisher", "publicationTitle": "work", "date": "date", "ISSN": [ "issn" ], "ISBN": [ "isbn" ], "contributor": "others", "author": [ [ "first", "last" ], [ "first2", "last2" ], [ "first9", "last9" ] ], "editor": [ [ "editor-first", "editor-last" ] ] } }

InterfaceText (chaîne ou objet)

Une chaîne textuelle brute de format libre (par exemple autre chose que du wikicode ou du HTML), dans la langue du contenu du wiki, ou un objet contenant ces chaînes et pour lequel la clé est le code de langue.

La valeur par défaut pour tous les champs de InterfaceText est null.

Type String

Si c'est une chaîne, elle doit contenir une chaîne non-localisée dans la langue du contenu du wiki local.

Type Object

Si c'est un objet, celui-ci doit faire la correspondance suivante :

Clé	Type	Description
code de langue de Wikipedia	chaîne	Chaîne traduite pour les utilisateurs de cette langue d'interface.

Exemple de correspondance d'objets :

Clé	Valeur
"en"	"Welcome to Wikipedia"
"de"	"Willkommen bei Wikipedia"
"fr"	"Bienvenue sur Wikipédia"
"nl"	"Welkom op Wikipedia"
"it"	"Benvenuti su Wikipedia"
"es"	"Bienvenidos a Wikipedia"
"ru"	"Добро пожаловать в Википедию"

Exemple

Exemple de structure TemplateData telle qu'elle est spécifiée dans le wikicode sur la page du modèle.

<templatedata>
{
    "description": "Label unsigned comments in a conversation.",
    "params": {
        "user": {
            "label": "User's name",
            "type": "wiki-user-name",
            "required": true,
            "description": "User name of person who forgot to sign their comment.",
            "aliases": ["1"]
        },
        "date": {
            "label": "Date",
            "suggested": true,
            "description": {
                "en": "Timestamp of when the comment was posted, in YYYY-MM-DD format."
            },
            "aliases": ["2"],
            "autovalue": "{{subst:#time:Y-m-d}}"
        },
        "year": {
            "label": "Year",
            "type": "number"
        },
        "month": {
            "label": "Month",
            "inherits": "year"
        },
        "day": {
            "label": "Day",
            "inherits": "year"
        },
        "comment": {
            "required": false
        }
    },
    "sets": [
        {
            "label": "Date",
            "params": ["year", "month", "day"]
        }
    ],
    "maps": {
        "ExampleConsumer": {
            "foo": "user",
            "bar": ["year", "month", "day"],
            "quux": [
                "date",
                ["day", "month"],
                ["month", "year"],
                "year"
            ]
        }
    }
}
</templatedata>

Ci-dessous vous trouverez la manière dont l'exemple précédent sera affiché sur la page du modèle :

Label unsigned comments in a conversation.

Template parameters
Parameter		Description	Type	Status
User's name	`user` `1`	User name of person who forgot to sign their comment.	User	required
Date	`date` `2`	Timestamp of when the comment was posted, in YYYY-MM-DD format. Auto value `{{subst:#time:Y-m-d}}`	Unknown	suggested
Year	`year`	no description	Number	optional
Month	`month`	no description	Number	optional
Day	`day`	no description	Number	optional
comment	`comment`	no description	Unknown	optional

API

Voir l'aide générée sur Special:ApiHelp/templatedata. L'appel de cet exemple (formaté pour que ce soit lisible pour un humain) est :

api.php?action=templatedata&titles=Template:Cite%20web&format=json [Essayez !]

Ceci renvoie les données de modèle pour Modèle:Cite web. Le bloc ‎<templatedata>...‎</templatedata> pour ce modèle est sur la page de documentation du modèle transclus, soit fr:Template:Cite web/doc.

Ajouts et modifications du JSON reçu de l'API

La structure JSON fournie dans la réponse à une requête HTTP GET est un peu différente de celle qui est définie dans le bloc ‎<templatedata>...‎</templatedata> . Dans la réponse à la requête vers l'API, l'extension TemplateData fait les modifications suivantes dans l'objet JSON :

Ajoute deux objets encapsulants :
1. Un objet Pages global contenant un ou plusieurs objets Page
2. Un objet avec une clé numérique : un objet Page
Additions/modifications de l'objet TemplateData actuel
1. Ajoute la clé title avec le nom de la page de laquelle les données ont été demandées (par exemple « Template:Cite web »).
2. Ajoute la clé sets
3. Modifie toutes les occurences de TemplateText qui sont simplement des chaînes vers les objets avec une seule clé pour le code de langue Wikipedia actuel
4. Enlève toutes les clés inherits .
  - Ajoute toutes les propriétés du paramètre à partir duquel un héritage est défini, et qui ne sont pas réécrasées par les clés définies explicitement dans l'objet Parameter qui hérite.
5. Ajoute les valeurs par défaut pour toutes les clés dans chaque objet Parameter qui n'a pas été explicitement défini ou hérité.

Différences visuelles dans un objet JSON TemplateData délivré par l'API

Racine JSON
Clé	Type	Description
`pages`	Objet Page	L'objet Page (contient une clé qui est le numéro de la page). Si plusieurs pages ont été demandées en même temps, il y aura plusieurs objets Page .

Object Page
Clé	Type	Description
(numéro de page)	Objet TemplateData	objet TemplateData contenant la charge utile de l'information. La clé est un numéro de page statique pour la page du modèle de laquelle les données JSON ont été demandées.

Objet TemplateData (ajouté par l'API)
La clé suivante est ajoutée à la racine de l'objet JSON qui est encadré dans les balises `‎<templatedata>` de la page du modèle.
Clé	Type	Description
`title`	chaîne	Nom de page du modèle (par exemple « Template:Cite web » ). Cette clé ne se trouve pas dans la structure JSON sde la page du modèle. Elle est ajoutée à la structure par le logiciel MediaWiki dans le but de délivrer via l'API.
`sets`	Tableau d'objets Set	Un tableau contenant les spécifications de l'ensemble. Un ensemble (set) est un groupe de paramètres qui doivent être utilisés ensemble. S'il n'existe pas sur la page du modèle il est ajouté en tant que tableau vide à la structure fournie par l'API.

Objets Parameter de l'API
Clé	Type	Description
`label`	InterfaceText	traduit en objet InterfaceText s'il n'est pas déjà dans ce format.
`required`	booléen	S'il n'est pas défini, la valeur par défaut false est ajoutée.
`description`	InterfaceText ou `null`	S'il est défini en tant que chaîne, il est converti en objet InterfaceText . S'il n'est pas défini, la clé est ajoutée avec une valeur `null` .
`deprecated`	booléen ou chaîne	S'il n'est pas défini, la valeur par défaut false est ajoutée.
`aliases`	tableau de chaînes	S'il n'est pas défini, il reçoit par défaut la valeur d'un tableau vide (c'est à dire [] ).
`default`	chaîne	S'il n'est pas défini, la valeur par défaut assignée est "".
`type`	chaîne	S'il n'est pas défini, la valeur par défaut assignée est "unknown".
`inherits`	(supprimé)	Cette clé est supprimée et toutes les clés héritées sont ajoutées. Les clés définies pour le paramètre actuel prévalent, et toute clé non définie soit pour le paramètre actuel, soit pour l'un de ceux dont il hérite, reçoivent la valeur par défaut.

InterfaceText (objet ou `null`) :
Un objet contenant des chaînes sélectionnées en fonction du code de langue.
Clé	Objet ou type primitif	Description
Objet (contenant des chaînes traductibles en fonction du code de langues Wikipedia) Si un champ TemplateData de la page du modèle contient une chaîne, et non pas un objet avec des chaînes traductibles, MediaWiki la traduit en un objet InterfaceText avec une chaîne assignée au nom de la clé correspondant au code de langue Wikipedia du Wikipedia source. La valeur par défaut pour tous les champs InterfaceText est `null`.
(code en langage Wiki)	chaîne	Chaîne traduite pour les utilisateurs de cette langue d'interface.

Exemple d'objet JSON fourni par l'API

La réponse à une requête API pour la structure TemplateData dans la section Exemple (ci-dessus) peut être vu :

En format HTML : https://www.mediawiki.org/w/api.php?action=templatedata&titles=Extension:TemplateData&format=jsonfm
Tel que délivré par l'API: https://www.mediawiki.org/w/api.php?action=templatedata&titles=Extension:TemplateData

Configuration

Variable	Par défaut	Description
`$wgTemplateDataUseGUI`	`true`	Interface de dialogue expérimental pour modifier les TemplateData JSON

Voir aussi

Extension:TemplateWizard – interface utilisateur pour sélectionner et insérer le wikicode des modèles, en fonction de leurs TemplateData.
GitHub: jeblad/TemplateData – version alternative, avec quelques fonctionnalités Lua.
Modèle traductible
Wikibase/Maps TemplateData

Cette extension est utilisée par au moins un des projets Wikimédia. Cela signifie probablement que l’extension est assez stable et fonctionnelle pour être utilisée sur des sites à fort trafic. Recherchez le nom de cette extension dans le CommonSettings.php de Wikimédia et dans le fichier de configuration InitialiseSettings.php pour situer les endroits où elle est installée. Une liste complète des extensions installées sur un Wiki donné peut être visualisée sur la page Special:Version de ce wiki.

Cette extension est incluse dans les fermes de wikis ou les hôtes suivants et / ou les paquets :

Cette liste ne fait pas autorité. Certaines fermes de wikis ou hôtes et / ou paquets peuvent contenir cette extension même s'ils ne sont pas listés ici. Vérifiez toujours cela avec votre ferme de wikis ou votre hôte ou votre paquet avant de confirmer.

TemplateData État de la version : stable

Implémentation	Balise , API
Description	Permet d'enregistrer, de retrouver et de visualiser des informations à propos des templates
Auteur(s)	Timo Tijhof, Moriel Schottlender, James Forrester, Trevor Parscal, Bartosz Dziewoński, Marielle Volz, ...
Dernière version	0.1.2 (Mises à jour constantes)
Politique de compatibilité	Versions ponctuelles alignées avec MediaWiki. Le master n'est pas compatible arrière.
MediaWiki	>= 1.43
PHP	5.4+
Modifie la base de données	Non
Licence	Licence publique générale GNU v2.0 ou supérieur
Téléchargement	Télécharger l'extension Git ^[?]: Télécharger la branche master de Git parcourir le dépôt (Phabricator · GitHub) historique des validations (commits) contributeurs du dépôt (GitHub) relecture du code
Paramètres $wgTemplateDataUseGUI
Balises `‎<templatedata>`
Accroches utilisées EditPage::showEditForm:fields EditPage::showEditForm:initial MultiContentSave OutputPageBeforeHTML ParserFetchTemplateData ParserFirstCallInit ResourceLoaderRegisterModules
Téléchargements trimestriels	277 (Ranked 19^th)
Utilisé par les wikis publics	6,971 (Ranked 24^th)
Traduire l’extension TemplateData sur translatewiki.net si elle y est disponible
Problèmes	Tâches ouvertes · Signaler un bogue