When you install a module with the installmodule or the installapp command :

• jelix looks at the modules section inside the configuration of each entry point, and retrieve the access value of the module
• It will launch the installation of the module for each entry points where the access value of the module is higher than 0
• It then looks at the var/config/installer.ini.php file: it checks if the module is already installed
• If it is already installed, it will execute all scripts of update provided by the module, corresponding to a version between the installed version and the new version of the module
• If it is not already installed, it will execute the installation script provided by the module
• After the installation or the update, Jelix stored the new version number of the module into installer.ini.php.

Of course, installation scripts or scripts of update are not required.

But if you provide them, it is very important to store into the module.xml file, a good version number and the date of the release !

Why is an installation script called several time? ¶

This is a file, install.php, that you store into the install/ directory of the module.

It should contain a class, inheriting from jInstallerModule, and named {module}ModuleInstaller, where {module} should be the name of the module. Ex: mainModuleInstaller for the main module.

In this class, you need to create a method install where you'll do all things to install the module: database modifications, file copies, configuration changes etc..

<?php
class newsModuleInstaller extends jInstallerModule {

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

You can redefine the methods preInstall and postInstall, which are executed respectively before and after the installation of all modules.

<?php
class newsModuleInstaller extends jInstallerModule {

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

jInstallerModule contains a number of properties and method which helps you to access to the database, to the configuration file etc..

Main properties or methods ¶

To not execute some part of your script ¶

Database profile used for the installation ¶

Parameters for an installation ¶

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

  function install() {
     if ($this->getParameter('enablecategories')) {
        // here some code to create the categories table for example...
        // ...

        // now create the default category
        $defaultCategory = $this->getParameter('defaultcategory');
        if ($defaultCategory) {
           // here we could insert a record in the categories table
           // with the label given into $defaultCategory.
        }
     }
  }

These scripts have specific file names: upgrade_{label}.php where {label} is a name which will be part of the name of the class. In jelix 1.2.5 and lower, the filename could be upgrade_to_{version}_{label}.php, where {version} should be replaced by a version number. This format is now deprecated.

These scripts should be stored into the install/ directory of the module. They will be executed in the ascendant order of the version indicated into the filename. And only those for which the version is higher than the current installed version of the module, and lower and equal than the new version of the module. Imagine that you have these scripts (with deprecated format of names):

• 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 (new name format, with a version number 1.2, indicated into the class)
• upgrade_to_1.3_ggg.php

If the current version of the module is 1.1 and the new version of the module (indicated by the new module.xml file) is 1.2, then only these scripts will be executed, in this order:

• upgrade_to_1.2a1_eee.php
• upgrade_fff.php

A script for update should contain a class, named {module}ModuleUpgrader_{label}, where {module} should be the module name, and {label}}, the label indicated in the filename of the script.

Because several scripts for update can be executed for the module, then class name must be different (else PHP won't like it). This is why we use a label, which should be different for each script of a module. (Jelix developers could use the version number instead of a label, but unfortunately, PHP doesn't like characters like "." or "-" in a class name).

The class should inherit from jInstallerModule, so you have exactely same behaviors and methods as in installation script. So you must implements a method install, you can call firstDbExec, getParameter etc..

For scripts with new names (jelix 1.2.6 and higher), you must indicate the version number into the property $targetVersions (which is an array), and a date in the property $date with the format 'yyyy-mm-dd' or 'yyyy-mm-dd HH:ii'.

<?php
class newsModuleUpgrader_fff extends jInstallerModule {

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

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

} 

You'll guess that you can indicate several versions in $targetVersions. It is useful when you have several branch in a project, and when an update script should be executed for several branch. With the date of the release, Jelix can determinate if, during an update, it can execute the script or not. For instance, you have a script for an update for versions 1.24 and 1.35. If the user update from the version 1.2.3 or from the version 1.3.4, the script will be called. If he update from the version 1.2.5 to the version 1.3.6, the script won't be called because the 1.2.6 version contains modifications brought by the 1.2.5 version.