Voir la source de Modèle:Méta documentation de modèle/Documentation

{{Sous-page de documentation}}
{{Modèle utilisant les modules Lua|Module:Documentation}}
{{Modèle utilisant TemplateStyles|Méta documentation de modèle/styles.css}}
<nowiki>{{</nowiki>'''Méta documentation de modèle'''<nowiki>}}</nowiki> est un méta-modèle pour la création de modèles de [[Aide:Documentation de modèle|documentation]] affichant une boîte verte (comme celle contenant le texte que vous lisez actuellement).

== Fonctionnement ==
Ce modèle est basé sur le module [[Module:Documentation|Documentation]]. L'affichage est constitué d'un titre affiché en haut, de la documentation elle même, et d'une notice affichée en bas.

Le contenu de la documentation est généré depuis différentes sources :
* Le contenu de la documentation est obtenu depuis la sous-page <code>/Documentation</code>, sauf si le paramètre <code>contenu</code> est renseigné. C'est alors sa valeur qui est utilisée.
* Le paramètre <code>page doc</code> permet de cibler une page de documentation différente de la sous-page <code>/Documentation</code>, par exemple pour mutualiser une page entre plusieurs modèles.
* Il est possible de définir un contenu automatique pour la documentation, qui s'affichera sur toutes les pages utilisant le modèle, en utilisant les paramètres <code>contenu auto haut</code> et <code>contenu auto bas</code>. Leur valeur sera alors affichée respectivement au dessus et en dessous du contenu, qu'il provienne de la sous-page de documentation ou du paramètre <code>contenu</code>.

Différents bandeaux sont affichés en fonction du contexte :
* Si le modèle est protégé, un bandeau décrivant la protection est affiché. Le paramètre <code>message protection</code> permet de modifier le titre de celui-ci. Une icône de titre est également placée en haut de la page.
* Lorsque le modèle est un bac à sable, il ajoute automatiquement le modèle {{m|Sous-page de bac à sable}} en haut de page.
* En l'absence de contenu pour la documentation, c'est-à-dire lorsqu'il n'y a ni sous-page de documentation ni valeur fournie paramètre <code>contenu</code>, un bandeau incitant à création de celle-ci est affiché, et le modèle est placé dans la {{Catégorie|Modèle sans documentation}}. Si les paramètres <code>contenu auto haut</code> ou <code>contenu auto bas</code> sont renseignés et jouent déjà ce rôle, il est possible de fournir le paramètre <code>contenu facultatif</code> (avec n'importe quelle valeur) pour éviter l'affichage du bandeau. Ce bandeau n'est pas affiché si le modèle ne permet de définir du contenu (utilisation du paramètre <code>aucun contenu additionnel</code>.)

Enfin, des liens sont également générés automatiquement :
* En l'absence de contenu pour la documentation, un lien [créer] est affiché, qui permet de débuter la création de la page en préchargeant le format de page de documentation de base.
* Des liens disponibles au bas de la notice permettent également de créer les sous-pages /Bac à sable et /Test.

== Quand utiliser ce méta-modèle ? ==
Pour documenter un modèle seul, il vaut mieux utiliser directement le modèle {{m|Documentation}} associé à une sous-page de documentation. Lorsqu'une poignée de modèles doivent utiliser une documentation commune, le plus simple est de créer une page de documentation, et de la référencer sur tous ces modèles à l'aide du paramètre <code>1</code> du modèle {{m|Documentation}}.

Il devient utile de disposer d'un modèle de documentation spécifique lorsque de nombreux modèles doivent avoir la même documentation, ou que plusieurs modèles doivent utiliser la même documentation mais que celle-ci contient des paramètres propres à chaque modèle. Dans ce cas, il faut créer un modèle de documentation spécifique faisant appel au modèle '''Méta documentation de modèle'''.

== Comment utiliser ce méta-modèle ? ==
Lorsque l'utilisation d'un modèle de documentation spécifique est nécessaire, il faut alors créer un modèle faisant appel au modèle '''Méta documentation de modèle'''. Dans ce cas, ce modèle doit comporter le contenu suivant :
* Renseigner le paramètre <code>nom modèle</code> pour générer automatiquement la notice du modèle.
* Optionnellement, renseigner le paramètre <code>titre</code>, qui fournit la valeur du titre à indiquer en tête du modèle de documentation. Par défaut, le titre affiche '''Documentation'''.
* Renseigner les paramètres <code>contenu auto haut</code> et/ou <code>contenu auto bas</code>, qui doivent contenir le texte à afficher automatiquement dans la documentation.
* Si un contenu supplémentaire doit pouvoir être ajouté au modèle :
** Ajouter le paramètre <code><nowiki>contenu = {{{contenu|}}}</nowiki></code> pour permettre d'ajouter un contenu entre <code>contenu auto haut</code> et <code>contenu auto bas</code>. En l'absence de ce paramètre, le contenu de la sous-page de documentation s'affichera automatiquement.
** Éventuellement, ajouter le paramètre <code>contenu facultatif = oui</code> si la documentation est complète sans que l'on ait obligatoirement à renseigner un paramètre <code>contenu</code> ou une sous-page de documentation, qui sont alors facultatifs.
* Si au contraire on souhaite ne pas permettre de définir de contenu supplémentaire, il faut ajouter le paramètre <code>aucun contenu additionnel = oui</code>.
* Enfin, on peut ajouter les paramètres <code><nowiki>page doc = {{{page doc|}}}</nowiki></code> et/ou <code><nowiki>message protection = {{{message protection|}}}</nowiki></code> pour permettre de personnaliser ces éléments (voir la liste des paramètres ci-dessous pour le détail de leur comportement).

== Paramètres ==
Il faut différencier les méta-paramètres, destinés à être utilisés directement par les modèles qui utilisent ce méta-modèle, et les paramètres, qui sont destinés à l'usage final et que les modèles peuvent se contenter de transmettre.

=== Liste des paramètres ===
Ces paramètres peuvent être transmis par les modèles qui utilisent ce méta-modèle, pour utilisation dans l'inclusion finale.
* <code>contenu</code> : Contenu brut à afficher dans la documentation. Remplace le contenu affiché depuis la sous-page si elle existe.
* <code>page doc</code> : Indique la page de documentation à charger si elle est différente de la sous-page <code>/Documentation</code>. Permet de mutualiser une sous-page de documentation entre plusieurs modèles.
* <code>message protection</code> : Personnalise le titre du bandeau de protection si le modèle est protégé.

=== Liste des méta-paramètres ===
Ces paramètres sont destinés uniquement aux modèles de documentation qui utilisent ce méta-modèle. Ils ne doivent pas être transmis pour utilisation finale.
* <code>nom modèle</code> : À renseigner avec le nom du modèle de documentation (sans le préfixe <code>Modèle:</code>). Utilisé pour afficher un lien vers celui-ci dans la notice.
* <code>titre</code> : Permet de personnaliser le titre du modèle de documentation. En son absence, le titre est simplement '''Documentation'''.
* <code>contenu auto haut</code> : Ajoute un contenu au-dessus du contenu de la documentation.
* <code>contenu auto bas</code> : Ajoute un contenu en dessous du contenu de la documentation.
* <code>aucun contenu additionnel</code> : Si renseigné, le modèle ne permettra pas d'ajouter de contenu supplémentaire au texte qu'il définit. Une éventuelle sous-page de documentation sera ignorée.
* <code>contenu facultatif</code> : Indique que la présence d'un contenu de documentation n'est pas obligatoire pour éviter l'affichage du bandeau. À ne renseigner que si le paramètre <code>contenu auto haut</code> ou le paramètre <code>contenu auto bas</code> remplissent déjà ce rôle.

=== Template data ===
<templatedata>
{
	"params": {
		"page doc": {
			"description": " Spécifie le nom d'une page de documentation à utiliser différente, qui peut être partagée par plusieurs modèles",
			"type": "string"
		},
		"contenu": {
			"description": " Spécifie le contenu de la documentation, pour qu'il soit directement inclus dans le corps du modèle. Ne pas utiliser si vous voulez créer une sous page.",
			"type": "string"
		},
		"message protection": {
			"description": " Modifie le titre du bandeau ajouté lorsque la page est en protection complète.",
			"type": "string"
		},
		"nom modèle": {
			"description": "Méta-paramètre : à renseigner avec le nom du modèle de documentation.",
			"type": "string"
		},
		"titre": {
			"description": "Méta-paramètre : modifie le titre de la documentation.",
			"type": "string"
		},
		"contenu auto haut": {
			"description": "Méta-paramètre : ajoute un contenu statique au dessus du contenu.",
			"type": "string"
		},
		"contenu auto bas": {
			"description": "Méta-paramètre : ajoute un contenu statique en-dessous du contenu.",
			"type": "string"
		},
        "aucun contenu additionnel": {
			"type": "string",
			"description": "Renseigner à n'importe quelle valeur pour indiquer que le modèle ne doit pas permettre d'ajouter un contenu au texte qu'il définit."
		},
		"contenu facultatif": {
			"type": "string",
			"description": "Renseigner à n'importe quelle valeur pour indiquer que la présence d'un contenu de documentation n'est pas obligatoire. À ne renseigner que si le paramètre <code>contenu auto haut</code> ou le paramètre <code>contenu auto bas</code> remplissent déjà ce rôle."
		}
	},
	"description": "Ce modèle est un méta-modèle pour la création de modèles de documentation."
}
</templatedata>

== Voir aussi ==
* [[Aide:Documentation de modèle]]
* {{m|Documentation}}
* [[Module:Documentation]]

<includeonly>
[[Catégorie:Modèle de documentation|*]]
[[Catégorie:Méta-modèle|Documentation]]
</includeonly>