Aide:TemplateData

Une page de Wikipédia, l'encyclopédie libre.
Aller à : navigation, rechercher
Cette page est une copie du document expliquant TemplateData disponible en français sur mediawiki.org. Il est recommandé de conserver le formatage existant afin de préserver la compatibilité des deux pages et de faciliter les mises à jour. Il est également recommandé d'effectuer les modifications directement sur mediawiki.org, sauf si elles ne s'appliquent qu'à Wikipédia en français.



Qu'est-ce que TemplateData ?[modifier | modifier le code]

TemplateData (en français, « Données des modèles ») est une façon de stocker les informations sur les paramètres d'un modèle, afin que l'ÉditeurVisuel puisse les récupérer et les afficher pour faciliter leur modification avec l'ÉditeurVisuel.

TemplateData permet aux utilisateurs d'écrire du code dans la page d'un modèle, ou dans toute page qui y est transcluse (typiquement sa documentation). Une fois que le modèle dispose des données structurées ajoutées par un utilisateur, il peut être correctement modifié via l'ÉditeurVisuel. Il ne faut pas s'effrayer du code à écrire dans la page des modèles, il est en fait très simple.

Syntaxe du TemplateData[modifier | modifier le code]

La syntaxe du TemplateData est basée sur un format JSON standard, et est vraiment simple à manipuler. Notez que toutes les descriptions du TemplateData doivent être du texte standard (pas de wikicode, pas de lien, etc.).

La première chose à faire est d'écrire une paire de balises <templatedata>, n'importe où dans la sous-page de documentation, comme ceci :

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

Cela indique au logiciel que tout ce qui est entre les balises est du TemplateData et devrait être référencé lorsque le modèle est utilisé.

Exemple[modifier | modifier le code]

Les descriptions dans les balises <templatedata> suivent une présentation uniforme. Imaginons que vous ayez un modèle appelé « Commons » pour lier un sujet vers une catégorie de Commons. La données du TemplateData devraient ressembler à quelque chose comme ça :

<templatedata>
{
        "description": "Modèle pour lier un sujet vers une catégorie de Commons",
        "params": {
                "1": {
                        "label": "Catégorie de Commons",
                        "description": "La catégorie de Commons que vous voulez lier.",
                        "default": "Catégorie:CommonsRoot",
                        "type": "string",
                        "required": true
                }
        }
}
</templatedata>

Le résultat qui s'afficherait alors dans la documentation ressemble à ceci :

Modèle pour lier un sujet vers une catégorie de Commons

Paramètres du modèle
Paramètre Description Type Par défaut Valeur automatique Statut
Catégorie de Commons 1 La catégorie de Commons que vous voulez lier. string Catégorie:CommonsRoot vide obligatoire

Pour un exemple concret, comparez les paramètres de Modèle:Escalade ascensions notables et le TemplateData associé.


Description et paramètres[modifier | modifier le code]


La première étiquette se nomme "description", et décrit ce que le modèle fait.
"description": "Modèle pour lier un sujet vers une catégorie de Commons",

Il y a ensuite l'étiquette "params", qui sert à introduire la liste des paramètres du modèle.

Toutes les étiquettes qui suivent seront incluses dans la section introduite par "params".

"params": {
        ...            <-- les paramètres vont ici
    }

Pour chaque sous-section d'un paramètre, la première étiquette est le nom du paramètre du modèle présent dans le code source du modèle.

Si le paramètre a un nom, comme {{{lien catégorie}}}, cette étiquette serait "lien catégorie".

Si le paramètre est sans nom, c'est-à-dire s'il est juste un nombre comme {{{1}}}, l'étiquette serait "1".

Tous les fragments d'information à propos du paramètre sont incluses dans la section qui commence avec son nom.

        "1": {                 <-- nom du paramètre
            ...            <-- les informations à propos du paramètre vont ici
        }

Ensuite, nous avons "label", dans lequel vous mettez un titre lisible pour le paramètre qui sera affiché dans l'éditeur de modèle.
            "label": "Catégorie de Commons",

Nous avons ensuite l'étiquette "description" : cette fois, il s'agit de la description du paramètre, pas de celle du modèle.
            "description": "La catégorie de Commons que vous voulez lier.",

Le paramètre suivant est "default", qui sert à préciser la valeur par défaut pour le paramètre.

S'il n'y a pas de défaut, il suffit de ne pas ajouter le paramètre "default".

            "default": "Catégorie:CommonsRoot",

Après, nous avons "type", qui permet à l'éditeur du modèle de savoir comment il interprètera le paramètre. Ce peut être :
  • "string" : une séquence de caractères, comme cette phrase ;
  • "line" : une courte séquence de caractères, sur une ligne ;
  • "number" : une suite de chiffres ;
  • "content" : wikitexte, pouvant contenir des liens, images...
  • "wiki-user-name" : une suite de caractères qui représentent un nom d'utilisateur ;
  • "wiki-page-name" : une séquence de caractères qui représentent un titre de page.
  • "wiki-file-name" : une séquence de caractères qui représentent le nom d'un fichier.
  • "boolean" : texte qui sera interprété comme valeur oui ou non.
            "type": "string",

Vient "required", qui peut prendre comme valeur true ou false.

Cela sert simplement à contrôler si le paramètre rempli est obligatoire pour ce modèle.

            "required": true

"suggested" peut aussi prendre comme valeur true ou false.

Alternative à "required" si le paramètre rempli est suggéré pour ce modèle, c'est à dire non obligatoire, mais souvent utilisé, donc automatiquement proposé par l'éditeur visuel.

            "suggested": true

Une fois que vous avez fini de remplir les champs, cliquez sur « Publier ». Si vous avez fait des erreurs, la sauvegarde n'aura pas lieu (cela peut paraître perturbant, mais c'est avant tout une sécurité).

Si vous rencontrez des anomalies, expliquez sur la page de retour d'expérience ce que vous essayiez de faire, et nous serons heureux de vous aider.

Notez que chaque fragment d'information est entouré de guillemets anglais (sauf pour true et false), et séparé du texte par une virgule (à moins que le fragment d'information en question soit le dernier de la liste).

Alias des paramètres[modifier | modifier le code]

Certains modèles autorisent différents noms pour un même paramètre.

Par exemple, {{Commons|catégorie=Pommes}} pourrait aussi être écrit {{Commons|Pommes}} ou {{Commons|lien=Pommes}}.

Pour ajouter cette information au TemplateData, vous devez simplement ajouter les alias aux informations relatives au paramètre :

        "params": {
                "catégorie": {
                        ...
                        "aliases": ["1", "lien"]
                }

Paramètres multiples[modifier | modifier le code]

Si le modèle a plusieurs paramètres, il suffit de répéter l'opération avec d'autres sections (juste après la section pour le paramètre "1") et de les remplir comme bon vous semble. Notez que si un modèle a plusieurs paramètre, vous devez les séparer par une virgule dans le <templatedata>, comme ceci :

        "params": {
                "1": {
                        ...
                },                     <-- remarquez la virgule ici
                "2": {
                        ...
                },                     <-- et ici
                "3": {
                        ...
                }
        }

Paramètres similaires[modifier | modifier le code]

Parfois, quand un modèle a plusieurs paramètres, certains d'entre eux peuvent contenir les mêmes informations. Dans ce cas, vous avez seulement besoin de fournir l'ensemble des informations pour le premier d'entre eux, et les autres pourront « hériter » leurs informations de celui-ci.

        "params": {
                "sujet1": {
                        "label": "Sujet",
                        "description": "Un sujet mentionné sur cette page d'homonymie",
                        "type": "string",
                },
                "sujet2": {
                        "inherits": "sujet1"
                },
                "sujet3": {
                        "inherits": "sujet1"
                },
        }

Patron à copier[modifier | modifier le code]

Vous pouvez copier le patron ci-dessous pour ajouter de nouvelles métadonnées TemplateData à un modèle. Il contient les informations les plus courantes.

<templatedata>
{
        "description": "",
        "params": {
                "1": {
                        "label": "",
                        "description": "",
                        "type": "",
                        "required": 
                },
                "2": {
                        "label": "",
                        "description": "",
                        "type": "",
                        "required": 
                }
        }
}
</templatedata>

Limitations et questions[modifier | modifier le code]

  • Fonctionnalités manquantes — TemplateData est un très bon exemple d'outil qui a été mis en place avec peu de fonctionnalités, en espérant que les utilisateurs aideront à guider au développement de ce dernier en fonction des besoins. Si vous voulez demander de nouvelles fonctionnalités pour TemplateData, merci de nous le faire savoir.
  • Retards d'affichage dans les modèles — Après avoir ajouté TemplateData à un modèle, les métadonnées devraient être visibles immédiatement quand le modèle est modifié via l'ÉditeurVisuel. Cependant, il est possible qu'il faille plusieurs heures avant que les métadonnées apparaissent. Vous pouvez forcer la mise à jour en faisant une « modification vide » sur la page du modèle lui-même (pas sur la sous-page de documentation). Pour effectuer une « modification vide », il suffit simplement de cliquer sur « Modifier » dans la page du modèle, puis de publier sans faire aucun changement.
  • Problèmes actuels — Une liste des anomalies actuelles et des fonctionnalités demandées est disponible dans Bugzilla.

Outils[modifier | modifier le code]

  • TemplateDataEditor — Un programme en javascript qui permet d'ajouter TemplateData plus facilement.
  • TemplateData Wizard — Un programme de génération du JSON avec interface interactive.
  • JSONLint permet de valider le JSON écrit manuellement pour aider à trouver les erreurs de syntaxe.