Quick links: Content - sections - sub sections
EN FR

A module is a directory with a precise file-system hierarchy. Modules are groupped in one or several directories called modules group, or repository of modules.

Since Jelix 1.6.9, it is also possible to declare some modules outside from modules group.

Declaring a modules group

Module groups are declared in the configuration property modulesPath. It's possible to set a value of one or several relative or absolute paths separated by commas. It's also possible to use directory codes with a particular notation:


   directorycode:relative/path/

The following directory codes are available:

lib
lib/ directory
app
application directory

This prevents from having really relative paths and is easier to maintain. For example:


   modulesPath = lib:jelix-modules/,app:modules/

It declares two module groups :

  • jelix-modules, subdirectory of jelix's lib/
  • modules, subdirectory of your application path.

Modules from both directories could be activated and installed in your application.

Declaring a single module

Since Jelix 1.6.9, 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 Jelix configuration.

It is done into the modules section (and not in modulesPath), with a parameter .path:


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

Directories of a module

A module is a directory having at least one file, module.xml, containing some informations about the module: version, dependencies...

And you have some sub-directories, depending of what the module provides, and each containing specific files:

controllers/
controllers, corresponding to some URL
classes/
business classes, librairies, listeners for events etc.
templates/
file containing the content to send to browsers
responses/
response object that the module can provide for the whole application
locales/
properties files to localize templates or content generated by controllers
zones/
classes generating some part of a web page
daos/
files declaring mapping to a database
forms/
file declaring forms
install/
scripts to install or to upgrade the module
scripts/
scripts for the command line
plugins/
plugins for various components (jDb, jTpl...)
www/
CSS, JS, images files. There are accessible from a browser, by calling a specific controller of the "jelix" module
tests/
files doing unit tests for PHPUnit or Simpletest

Create a module

It's as simple as creating a sub-directory of a modules group, and filling it with controllers, persistent objects ...

The createmodule command helps you to create all this directories, and to activate and install automatically the new module:


   php cmd.php createmodule mymodule

This command creates the module "mymodule" in your application's sub-directory modules. It creates also some sub-directories as well as a default controller.

Important: The name of modules are used in the name of some classes generated automatically by Jelix. So you mustn't use other characters than a-z, A-Z, 0-9 and _.

By default, the module is created in the modules/ directory of the application. Perhaps you would like to create it into an other modules group. In this case, indicate the path of the repository after the module name. You can use the same syntax as in modulesPath (an absolute path or a relative path with "lib:" or "app:".

This example creates a "supermodule" module into the shared-modules/ directory which is itself into the lib directory provided with jelix.


php cmd.php createmodule supermodule lib:shared-modules/

See the online help of the createmodule command to know other options.

Setting the version and dependencies

After creating the module, you should verify if the default initial version is ok for you (0.1), and set dependencies. It is very important for the installation system of Jelix.

You can indicate the version to the createmodule command, with the -ver option:


php cmd.php createmodule -ver 1.0 supermodule

You can also modify the version in the module.xml file generated in the module, if needed.

You can set dependencies of the module. Dependencies are modules necessary to execute the new module. In the <dependencies> element in the module.xml file, add a <module> element for each required module.


   <dependencies>
     <jelix minversion="1.6.0" maxversion="1.6.*" />
     <module name="jauth" minversion="1.2" />
     <module name="anOtherModule" minversion="1.0" maxversion="1.4.*" />
   </dependencies>

The attributes minversion and maxversion are optional.

For more details about the content of module.xml, read the corresponding chapter.