Section: Installing a module
|« How the installer works||^ Configurator and installer of Jelix||Installer configuration »|
− Table of content
This section is not targeting new modules created with the
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
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
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
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
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
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
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
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
It executes the installation script provided within the module, if it exists,
and then it declares the module into the
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..
Updating a module ¶
To update a module, replace current sources of the module by the new sources, then launch
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.