Extension:TemplateData

This page is a translated version of the page Extension:TemplateData and the translation is 100% complete.
Other languages:
Deutsch • ‎English • ‎Türkçe • ‎dansk • ‎español • ‎français • ‎lietuvių • ‎polski • ‎português • ‎čeština • ‎русский • ‎українська • ‎ߒߞߏ • ‎अवधी • ‎हिन्दी • ‎বাংলা • ‎中文 • ‎日本語
Cette extension est fournie avec MediaWiki 1.35 et supérieur. Ainsi vous n'avez pas besoin de la télécharger à nouveau. Néanmoins, vous devez encore suivre les autres instructions fournies.
Manuel des extensions MediaWiki
OOjs UI icon advanced.svg
TemplateData
État de la version : stable
Screenshot of TemplateData extension.png
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 Pascal, Bartosz Dziewoński, Marielle Volz, ...
Dernière version 0.1.2 (Mises à jour constantes)
Politique de compatibilité branches de version
MediaWiki 1.25+
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
  • $wgTemplateDataUseGUI
<templatedata>
Traduisez l’extension TemplateData sur translatewiki.net
Vérifiez la matrice des utilisations et des versions.
Problèmes Tâches ouvertes · Signalez un bogue

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

Installation

  • Téléchargez et placez le(s) fichiers (s) dans un répertoire appelé TemplateData dans votre dossier extensions/.
  • 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.

Édition

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 :

  1. Le contenu doit être du JSON valide;
  2. 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
  3. pour les éléments qui ont une liste spécifique de valeurs possibles (par exemple : params.yourParameterName.type), 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 d'édition.

Pour les éléments à valeur automatique (autovalue), bug 2700 empêche subst: de travailler dans tout modèle qui est ajouté à l'intérieur d'un <tag>, 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é.

Notez que vous ne pouvez pas utiliser {{#tag:templatedata}} à la place de <templatedata>.

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.
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.
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. Si cette clé n'existe pas dans la structure <templatedata></templatedata> sur la page du modèle, elle est ajoutée à la structure fournie par l'API en utilisant l'ordre dans lequel les paramètres apparaissent dans l'objet TemplateData.
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 Maps Un objet qui fait correspondre le nom simplifié de consommateur-tiers des données du modèle (par exemple Citoid, Special:MyLanguage/Wikidata, etc.), à un objet qui associe le nom d'un paramètre de consommateur à un ou plusieurs noms 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.
description InterfaceText null Une brève description du paramètre, pour que les utilisateurs sachent lequel choisir dans une liste d'options.
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é).
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é).
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.
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 ».
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.
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}}.
example InterfaceText null Un texte d'exemple pour le paramètre, pour aider les utilisateurs à utiliser la bonne valeur.
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é
"number" Toute valeur numérique (sans le séparateur décimal - point ou virgule - ni celui des milliers)
"string" Toute valeur textuelle. Peut contenir des passages à la ligne.
"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.
"boolean" Une valeur booléenne ('1' pour true, '0' pour false et '' pour inconnue), voir la logique ternaire.
"date" Une date dans le format ISO 8601, par exemple "2014-05-09" ou "2014-05-09T16:01:12Z"
"url" Une URL, avec son protocole, par exemple "http://www.example.org", "https://example.org", ou "//example.org".
"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.
"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 » ).
"wiki-template-name" Un nom de modèle MediaWiki valide pour le wiki actuel.
"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 » ).
"content" Contennu de la page en wikicode, tel que le style du texte, les liens, les images, etc.
"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>}}
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.

Objet Set

Key Type Valeur par défaut Description
tableau de tableaux [] Type du paramètre, pour les indications (logicielles) de type. Une valeur parmi :
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.

Objet Maps

Clé Type Valeur par défaut Description
nom du consommateur objet {} Un objet qui fait correspondre un nom de consommateur à un objet faisant correspondre un nom de paramètre consommateur, à un ou plusieurs noms de paramètres de modèle associés.

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 illustre la structure d'un objet de correspondance.

{
	"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 traductible pour être utilisée sur Wikipedia et correspondant au code de langue donné.

Exemple de correspondance d'objets :

Clé Valeur
"en" "Welcome to Wikipedia"
"de" "Willkommen bei Wikipedia"
"fe" "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

ParameterDescriptionTypeStatus
User's nameuser 1

User name of person who forgot to sign their comment.

Userrequired
Datedate 2

Timestamp of when the comment was posted, in YYYY-MM-DD format.

Auto value
{{subst:#time:Y-m-d}}
Unknownsuggested
Yearyear

no description

Numberoptional
Monthmonth

no description

Numberoptional
Dayday

no description

Numberoptional
Commentcomment

no description

Unknownoptional

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 :
    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é paramOrder et le tableau en utilisant l'ordre dans lequel les paramètres apparaissent dans la clé params à l'intérieur de l'objet TemplateData sur la page du modèle.
    3. Ajoute la clé sets
    4. 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
    5. 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.
    6. 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

Objets encapsulants ajoutés au JSON délivré par l'API
Ils ne sont pas définis dans l'objet JSON encadré par les balises <templatedata> de la page du modèle.
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.
paramOrder Tableau contenant les chaînes des noms de paramètres Ordre logique dans lequel les paramètres doivent apparaître. Le tableau contient les clés des paramètres une fois exactement. Chaque chaîne doit être une clé valide de l'objet params.
S'il n'existe pas dans la structure de <templatedata></templatedata> sur la page du modèle, il est ajouté à la structure telle qu'elle est fournie par l'API, en utilisant l'ordre dans lequel les paramètres apparaissent dans l'objet TemplateData.
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 traductible à utiliser sur Wikipedia correspondant au code de langue Wikipedia.

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