Raccourcis : Contenu - rubriques - sous rubriques
EN FR
La page correspondant à la dernière version stable est consultable dans le Manuel Jelix 1.8

Cette section ne concerne pas les modules fraîchement créés avec la commande dev.php module:create, puisque celle-ci les active automatiquement et les installe.

Par contre, pour utiliser un module existant fourni avec jelix ou installer un module tiers, il faut suivre les instructions de ce chapitre.

Déclarer le répertoire d'un module

Dans le chapitre sur la création des modules, nous avons vu que nous pouvions déclarer les répertoires (groupes de modules) où se trouvent des modules, dans le fichier application.init.php.


jApp::declareModulesDir(__DIR__.'/vendor-modules/');

Il est possible d'avoir un module en dehors d'un groupe de module (par exemple dans un paquet Composer). On peut alors indiquer directement son chemin dans le fichier application.init.php.


jApp::declareModule(__DIR__.'/somewhere/mymodule/');

Une autre possibilité est de déclarer le chemin du module dans la configuration de l'application. C'est fait dans la section modules, avec le paramètre *.path. Par exemple :


[modules]
my_module.path = app:vendor/my_vendor_name/my_package/the_module

Cela facilite la migration depuis Jelix 1.6.x, et est utile pour déclarer un module tiers depuis un script de configuration.

Activation et configuration d'un module

Il ne suffit pas d'avoir un module dans un dépôt de module pour que celui-ci soit utilisable directement. Il faut aussi l'activer et le configurer avant de pouvoir lancer l'installateur et en profiter dans l'application. Ceci pour améliorer la sécurité et éviter des dysfonctionnements. En effet, il se peut que vous ayez un dépôt de modules partagé par plusieurs applications, et vous ne voulez pas forcément que certains de ses modules soient utilisables par votre application.

Pour configurer le module, il faut lancer le configurateur de Jelix. Cela se fait au moyen de la commande module:configure en lui indiquant son nom (ici mymodule) :


php dev.php module:configure mymodule

Cela indique dans la section [modules] du fichier mainconfig.ini.php que le module est activé, via une propriété .enabled : mymodule.enabled = 1.

De plus cela lance le configurateur du module si il en possède un. Ce configurateur peut modifier la configuration pour ajouter des paramètres propres au module. Il peut vous demander interactivement des valeurs de paramètres de configuration. Il peut aussi installer des fichiers dans divers répertoires si nécessaire (typiquement des fichiers css et js dans www/).

Si le module a des dépendances, le configurateur de Jelix activera ces modules dépendants et lancera leurs configurateurs.

Bien sûr, si vous avez plusieurs points d'entrée, vous avez alors forcément des modules accessibles par certains points d'entrées et pas par d'autres. Il ne faudra alors pas oublier de configurer correctement le moteur d'url, afin que les urls générées par Jelix utilisent bien le point d'entrée associé à chacun des modules.

Note : dans Jelix 1.6 et précédent, l'activation se faisait au moyen d'une propriété access au lieu de enabled dans la configuration. Cette propriété n'est plus utilisée, et normalement a été renommé par l'outil de migration de Jelix.

Paramètres d'installation

Un module peut avoir un script pour son installation dans une instance de votre application, et ce script peut avoir besoin de paramètres. Ces paramètres peuvent être indiqués dans une option spécifique de la section "modules" : themodule.installparam=something. Un exemple pour un module "news":


   news.installparam = "enablecategories;defaultcategory=In the world"

Les paramètres, séparés par un point virgule, peuvent être de simples mot-clefs, ou des clés/valeurs. La valeur pour un mot clef peut être une liste de valeurs : celles-ci sont alors séparées par des virgules.

Il y a de forte chance pour que le configurateur du module (que vous lancez avec module:configure) vous demande les valeurs de ces paramètres, et donc génère cette propriété installparam automatiquement.

Installation d'un module

L'activation et la configuration du module est une étape faîte par le développeur, une seule fois au moment de l'intégration du module dans l'application, tandis que le lancement de l'installateur se fait sur chaque instance de l'application par leurs administrateurs.

Que ce soit les développeurs sur leurs instances de tests, ou les propriétaires des instances de l'application, tous doivent lancer l'installateur à chaque mise à jour de l'application, pour que les nouveaux modules soient réellement installés.

Ceci se fait au moyen du script install/installer.php qui, concrètement, exécute les scripts d'installations éventuels fournis dans le module puis met à jour un fichier var/config/installer.ini.php, qui contient entre autres le numéro de la version de chaque module installé, pour chaque point d'entrée.

Un script d'installation d'un module initialise des données et autres processus nécessaires au bon fonctionnement du module dans l'instance de l'application, comme par exemple créer des tables en base de données, insérer des données dans la base, générer des clés ou autre.


php install/installer.php

Mise à jour d'un module

Pour mettre à jour un module, il suffit d'abord de remplacer les sources du module existant par celles de la nouvelle version, puis de relancer le script install/installer.php.

Le système d'installation de Jelix va alors se charger d'exécuter les scripts de migration du module si il y en a, et de mettre à jour le fichier var/config/installer.ini.php. Bien entendu, cela ne fonctionnera que si le fichier module.xml du module est bien renseigné au niveau du numéro de version du module.