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...');
       }
    }
} 

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..

Vous pouvez surcharger les fonctions preInstall et postInstall qui sont exécutées respectivement avant et après que tout les modules sont installés. Cela vous permet de préparer par exemple certains fichiers.

<?php
class newsModuleInstaller extends jInstallerModule {

    function preInstall() {
    }

    function install() {
    }

    function preInstall() {

    }

} 

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. Depuis Jelix 1.2.6 et 1.3RC3, 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. 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 avec les versions 1.2.6/1.3RC3 et suivantes, 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
• upgrade_to_1.1pre.1234_bbb.php
• upgrade_to_1.1pre.1350_ccc.php
• upgrade_to_1.1_ddd.php
• upgrade_to_1.2a1_eee.php
• upgrade_fff.php (avec un numéro de version 1.2 indiqué dans la classe)
• upgrade_to_1.3_ggg.php

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_to_1.2a1_eee.php
• upgrade_fff.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..

Pour les scripts de mise à jour sans numéro de version dans le nom de fichier (jelix 1.2.6/1.3RC3 et supérieur), vous devez indiquer le 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.