Extension: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 | |
|
|
<templatedata> |
|
| 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 |
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é
TemplateDatadans votre dossierextensions/.
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
typed'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 :
→ 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 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.
| 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.
| 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 :
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 :
- Un objet Pages global contenant un ou plusieurs objets Page
- Un objet avec une clé numérique : un objet Page
- Additions/modifications de l'objet TemplateData actuel
- Ajoute la clé
titleavec le nom de la page de laquelle les données ont été demandées (par exemple « Template:Cite web »). - Ajoute la clé
sets - 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
- 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.
- 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é.
- Ajoute la clé
Différences visuelles dans un objet JSON TemplateData délivré par l'API
| ||||||
|
| 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. |
| 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. |
| 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 :
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. |