Help:TemplateData

From MediaWiki.org
Jump to: navigation, search
This page is a translated version of the page Help:TemplateData and the translation is 85% complete.

Other languages:
asturianu • ‎azərbaycanca • ‎български • ‎বাংলা • ‎dansk • ‎Deutsch • ‎Zazaki • ‎emiliàn e rumagnòl • ‎English • ‎español • ‎suomi • ‎føroyskt • ‎français • ‎Frysk • ‎galego • ‎hrvatski • ‎magyar • ‎Հայերեն • ‎Bahasa Indonesia • ‎Ilokano • ‎italiano • ‎日本語 • ‎ქართული • ‎한국어 • ‎Lëtzebuergesch • ‎मराठी • ‎Nederlands • ‎Oromoo • ‎polski • ‎پښتو • ‎português • ‎português do Brasil • ‎русский • ‎Scots • ‎slovenščina • ‎svenska • ‎中文
PD Note: Lorsque vous modifiez cette page, vous acceptez de libérer votre contribution en vertu de CC0. Voir Public Domain Help Pages pour plus d'informations.
PD


Qu'est-ce que TemplateData ?[edit | edit source]

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

Éditeur de TemplateData[edit | edit source]

Il y a un outil intégré pour modifier TemplateData. Il n'est peut être pas encore installé sur votre wiki.

To use the TemplateData editor, go to the template's page (or its documentation subpage) and press the "Edit" button. That will give you a button that says "Manage TemplateData", just above the open editing window:
Manage template documentation button for TemplateData 2014.png
Cliquez ce bouton pour ouvrir l'outils graphique d'édition de TemplateData.
A screenshot of the TemplateData editing tool
The editor allows you to add one row per template parameter and to set the most common attributes. If the page you edited already contains a block of TemplateData, then the information already documented will automatically be shown when you open the correct page in the TemplateData editor. In the first box, you can add or update a short description of the template in plain text. After that, you can use the "Import parameters" and "Add parameters" buttons to document the names and attributes of the parameters that the template uses. You can list the name of the parameter, any aliases for it, the label and the description that will display to users. The only required field is Name (the first field in each row), which is where you record the exact, case-sensitive name of the parameter. In the pop-up menu, you can choose the type of content that the parameter should receive, such as a string (for plain-text answers), page (for links to other pages), or dates. If the template will produce an error if this parameter is left blank, please mark it as "Required". If the parameter is commonly used or recommended, then mark it as "Suggested". The "Remove" button will delete the parameter's entry from TemplateData.
Screenshot of the TemplateData editor, showing a second parameter being added

When you are finished documenting each of the parameters, click "Apply" to insert the pre-formatted TemplateData into the open editing box. You must still save the page, using the normal "Save" button underneath the editing window.

Caution: The TemplateData editor will place TemplateData on either the template page or on a documentation subpage. You determine where the TemplateData will be added by opening (editing) the page that you want the TemplateData to be placed on. However, if multiple TemplateData blocks are placed on the same template, then only one of those TemplateData blocks will be used. If there is already TemplateData on a page, then you need to edit the page where the TemplateData was previously placed to avoid accidentally creating multiple blocks of TemplateData.

Syntaxe du TemplateData[edit | edit source]

La syntaxe du TemplateData est basé 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[edit | edit source]

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 vers laquelle vous voulez créer un lien.",
                        "default": "Category: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

Template parameters
Parameter Description Type Default Auto value Status
Catégorie de Commons 1 La catégorie de Commons que vous voulez lier. string Category:CommonsRoot empty required

Description et paramètres[edit | edit source]


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.",

Next is "default". Some templates have a default value that is used unless you change it. This item tells the user what the default value for this parameter is.

Vous pouvez ignorer ce paramètre si il n'y a pas de valeur par défaut.

                "default": "Category: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 ;
  • "number": une suite de chiffres ;
  • "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": a file name.
                "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

Finally, there is "suggested", which can be set to either true or false.

This is a status for parameters which are not 'required' but are recommended to be high value (but not mandatory) for template users. If you don't specify, it will be assumed to be false.

                "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[edit | edit source]

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"]
                }

Auto value[edit | edit source]

You can specify an "autovalue" for a parameter. When users add the template to a page, this value will be added automatically. For example, many clean-up templates need to have the date added. If you specify an autovalue for the template's date parameter, then the date will be filled in automatically.

To add this information to TemplateData, simply add the autovalue to the parameter's information:

        "params": {
                "date": {
                        ...
                        "autovalue": "{{CURRENTMONTHNAME}} {{CURRENTYEAR}}"
                }

Paramètres multiples[edit | edit source]

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[edit | edit source]

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[edit | edit source]

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": ""
                },
                "2": {
                        "label": "",
                        "description": "",
                        "type": ""
                }
        }
}
</templatedata>

Limitations et questions[edit | edit source]

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

Other tools[edit | edit source]

  • TemplateDataEditor — Un script utilisateur qui simplifie l'ajout de TemplateData. Il existe actuellement en français, est traduit en anglais, italien, japonais, coréen, ... et peut facilement être traduit dans d'autres langues.
  • TemplateData Wizard — Un outil interactif qui génère un TemplateData.
  • Skeleton TemplateData generator — Un outil qui lit le wikicode d'un modèle, cherche les paramètres utilisés et produit un squelette de TemplateData avec tous les paramètres trouvés.
  • JSONLint — Un outil qui permet de valider du JSON écrit manuellement, afin de trouver les erreurs de syntaxe.