TemplateData est un moyen de stocker des informations au sujet d’un modèle et de ses paramètres, de manière à ce que l'ÉditeurVisuel puisse les récupérer et les afficher dans son éditeur de modèles, rendant ainsi plus facile l’édition de pages qui utilisent ce modèle. Il est également utilisé ailleurs dans les scripts, les outils et les gadgets. Il permet également d'insérer rapidement un modèle avec l'éditeur de wikicode via l'outil TemplateWizard.

La syntaxe TemplateData permet aux utilisateurs d'écrire de petits morceaux de données structurées dans une page de modèle, ou à inclure dans la page du modèle (par exemple sur une sous-page de documentation). Une fois qu'un modèle a ces données structurées, il peut être modifié correctement depuis l'éditeur de modèle dans l'éditeur visuel. Bien que cela puisse sembler compliqué, c'est en fait très simple.

Éditeur de données TemplateData

modifier

Un éditeur de données TemplateData est intégré à Wikipédia, permettant de créer ou modifier les données TemplateData de manière facile.

Pour utiliser l'éditeur TemplateData, allez sur la page du modèle (ou sur sa sous-page de documentation, si le modèle en possède une), et cliquez sur le bouton « Modifier » (ou « Modifier le code »). Ceci fera apparaître un bouton nommé « Gérer TemplateData », en haut à gauche de la page, sous le titre :

 
Bouton « Gérer TemplateData » pour modifier les données TemplateData.

Appuyez sur le bouton « Gérer TemplateData » pour entrer dans l'interface d'édition du TemplateData.

 
L'outil d'édition TemplateData, dans une page qui ne contient pas encore de TemplateData.

L'éditeur vous permet d'ajouter les paramètres du modèle et d'y attribuer les valeurs les plus courantes. Si la page que vous avez éditée contient un bloc de TemplateData, l'information déjà documentée sera automatiquement affichée quand vous ouvrirez la page adéquate dans l'éditeur de TemplateData.

Plusieurs boutons et champs sont présents, dans l'ordre d'affichage :

Bouton « Annuler »
Annule les modifications effectuées et ferme l'outil de configuration TemplateData.
Bouton « Appliquer »
Insère les données TemplateData modifiées dans le wikicode de la page, puis ferme l'outil de configuration et ré-affiche la fenêtre de modification du wikicode. Il est ensuite nécessaire d'ajouter un résumé de modification, et de cliquer sur « Publier les modifications » pour quelles soient définitivement enregistrée.
Champ « Description »
Permet d'ajouter une description décrivant ce que le modèle fait, à quoi il sert, etc. Voir également les #Bonnes pratiques y afférentes.
Boutons « Mise en forme suggérée du wikitexte »
Permet de définir la mise en forme du wikicode généré par l'éditeur visuel, deux formats prédéfinis, « Sur une seule ligne » et « Multiligne » sont disponibles, et en cliquant sur le bouton « Personnalisation », il est possible de définir un format personnalisé (nécessaire notamment pour les infobox).
Voir les différents formats de mise en forme pour plus de détails.
« Ajouter un paramètre »
Permet d'ajouter un nouveau paramètre
« Ajouter le(s) paramètre(s) suggéré(s) »
Ajoute automatiquement tous les paramètres utilisés par le modèle (seul le nom du paramètre est ajouté, c'est à vous de les configurer individuellement après). Attention, des alias et des paramètres inutilisés peuvent également être ajoutés, veillez donc à vérifier qu'il n'y ait pas de paramètres à double ou des alias de paramètres, et à faire le ménage en conséquence. Cela ne fonctionne qu'avec les modèles conventionnels écris en wikicode. Les modèles basés sur des modules Lua ne sont pas supportés.
 
Édition d'un paramètre dans l'éditeur de TemplateData.

Vous pouvez définir le nom du paramètre, ses éventuels alias (autres noms pour le même paramètre), le libellé (nom du paramètre à afficher dans l'éditeur visuel) et la description qui sera affichée. Vous pouvez aussi proposer un exemple sur la façon de remplir le paramètre. Le seul champ obligatoire est le « Nom » (le premier champ de chaque ligne), qui est l’endroit où vous inscrivez le nom exact du paramètre, avec la casse correcte. Dans le menu déroulant « Type », vous pouvez choisir le type de contenu que le paramètre doit recevoir. Si un paramètre est obligatoire pour le bon fonctionnement du modèle, marquez le paramètre comme « Obligatoire ». Si le paramètre est souvent utilisé ou recommandé, marquez-le comme « Suggéré » (cela l'ajoute systématiquement dans le wikicode, même non rempli). Le bouton « Supprimer le paramètre » retire du TemplateData l’entrée concernant le paramètre.

Voir #Attributs pour les paramètres pour plus de détails.

 
Fenêtre principale de l'éditeur de TenplateData, avec la liste des paramètres configurés.

Une fois les différents paramètres du modèle configurés, vous pouvez modifier l'ordre dans lequel les paramètres sont affichés dans l'éditeur visuel, en les réordonnant. Pour modifier l'ordre, il suffit de cliquer et de maintenir appuyé sur le bouton   à gauche du nom du paramètre, et de la déplacer à la position souhaitée. Cet ordre est également utilisé par l'éditeur visuel pour déterminer la position dans le wikicode où insérer de nouveaux paramètres d'un modèle. Cela n'a pas d'impact sur les paramètres d'un modèle qui sont déjà présents dans le wikicode.

Lorsque vous avez fini de documenter chacun des paramètres, cliquez sur « Appliquer » pour insérer le TemplateData pré-formaté dans le champ d’édition. Vous devez ensuite encore enregistrer la page en utilisant le bouton classique « Publier les modifications » sous le champ d’édition.

Si vous voulez éviter de perdre tout votre travail en cours en cas de plantage du navigateur ou d'erreur de manipulation, particulièrement quand vous travaillez sur un modèle complexe et que vous y passez beaucoup de temps, vous pouvez faire des sauvegardes intermédiaires de votre travail en cliquant sur « Appliquer » puis en copiant depuis la fenêtre d'édition le code situé entre les balises <templatedata> et </templatedata> et le coller dans un fichier texte sur votre ordinateur, que vous enregistrerez. En effet, si vous passez 30 minutes à remplir des données, il est dommage de les perdre à la suite d'une erreur de manipulation. Si vous devez restaurer vos modifications depuis votre sauvegarde, il vous suffira de faire l'opération inverse.
L’éditeur TemplateData placera le TemplateData soit sur la page du modèle, soit sur sa sous-page de documentation. Vous déterminez l’endroit où le TemplateData sera ajouté en ouvrant (en éditant) la page où vous voulez que le TemplateData soit. Si une sous-page de documentation existe, il faut ajouter le TemplateData sur cette page. Toutefois, si plusieurs blocs de TemplateData sont placés sur un même modèle, seul un de ces blocs de TemplateData sera utilisé. S’il y a déjà un TemplateData sur une page, alors vous devez éditer la page où le TemplateData a été ajouté précédemment pour éviter de créer accidentellement plusieurs blocs de TemplateData.

Emplacement des TemplateData

modifier

TemplateData doit être sur la page du modèle qu'il décrit, ou être inclus dedans. Si une sous-page de documentation existe, les données TemplateData doivent être placées dans celle-ci.

Dans les sous-pages de documentation, le bloc des données TemplateData est généralement placé à la fin de la page de documentation, dans une section == TemplateData ==, située juste avant une éventuelle section « Voir aussi » ou « Modèles connexes », et avant les catégories et éventuels modèles {{Projet}}.

Parfois, dans le cas de modèles relativement simples, ou en l'absence d'une documentation pré-existante des paramètres du modèle, la documentation TemplateData peut remplacer la documentation écrite des différents paramètres. Dans ce cas, le bloc TemplateData peut être positionné à la place.

Si les données Templatedata sont inscrites directement sur la page du modèle, et non sur une sous-page de documentation, il doit impérativement être entouré de balises <noinclude> et </noinclude>, afin d'empêcher que les données TemplateData soient incluses dans un article lors du l'utilisation du modèle.

Structure des TemplateData

modifier

La structure des TemplateData est basée sur le standard JSON. Notez que toutes les descriptions dans un TemplateData doivent être en texte seul (pas de wikicode, pas de liens, etc.).

Les données TemplateData sont insérées dans une paire de balises <templatedata></templatedata>, comme ceci :

<templatedata>
{
    ... // Le contenu du TemplateData va ici
}
</templatedata>

Cela fait savoir au logiciel que tout ce qu’il y a entre ces deux balises sera du TemplateData, et devra être référencé lorsque le modèle sera utilisé.

Exemple

modifier

Les descriptions dans les TemplateData suivent un schéma standard assez simple ; voici un exemple des données TemplateData utilisées pour le modèle {{Lien}} (modèle permettant de faire un lien vers un article inexistant sur la Wikipédia en français, mais existant sur une autre Wikipédia).

<templatedata>
{
	"description": "Ce modèle a pour but de placer un lien interne vers un article inexistant à créer dans la Wikipédia en français (donc apparaissant par défaut en rouge), tout en fournissant un lien supplémentaire vers un article équivalent dans une version de Wikipédia dans une autre langue.",
	"params": {
		"langue": {
			"label": "Langue",
			"description": "Code langue de la Wikipédia en langue étrangère où il existe un article correspondant au sujet. Si omis, désigne la Wikipédia en anglais.",
			"type": "string",
			"default": "en",
			"aliases": [
				"lang"
			],
			"suggested": true,
			"example": "de",
			"autovalue": "en"
		},
		"trad": {
			"label": "Article en langue étrangère",
			"description": "Titre de l’article existant sur la Wikipédia en langue étrangère. Si omis, utilise le même titre que l’article inexistant à créer sur la Wikipédia en français.",
			"suggested": true,
			"example": "Ausschuss für die friedliche Nutzung des Weltraums"
		},
		"fr": {
			"label": "Article en français",
			"description": "Titre de l’article inexistant à créer sur la Wikipédia en français. Si omis, utilise le même titre que l’article existant en langue étrangère.",
			"aliases": [
				"1"
			],
			"suggested": true,
			"example": "Comité des utilisations pacifiques de l'espace extra-atmosphérique"
		},
		"texte": {
			"label": "Texte",
			"description": "Texte en français (souvent abrégé ou accordé différemment) à afficher sur le lien. Si omis, affiche le titre de l’article à créer en français, sinon affiche le titre de l'article existant sur la Wikipédia en langue étrangère.",
			"type": "content",
			"example": "COPUOS"
		}
	}
}
</templatedata>

Ce qui donne ceci sur la page de documentation du modèle :


Ce modèle a pour but de placer un lien interne vers un article inexistant à créer dans la Wikipédia en français (donc apparaissant par défaut en rouge), tout en fournissant un lien supplémentaire vers un article équivalent dans une version de Wikipédia dans une autre langue.

Paramètres du modèle

ParamètreDescriptionTypeÉtat
Languelangue lang

Code langue de la Wikipédia en langue étrangère où il existe un article correspondant au sujet. Si omis, désigne la Wikipédia en anglais.

Par défaut
en
Exemple
de
Valeur automatique
en
Chaînesuggéré
Article en langue étrangèretrad

Titre de l’article existant sur la Wikipédia en langue étrangère. Si omis, utilise le même titre que l’article inexistant à créer sur la Wikipédia en français.

Exemple
Ausschuss für die friedliche Nutzung des Weltraums
Inconnusuggéré
Article en françaisfr 1

Titre de l’article inexistant à créer sur la Wikipédia en français. Si omis, utilise le même titre que l’article existant en langue étrangère.

Exemple
Comité des utilisations pacifiques de l'espace extra-atmosphérique
Inconnusuggéré
Textetexte

Texte en français (souvent abrégé ou accordé différemment) à afficher sur le lien. Si omis, affiche le titre de l’article à créer en français, sinon affiche le titre de l'article existant sur la Wikipédia en langue étrangère.

Exemple
COPUOS
Contenufacultatif

Attributs

modifier

Attributs généraux du modèle

modifier
Attributs TemplateData généraux du modèle
Nom de l'attribut Description Exemple d'utilisation
description L'attribut "description" sert à indiquer la fonction du modèle.

Si vous devez utiliser des guillemets doubles " dans la description, il est nécessaire d'ajouter un caractère d'échappement, un antislash \, devant le guillemet double, comme ceci : \". Sinon cela provoquera une erreur.

Les 4 à 5 premiers mots sont également affichés en dessous du nom du modèle lors de la recherche de modèles à insérer depuis l'éditeur visuel. Il est donc primordial d'écrire de manière judicieuse la description.

Voir les #Bonnes pratiques pour utiliser au mieux cet attribut.

"description": "Bandeau de section pour lien vers un article approfondissant le sujet.",
format L'attribut "format" indique comment le wikicode du modèle sera généré. Il peut prendre pour valeur les formats suivants :
undefined
C'est le comportement par défaut, quand aucun format n'est défini. Le comportement est le suivant :
Modification d'un modèle existant
L'éditeur visuel préservera la mise en forme existante du wikicode du modèle. En cas d'ajout de nouveaux paramètres, ils seront ajoutés de manière inline. Si un ordre des paramètres a été défini pour le modèle, le paramètre sera ajouté à une position en accord avec cet ordre, sinon ce sera à la suite du dernier paramètre présent.
Insertion d'un nouveau modèle
Le comportement est alors le même que pour le format "inline".
"inline"
Le modèle est condensé sur une seule ligne de wikicode, sans espace blanc, comme ceci :
{{Nom du modèle|param=abc|param2=123}}
"block"
Le modèle sera sur plusieurs lignes, avec une ligne par paramètre (à moins que le modèle ne contienne aucun paramètre) :
{{Nom du modèle
| param = abc
| param2 = 123
}}
un format personnalisé
Permet de définir une indentation des paramètres pour aligner verticalement les valeurs des paramètres (doit être utilisé pour les infobox).
Offre aussi la possibilité d'indiquer si du contenu autre que le modèle peut-être présent, ou non, avant et/ou après le modèle, sur la même ligne que ce dernier.
"format": "inline",
params L'attribut "params" contient les définitions des paramètres du modèle.
"params": {
    ...    // les paramètres vont ici
}

Attributs pour les paramètres

modifier

Tous les paramètres qui suivent sont inclus dans le bloc "params" :

Attributs TemplateData pour chaque paramètre du modèle
Nom de l'attribut Nom de l'attribut en français
(sur l'éditeur de TemplateData)
Description Exemple d'utilisation
nom du paramètre du modèle Nom Chaque paramètre du modèle est défini dans un bloc portant le nom qu'a le paramètre dans le modèle, en respectant la casse :
  • Si le paramètre a un nom, comme {{{article}}} (utilisation : |article=abc), ce nom sera "article".
  • Si le paramètre n’a pas de nom, mais un simple numéro, c'est-à-dire que sa signification dépend de sa position dans le wikicode (paramètre positionnel), comme {{{1}}} (utilisation : |abc, ce nom sera "1".

Toutes les informations à propos de ce paramètre sont incluses dans un bloc qui porte le nom du paramètre.

"article":{
    ... // les informations sur ce paramètre viennent ici
},
label Libellé L'attribut "label" permet d'indiquer pour le paramètre un titre lisible (et facilement compréhensible) par un humain, qui sera affiché dans l’éditeur de modèle de l'éditeur visuel.

Voir les #Bonnes pratiques concernant le nommage des paramètres avec label.

"label": "Article",
description Description L'attribut "description" permet d'ajouter une description détaillée du paramètre.

Si vous devez utiliser des guillemets doubles " dans la description, il est nécessaire d'ajouter un caractère d'échappement, l'antislash \, devant le guillemet double, comme ceci : \". Sinon cela provoquera une erreur.

"description": "L'article vers lequel faire un lien.",
default Par défaut L'attribut "default" est utile pour certains modèles qui ont une valeur ou un comportement par défaut. Cet attribut permet d'indiquer cette valeur ou comportement par défaut à l'utilisateur, sans pour autant pré-remplir le champ. L'utilisateur peut néanmoins toujours saisir une valeur en procédant comme pour tout champ.

Visuellement, l'effet est similaire au champ "example". Pour une valeur par défaut de oui cela affichera en arrière-plan « Par défaut : oui » dans le champ vide de l'éditeur de modèle.

Attention : Il s'agit seulement d'indiquer à l'utilisateur la valeur ou le comportement par défaut d'un paramètre si non-rempli, il ne s'agit en aucun cas d'un pré-remplissage du champ. Si aucune valeur n'est précisée par l'utilisateur, le champ restera vide dans le code généré. Si vous voulez pré-remplir le champ, il faut utiliser l'attribut "autovalue".

Vous pouvez ignorer cet attribut s’il n’y a pas de valeur ou comportement par défaut.

"default": "oui",
autovalue Valeur automatique L'attribut "autovalue" permet de pré-remplir le champ automatiquement, avec une valeur. Utilisé pour un paramètre dont la valeur la plus courante est connue, mais permettant à l'utilisateur de modifier facilement celle-ci. Peut aussi être utilisé pour ajouter automatiquement le mois et l'année actuelle, en substant les mots magiques {{CURRENTMONTHNAME}} et {{CURRENTYEAR}} avec {{subst:}}, par exemple avec "{{subst:CURRENTMONTHNAME}} {{subst:CURRENTYEAR}}" (donnera après enregistrement quelque chose comme « janvier 2018 »).

Vous pouvez ignorer cet attribut s’il n’y a pas de valeur à pré-remplir.

"autovalue": "{{subst:CURRENTMONTHNAME}} {{subst:CURRENTYEAR}}",
type Type L'attribut "type" contrôle comment l’éditeur de modèle interprétera la valeur de ce paramètre. Les types possibles sont :
"string" (« chaîne »)
une chaîne de caractères, comme cette phrase, pouvant être sur plusieurs lignes ;
"line" (« ligne »)
une chaîne de caractères courte, sur une seule ligne, par exemple pour un nom, une étiquette, etc. ;
"number" (« nombre »)
un nombre ;
"boolean" (« booléen »)
Pour un paramètre attendant des valeurs oui/non (0 pour non, 1 pour oui, vide pour inconnu) ;
"wiki-page-name" (« page »)
Le titre d'un article ou d'une page, donne des suggestions de recherche lors de la saisie ;
"wiki-user-name" (« utilisateur »)
Un nom d'utilisateur (sans la partie Utilisateur:), donne des suggestions de recherche lors de la saisie ;
"wiki-file-name" (« fichier »)
un nom de fichier (sans la partie Fichier:) ;
"wiki-template-name" (« modèle »)
un nom de modèle (sans la partie Modèle:), pour le cas où ce paramètre est rempli avec un nom de modèle uniquement, donne des suggestions de recherche lors de la saisie ;
"url" (« url »)
une URL, utilisé pour un lien externe (affiche une icône   dans l'éditeur de modèle) ;
"date" (« date »)
une date, selon le format ISO 8601 (exemple : 2017-12-31). À n'utiliser que pour les modèles acceptant des dates avec ce format d'entrée et le convertissant en un format lisible pour l'affichage ;
"content" (« contenu »)
pour du wikicode pouvant contenir plusieurs paragraphes, des fichiers, etc. ;
"unbalanced-wikitext" (« wikitexte non équilibré »)
pour un paramètre pouvant recevoir du wikicode non équilibré (exemple : {{echo|before=<u>|after=</u>}}), paramètre d'usage très rare ;
"unknown" (« inconnu »)
type de contenu inconnu.
"type": "string",
suggestedvalues Valeurs suggérées L'attribut "suggestedvalues" permet de mentionner les différentes valeurs possibles du paramètre. Dans l'éditeur visuel, il sera proposé ces valeurs dans un menu déroulant. Si de nombreuses valeurs sont proposées (par exemple une liste de pays), il suffit de taper les premières lettres pour filtrer les choix proposés.

Il reste possible de saisir une valeur ne faisant pas partie de la liste, mais un avertissement sera affiché indiquant que la valeur saisie ne fait pas partie de la liste prédéfinie.

Cette fonctionnalité ne peut être utilisée pour le moment qu'avec les types de données string, line, number, content, unbalanced-wikitext et unknown.

Ajout de valeurs suggérées depuis l'éditeur de données TemplateData :

Les différentes valeurs doivent être saisies une par une. Saisissez une valeur (espace et caractères spéciaux compris), puis appuyez sur Entrée. Répétez l'opération autant de fois que nécessaire.

"suggestedvalues": [
    "html",
    "pdf",
    "doc",
    "xls"
],
example Exemple L'attribut "example" (exemple) permet de mentionner un ou plusieurs exemples d'utilisation du paramètre.

Le contenu de cet attribut est affiché en arrière-plan grisé du champ de saisie correspondant si le paramètre est vide. Il est également visible en cliquant sur l'icône   dans l'éditeur visuel.

Si plusieurs exemples sont mentionnés, il est recommandé d'utiliser des guillemets français (« et ») pour séparer les différents exemples : « 1 janvier 2000 » ou « 1er janvier 2000 ».

"example": "Aéroport international de Genève",
"example": "« 1 janvier 2000 » ou « 1er janvier 2000 »",
required Obligatoire L'attribut "required" (obligatoire) peut être positionné à true (oui) ou false (non, par défaut).

Indique que le paramètre doit obligatoirement être rempli pour que le modèle fonctionne correctement. Un message d'avertissement s'affiche dans l'éditeur visuel si l'on tente d'insérer un modèle avec des paramètres obligatoires non remplis.

Il ne faut déclarer un paramètre obligatoire que si celui-ci est réellement indispensable au bon fonctionnement du modèle.

"required": true,
suggested Suggéré L'attribut "suggested" (suggéré) peut être positionné à true (oui) ou false (non, par défaut).

Indique qu'il s'agit d'un paramètre suggéré. Les paramètres suggérés sont directement affichés dans l'éditeur de modèles de l'éditeur visuel.

"suggested": true,
deprecated Obsolète L'attribut "deprecated" (obsolète) peut être positionné à true (oui), false (non, par défaut) ou à une chaîne de caractères décrivant ce que les utilisateurs devraient faire à la place.

Ce statut est à utiliser pour des paramètres qui ne devraient plus être utilisés, mais qui continuent d’exister pour le moment. Cela pourrait être parce que l'utilisation du modèle est en train de basculer d'un jeu de paramètres à un autre.

"deprecated": "Paramètre déprécié, veuillez utiliser dorénavant le champ « Publication - date ».",
aliases Alias (séparés par des virgules) L'attribut "aliases" (autres noms) permet de saisir d'éventuels alias pour le paramètre concerné.

Exemple : un paramètre langue pourrait avoir comme alias lang, language et un paramètre positionnel non nommé 2.

Les alias ne doivent être mentionnés qu'en tant qu'alias, ils ne doivent pas être paramétrés ailleurs.

"aliases": [ "lang", "language", "2" ],
inherits non supporté L'attribut "inherits" (héritage) permet d'hériter les attributs du paramètre indiqué. Il suffit d'indiquer de quel paramètre ont veut hériter les attributs.

Cela permet de simplifier le code, et de gagner du temps, quand plusieurs paramètres aux attributs identiques sont présents, comme des paramètres article1, article2, article3, etc., il devient inutile de répéter les mêmes choses pour chaque paramètre.

À noter qu'il est possible d'outrepasser chaque attribut hérité, en la redéfinissant avec une valeur différente de celle obtenue par héritage, comme le "label" ou un paramètre suggéré ("suggested": true), que l'on passerait à non-suggéré ("suggested": false), par exemple.

Attention également au fait que l'héritage n'est pas récursif, il ne faut donc pas hériter d'un paramètre qui hérite lui-même certains attributs d'un autre paramètre.

Cet attribut n'est pas supporté par l'éditeur visuel de données TemplateData.

"inherits": "article1",
Notez que chaque valeur doit être entourée par des guillemets droits " (sauf pour true et false), et séparée de la suivante par une virgule, à moins que ce ne soit la dernière.

Une fois que vous avez fini, cliquez sur « Publier les modifications ». Si vous avez fait des erreurs, l'enregistrement sera refusé (ce qui peut être troublant, mais garantit que vous ne pouvez rien casser). Si vous avez des erreurs, vous pouvez essayer de corriger le code d'après les indications fournies par le message d'erreur, notamment la ligne concernée. Si besoin, vous pouvez demander de l'aide sur Discussion aide:TemplateData ou sur Wikipédia:Questions techniques.

Formats personnalisés de mise en forme du wikicode

modifier

Un format personnalisé permet de définir quelle sera la forme du wikicode (une ou plusieurs lignes, indentation, etc.) du modèle une fois ajouté, ce qui est important pour la lisibilité du wikicode.

Un format mal configuré ou absent peut aboutir à ce que le wikicode d'inclusion du modèle soit “massacré” lors d'une édition depuis l'éditeur visuel (par exemple une infobox de plusieurs dizaines de paramètres peut se retrouver sur une seule ligne dans un article). le format n'agit que sur le wikicode généré, mais pas sur l'affichage du modèle lors de la consultation de l'article.

Lorsque vous modifiez des chaînes de format personnalisé dans l’éditeur de TemplateData, vous pouvez entrer \n ou bien appuyer sur la touche Entrée pour représenter une nouvelle ligne ; dans les deux cas cela sera affiché dans le champ de saisie.

Utilisation courante

modifier

Un format personnalisé s'utilise généralement pour les infobox et autres modèles ayant une syntaxe multiligne sous forme de blocs « aérés » :

{{Modèle
 | paramètre a      = 
 | paramètre long b = 
 | paramètre c      = 
}}

Il faut alors renseigner dans l'éditeur TemplateData ce type de format personnalisé :

{{_\n | ________________ = _\n}}\n

Pour cela, il faut compter le nombre de caractères (espaces compris) du plus long paramètre couramment utilisé[1] dans les articles (même s'il reste vide). Ensuite, écrire autant de tirets bas qu'il y a de caractères. Il ne faut en revanche pas compter les espaces avant le début et la fin du paramètre.

Pour identifier facilement quels sont les paramètres les plus utilisés d'un modèle, voir #Connaître le nombre d'inclusion et l'utilisation d'un paramètre.

Syntaxe avancée

modifier

Un format personnalisé se définit à l'aide des éléments suivants : {{, }}, \n, _, ' ' (espace), | et =.

Détail des séquences possibles
Séquence Description
{{ Indique le début du modèle.
}} Indique la fin du modèle.
\n Indique un retour à la ligne, dont le résultat dépend de sa position :
avant la séquence {{ (début du modèle)
le modèle sera ajouté au début d'une nouvelle ligne vierge (aucun contenu extérieur au modèle sur la même ligne, un retour à la ligne sera inséré entre ce contenu et le modèle),
En raison d'un bug, il faut éviter pour le moment d'utiliser des formats avec un \n avant le début du modèle, pour tous les modèles susceptibles de se retrouver sur la première ligne d'un article.
après la séquence }} (fin du modèle)
un retour à la ligne sera ajouté après la fin du modèle (aucun contenu extérieur au modèle sur la même ligne),
ailleurs dans le code
insère un retour à la ligne après le nom du modèle, et avant les paramètres.
_ Un ou plusieurs tirets de soulignement _ (aussi appelés underscores) à la suite indiquent l'endroit où le nom du modèle, paramètre ou valeur sera inscrit :
1re séquence de tirets de soulignement
position où le nom du modèle sera inscrit,
2e séquence
position où le nom des paramètres du modèle seront inscrits,
3e séquence
position où les valeurs des paramètres seront inscrites.

D'éventuels tirets de soulignements supplémentaires accolés au premier seront remplacés par le nom du modèle/paramètre/valeur ;

  • si ce contenu est inférieur au nombre de tirets de soulignements, les tirets de soulignements excédentaires seront remplacés par des espaces,
  • si ce contenu est plus grand que le nombre de tirets de soulignement, aucun tronquage n'est effectué, cela n'a aucune conséquence, hormis un décalage d'indentation du paramètre.

Cela est très utile pour les infobox, afin d'aligner verticalement les valeurs des paramètres, il faut pour cela prendre en compte le nombre de caractères (espaces compris) que fait le nom du paramètre le plus long de l'infobox (ou en tout cas, le plus long couramment présent dans le code, même non utilisé), et inscrire le même nombre de tirets de soulignements à l'endroit voulu.

' ' (espace) Une ou plusieurs espaces sont traitées comme telles, et systématiquement insérées à la position mentionnée. Inscrire plusieurs espaces est parfois utile pour faire une indentation avant le nom du paramètre, méthode utilisée pour quelques modèles.
| Indique la position du séparateur de paramètre.
= Indique la position de l'opérateur d'affectation, séparant le nom du paramètre de sa valeur.

Exemples

modifier
Exemples d'autres formats personnalisés pouvant être utilisés
Objectif Chaine de format Rendu
Forme en ligne. inline
{{_|_=_}}
texte avant le modèle{{Foo|param=abc|param2=1234|paramètre-vraiment-très-long=bidule}}texte après le modèle
Forme en bloc. block
{{_\n| _ = _\n}}
texte avant le modèle{{Foo
| param = abc
| param2 = 1234
| paramètre-vraiment-très-long = bidule
}}texte après le modèle
Format infobox, avec alignement de tous les noms de paramètres à une mesure donnée, retour à la ligne avant et après le modèle. (voir la page détaillée) {{_\n | _______________ = _\n}}\n
texte avant le modèle{{Foo
 | param           = abc
 | param2          = 1234
 | paramètre-vraiment-très-long = bidule
}}
texte après le modèle
Forme en ligne, avec ajout d'une espace à la fin du nom du modèle et de chaque paramètre (améliore la lisibilité) {{_ |_=_}}
texte avant le modèle{{Foo |param=abc |param2=1234 |paramètre-vraiment-très-long=bidule}}texte après le modèle
Pas d’espace avant le nom du paramètre, chaque modèle sur sa propre ligne. \n{{_\n|_ = _\n}}\n
texte avant le modèle
{{Foo
|param = abc
|param2 = 1234
|paramètre-vraiment-très-long = bidule
}}
texte après le modèle
Indenter chaque paramètre. {{_\n |_ = _\n}}
texte avant le modèle{{Foo
 |param = abc
 |param2 = 1234
 |paramètre-vraiment-très-long = bidule
}}texte après le modèle
La barre verticale à la fin de la ligne précédente, aligner à une mesure donnée. {{_|\n _______________ = _}}
texte avant le modèle{{Foo|
 param           = abc|
 param2          = 1234|
 paramètre-vraiment-très-long = bidule}}texte après le modèle
Style en ligne avec plus d’espaces, doit être au début de la ligne.
En raison d'un bug, il faut éviter pour le moment d'utiliser des formats avec un \n avant le modèle, et ce pour tous les modèles susceptibles de se retrouver sur la première ligne d'un article (infobox, bandeaux, etc.). Voir #Problème concernant les modèles se trouvant sur la 1re ligne d'une page.
\n{{_ | _ = _}}
texte avant le modèle
{{Foo | param = abc | param2 = 1234 | paramètre-vraiment-très-long = bidule}}texte après le modèle
Modèle au début de la ligne, paramètres indentés et alignés, barre verticale sur la ligne précédente.
En raison d'un bug, il faut éviter pour le moment d'utiliser des formats avec un \n avant le modèle, et ce pour tous les modèles susceptibles de se retrouver sur la première ligne d'un article (infobox, bandeaux, etc.). Voir #Problème concernant les modèles se trouvant sur la 1re ligne d'une page.
\n{{_ |\n _______________ = _}}
texte avant le modèle
{{Foo |
  param           = abc |
  param1          = 1234 |
  paramètre-vraiment-très-long = bidule}}texte après le modèle

Problème concernant les modèles se trouvant sur la 1re ligne d'une page

modifier

Un bug provenant d'une implémentation défaillante concerne actuellement les formats personnalisés. Il affecte les modèles se retrouvant sur la 1re ligne d'une page ET dont le format impose que le modèle commence au début d'une ligne (code \n au début du format).

Si un modèle disposant d'une tel format se retrouve sur la première ligne d'une page, une ligne vide est ajoutée par erreur par l'éditeur visuel avant le modèle. Afin d'éviter ce problème, tous les modèles susceptibles de se retrouver sur la première ligne d'un article ne devraient pas contenir de \n au début de leur format. Cela concerne avant tout les infobox et les bandeaux.


Bonnes pratiques

modifier

Le simple ajout de données TemplateData à un modèle n'est pas forcément suffisant pour permettre son utilisation facile depuis l'éditeur visuel ou depuis l'outil TemplateWizard, surtout pour un contributeur ne connaissant pas ou peu le modèle concerné. Si un contributeur utilisant l'éditeur de wikicode peut se contenter d'aller consulter la page de documentation du modèle pour comprendre comment s'en servir, un utilisateur de l'éditeur visuel dépend des données TemplateData pour comprendre comment son modèle fonctionne, et comment remplir ses différents paramètres.

Pour se rendre compte de la façon dont ces données sont utilisées, et si un modèle est correctement documenté, il faut essayer de s'en servir depuis l'éditeur visuel. Rien que l'étape de recherche du modèle en tapant ses premières lettres permet déjà de se rendre compte d'une première chose : est-ce que la description du modèle est utile et pertinente ou pas (est-ce qu'elle permet de déterminer de quel type de modèle il s'agit, et si c'est celui que l'on cherche).

Ensuite, il faut essayer de compléter les différents paramètres, comme si l'on ne connaissait pas le modèle. Les libellés des paramètres (qui peuvent être différents du nom « wikicode » du paramètre) sont-ils suffisamment clairs, la description des paramètres compréhensible et pertinente, ainsi que la manière de les remplir ?

Est-ce qu'un exemple de la manière dont il doit être rempli est fourni ?

Est-ce qu’il n'y a pas des paramètres “en trop” (paramètres suggérés) qui s'affichent mais que l'on n'aimerait pas avoir même vide dans le wikicode ?

Plusieurs conseils et bonnes pratiques ont donc été regroupés ci-dessous pour aider à construire des données TemplateData les plus pertinentes. Ces conseils sont issus de diverses sources, de tests pratiques et d'expérience empirique. Leur suivi n'est aucunement obligatoire.

Description du modèle

modifier

La description du modèle doit remplir deux objectifs :

  1. Faciliter la recherche du modèle
  2. Expliquer son fonctionnement, dans le cas où celui-ci est inhabituel. Elle permet également d'indiquer des instructions spéciales.

Elle doit être aussi courte que possible (pour des raisons de lisibilité), mais aussi longue que nécessaire. Des phrases du genre « Ce modèle permet d'insérer ceci faisant cela. » sont à éviter.

Lors de la recherche de modèles depuis l'éditeur visuel, seuls les 6 à 8 premiers mots sont affichés (cela peut varier légèrement selon les navigateurs). Il faut donc fournir le maximum d'informations sur ces premiers mots, qui ne soient pas déjà fournies par le nom du modèle. Il est important notamment d'indiquer le type de modèle dont il s'agit, car cela permet d'effectuer un premier tri.

Les contributeurs débutants ne connaissent généralement pas le nom exact des modèles courants. La fenêtre de recherche de modèles dans l'éditeur visuel joue donc ce rôle de recherche. Mais pour cela, la description doit permettre de répondre du mieux possible à plusieurs questions.

  • De quel type de modèle il s'agit (est-ce un modèle pour faire des références ou un bandeau ?)
  • Est-ce qu'il est destiné aux articles ?
  • À quoi sert-il ?
Rendu dans la fenêtre de recherche de l'éditeur visuel.
Exemple avec les modèles {{Article}} et {{Article détaillé}}.
Descriptions peu explicites Descriptions explicites
  • Article
    Pour citer un article en tant que référence (menu \"Citer\")...
  • Article détaillé
    Ce modèle, en début de section, met en exergue un...
  • Article
    Modèle de source pour citer un article en tant que...
  • Article détaillé
    Bandeau de section pour lien vers un ou plusieurs...

Quelques conseils pour la description :

Type de modèle
Préciser le type de modèle est important pour pouvoir faire un premier tri lors de la recherche, et savoir de quel genre de modèle il s'agit.
Utiliser donc en début de description des termes comme : « Bandeau », « Bandeau de section », « Modèle de pied-de-page », « Modèle de source », etc.
Cela permet d'avoir une certaine cohérence entre les descriptions de différents modèles, et de fournir des informations additionnelles à celles que fournit déjà le nom du modèle.
Modèles réservés à l'espace non-encyclopédique
Il n'existe pas de méthode permettant actuellement de retirer un modèle de la liste, ni de restreindre les espaces de noms dans lesquels il est censé être utilisé.
En attendant, il est donc judicieux de commencer la description des modèles concernés par la phrase : « Réservé aux pages internes. » ou similaire. Cela indique clairement que ce modèle est d'usage restreint. Il faut éviter des phrases contenant des termes du genre « espace non-encyclopédique » ou « pages méta », qui, s'ils sont bien compris des contributeurs expérimentés, sont généralement incompréhensibles pour des contributeurs débutants.
Il est plus important d'indiquer qu'un modèle est à usage restreint plutôt que d'indiquer à quoi il sert, ces modèles n'étant quasiment utilisés que par des contributeurs expérimentés, et de plus généralement sur des pages où l'éditeur visuel n'est pas disponible.

Libellé des paramètres

modifier

Exemple libellé « Débit moyen »
 
Caractéristiques
Débit moyen 200 m3/s

Le libellé d'un paramètre, ou nom affiché (label) n'a aucun besoin d'être identique ni même similaire au nom technique du paramètre, utilisé en wikicode.

il est d'usage de le faire commencer par une majuscule.

La première chose à garder à l'esprit est que l'utilisateur de l'éditeur visuel est bien souvent débutant dans ses contributions à l'encyclopédie, ou du moins peu connaisseur des différents modèles. De nombreux paramètres aux noms peu explicites existent, et d'autres s'y sont rajoutés au fil des années — y compris encore aujourd'hui. Parfois le nom d'un paramètre ayant la même fonction diffère selon les modèles. Il y a donc tout intérêt à pouvoir offrir des noms plus cohérents — à fonction identique, nom identique — quel que soit le modèle. Sans pour autant impacter les utilisateurs du wikicode.

Typiquement, pour un champ d'une infobox, donner au paramètre le même libellé que le titre de la ligne qui est affiché peut être judicieux. Comme l'exemple ci-contre le montre : l'{{Infobox Cours d'eau}} dispose d'un paramètre débit, qui correspond au débit moyen du cours d'eau. La ligne alors affichée dans l'infobox est intitulée « Débit moyen ». Utiliser « Débit moyen » comme libellé du paramètre est alors judicieux, l'éditeur visuel étant un outil basé sur le rendu.

Cela n'est bien entendu pas toujours aussi simple, ni même parfois souhaitable.

Grouper les noms des paramètres

modifier

Afin de faciliter l'utilisation des modèles et de réduire les erreurs d'utilisation, il est judicieux de regrouper via leurs libellés les « sous-paramètres » d'un paramètre qui forment un ensemble. Il n'existe à l'heure actuelle aucun moyen permettant de spécifier des relations de dépendances entre paramètres. Les libellés représentent donc également le seul moyen permettant d'indiquer de manière claire de telles relations de dépendances.

Exemple de paramètres avec libellés groupés
Nom
(wikicode)
Libellé
(éditeur visuel)
image Image
légende Image - légende
taille image Image - taille
image alt Image - alternative textuelle

Cela offre un ensemble plus cohérent. Il devient plus facile de trouver dans la liste des paramètres optionnels. Et cela permet par la même occasion d'expliciter les relations de dépendances éventuelles entre paramètres.

Il faut essayer d'obtenir une certaine cohérence entre différents modèles du même type. De nombreux modèles se contentent encore actuellement d'un libellé issu directement du nom du paramètre.

Paramètres suggérés

modifier

Marquer un paramètre comme suggéré a comme principal effet de l'afficher dans l'éditeur visuel dans la liste des paramètres du modèle, sans avoir besoin de consulter la liste complète. Si un paramètre est utilisé régulièrement, il est généralement pertinent de le marquer comme suggéré. S'il n'est pas rempli, il ne sera pas ajouté au wikicode généré (mais s'il est déjà présent, il ne sera pas retiré).

Paramètres « nocat »

modifier

Certains modèles possèdent un paramètre nommé nocat permettant d'éviter de catégoriser dans des catégories de maintenance dédiées les erreurs d'utilisation du modèle. Ce paramètre est parfois nécessaire en cas d'usage inhabituel du modèle sur une page d'aide ou comme exemple dans une page de documentation.

Ces paramètres nocat ne devant pas être utilisé dans les articles, leur documentation n'est d'aucune utilité aux utilisateurs de l'éditeur visuel. Documenter ces paramètres peut même être dangereux : en cas d'erreur de manipulation ou d'utilisation du modèle par un utilisateur — avec nocat non-vide — il peut devenir impossible d'identifier la présence d'une erreur d'utilisation.

Connaître le nombre d'inclusion et l'utilisation d'un paramètre

modifier

Pour connaître quels sont les paramètres les plus utilisés d'un modèle, l'outil wstat.fr peut être utilisé.

L'outil wstat.fr développé par Orlodrim permet d'obtenir facilement des informations sur l'utilisation des paramètres d'un modèle. Il permet d'obtenir facilement le nombre d'utilisations de chaque paramètre, et d'identifier ainsi quels sont les paramètres les plus ou moins utilisés. Il offre aussi un moyen rapide de comprendre comment un paramètre est utilisé (les différentes valeurs du paramètre dans les articles).

Cet outil est accessible depuis n'importe quel modèle en cliquant sur « Pages liées » dans le menu de gauche, puis sur « infos diverses ».

Questions fréquentes

modifier
Fonctionnalités manquantes
TemplateData est vraiment un exemple d’outil qui a été créé avec peu de fonctionnalités, dans l’espoir que les utilisateurs aideraient à guider le développement de fonctionnalités telles qu’ils le désirent. Si vous voulez demander de nouvelles fonctionnalités pour TemplateData, faites-le-nous savoir.
Retards pour l'affichage dans les modèles
Après que des données TemplateData ont été modifiées, les métadonnées devraient être visibles immédiatement lorsque le modèle est ouvert dans l’éditeur visuel. Toutefois, il est possible que cela prenne plusieurs heures avant que les métadonnées ne soient affichées. Vous pouvez forcer la mise à jour en faisant une modification nulle (null edit) sur la page du modèle lui-même (pas la sous-page de documentation). Pour faire une modification nulle, ouvrez la page du modèle en édition et enregistrez la page sans faire aucun changement ni ajouter de résumé de modification.
Problèmes en cours
Une liste des bogues actuels et des demandes de fonctionnalités est disponible sur Phabricator.
Erreurs de syntaxe
Des erreurs syntaxiques dans le code JSON des données TemplateData peuvent être commises. Dans ce cas, un message d'erreur « Erreur de syntaxe dans JSON. » s'affiche à la place. Dans la plupart des cas, les erreurs syntaxiques sont causées par une virgule finale en trop à la fin du dernier élément d'un niveau quelconque. L'outil JSONLint peut être utilisé pour détecter facilement l'emplacement d'erreurs syntaxiques. Il suffit de copier le code situé entre les balises <templatedata> et </templatedata> (en veillant à bien prendre le { au début et le } à la fin), et de le coller dans la zone de texte, puis cliquer sur « Validate JSON ».
Tester des données TemplateData
Il est possible de tester des données TemplateData sur un bac à sable dédié : Modèle:Bac à sable/TemplateData. Un bloc TemplateData pré-défini est déjà présent, avec de nombreux paramètres pré-définis. Il est ainsi possible de tester le comportement de l'éditeur visuel avec différents types de paramètres. Vous pouvez également remplacer les données TemplateData pré-définies par les vôtres à des fins de tests.

Autres outils

modifier
  • TemplateData Wizard : Un outil qui génère les données TemplateData grâce à une interface interactive. Recommandé pour sélectionner rapidement les paramètres obligatoires/suggérés et copier les descriptions depuis la documentation sans passer par des sous-menu.
  • JSONLint : Un outil qui vous permet de valider un JSON écrit à la main ou d'identifier les erreurs de syntaxe en cas de message d'erreur « Erreur de syntaxe dans JSON. ».
  • Special:PagesWithProp/templatedata : Liste de tous les modèles ayant un bloc de données TemplateData sur ce wiki.
  1. Les paramètres d'usage très rare, présents dans moins de 5 % des articles, ne devraient généralement pas être pris en compte.