installing-a-module.gtw

~~LANG:FR@frman:installer-un-module~~

This section is not targeting new modules created with the @@c@createmodule@@ command, as this command activate and install the new module except if you want to change the access level.

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

===== Access level of 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 this modules you don't want to use in your application.

To activate a module, you should indicate it in the "modules" section of the file @@F@defaultconfig.ini.php@@, with an access level. In this section each keys are the name of a module + ".access", and the value the access level:

   * 0: if the module is not used at all (default value if the module is not listed in the modules section)
   * 1: the module is used (you use its dao, forms, business classes etc from an other module), but is not publicly available (it is not accessible from the web).
   * 2: the module is used and is accessible from the web

Example:
<code ini>
[modules]
testapp.access = 2
junittests.access = 2
jacldb.access = 0
jacl2db.access = 1
jauthdb.access = 1
jauth.access = 2
</code>

In this example, modules testapp, junittessts and jauth are activated normally.
jacl2db and jauthdb are activated, but only their resources (forms, daos,
business classes...) are usable, and you cannot access to it from the web.
jacldb is not used at all and is "invisible".

Of course, if you have several entry points, some modules could be activated for some entry points and not for others. So you have to create a "modules" section in configuration files of each entry points. Values in defaultconfig.ini.php are considered as default values, if there are not defined in configuration files of entry points.

Don't forget to [[urls|configure correctly the url engine]], so Jelix could generate modules URLS correctly with their respective entrypoints.

Note that when you use the @@c@createmodule@@ command, the new module is automatically activated with the access level 2. Further more, configuration options like @@V@checkTrustedModules@@, @@V@trustedModules@@ and @@V@unusedModules@@ do not exist anymore (since jelix 1.2).


Note: if you want all modules accessible (access=2), you can set this option in the global section of the configuration: @@enableAllModules=on@@. Access values in the modules section will be ignored. **Warning**: only do this if you know what you do, you could activate some modules you don't know. Use it only on particular project.


===== 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 coma, can be simple keyword, or some key/value.

If you don't want to execute the installation script of a module, indicate it with the skipinstaller option and the value "skip".

<code>
news.skipinstaller=skip
</code>


===== Installation =====

After defining the access level of a module, you should "install" it. You do this with the command @@c@installmodule@@, which executes the installation script provided with the module, if it exists (this script could create some SQL tables...), and activates the module in the @@F@var/config/installer.ini.php@@.

For example, to use the jauth module provided with jelix, and after declaring it into the modules section in the configuration file, do it:

<code bash>
php cmd.php installmodule jauth
</code>


Note: It is possible to deactivate completely the installation system, and then modules will be implicitely installed, without calling the command installapp or installmodule. To deactivate, set this option in the global section of the configuration: @@disableInstallers=on@@. However, you should configure and install all things needed by the module (tables in the database for instance). Updates will be harder too. Deactivate it only on some specific project.

===== Updating a module =====

To update a module, replace current sources of the module by the new sources, then launch the command @@c@installmodule@@ with the name of the module. 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.

If you have several modules to update, you can indicate several name to the @@c@installmodule@@ command, or launch the @@c@installapp@@ command. It is useful to update an application on a production server.

Note: If you have deactivate the installation system with @@disableInstallers=on@@, you don't have to execute installmodule. Update the sources of the module, and update all things needed by the module, "by hand". That's all (but it is less easy).