Quick links: Content - sections - sub sections
EN FR
The page corresponding to the latest stable release can be seen in the Jelix 1.8 Manual

This section is not targeting new modules created with the dev.php module:create command, as this command activate and install the new module.

You should read this section if you want to create manually a module, or to install an existing module, provided by Jelix or by an other project.

Declaring the directory of a module

In the chapter about the module creation, we saw we could declare directories of several modules (modules groups), in the application.init.php file.


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

It is possible to have a module outside a modules group (for example, in a Composer package). So you can indicate its path directly into the application.init.php file.


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

An other possibility is to declare its path into the Jelix configuration. It is done into the modules section, with a parameter *.path, for example:


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

It eases migration from jelix 1.6.x and is useful to declare a module with a configuration script, which cannot add a line of code into application.init.php without risks.

Activate and configure a module

Modules inside modules group can be used only if there are activated and then installed, in order to improve the security and to avoid unneeded behaviors. Indeed you could have a module groups, shared between many application, and there are certainly some of these modules you don't want to use in your application.

To configure a module, you should launch the configurator of Jelix, with the command module:configure by given the module name to it (here mymodule):


php dev.php module:configure mymodule

It modify the [modules] section of mainconfig.ini.php by adding the property mymodule.enabled = 1.

It also launch the configurator of the module, if it exists. This configurator can modify the configuration files. It can ask you interactively some configuration parameters. It can also install some files in some directories, typically, installing some css and js files into your www/ directory.

If the module declares some dependencies, the configurator will enable the dependent modules, and will launch their configurators too.

Of course, if you have several entry points, the module should be accessible only from a one of them. So don't forget to configure correctly the url engine, and so Jelix could generate modules URLS correctly with their respective entrypoints.

Note: in Jelix 1.6 and before, the activation was made with the property access instead of enabled. This property is not used anymore, and the migration tools of Jelix may have made the modification.

Parameters for the installation

The module can have a script to install it, and this script may need some parameters. These parameters can be indicated into a specific options into the section "modules": themodule.installparam=something. Example for a module "news":


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

Parameters, separated by a semi-colon, can be simple keyword, or some key/value. For values that are list of values, each value is separated by a coma.

In general, the configurator of a module ask you the value of these parameters (when you launch module:configure). And so, the installparam property will be set automatically.

Installation of a module

Activating and configuring a module is a step made by the developer, only one time during the development, whereas the launch of the installer should be executed on each application instances by their administrators.

So you, as a developer on your test instance, or any owner of production instances, should launch the installer at each new version of the application, so new modules will be "installed".

You do it with the script install/installer.php. It executes the installation script provided within the module, if it exists, and then it declares the module into the var/config/installer.ini.php file.

An installation script of a module do everything that are needed in order to have a module that can be executed correctly in the current instance of the application. It may initialize some data into a database, it may create some tables into a database, it may generate some cryptographic keys etc..


php install/installer.php

Updating a module

To update a module, replace current sources of the module by the new sources, then launch the script install/installer.php.

The installation system of Jelix will execute update scripts of the module if they exist, and update the var/config/installer.ini.php file. Of course, it works well only if the version of the module is well indicated into the module.xml file of the module.