Module development

To create a new module/addon for Dolibarr, there is several steps. This tutorial will describe you each of them to build a module to extend Dolibarr features, like one or several of the following : etc... All those operations are possible with version 3.2 or more of Dolibarr.
 * Add new tables in database
 * Add your own menu entries
 * Add new screens to edit new tables
 * Add or remove tabs on object view (invoice, product, order, event, ...)
 * Add predefined exports for the internal export tool
 * Add new information boxes in the home page
 * Add new substitutions variables
 * Define new permissions
 * Execute code automatically triggered by a particular Dolibarr action
 * Insert your code inside Dolibarr hooks positions
 * Add your numbering module
 * Add a new document template
 * Add a new skin

Following chapters presents how to do all of this manually with an easy way. For experienced developers, a method to do this using MDA generation is also on the work. See last chapter for this.

=Example of Template External Module= A good model to start development of external module can be found here : GitHub Dolibarr Module Modèle

=Create your module =

Create a descriptor of Module (required)
When: Required as soon as an addon is developed, whatever its goal is (except for adding a skin or a document template).

Create your module descriptor
The first step is to create a file descriptor for the module. Then change the contents of this file as follows: Your file descriptor for your module is ready.
 * Create directory /htdocs/mymodule/core/modules. Then go into the directory dev/skeletons and copy the file modMyModule.class.php in this directory htdocs/mymodule/core/modules.
 * Replace all "modMyModule" with a value which corresponds to the purpose of your module. This value must always start with 'mod' and contains only alpha characters.
 * Change the number in: $this->numero = 100000 by a number that designate your module id. To avoid conflicts with other modules, you can consult tha page that list already reserved id numbers: List of modules id.
 * Modify any other variables defined in the constructor (see comment in the code skeleton for their meaning).

Test your descriptor
Launch Dolibarr and go to page Setup->module? You must see a new line with your new module and the possibility to activate it or not (browse all the tabs of each category of modules to find it). The value of $this->special determines in which tab will be your module.

Tree of path for new module files (required)
This is how your files must be organized when building a new module (the zip file must also match this rule). Note: Only second line is mandatory.

Create your SQL tables and the PHP DAO class (optional)
When: If your module needs to manage data of its own

Create your .sql file
If your module is designed to manage data of its own, which are not available in the standard version of Dolibarr, it is necessary to define SQL tables to store the data.

Files for your own module must be placed in a directory.

Create a subdirectory called "sql" into directory of your module (eg htdocs/mymodule/sql) to put the sql scripts that you will create. Then in the "load_tables" function of your file descriptor module, modify the line

by

Rules to follow:
 * Add the files about creating tables commands on the principle of a file llx_matable.sql per table with a possibly file llx_matable.key.sql (see existing files in install/mysql/tables for examples).


 * To manage data, you must create a file called data.sql inside directory /mymodule/sql/ that contains SQL command to add/edit/delete datas.

Example of content of a file data.sql

Files must be operational for the database mysql. Rem: The files of other databases are not maintained. They will be read and converted on the fly by the driver of the other database.

Test your .sql files
Once the files ready, you can return to Dolibarr to disable the module, drop those tables in database and reactivate the module. The tables should be recreated by the activation of the module. If this is not the case, check your scripts by passing them by hand, or check the Dolibarr logs.

Generate the PHP DAO class
Once you have created your tables into the database, move to the dev/skeletons directory and run the script

Note: If the command does not work, try to use php-cli php instead.

This will generate a file out.tablename.class.php that contains the class to manage table tablename. In this class, you can find the CRUD methods (Create / Read / Update / Delete) already working to do an insert, a fetch (select), an update, a delete of a row in table. Remove just the "out" from the file name and put the file in a subdirectory of htdocs specific to your module (in htdocs/mymodule for example).

A file out.tablename_script.php has been generated and contains a sample code to use the class for each of the 4 CRUD methods.

Add or removed your own tabs on object sheets
When: To add a tab on an object (invoices, orders, proposals, member ...)

To do this go into the file descriptor of module previously created and edit the $this->tabs array:

The table should contain a list of strings, each string representing a new tab. The format of the string consisting of 5 parts separated by ":"
 * Part 1: The element type (objecttype) where should the tab appears is a value from the following:


 * Part 2: A code to identify tab to add (start with +) or to remove (start with -)
 * Part 3: The title of the tab. This can be a hard read or better code translation in a file lang.
 * Part 4: The name of the file. Lang which contains correspondence between the code translation and language to display. If this name start with @, Dolibarr will search translation file into the lang file of module, so htdocs/mymodule/langs/code_CODE/mymodule.lang, otherwise Dolibarr will look for file htdocs/langs/code_CODE/mymodyle.lang
 * Part 5: The url of the page to display when you click on the tab. The __ID__ string will be replaced automatically by the Id of the element concerned.

To feed the contents of the tab with data from the database, see the next chapter.

Show tabs navigation into your own pages
When: To show all standard tabs of an object (produit, tiers, etc.) on your page.

You must follow these steps :

1. Include files you need into your file

For each object type, there are two files to include with line

This is list of those files to include (DOL_DOCUMENT_ROOT is often dolibarr/htdocs/) :
 * Object thirdparty (thirdparty) :
 * DOL_DOCUMENT_ROOT/societe.class.php
 * DOL_DOCUMENT_ROOT/lib/company.lib.php
 * Object product (product) :
 * DOL_DOCUMENT_ROOT/product.class.php
 * DOL_DOCUMENT_ROOT/lib/product.lib.php
 * Object invoice (invoice) :
 * DOL_DOCUMENT_ROOT/facture.class.php
 * DOL_DOCUMENT_ROOT/lib/invoice.lib.php

2. Create and load the object to show into your tab

Create instance of object of the correct class and load object from database by using the fetch method of object en providing to this method the id you get from url (ie : /mytab.php?id=1).

Example :

3. Get list of all tabs to show for your object type

Use fonction XXX_prepare_head($obj), where XXX is name of object. This will return an array with all definition of tab entries to show. Parameter to put into this method is the instance of object you want tabs.

The resulting array has the following structure

Example :

4. show tabs into your page

Use function dol_fiche_head to show all tabs defined into array $head returned by XX_prepare_head.

This function will show required tabs and open an html element   that correspond to the area under the tabs. To close area of a tab, just use < /div > into your PHP page.

Create or modify PHP screens (optional)
When: If the purpose of your module is to add features that require new or modified screens.

Create a new PHP screen
You must then create your PHP pages that will show/edit data from tables using the skeleton templates provided as an example in the directory dev/skeletons (For the development of a script from the command line, see Script development).

To create a new user screen, create a subdirectory of htdocs (if not already done) for your module (in htdocs/mymodule for example) to store the pages you will create.

Copy, into that directory, the file skeletons_page.php that will serve as a starting point for your page file. Edit the file to have a correct relative path to the main.inc.php file. Note that you may add more "../" depending on the depth of the file relative to your module directory tree. The modules developed for all version of Dolibarr after the 3.2 should be able to be moved in a different folder than "htdocs", like "htdocs/custom", without having to modify the source code of the module, that's why we make several includes, so this rule must be applied by all modules.

It's in the main.inc.php file that is loaded technical environment variables and permissions. The following variables are objects positioned in this file:


 * $user   Objet that contains the characteristics of the user + his permissions.
 * $conf   Objet that contains Dolibarr configuration.
 * $db     Objet that contains an opened connection handler to the database.
 * $langs  Objet that contains the user's language.

Then enter your code to display the page.

Example :
 * To include a class or library dedicated to the module is done using a Dolibarr function (and not using directly include_once):

Example :
 * To include classes provided with Dolibarr, use the following syntax:

Add some fields into existing forms
You may want to provide a module that add more fields into forms (input and view) of some elements.

A heavy solution (but not so bad) may be to replace all pages used to create element (this means disable the "New element" menu entry and adding yours, and disable tab that show element to replace with a tab that is your own full page (copied/pasted from original) to do same than original page but modified to add your fields and stored added data into your own table). Go to menu and  if this solution suits you (this solution is more powerfull since you can change everything you want into page).

We will describe here another solution, that works only to "add fields" at end of existing fields, using the element "category" as an example but you can convert this tutorial for invoice, proposal ... If you follow this tutorial, to be able to add fields into category forms, you must do:
 * First thing is to add a table, owned by your module, to store value of new fields. This table will have only one column called "rowid" (will contains same value than field rowid of element table) + one column for each new field you want to add. Then create a class with CRUD (Create/Read/Update/Delete) methods for this new table. For this two tasks, go back to previous chapter.
 * Next step is to add a hook into your module to add the new fields into the form. See chapter Hooks_system for generic documentation to use hooks.

Replace parts of screen that are templated (version 3.3+)
Some parts of Dolibarr screen are isolated into native PHP template files. You can develop a module to overwrite such templates with yours.

Add/replace part of fields supported by hooks
See chapter Hooks_system to know how to use Dolibarr existing hooks to add/replace code at Dolibarr hooks place.

Database access
If you need to edit some data in database inside you own table, use the PHP class generated before.

If you to make access to tables with no dedicated PHP class available, this is always possible (for example if you want to get a list of records with a particular join or filter). In this case, this is a code samples to follow:

To make an insert, update or delete:

To read:

Define style of your pages
To have the look of your own pages to match the Dolibarr theme, it is necessary to use the Dolibarr CSS styles.

You can use for example:


 * class="liste_titre" on tags tr and td for the head row of a table.
 * class="pair" or class="impair" on tags tr and td of other rows of a table.
 * class="flat" on all input fields (input, select, textarea...).
 * class="button" on HTML fields with type input type="submit".

Use the Dolibarr date picker
If you want to use the Dolibarr date selector (with its calendar popup) into your pages, use the following line: The string mykey will identify the date selector in the form. You must use different values if you use several date selectors in same page. The string myform is the name of the FORM in which the selector is included (value found in the form name="myform" in HTML page). This means a date selector must be included necessarily into an html FORM.

To get value after the POST of your form, the command is:

Add your own setup page (optional)
When: If your module need to ask user several parameters.

Create your page to edit parameters
If your module need several parameters to be setup, you must create a page to edit options (that will be saved into table llx_const). Create a page named mymodule_setuppage.php that show possibles options and update them into table from a form. It is a necessary to take an example from a page into directory /admin that will show you the way to read/save your parameter. Put this page into directory /admin. Then, into the descriptor file of your module, modify the variable config_page_url to set name of this PHP page (without the path that is not necesary if page is inside directory admin).

Test your page
Go into page Home->Setup->Modules, you should see a picture at the end of the line of your module to reach your setup page. Click on it, you should be able to view/edit parameters from your page.

Define your entries in menu (optional)
When: If you have created PHP pages, it is necessary that those pages can be reached from menu entries in Dolibarr menu.

Define your menu entries
For this, you must define into the module descriptor, the array this->menu that declare all menus added by your module. This array contains entries that will appear once your module is activated. The example module descriptor file modMyModule.class.php contains an example to declare a top menu and also its left menu entries.

This is the example of code to declare your own menu entries in a module descriptor file:

To show menu or not depending on a permission, modify property perms in array. See chapter on permissions later to see how to add permissions.

Test your menu entries
Disable and reenable your module under Dolibarr module setup page, menus entries must appear (if property 'enabled' is declaration array is ok).

Add your own permissions (optional)
When: If you want to add new permissions.

The way to define permissions that will manage your module is done inside the module descriptor created previously. Modify line with correct value for mymodule.

Then you must fill the array $this->rights with as many entries than different permissions you need to manage.

Into $this->rights[$r][0], put a permission id not already used (See into menu System info on a working installation of Dolibarr to know list of id already used by standard modules. Into $this->rights[$r][3], put 1 if this permission must be granted automatically by default to any new created user. Into $this->rights[$r][1], put a label by default for permission (This label will be used if no translation can be found into the file admin.lang). Into $this->rights[$r][4] and $this->rights[$r][5], put an action and subaction string without spaces. You will be able to test if a user has the permission in your PHP source code with the sequence:

Define you own box (optional)
When: If your module need to provide one or several new boxes to show on home page.

Define your box
For this, modify the array $this->boxes into the module descriptor file. All you have to do is to add 2 lines for each box file you will create into directory htdocs/mymodule/core/boxes

Example:

Then create files htdocs/mymodule/core/boxes/mybox0.php, htdocs/mymodule/core/boxes/mybox1.php... by copying an example from an existing box file (found into directory htdocs/core/boxes).

Test if your box is detected by Dolibarr
Disable and enabled module.

Go into menu Home - Setup - Boxes.

Your boxes must appear in the list of boxes you can activated. Activate the box and go on home page to see if the box is showing correctly.

Define your own export (optional)
When: If your module provide new predefined database export profiles (for its own tables or for already existing tables of another module).

Define export
For this uncomment and modify arrays $this->export_xxx in your module descriptor file.

Test your export
Go into menu Tools -> Export. Your export will appear in the list of available predefined exports (if your module is enabled). Choose it, you must see list of all possible fields defined in the export arrays. Choose on field and try to build an export file. If ok, try again with all fields.

Define your CSS styles (optional)
When: If in your PHP pages, you use class styles that are not defined inside Dolibarr themes CSS (not recommanded).

Create and declare your style sheet
Create a style sheet CSS named mymodule.css or mymodule.css.php and put it into directory htdocs/mymodule. You can have only one CSS file per module. Remember it's better to use existing styles already available by default into Dolibarr (The CSS file used by Dolibarr is file themes/mytheme/themename.css.php. Create your own CSS file only if you need absolutely to add not already existing styles.

Once your style sheet is ready, declare it into your module descriptor file by modifying the property $this->modules_parts. Value to put here must be a relative URL to your CSS file. For example

Test your style sheet
Disable and enable your module.

Go on home page (index.php). Show the HTML source of the page.

You should see into the HTML header, a line that declare your style sheet.

Add your Javascript functions (optional)
When: If in your PHP pages, you use javascript functions not available in Dolibarr (in file lib_head.js)

If you need to use your own javascript functions inside your PHP pages, it is necessary to have your functions, defined into your javascript file htdocs/mymodule/js/mymodule.js, included into the HTML HEAD section. To ask Dolibarr that forge this header to include your own javascript file, you must just provide it to the llxHeader function called by your page.

Example for page /htdocs/mymodule/mypage.php :

Run your own code on any Dolibarr event (optional)
When: If you want to execute your own code once a common Dolibarr event has occurred (example: I want to update a table in my module when an invoice is created into Dolibarr), you must create a triggers.

See also Interfaces_Dolibarr_toward_foreign_systems and Interfaces_from_foreign_systems_toward_Dolibarr

Insert your code inside Dolibarr hooks positions (optional)
When: When you want to add code or replace Dolibarr code into another situation than a business event (See previous chapter for adding code during a business event).

See page Hooks_system.

Add your own numbering rules
When: When you need a new rule for generated ref of elements that is not covered by existing rules.

See page Create numbering module.

Add your document template (optional)
When: When you want to personalized your own generated PDF or ODT documents.

Note: To add this feature you don't need to create a module descriptor.

Documentation to add your own template is available on page Create_a_PDF_document_template or Create_an_ODT_document_template.

Add your skin (optional)
When: When you want to personalized your colors/fonts/images.

Note: To add this feature you don't need to create a module descriptor.

To add your own skin, read page Skins.

=Some coding rules and predefined functions = The coding rules to be followed are defined in the Developer documentation, under section "General Information - Language and standards development".

A lot of predefined features for developers are also available and described into page Developer documentation under section "Technical components of Dolibarr".

=Using MDA = A method to generate a functional module from a UML model has been developed. More information on the page UML2Dolibarr - Build a module using MDA.

=Create a package to distribute and install your module = This process must be used to generate a package to submit it on the http://www.dolistore.com market place. But you can use it to have a package easy to distribute on your on network.


 * Go into the directory /build and copy the file makepack-dolibarrmodules.conf into makepack-mymodule.conf. Warning, this directory may not be provided in some packages of stable versions. If so, it can be retrieved from the snapshot available for download on the Dolibarr website in area "Development version" (taken in this case the whole build directory which is autonomous and independent directory).

Edit this file to add list of file names for all new files you created for your module (module descriptor, new sql tables files, php page, images, etc...)

The script asks you the name of your module, its major and minor version. A file mymodule.zip  will then be manufactured containing your module ready to be deployed.
 * Run the script via Perl (need the Perl version 5.0 or later):


 * The person who receives your module must then place the file in the root directory of a Dolibarr installation and perform the command:


 * If you want your module to be public, you can submit it (the zip file) on Dolibarr market place web site: (you must create an account first and be logged to use the link "Submit a module/product").
 * If your module was build correctly, file will be validated later.
 * If quality is enough and license permits it, code might be added inside main Dolibarr sources (except if you disagree for that).

= Enabling/activation condition of external module on DoliStore =

See Validation Rules