creating-a-module.gtw

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


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.


===== Declaring a modules group =====

Module groups are declared in the configuration property @@V@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:

<code>
   directorycode:relative/path/
</code>

The following directory codes are available:

; @@lib@@ : @@F@lib/@@ directory
; @@app@@ : application directory

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

<code ini>
   modulesPath = lib:jelix-modules/,app:modules/
</code>

It declares two module groups :

  * @@F@jelix-modules@@, subdirectory of jelix's @@F@lib/@@
  * @@F@modules@@, subdirectory of your application path.

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

===== Directories of a module =====

A module is a directory having at least one file, [[config#the-module.xml-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:

; @@F@controllers/@@ : controllers, corresponding to some URL
; @@F@classes/@@ : business classes, librairies, listeners for events etc.
; @@F@templates/@@ : file containing the content to send to browsers
; @@F@responses/@@ : response object that the module can provide for the whole application
; @@F@locales/@@ : properties files to localize templates or content generated by controllers
; @@F@zones/@@ : classes generating some part of a web page
; @@F@daos/@@ : files declaring mapping to a database
; @@F@forms/@@ : file declaring forms
; @@F@install/@@ : scripts to install or to upgrade the module
; @@F@scripts/@@ : scripts for the command line
; @@F@plugins/@@ : plugins for various components (jDb, jTpl...)
; @@F@www/@@ : CSS, JS, images files. There are accessible from a browser, by calling a specific controller of the "jelix" module
; @@F@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 @@c@createmodule@@ command helps you to create all this directories, and to
activate and install automatically the new module:

<code bash>
   php cmd.php createmodule mymodule
</code>

This command creates the module "mymodule" in your application's sub-directory
@@F@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 @@F@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 @@F@shared-modules/@@
directory which is itself into the @@F@lib@@ directory provided with jelix.

<code bash>
php cmd.php createmodule supermodule lib:shared-modules/
</code>

See the online help of the @@c@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:

<code bash>
php cmd.php createmodule -ver 1.0 supermodule
</code>

You can also modify the version in the @@F@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 @@E@<dependencies>@@ element in the
@@F@module.xml@@ file, add a @@E@<module>@@ element for each required module.

<code xml>
   <dependencies>
     <jelix minversion="1.3" maxversion="1.3.*" />
     <module name="jauth" minversion="1.2" />
     <module name="anOtherModule" minversion="1.0" maxversion="1.4.*" />
   </dependencies>
</code>

The attributes @@A@minversion@@ and @@A@maxversion@@ are optional.

For more details about the content of module.xml, [[config#the-module.xml-file|read the corresponding chapter]].