Quand vous installez un module via la commande installmodule ou installapp :

• Jelix regarde la section modules située dans la configuration de chaque point d'entrée, et cherche la valeur d'accès du module
• Il lancera l'installation du module pour chaque point d'entrée si la valeur d'accès du module est supérieur à 0
• Il regardera alors le fichier var/config/installer.ini.php et vérifiera si le module est déjà installé
• S'il est déjà installé, il exécutera tous les scripts de mises à jour fournit par le module dont la version est comprise entre celle du module déjà installé et celle de la nouvelle version du module
• S'il n'est pas déjà installé, il exécutera le script d'installation fournit par le module
• Après l'installation ou la mise à jour, Jelix enregistre le nouveau numéro de version du module dans le fichier installer.ini.php.

Bien entendu, les scripts d'installation ou de mise à jour ne sont pas indispensables.

Mais si vous en fournissez, il est très important d'indiquer dans le fichier module.xml, le bon numéro de version et la date de la version !

Pourquoi un script d'installation est appelé plusieurs fois ? ¶

C'est un script, install.php, que vous placez dans le dossier install/ de votre module.

Il devrait contenir une classe, héritant de jInstallerModule, et nommée {module}ModuleInstaller, où {module} est le nom de votre module. Ex: mainModuleInstaller pour le module main.

Dans cette classe, vous devez créer une méthode install dans laquelle vous ferez toutes les choses nécessaires à l'installation du module : modifications de la base de données, copies de fichiers, changements de configuration etc..

<?php
class newsModuleInstaller extends jInstallerModule {

    function install() {
       if ($this->firstDbExec()) {
           $db = $this->dbConnection();
           $db->exec('CREATE TABLE...');
       }
    }
} 

Vous pouvez surcharger les fonctions preInstall et postInstall qui sont exécutées respectivement avant et après que tout les modules soient installés. La méthode preInstall(), vous permet par exemple de préparer certains fichiers ou données, ou de vérifier les conditions requises pour l'installation. Si les conditions ne sont pas requises, vous pouvez alors émettre une exception qui stoppera alors le processus d'installation.

<?php
class newsModuleInstaller extends jInstallerModule {

    function preInstall() {
    }

    function install() {
    }

    function postInstall() {

    }

} 

jInstallerModule contient un certain nombre de propriétés et de méthodes qui vous aideront à accéder à la base de données, aux fichiers de configuration etc..

Note: dans Jelix 1.7, l'API pour l'installateur a été changée. Jelix 1.7 prend en charge les install.php de Jelix 1.6. Mais si vous voulez faire un module dont l'installateur profite des améliorations de la version 1.7, mais continue à fonctionner dans jelix 1.6, il faut alors réaliser en fait 2 scripts : install.php qui utilisera l'API de Jelix 1.7, et install_1_6.php qui est développé comme indiqué dans cette documentation. Jelix 1.6.19 et plus savent prendre en charge install_1_6.php, c'est à dire que si install_1_6.php est présent, Jelix 1.6.19 l'executera plutôt que install.php.

Méthodes ou propriétés principales ¶

Pour ne pas exécuter une partie de votre script ¶

Profil d'accès à la base de donnée pour l'installation ¶

Paramètres pour une installation ¶

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

  function install() {
     if ($this->getParameter('enablecategories')) {
        // ici du code pour créer la table des catégories par exemple...
        // ...

        // création de la catégorie par défaut
        $defaultCategory = $this->getParameter('defaultcategory');
        if ($defaultCategory) {
           // là on pourrait insérer un enregistrement dans la table des catégories
           // avec le label donné dans $defaultCategory.
        }
     }
  }

Ces scripts ont des noms de fichiers spécifiques. Ils doivent avoir pour nom upgrade_{label}.php où {label} doit être remplacé par un nom qui sera une partie du nom de la classe.

Note: Jusqu'à Jelix 1.2.5, les noms des fichiers devaient être upgrade_to_{version}_{label}.php, où {version} était un numéro de version. Ces noms restent compatibles mais ils sont obsolètes.

Ces scripts doivent être stockés dans le répertoire install/ du module. Il seront exécutés en ordre ascendant de version indiquée dans la classe d'installation (Jelix 1.2.6 ou plus) ou dans le nom de fichier (Jelix 1.2.5 et inférieur). Et seuls ceux dont la version est plus grande que la version actuelle installée du module, et plus petite ou égale à la nouvelle version du module, seront exécutés. Imaginez que vous ayez ces scripts :

• upgrade_to_1.0_aaa.php (ancien nomage)
• upgrade_zzz.php (déclarant la version 1.1pre.1234 dans la classe)
• upgrade_foo.php (déclarant la version 1.1pre.1350)
• upgrade_bar.php (déclarant la version 1.1)
• upgrade_fff.php (déclarant la version 1.2a1)
• upgrade_eee.php (déclarant la version 1.2)
• upgrade_hello.php (déclarant la version 1.3)

Si la version courant du module est 1.1 et que la nouvelle version du module (indiquée par le nouveau fichier module.xml) est 1.2, alors seuls les scripts suivants seront lancés, dans cet ordre:

• upgrade_fff.php
• upgrade_eee.php

Un script de mise à jour contient un classe, appelée {module}ModuleUpgrader_{label}, où {module} doit être le nom du module, et {label}, le label indiqué dans le nom de fichier du script.

Puisque plusieurs scripts de mise à jour peuvent être exécutés pour le module, alors le nom de classe doit être différent (sinon PHP ne va pas aimer ça). C'est pourquoi nous utilisons un label, qui doit être différent pour chaque script du module. (Les développeurs Jelix pourraient utiliser le numéro de version au lieu d'un label, mais malheureusement, PHP n'aime pas les caractères comme "." ou "-" dans un nom de classe).

La classe devra hériter de jInstallerModule, pour que vous puissiez avoir exactement les mêmes comportements et méthodes que le script d'installation. Vous devez donc implémenter la méthode install, vous pouvez appeler firstDbExec, getParameter etc..

Comme on l'a vu, une classe fait une mise à jour pour une version particulière. Il faut indiquer ce numéro de version dans la propriété $targetVersions (qui est un tableau), et une date au format 'yyyy-mm-dd' ou 'yyyy-mm-dd HH:ii' dans la propriété $date.

<?php
class newsModuleUpgrader_fff extends jInstallerModule {

    public $targetVersions = array('1.2');
    public $date = '2001-06-21';

    function install() {
       // ....
    }

} 

Vous devinerez que vous pouvez indiquer plusieurs versions dans $targetVersions. Cela est utile quand vous avez plusieurs branches d'un projet, et qu'un script de mise à jour, faisant la même chose, est nécessaire dans chaque branche. Avec la date de la version, Jelix peut déterminer si, lors d'une mise à jour, quel que soit la branche, il peut exécuter le script ou non. Exemple : vous avez un script de mise à jour pour la version 1.2.4 et 1.3.5. Si l'utilisateur met à jour depuis la version 1.2.3, ou depuis la version 1.3.4, le script sera appelé. Par contre si il met à jour depuis une version 1.2.5 vers une version 1.3.6, le script ne sera pas exécuté, puisque la version 1.2.6 était censé déjà inclure la modification apportée par la 1.2.4. Et il le sait en comparant la date des versions que l'utilisateur a installé à l'origine, celle des versions qu'il utilise actuellement, et celle des versions qu'il va installer.

Depuis Jelix 1.6.19, une fonctionnalité de Jelix 1.7 a été ajouté: la possibilité d'avoir un script global de mise à jour, upgrade.php, c'est à dire un script executé à chaque lancement de l'installateur Jelix, quand le module change de version. Cela évite de devoir faire les mêmes scripts de mises à jour à chaque nouvelle version.

Tout comme les autres scripts de mise à jour, upgrade.php doit contenir une classe qui hérite de jInstallerModule. Cependant son nom ne contient pas de suffixe, simplement {module}ModuleUpgrader, où {module} doit être le nom du module.