Aide:Créer un modèle

Aide de Wikipédia Créer un article, un modèle

Cette page ne concerne que le wikicode (liens « modifier le code »).

Niveau avancé

Nous vous recommandons de lire auparavant Aide:Modèle

Cette page explique comment créer un modèle, comment le documenter et montre les possibilités techniques. Avant de créer un nouveau modèle, il faut s’assurer qu’un modèle équivalent n’existe pas sous un titre différent.

La méthode de création d’un modèle est similaire à celle de la création d’une page. Le nom de la nouvelle page doit commencer par « Modèle: » (Modèle:Nom du modèle) et peut contenir des espaces. Le plus simple est d’insérer un appel au modèle dans une page, puis de cliquer sur le lien qui apparaîtra en rouge ; l’appel s’effectue en tapant le code {{Nom du modèle}}.

Un modèle peut inclure un ou plusieurs autres modèles. Les redirections entre modèles fonctionnent.

Créez votre page Mon modèle (pour vous entraîner à la création des modèles). Pour l'utiliser, ajoutez {{Utilisateur:Monpseudo/Mon modèle}} à votre page utilisateur. Il vaut mieux travailler sur une page de brouillon pour éviter les effets de bord désagréables pour les visiteurs.

Il est nécessaire de documenter les modèles en utilisant un TemplateData pour que les autres utilisateurs n'aient pas à regarder le code source pour trouver les paramètres.

Un modèle est un outil partagé par tous ceux qui souhaitent l’utiliser. Il est donc indispensable de fournir une documentation expliquant : à quel besoin le modèle répond, dans quels cas il est adapté / inadapté, ce qu’il fait et comment il doit être utilisé.

Se reporter à la page Comment documenter un modèle ? qui explique comment procéder.

  Se rendre sur le Projet:Modèle 

Si vous avez besoin de l’aide d’utilisateurs expérimentés pour fabriquer un nouveau modèle, vous pouvez déposer une requête sur la page Projet:Modèle/Demandes.

Comme vous pourrez le remarquer, certains modèles complexes font appel à un langage informatique particulier. Pour plus de détails sur les caractères spéciaux en langage html, les ParserFunctions ou les mots magiques voir aide à la syntaxe.

Un modèle peut dépendre de paramètres (ou arguments) extérieurs. Par exemple, le modèle {{Coord}} qui permet de placer des coordonnées géographiques, nécessite au moins deux paramètres : la latitude et la longitude.

Les paramètres sont spécifiés à l'inclusion, et suivent le nom du modèle ; ils sont isolés par des séparateurs « | » (la liste des paramètres se terminant donc par « }} ») : {{Nom du modèle|paramètre1|paramètre2…}}.

Sur la page du Modèle:, ils sont désignés entre triples accolades : {{{paramètre 1}}}. Prenons par exemple la page fictive [[Modèle:Modèle de chose]] qui contiendrait :

La '''{{{objet}}}''' est un {{{type}}}.

Si vous effectuez l’appel :

{{modèle de chose
| objet = pomme
| type = fruit
}}

Les paramètres seront « remplacés » par leur valeur (la valeur pomme sera attribuée au paramètre objet) et le modèle affichera :

La pomme est un fruit.

Il ne doit pas y avoir de retour à la ligne dans une valeur, mais <br> est permis. Une valeur peut être un lien externe ou interne (la syntaxe des liens wiki est possible : [[page visée|texte qui apparaîtra]]).

Afin d’améliorer la lisibilité, des retours à la ligne peuvent apparaître dans l'appel au modèle (comme ci-avant).

Par défaut, les paramètres sont désignés par leur nombre ordinal (ou rang), ils sont numérotés à partir de 1 dans leur ordre d’apparition dans l'appel. Le paramètre 2, exprimé par le code {{{2}}}, fait référence à la valeur du deuxième paramètre.

Pour reprendre l'exemple du [[Modèle:Modèle de chose]], présenté précédemment, et pour obtenir le même résultat, il faut procéder de la manière suivante :

Autre exemple, le modèle {{Annonce}} utilise un paramètre 1 et un paramètre 6 de cette manière : [[Fichier:{{{1}}}|20px|{{{6}}}]] qui s’interprète comme : « afficher l’image qui a pour nom la valeur du 1^er paramètre, avec une taille de 20 pixels, et avec comme nom d'affichage la valeur du 6^e paramètre ».

Une aide est certainement nécessaire pour expliquer la signification de ces paramètres.

Note : Contrairement à ce qui se passe pour les paramètres nommés, les espaces, retours chariots, sauts de ligne, tabulations… au début et à la fin des paramètres positionnels ne sont pas automatiquement enlevés. Pour les supprimer, il faut utiliser le modèle {{trim}}.

L’usage de modèles peut être facilité par des paramètres nommés ; cette pratique est aussi recommandée pour faciliter le contrôle par des robots.

Pour nommer un paramètre, il suffit d’utiliser un nom représentatif de son rôle (au lieu des noms par défaut 1, 2, 3…) en précisant un couple paramètre=valeur. Par exemple, le code {{Avancement|42}} n'est pas très explicite ; {{Avancement|pourcentage=42}} serait plus clair.

Dans le code source du modèle « Avancement », il suffit d'utiliser {{{pourcentage}}} en lieu et place de {{{1}}}.

On peut appeler les paramètres nommés dans n’importe quel ordre.

Note : Les espaces, retours chariots, sauts de ligne, tabulations, … au début et à la fin des paramètres nommés sont automatiquement enlevés.

On a vu que le signe « = » permet d'associer un paramètre et une valeur. Mais il est possible que l'on veuille utiliser « = » dans une valeur (par exemple si on veut utiliser une URL).

• Pour les paramètres explicites, {{MonModèle|paramètre=aaa=bbb}} associe bien la valeur « aaa=bbb ».
• Pour les paramètres implicites, il faut les rendre explicites. Par exemple, dans {{MonModèle|1=aaa=bbb}}, le paramètre implicite « 1 » est explicité.

Le | permet de séparer les paramètres. Pour que la valeur d'un paramètre puisse contenir « | », il faut passer par le modèle {{!}} pour le remplacer, afin d'éviter la confusion.

Par exemple, {{Mon modèle|paramètre1=truc{{!}}machin…}}.

Si un paramètre n'a pas de valeur spécifiée, la valeur restituée est « le code lui-même » (le code {{{1}}} sera « remplacé » par le texte affiché non interprétable {{{1}}}). (Rq : pour les appels imbriqués voir infra).

Le concepteur peut définir une valeur par défaut qui sera utilisée dans ce cas, en suivant la syntaxe : {{{param|123}}} dans le modèle (que l'on peut lire : « Si le paramètre param est absent, le code est fait pour utiliser 123 à la place. »). Un tel paramètre est alors dit facultatif.

Il est possible de ne rien définir pour la valeur par défaut en n’écrivant rien après la barre verticale : {{{param|}}}.

La valeur d'un paramètre facultatif ne renvoyant rien peut aussi être dite vide (nulle ou de taille 0); Si on a rien écrit dans l'appel du modèle après la barre verticale de position (paramètre implicite), ou bien rien après le signe « = » (paramètre nommé). Exemple : {{Mon modèle|}} ou {{Mon modèle|monparamètre=}}.

Pour définir la valeur par défaut d'un paramètre absent ou vide il faut utiliser la syntaxe suivante dans le modèle avec une parser function (voir infra).

{{#if: {{{param|}}} | {{{param}}} | <valeur-par-défaut>}} (que l'on peut lire : « Si^[1] le paramètre param est absent ou vide, utiliser <valeur-par-défaut> à la place. »).

En imbriquant les paramètres {{{paramètre1|{{{paramètre2|...}}} }}}, un modèle peut établir une séquence de sélection ordonnée des valeurs.

Par exemple, le modèle fictif Monmenu qui est un « Menu fromage ou dessert » comporte l'imbrication {{{fromage|{{{dessert|ni fromage ni dessert}}} }}} :

• L'appel {{monmenu|fromage=camembert}} retournera le texte « camembert », de même que {{monmenu|fromage=camembert|dessert=pomme}}.
• L'appel {{monmenu|dessert=pomme}} retournera le texte « pomme ».
• L'appel {{monmenu}} retournera le texte « ni fromage ni dessert ».

Ce sont des balises XML propres au wikicode permettant de sélectionner une partie du code source d’une page. Il est utile de pouvoir placer certains éléments du code source du modèle, comme la documentation ou la catégorisation du modèle, sans que ces éléments apparaissent sur les pages où le modèle est inséré.

Pour cela, on place les éléments à exclure entre des balises <noinclude> et </noinclude>.

Par exemple, un modèle contenant :

''(contenu {{{1|}}} à compléter…)''

et qui affiche ceci dans l’article qui l’inclut :

Doit (au minimum) être complété d’une catégorie spécifique à la catégorisation de modèles et d'une documentation (directement ou en sous-page). Mais tout cela n'est pas destiné aux articles qui incluent ce modèle.

On ajoute donc des balises <noinclude> et </noinclude> autour de ce genre de contenu :

''(contenu {{{1|}}} à compléter…)''<noinclude>
{{Documentation}}
[[Catégorie:Modèle de formatage]]
</noinclude>

Notez ci-avant l’absence de tout espace ou saut de ligne entre le code du modèle et la balise <noinclude>. Il ne faut jamais ajouter d'espace ou de saut de ligne avant la séquence <noinclude>, car ils seraient conservés à l’inclusion du modèle et pourraient nuire à la présentation de son contenu (par exemple un créant un paragraphe vide).

Ainsi :

• sur la page du modèle, les catégories apparaîtront, exactement comme si les deux balises <noinclude> et </noinclude> n’agissaient pas ;
• lorsque le modèle est inclus dans un article par le code {{Exemple}}, seule la ligne « ''(contenu {{{1|}}} à compléter…)'' » sera incluse, car cette ligne est située en dehors des <noinclude>...</noinclude>.

Pour les modèles produisant un contenu à partir de paramètres, il est généralement souhaitable d'empêcher l'affichage automatique du modèle quand on consulte la page du modèle, car cela produit souvent par effet de bord un résultat non pertinent, incompréhensible ou affiche un message d'erreur. Cela est typiquement utilisé par des modèles comme les infobox.

On peut donc placer le code du modèle (sans la documentation et la catégorisation du modèle) entre des balises <includeonly>...</includeonly>.

Il est alors impératif de documenter le modèle avec au moins un exemple de ce qu'affiche le modèle quand utilisé avec ses paramètres habituels. Dans le cas contraire, il n'y a alors aucun moyen de voir ce qu'il affiche.

<includeonly>(contenu {{{1|}}} à compléter…)</includeonly><noinclude>
{{Documentation}}
[[Catégorie:Modèle de formatage]]
</noinclude>

Notez également que pour ces deux systèmes de balises :

• <noinclude>...</noinclude> et
• <includeonly>...</includeonly>,
  il n'y a aucun saut de ligne ou espace intermédiaire entre les balises, pouvant interrompre une liste à puces, provoquer une rupture de paragraphe ou créer des vides indésirables.

Les alias permettent d'utiliser des noms différents pour le même paramètre.

{{#if: {{{<nom du champ>|{{{<alias du champ>|}}}}}}|<ce que renvoie le champ>}} — dans ce que le paramètre renvoie, la variable prend donc la forme {{{<nom du champ>|{{{<alias du champ>}}}}}}

Les parser functions sont des modèles « analyseurs » ; en anglais : parser. Ils permettent d’effectuer certaines fonctions d'analyse sur les paramètres passés à l'utilisation du modèle. Les plus courantes sont les branchements conditionnels #if: et #switch:.

Un exemple où les valeurs possibles d’un paramètre sont connues et en nombre limité :
si l’utilisateur donne la valeur 4 au paramètre positionnel 1 à l'appel d'un modèle contenant le code suivant : [[Fichier:{{#switch:{{{1|4}}}|0=00|1=25|2=50|3=75|4=100}}%.svg]] (Rq : ici l'argument 1 de la fonction switch est déclaré avec valeur par défaut 4),
l’image affichée sera l’icône Fichier:100 percent.svg →

Il est parfois nécessaire de connaitre le nom de la page-appelante, faire une manipulation de chaîne de caractère transmise ... Pour plus de détails, voir sur le site de MediaWiki :   Parser Functions .

Pour créer un modèle non encyclopédique (destiné à être appelé par une page utilisateur ou pour faire des tests), nul besoin de « polluer » l’espace des modèles. Cela peut se faire sur une sous-page utilisateur de manière tout à fait similaire.

Par exemple, si Utilisateur:Quidam veut tester un modèle appelé « Article fastidieux », il procède comme suit :

• Il crée une sous-page utilisateur Utilisateur:Quidam/Article fastidieux dans laquelle il écrit le modèle :

<div style="border: 1px solid black; background: rgb(80%,100%,80%); text-align: center; padding: 0.4ex;">
 ''Ceci est un article fastidieux. Le taux d’ennui est estimé à {{{ennui}}} %.''</div>

• Il l’utilise ensuite en tapant :

{{Utilisateur:Quidam/Article fastidieux|ennui=55}}

Ce qui donne :

D’une façon générale, la syntaxe d’appel d’un modèle {{espace de noms:nom de modèle|paramètre1=valeur1 …}} reconnaît la présence de l’espace de noms qui, ici, ne prend pas la valeur par défaut Modèle:. Les paramètres peuvent ainsi être nommés explicitement, ou implicitement.

Si vous voulez qu'un Modèle:Modèle1 ne soit pas substitué dans un Modèle:Modèle2, mais que le Modèle:Modèle1 soit substitué dans la page où vous substituerez le Modèle:Modèle2, vous devez placer dans le Modèle:Modèle2 le code suivant :

{{<includeonly>subst:</includeonly>Modèle2}}

De cette manière, vous repoussez le processus de substitution du Modèle:Modèle1 dans le Modèle:modèle2, processus qui se produira à chaque fois que vous substituerez Modèle:modèle2 dans une page.

Exemple :

Imaginons que vous vouliez créer un modèle qui dise

« À l'instant où je publie cette page il est : indication de l'heure exacte »

Il existe une manipulation qui permet d'indiquer l'heure au moment de la publication, il s'agit de {{subst:CURRENTTIME}}.

Utilisons pour notre exemple le modèle Modèle:Bac à sable et Aide:Bac à sable :

• Dans Modèle:Bac à sable copiez et publiez le code suivant :

À l'instant où je publie cette page il est : {{<includeonly>subst:</includeonly>CURRENTTIME}}

• Dans Aide:Bac à sable copiez {{subst:Bac à sable}}.

Grâce à l'imbrication de {{<includeonly>subst:</includeonly>CURRENTTIME}} dans Modèle:Bac à sable, vous obtiendrez ce que vous désirez dans Aide:Bac à sable ! Si vous n'aviez pas « cassé » {{subst:}}, le modèle {{CURRENTTIME}} se serait substitué dans Modèle:Bac à sable : vous auriez eu l'heure de publication de la page Modèle:Bac à sable et non celle de la page Aide:Bac à sable.

• Cet article est partiellement ou en totalité issu de l'article intitulé « Aide:Modèle » (voir la liste des auteurs).