Extension:TemplateData

From mediawiki.org
This page is a translated version of the page Extension:TemplateData and the translation is 97% complete.
Outdated translations are marked like this.
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
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.42
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>
Téléchargements trimestriels 270 (Ranked 25th)
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é 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' );
    
  • Yes 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 :

  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 : 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 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.

→ 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.

Objet Maps

Maps is a single data structure that goes multiple levels deep. It became common to call the second level a “map object”.

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 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

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é 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

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.
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 :

Configuration

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

Voir aussi