Help:TemplateData
 |
Note : Si vous modifiez cette page, vous acceptez de placer votre contribution sous licence CC0. Plus d'informations sont disponibles sur les pages d'aide du projet domaine public.
|
|
TemplateData est un moyen de stocker des informations au sujet d’un modèle wikitext et de ses paramètres, de manière à ce que l’éditeur visuel 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.
L’extension TemplateData est installée sur tous les wikis gérés par la fondation Wikimedia. Si vous avez votre propre wiki, vous devrez installer Extension:TemplateData.
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 cette page de modèle (comme par exemple sur un modèles de page de documentation). Une fois qu'un modèle a ces données structurées, il peut être affiché correctement dans l'éditeur visuel. Bien que cela puisse sembler compliqué, c'est en fait très simple.
Contents
Éditeur de données TemplateData
Il y a un outil intégré permettant de modifier les TemplateData de manière simplifiée.
Pour utiliser l'éditeur TemplateData, allez dans la page du modèle (ou dans sa sous page de documentation) et cliquez sur le bouton "Edit". Ceci fera apparaître un bouton nommé "Gérer TemplateData", juste au-dessus de la fenêtre ouverte d'édition :
Appuyez sur ce bouton pour entrer dans l'interface d'édition des 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 déjà é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. Dans la première zone de saisie, vous pouvez ajouter ou modifier la description succincte du modèle en texte brut. Ensuite, vous pouvez utiliser les boutons "Ajouter le(s) paramètre(s) suggéré(s)" et "Ajouter un paramètre" pour documenter le nom et les attributs des paramètres utilisés par le modèle.
Note : Si la documentation du modèle est dans une sous-page, seul le bouton "Ajouter le(s) paramètre(s) suggéré(s)" apparaîtra dans la page du modèle. Une solution est de modifier la page du modèle, de cliquer sur « Ajouter le(s) paramètre(s) suggéré(s) » dans l'éditeur de TemplateData et ensuite de copier-coller le contenu TemplateData (entre les balises <templatedata> et </templatedata>) dans le sous-page de documentation.
Si la page du modèle est protégée, vous pouvez copier-coller le code du modèle dans la sous-page, utiliser le bouton « Ajouter le(s) paramètre(s) suggéré(s) » ici, copier le contenu TemplateData, modifier la sous-page pour supprimer le code du modèle et ensuite coller le contenu TemplateData. Pour savoir où coller le contenu TemplateData à l'intérieur d'une sous-page, vous pouvez modifier TemplateData sans rien ajouter ; vous pouvez ensuite remplacer les balises <templatedata> et </templatedata> et leur contenu en collant par-dessus.
Vous pouvez lister le nom du paramètre, tous ses alias, l’intitulé et la description qui sera affichée pour les utilisateurs. Vous pouvez aussi proposer un exemple sur la façon d’utiliser 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 du contenu que le paramètre doit recevoir, tel qu’une chaîne (pour les messages en texte seul), une page (pour les liens vers d’autres pages), ou une date. Si le modèle produit une erreur lorsque ce paramètre n’est pas rempli, marquez ce paramètre comme « Obligatoire ». Si le paramètre est souvent utilisé ou recommandé, marquez-le comme « Suggéré ». Le bouton « Supprimer le paramètre » retire du TemplateData l’entrée concernant le paramètre.
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 « Enregistrer » sous le champ d’édition.
Attention : 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. 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.
Limitations et questions
- Fonctionnalités manquantes — TemplateData est vraiment un exemple d’outil qui a été créé avec de 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 TemplateData a été ajouté à un modèle, 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 vide sur la page du modèle lui-même (pas la sous-page de documentation). Pour faire une modification vide, 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 le gestionnaire de bugs Wikimedia.
Emplacement des TemplateData
TemplateData doit être sur la page qu'il décrit, ou être inclus dedans.
A l'intérieur d'un modèle, il doit typiquement être entouré de balises <noinclude> .
Concernant le rendu d'une page normale, il affiche la documentation générée automatiquement comme indiqué dans #Example.
Structure des TemplateData
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 wikitexte, pas de liens, etc.).
La première chose à faire est de taper une paire de balises <templatedata>, n’importe où sur la sous-page de documentation, 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
Les descriptions dans les TemplateData suivent un schéma standard ; supposons que vous ayez un modèle appelé « Commons » pour créer un lien vers une catégorie de Commons à propos d’un sujet. Il prend un paramètre obligatoire : le nom de la catégorie sur Commons. Le TemplateData ressemblerait à quelque chose comme ça :
<templatedata>
{
"description": "Un modèle pour créer un lien vers une catégorie de Commons à propos d’un article",
"params": {
"1": {
"label": "Catégorie de Commons",
"description": "La catégorie de Commons vers laquelle vous voulez créer un lien.",
"default": "Category:CommonsRoot",
"type": "string",
"required": true
}
}
}
</templatedata>
Ceci apparaîtrait, dans le modèle, ainsi :
Un modèle pour créer un lien vers une catégorie de Commons à propos d’un article
| Parameter | Description | Type | Status | |
|---|---|---|---|---|
| Catégorie de Commons | 1 | La catégorie de Commons vers laquelle vous voulez créer un lien.
| String | required |
Description et paramètres
| description | La première étiquette est une "description", qui renseigne sur ce que fait le modèle.
|
"description": "Un modèle pour créer un lien vers une catégorie de Commons",
|
|---|---|---|
| format | La suivante est "format", qui indique comment le wikitexte du modèle sera inséré. Elle peut prendre pour valeur les formats communs "inline" (défaut) et "block" ou bien un format personnalisé ; regardez plus bas pour plus de détails...
Si le paramètre est positionné à
Si le paramètre est positionné à {{Foo
| bar = baz
| qux = quux
}}
|
"format": inline
|
| params | Il y a ensuite une étiquette "params", qui indique que les sections qui suivent recouvrent chacun des paramètres du modèle.
Tous les paramètres qui suivent sont inclus dans la section |
"params": {
... // les paramètres vont ici
}
|
| Dans la sous-section de chaque paramètre, la première étiquette est le nom du paramètre du modèle, dans le modèle.
Si le paramètre a un nom, comme Si le paramètre n’a pas de nom, c’est-à-dire que c’est seulement un nombre comme Toutes les informations à propos de ce paramètre sont incluses dans la section qui commence avec le nom du paramètre. |
"1": { // nom du paramètre
... // les informations sur ce paramètre viennent ici
}
| |
| label | Ensuite, nous avons "label", dans lequel vous pouvez indiquer pour le paramètre un titre lisible par un humain, qui sera affiché dans l’éditeur de modèle.
|
"label": "Catégorie de Commons",
|
| description | Nous avons ensuite "description" : cette fois, c’est une description du paramètre, pas du modèle dans sa globalité.
|
"description": "La catégorie de Commons vers laquelle vous voulez créer un lien.",
|
| default | Ensuite vient "default". Certains modèles ont une valeur par défaut qui est utilisée si vous ne la changez pas. Cet item indique à l’utilisateur quelle est la valeur par défaut pour ce paramètre.
Vous pouvez ignorer ce paramètre s’il n’y a pas de valeur par défaut. |
"default": "Category:CommonsRoot",
|
| type | Après, nous avons "type", qui contrôle comment l’éditeur de modèle interprétera ce paramètre. Les types les plus courants sont :
Other types include |
"type": "string",
|
| required | Nous avons ensuite "required" (obligatoire), qui peut être positionné à true ou false.
Cela contrôle simplement si ce paramètre est obligatoire pour ce modèle. Si vous ne le spécifiez pas, il est supposé être à |
"required": true
|
| suggested | Nous avons ici "suggested" (suggéré), qui peut être positionné à true ou false.
C’est un statut pour les paramètres qui ne sont pas « obligatoires » mais qui sont recommandés car importants pour les utilisateurs du modèle. Si vous ne le spécifiez pas, il est supposé être à |
"suggested": true
|
| deprecated |
Enfin vient Ce statut est à utiliser pour les paramètres qui ne doivent 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.
Si vous ne le spécifiez pas, il est supposé être à |
"deprecated": "Please use 'publicationDate' instead."
|
Une fois que vous avez fini, cliquez sur « Enregistrer ». Si vous avez fait des erreurs, vous ne pourrez pas enregistrer (ce qui peut être troublant, mais garantit que vous ne pouvez rien casser). Si vous avez des erreurs, vous pouvez expliquer sur la page des retours ce que vous essayez de faire, et nous serons heureux de vous aider.
Notez que chaque information est entourée par des guillemets droits (") (sauf pour true et false), et séparée de la suivante par une virgule (à moins que ce soit la dernière).
Formats personnalisés
Lorsque vous modifiez des chaines 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.
| Objectif | Chaine de format | Rendu |
|---|---|---|
| Forme en ligne | {{_|_=_}} inline
|
{{Foo|bar=baz|qux=quux}}{{Bar}}
|
| Forme en bloc | {{_\n| _ = _\n}} block
|
{{Foo
| bar = baz
| qux = quux
}}{{Bar
}}
|
| Pas d’espace avant le nom du paramètre,
chaque modèle sur sa propre ligne. |
\n{{_\n|_ = _\n}}\n
|
{{Foo
|bar = baz
|qux = quux
}}
{{Bar
}}
|
| Indenter chaque paramètre. | {{_\n |_ = _\n}}
|
{{Foo
|bar = baz
|qux = quux
}}{{Bar
}}
|
| Aligner tous les noms de paramètres à une mesure donnée. | {{_\n|_______________ = _\n}}\n |
{{Foo
|bar = baz
|qux = quux
|veryverylongparameter = bat
}}
{{Bar
}}
|
| La barre verticale à la fin de la ligne précédente. | {{_|\n _______________ = _}}
|
{{Foo|
bar = baz|
qux = quux}}{{Bar}}
|
| Style en ligne avec plus d’espaces, doit être au début de la ligne. | \n{{_ | _ = _}}
|
{{Foo | bar = baz | qux = quux}}
{{Bar }}
|
| 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 _______________ = _}}
|
{{Foo |
bar = baz |
qux = quux}}
{{Bar}}
|
Alias de paramètres
Quelques modèles permettent qu’un même paramètre ait plusieurs noms différents.
Par exemple, {{Commons|category=Apples}} peut être écrit comme {{Commons|Apples}} ou {{Commons|link=Apples}}.
Pour ajouter cette information dans TemplateData, vous devez simplement ajouter les alias dans les informations du paramètre :
"params": {
"category": {
...
"aliases": ["1", "link"]
}
Valeur automatique
Vous pouvez spécifier une « valeur automatique » pour un paramètre. Lorsque les utilisateurs ajoutent le modèle sur une page, cette valeur sera ajoutée automatiquement. Par exemple, plusieurs modèles pour l’entretien des pages ont besoin que la date soit ajoutée ; si vous spécifiez une valeur automatique pour le paramètre date du modèle, alors la date sera complétée automatiquement.
Pour ajouter cette information dans TemplateData, ajoutez simplement la valeur automatique dans les informations du paramètre.
Il est probable que vous ayez besoin d’utiliser subst: pour faire que les valeurs soient permanentes :
"params": {
"date": {
...
"autovalue": "{{subst:CURRENTMONTHNAME}} {{subst:CURRENTYEAR}}"
}
Paramètres multiples
Si vous avez plusieurs paramètres, répétez simplement chaque section (en commençant par l'étiquette "1") et remplissez comme vous le désirez. Notez que si un modèle a plusieurs paramètres, vous devez les séparer par une virgule dans le TemplateData, comme ceci :
"params": {
"1": {
...
}, // notez la virgule ici
"2": {
...
}, // et ici
"3": {
...
}
}
Paramètres similaires
Lorsqu’un modèle a plusieurs paramètres, il est possible que certains d’entre eux soient du même type. Dans ce cas, vous n’avez besoin de remplir toutes les propriétés que pour le premier, et les autres peuvent « hériter » des propriétés de celui-ci.
"params": {
"sujet1": {
"label": "Sujet",
"description": "Un sujet mentionné sur cette page d’homonymie.",
"type": "string"
},
"sujet2": {
"inherits": "sujet1"
},
"sujet3": {
"inherits": "sujet1"
},
}
Structure vierge
Vous pouvez copier la structure vierge ci-dessous pour ajouter un nouveau TemplateData à un modèle. Seules les étiquettes les plus courantes sont présentes.
<templatedata>
{
"description": "",
"params": {
"1": {
"label": "",
"description": "",
"type": ""
},
"2": {
"label": "",
"description": "",
"type": ""
}
}
}
</templatedata>
Autres outils
- TemplateData Wizard
- Un outil qui génère un TemplateData grâce à une interface interactive.
- Skeleton TemplateData generator
- Un outil qui lit le wikicode source d’un modèle, essaye de trouver tous les paramètres utilisés et donne un squelette avec les paramètres listés.
- JSONLint
- Un outil qui vous permet de valider un JSON écrit à la main pour trouver les erreurs dans la syntaxe.
- Liste de tous les modèles avec TemplateData sur ce wiki
- Sur la version allemande de Wikipédia, avec le modèle TemplateData, les données du modèle sont affichées dans une boîte de dialogue, et le modèle est ajouté dans une catégorie des modèles avec TemplateData.
