Aide:TemplateData
- (en) Mises à jour
- (en) Problèmes connus
- (en) Statut
- Modifications faites avec l'ÉditeurVisuel
- Ajouter des métadonnées
TemplateData aux modèles
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 | modifier le code]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 :
Appuyez sur le bouton « Gérer TemplateData » pour entrer dans l'interface d'édition du 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.
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.
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.
Emplacement des TemplateData
[modifier | modifier le code]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 | modifier le code]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 | modifier le code]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ètre | Description | Type | État | |
|---|---|---|---|---|
| Langue | langue 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.
| Chaîne | suggéré |
| Article en langue étrangère | trad | 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.
| Inconnu | suggéré |
| Article en français | fr 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.
| Inconnu | suggéré |
| Texte | texte | 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.
| Contenu | facultatif |
Attributs
[modifier | modifier le code]Attributs généraux du modèle
[modifier | modifier le code]| 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 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 :
|
"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 | modifier le code]Tous les paramètres qui suivent sont inclus dans le bloc "params" :
| 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 :
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": "Article",
|
description
|
Description | L'attribut "description" permet d'ajouter une description détaillée du paramètre.
Si vous devez utiliser des guillemets doubles |
"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 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 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 :
|
"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 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 Si plusieurs exemples sont mentionnés, il est recommandé d'utiliser des guillemets français ( |
"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 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 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",
|
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 | modifier le code]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 | modifier le code]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 | modifier le code]Un format personnalisé se définit à l'aide des éléments suivants : {{, }}, \n, _, ' ' (espace), | et =.
| 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 :
|
_
|
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 :
D'éventuels tirets de soulignements supplémentaires accolés au premier seront remplacés par le nom du modèle/paramètre/valeur ;
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 | modifier le code]| 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. | \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. | \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 | modifier le code]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 | modifier le code]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 | modifier le code]La description du modèle doit remplir deux objectifs :
- Faciliter la recherche du modèle
- 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 ?
| Descriptions peu explicites | Descriptions explicites |
|---|---|
|
|
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 | modifier le code]
| Exemple libellé « Débit moyen » | |
| |
| Caractéristiques | |
|---|---|
| Débit moyen | 200 m3/s |
modifier  |
|
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 | modifier le code]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.
| 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 | modifier le code]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 | modifier le code]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 | modifier le code]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 | modifier le code]- 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 | modifier le code]- 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.
- 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.