installing-a-module.gtw

~~LANG:FR@frman:configurateur-installateur/installer-un-module~~

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.

<code php>
jApp::declareModulesDir(__DIR__.'/vendor-modules/');
</code>

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.

<code php>
jApp::declareModule(__DIR__.'/somewhere/mymodule/');
</code>

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:

<code ini>
[modules]
my_module.path = app:vendor/my_vendor_name/my_package/the_module
</code>

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):

<code bash>
php dev.php module:configure mymodule
</code>

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 [[/components/urls|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 [[create-install-scripts|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":

<code>
   news.installparam = "enablecategories;defaultcategory=In the world"
</code>

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

<code bash>
php install/installer.php
</code>


===== 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 @@F@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.