creer-un-module.gtw

~~LANG:EN@enman:creating-a-module~~

Un module est un répertoire dans lequel il y a une arborescence précise. Les
modules sont regroupés dans un ou plusieurs répertoires que l'on appelle groupe
de modules, ou aussi dépôt de modules.

===== Déclarer un dépôt de module =====

Pour avoir accès aux modules, il faut déclarer ces dépôts de modules dans la
configuration, par la propriété @@V@modulesPath@@. On peut y indiquer plusieurs
chemins en les séparant par des virgules. On peut indiquer soit des chemins
complets, soit des chemins relatifs à un répertoire spécifique de l'arborescence
Jelix. Ces chemins relatifs ont une notation spéciale :

<code>
   coderepertoire:chemin/relatif/
</code>

@@coderepertoire@@ est un de ces codes :

; @@lib@@ : répertoire lib/ de jelix
; @@app@@ : répertoire de l'application

Cela évite d'avoir à indiquer un véritable chemin relatif. Et donc d'avoir à
changer à la fois le fichier @@F@application.init.php@@ et le fichier de
configuration quand on fait une modification dans l'arborescence, quand on migre
l'application d'un serveur à un autre (entre le développement et la production
par exemple). 

Exemple :

<code ini>
   modulesPath = lib:jelix-modules/,app:modules/
</code>

On déclare ici qu'il y a deux dépôts de modules : le premier, @@F@jelix-modules/@@,
se trouvant dans le répertoire @@F@lib/@@ de jelix; le deuxième, le répertoire
@@F@modules/@@ de l'application.

Tous les modules se trouvant dans ces deux répertoires pourront être activés
dans l'application.

===== Arborescence d'un module =====

Un module est un répertoire contenant au moins un fichier [[configuration#module.xml|module.xml]],
qui contient certaines informations à propos de ce module : version, dépendances... 

Et vous avez un certain nombre de répertoires, en fonction de ce que fourni le module, et
contenant chacun des fichiers spécifiques. Voici les répertoires possibles :

; @@F@controllers/@@ : les classes utilisées lorsque les URLs correspondantes sont appellées
; @@F@classes/@@ : classes métiers, utilitaires, listener pour les évènements...
; @@F@templates/@@ : fichier des contenus à envoyer au navigateur
; @@F@responses/@@ : objets réponses que le module peut fournir pour l'application entière
; @@F@locales/@@ : fichiers "properties", contenant les traductions pour les templates ou controleurs
; @@F@zones/@@ : classes gérant des parties de pages HTML
; @@F@daos/@@ : fichiers de mapping avec une base de données
; @@F@forms/@@ : fichiers déclarant les formulaires
; @@F@install/@@ : scripts d'installation et de mise à jour pour le module
; @@F@scripts/@@ : scripts à lancer en ligne de commandes
; @@F@plugins/@@ : plugins pour les divers composants de Jelix (jDb, jTpl...)
; @@F@www/@@ : images, CSS, fichiers Javascripts. Ces fichiers peuvent être
               utilisés par un navigateur, en appelant un contrôleur spécifique du module "jelix"
               (comme indiqué sur la page [[vues/vue-html#ajouter-des-feuilles-de-styles-fichiers-javascript-images|Générer une page HTML5]])
; @@F@tests/@@ : tests unitaires pour PHPUnit ou Simpletests.



===== Créer un module =====

Le principe : il suffit de créer un répertoire dans un dépôt, avec un nom
précis, et d'y mettre les contrôleurs, les daos et tout ce qu'il faut dans leurs
sous-répertoires respectifs.

Le plus simple est encore d'utiliser la commande @@c@createmodule@@. Dans votre
application :

<code bash>
   php cmd.php createmodule monmodule
</code>

Cela vous créé un module de nom "monmodule" dans le répertoire @@F@modules/@@ de
l'application, ainsi que l'arborescence classique d'un module et un contrôleur
par défaut.

**Important** : Le nom des modules est repris dans certaines classes générées
automatiquement par Jelix, aussi ne peut-il comporter que des caractères
autorisés par PHP pour les noms de classes : lettres minuscules, majuscules, non
accentuées, les chiffres et le caractère @@_@@.

Par défaut, le module est créé dans le répertoire @@F@modules/@@ de
l'application, mais si vous voulez le créer dans un autre dépôt de module
déclaré dans @@V@modulesPath@@, vous pouvez l'indiquer après le nom du module,
en utilisant la même syntaxe que pour @@V@modulesPath@@, à savoir un chemin
absolu ou un chemin relatif précédé de "lib:" ou "app:".

Cet exemple crée le module supermodule dans le répertoire lib/shared-modules/ 

<code bash>
   php cmd.php createmodule supermodule lib:shared-modules/
</code>

Voir l'aide en ligne de la commande @@c@createmodule@@ pour connaître d'autres
options.

===== Indiquer le numéro de version et les dépendances =====

Après avoir créer le module, vous devez vérifier que le numéro de version
initial est bon pour vous. Par défaut, c'est 0.1pre. Vous devez aussi
éventuellement indiquer les dépendances. Ces deux choses sont très importantes
pour le système d'installation de jelix.

Vous pouvez indiquer le numéro de version à la commande @@createmodule@@, grâce
à l'option @@-ver@@ :

<code bash>
php cmd.php createmodule -ver 1.0 supermodule
</code>

Vous pouvez aussi le modifier directement dans le fichier @@F@module.xml@@ de
votre module.

Vous pouvez enfin définir les dépendances de votre module. Les dépendances sont
les modules nécessaires à l'exécution du nouveau module. Dans l'élément
@@E@<dependencies>@@ dans le fichier @@F@module.xml@@, ajouter autant de balises
@@E@<module>@@ que de modules nécessaires.

<code xml>
   <dependencies>
     <jelix minversion="1.3" maxversion="1.3.*" />
     <module name="jauth" minversion="1.2" />
     <module name="anOtherModule" minversion="1.0" maxversion="1.4.*" />
   </dependencies>
</code>

Les attributs @@A@minversion@@ et @@A@maxversion@@ sont facultatifs.


Pour plus de détails sur le contenu de module.xml,
[[configuration#module.xml|lisez le chapitre correspondant]].