Aide:Module

Un module est un morceau de code informatique, enregistré sur une page de l’espace Module: de Vikidia. Les fonctions de ces modules peuvent être appelées depuis le wikicode placé dans les autres espaces ; la valeur de retour de la fonction est alors interprétée par MediaWiki comme du code html. Cela en fait donc un outil puissant pour créer des modèles, qui sont à leur tour utilisés dans l’espace de l’encyclopédie ou dans les autres pages de Vikidia.

Quelques principes

Documentez tout. Sérieusement.

C’est techniquement faisable, mais on n’appelle jamais un module depuis l’espace de l’encyclopédie directement. L’espace de l’encyclopédie doit appeler des modèles, qui se chargent d’appeler les modules. Cela évite d’ajouter des éléments de syntaxe compliqués, et permet de faire évoluer les appels plus facilement. Dans certains autres espaces, il y a des cas où un module peut être appelé directement, mais ce sont des cas particuliers ; en général, il faut toujours appeler des modèles qui se chargent d’appeler les modules.

Documentez tout. Sérieusement.

Le code des modules ne peut pas être substé (c’est-à-dire, enregistré sur la page comme le wikicode qu’il produit), à l’inverse de celui des modèles. On garde donc toujours un appel au code du module, même si l’on subste le modèle qui l’appelle. Cela est une bonne chose : si l’on veut faire évoluer le code produit (améliorations du code html, utilisation d’une nouvelle fonction de MediaWiki), on le peut toujours. Cela nécessite par contre d’élaborer une stratégie si l’on veut « figer le rendu » d’un modèle substé comme avec du wikicode.

Documentez tout. Sérieusement.

Comment documenter

Dans l’espace Module:, toute sous-page appelée « Documentation » (donc, Module:Exemple/Documentation) est considérée comme étant la documentation de sa page parente (dans notre exemple, Module:Exemple). Elle n’est donc pas comprise comme du lua par MediaWiki, mais comme du wikicode habituel. Son contenu est automatiquement reproduit en haut de la page qui est documentée. La faire commencer par un appel au modèle : Sous-page de documentation.

Comme toujours en informatique, il est très important de documenter tout ce qui est fait techniquement, pour permettre à d’autres personnes de reprendre le code par la suite. Doivent être notamment répondues dans la documentation les questions : pourquoi ce code existe-t-il, comment est-ce qu’il fonctionne, quelles évolutions sont prévues ; ainsi que toutes les autres informations nécessaire à la compréhension du code et de sa logique par une personne qui débarque.

Présentation rapide

Les modules sont écrits dans un langage informatique appelé le lua. Il est possible un jour que d’autres langages soient autorisés, mais ce n’est pas fait. L’extension MediaWiki qui gère les choses est appelée Scribunto. Dans l’espace Module:, toute page qui n’est pas une documentation est considérée comme étant du code lua. Une documentation complète des fonctions offertes, en anglais, est située à la page Lua reference manual, dont la lecture est — si possible — recommandée.

Création du module

Un module standard doit renvoyer une table lua, souvent appelée p, qui contient au moins une fonction. Le module peut également contenir des fonctions locales, qui ne sont pas appelables depuis l’extérieur. Si l’on veut un petit module contenant une simple fonction appelable de l’extérieur (on peut la nommer truc par exemple) qui envoit le texte « hello world » (le hello world, c’est une tradition en informatique !), il suffit de créer une page Module:Exemple avec le code suivant.

local p = {}              -- on fabrique l’objet

function p.truc()         -- la définition de la fonction
	return "hello world"  -- le code retour de la fonction
end                       -- la fin de la fonction

return p                  -- on retourne l’objet

On documente immédiatement en créant la page Module:Exemple/Documentation.

{{Sous-page de documentation}}
Le '''module : Exemple''' est juste un exemple pour comprendre comment fonctionnent les modules sur Vikidia. Il comprend une fonction qui renvoit le texte {{"|hello world|en}}, pour une utilisation par le [[modèle : Exemple]].

Appel de la fonction

Pour appeler la fonction depuis un modèle, il faut utiliser la syntaxe {{#invoke:Nom du module|Fonction}}. Donc pour avoir un modèle (appelons-le aussi « Exemple ») qui affiche le texte « hello world », il suffit de créer le module précédent et d’inclure sur la page Modèle:Exemple le code suivant.

<includeonly>{{#invoke:Exemple|truc}}</includeonly><noinclude>{{Documentation}}</noinclude>

Bien sûr, on documente immédiatement en créant la page Modèle:Exemple/Documentation.

{{Sous-page de documentation}}
Le '''modèle : Exemple''' est juste un exemple pour comprendre comment fonctionne l’appel d’une fonction d’un module.
<includeonly>
[[Catégorie:Modèle]]
</includeonly>

On peut aussi appeler la fonction depuis un autre module, avec la syntaxe suivante.

require( 'Module:Exemple' ).truc()

Portail de l'aide —  Toutes les pages d'aide sur Vikidia.