Dolibarr ERP CRM Wiki - User contributions [en]

Module development

2022-06-22T09:37:34Z

Alograg: /* Create your module descriptor */

[[fr:Développement_module]]
[[es:Desarrollo_de_un_módulo]]
[[de:Modul_Entwicklung]]
[[zh:模块开发]]


[[Category:Core]]
{{TemplateDocDevEn}}

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 :

*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 widget 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 rule to generate the reference of objects
*Add a new document template.
*Add a new skin.

etc...

Following chapters presents how to do all of this manually with an easy way.

=Module creation with the module builder=
From Dolibarr 9.0 it is possible to create the main pages of your module with the Module Builder. To activate it:

*Go into the list of module and enable the module "Module Builder",

[[File:Mod_builder_2.png|400px]]

*Then click on the "bug" image in the top right of screen.

[[File:Mod_builder_3.png|400px]]

=Example of Template External Module=
A good model to start development of external module can be found here : [https://github.com/Dolibarr/dolibarr/tree/develop/htdocs/modulebuilder/template GitHub Dolibarr Module Modèle]

=Create your module=
==Create a Module descriptor for your Module (required)==
'''When it is required''': Required as soon as an addon is developed, whatever its goal is (except for adding a skin).

'''Since Dolibarr 9.0, you should use the ModuleBuilder module provided as a standard module to generate the module descriptor'''

===Create your module descriptor===
The first step is to create a file descriptor for the module.

*Create directory '''/htdocs/''mymodule''/core/modules'''. Then copy the file modMyModule.class.php from the directory '''htdocs/modulebuilder/template''' into this directory '''htdocs/''mymodule''/core/modules'''. Change the name of the file modMyModule.class.php to the name corresponding to the purpose of your module. Name of the file must start with initial 'mod' and end with .class.php (for example if you want to give the name 'NewName' to this file, then the name should be 'modNewName.class.php').

Next modify the contents of this file as follows:

*Replace all "modMyModule" with a value which corresponds to the purpose of your module. This value must always start with 'mod' and contain only alpha characters (again, if the name given to the file was 'NewName', then replace all "modMyModule" with "modNewName").
*Change the number in: $this->numero = 100000 by a number that designates your module id. To avoid conflicts with other modules, you can consult the page that lists already reserved id numbers: [[List of modules id|List of modules id]].
*Modify any other variables defined in the constructor (see comment in the code skeleton for their meaning).

Your file descriptor for your module is ready. See the next step to activate it.

===Test your descriptor===

Launch Dolibarr and go to page '''Setup->module'''?
If you set the property version in the module description you should see a new line with your new module and the possibility to activate it or not. If you set the property version to "develop" or "experiental", to see your module, you must first go into '''Setup-Others''' and set MAIN_FEATURES_LEVEL to 1 to see "experimental" modules or 2 to see "development" modules.

==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 the second line is mandatory.

{{TemplateModuleTreeSimple}}

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

Scripts for creating tables and loading data by your own module are saved into a subdirectory sql ('''"mymodule/sql"''') of your module. (With ModuleBuilder, the directory and all sql files will be created automatically when you will create a new Object from tab Object).

Then check into your descriptor file, into function '''init''' that the line

<syntaxhighlight lang="PHP">$this->_load_tables('/mymodule/sql/');</syntaxhighlight>

is not commented.

''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).
*The recommended type and name for SQL fields are defined into page [[Language_and_development_rules#Table_and_fields_structures]].
*To manage data, you must create a file called '''data.sql''' inside directory '''/mymodule/sql/''' that contains SQL command to add/edit/delete data.
*Don't use the double quote for strings (eg 'chaine' not "chaine") because the double quote have a specific meaning in PostGreSQL

Example of content of a file data.sql
<syntaxhighlight lang="sql">
delete from llx_const where name='MYMODULE_IT_WORKS' and entity='__ENTITY__';
insert into llx_const (name, value, type, note, visible, entity) values ('MYMODULE_IT_WORKS','1','chaine','A constant vor my module',1,'__ENTITY__');
</syntaxhighlight>

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 the page to enable Dolibarr modules and disable the module, drop those tables in the database (if they already exists) 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===
The DAO PHP files should have been generated by ModuleBuilder after creating an object.

You can however create them manually by copying existing object however using ModuleBuilder is highly recommended. You should find examples into '''htdocs/modulebuilder/templates/class/myobject.class.php'''

In this class, there are already operational CRUD (Create/Read/Update/Delete) methods to perform an insert, a fetch (select), an update, a delete of a table row. Edit the file to use the correct module name, tables and place this file in the class subdirectory of the module. The Module Builder allows you to do this with just a few mouse clicks.

==The tab management (optional)==

===Add or remove 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:

<syntaxhighlight lang="PHP">
// Array to add new pages in new tabs or remove existing one
$this->tabs = array('objecttype:+tabname1:Title1:mylangfile@mymodule:$user->rights->mymodule->read:/mymodule/mypagetab1.php?id=__ID__' // To add a new tab identified by code tabname1
'objecttype:+tabname2:Title2:mylangfile@mymodule:$user->rights->mymodule->read:/mymodule/mypagetab2.php?id=__ID__', // To add a new tab identified by code tabname2
'objecttype:-tabname'); // To remove an existing tab identified by code tabname
</syntaxhighlight>

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 (object type) where the tab should appear is a value from the following:
{{TemplateModuleTabs}}

*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 is followed with @mymodule, Dolibarr will search translation file "*.lang" within the module, so htdocs/mymodule/langs/code_CODE/mylangfile.lang, otherwise Dolibarr will look for file htdocs/langs/code_CODE/mylangfile.lang
*Part 5: A condition to test if tab must be visible. Put 1 to be always visible.
*Part 6: 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.

In order to get the names 'tabname' of existing tabs, you have to check the names used in the function 'product_prepare_head' of the file 'core/lib/module.lib.php' corresponding to section '$head[$h][2]'.

===Show tabs navigation into your own pages===
'''When''': To show all standard tabs of an object (product, 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
<syntaxhighlight lang="PHP">require_once($url_fichier) ;</syntaxhighlight>

This is example of files to include (DOL_DOCUMENT_ROOT is often dolibarr/htdocs/) :

*Object thirdparty (thirdparty) :
**DOL_DOCUMENT_ROOT/societe/class/societe.class.php
**DOL_DOCUMENT_ROOT/core/lib/company.lib.php
*Object product (product) :
**DOL_DOCUMENT_ROOT/product/class/product.class.php
**DOL_DOCUMENT_ROOT/core/lib/product.lib.php
*Object invoice (invoice) :
**DOL_DOCUMENT_ROOT/compta/facture/class/facture.class.php
**DOL_DOCUMENT_ROOT/core/lib/invoice.lib.php

...

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

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

''Example :''
<syntaxhighlight lang="PHP">
$id=GETPOST('id','int');
$ref=GETPOST('ref','alpha');
$product = new Product($db) ;
$result = $product->fetch($id,$ref) ; // Test $result to check the database read is ok
</syntaxhighlight>

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

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

The resulting array has the following structure
<syntaxhighlight lang="PHP">
$head // Array of tabs
$head[$h] // Element to describe one tab.
$head[$h][0] // Url of page to show when you click on tab
$head[$h][1] // Title of tab
$head[$h][2] // Code name to identify the tab
</syntaxhighlight>

''Example :''
<syntaxhighlight lang="PHP">
$head = product_prepare_head($product, $user) ; // parameter $user is present for some function anly
</syntaxhighlight>

'''4. show tabs into your page'''

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

<syntaxhighlight lang="PHP">
dol_fiche_head($links, $active='0', $title='', $notab=0, $picto='')
//$links // Tableau des onglets, appelé $head plus haut.
//$active // Onglet actif (mettre le nom de l'onglet défini dans votre fichier de module, ou un nom contenu dans $head[$h][2]). Cet onglet sera mis en surbrillance
//$title // Title to show (shown into a special tab that you can't click)
//$notab
//$picto // Name of image to show into title. Possible values are:
// product
// service
// company
</syntaxhighlight>

This function will show required tabs and open an html element ''< div class="" >'' 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 '''modulebuilder/myobject_page.php''' (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 '''myobject_page.phpp''' 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.
<syntaxhighlight lang="PHP">
// Load Dolibarr environment
$res=0;
// Try main.inc.php into web root known defined into CONTEXT_DOCUMENT_ROOT (not always defined)
if (! $res && ! empty($_SERVER["CONTEXT_DOCUMENT_ROOT"])) $res=@include($_SERVER["CONTEXT_DOCUMENT_ROOT"]."/main.inc.php");
// Try main.inc.php into web root detected using web root calculated from SCRIPT_FILENAME
$tmp=empty($_SERVER['SCRIPT_FILENAME'])?'':$_SERVER['SCRIPT_FILENAME'];$tmp2=realpath(__FILE__); $i=strlen($tmp)-1; $j=strlen($tmp2)-1;
while($i > 0 && $j > 0 && isset($tmp[$i]) && isset($tmp2[$j]) && $tmp[$i]==$tmp2[$j]) { $i--; $j--; }
if (! $res && $i > 0 && file_exists(substr($tmp, 0, ($i+1))."/main.inc.php")) $res=@include(substr($tmp, 0, ($i+1))."/main.inc.php");
if (! $res && $i > 0 && file_exists(dirname(substr($tmp, 0, ($i+1)))."/main.inc.php")) $res=@include(dirname(substr($tmp, 0, ($i+1)))."/main.inc.php");
// Try main.inc.php using relative path
if (! $res && file_exists("../main.inc.php")) $res=@include("../main.inc.php");
if (! $res && file_exists("../../main.inc.php")) $res=@include("../../main.inc.php");
if (! $res && file_exists("../../../main.inc.php")) $res=@include("../../../main.inc.php");
if (! $res) die("Include of main fails");
</syntaxhighlight>
As you can see, there are several tries to load the main.inc.php (or master.inc.php). The goal is to succeed in the most cases as possible. The minimum is 2 lines: one to try to load the master/main.inc.php into the dolibarr root directory and another one to try to load the file to support the case when the module is deployed into the "custom" directory. But you can have more to deal more situation. The provided example should be able to load the file main/master.inc.php in nearly all situation/setups.

Note that you may add more "../" depending on the depth of the file relative to your module directory tree.

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 Object that contains the characteristics of the user + his permissions.
*$conf Object that contains Dolibarr configuration.
*$db Object that contains an opened connection handler to the database.
*$langs Object that contains the user's language.

Then enter your code to display the page.

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

''Example :''
<syntaxhighlight lang="PHP">
dol_include_once('/mymodule/class/myclass.class.php', 'MyClass');
</syntaxhighlight>

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

''Example :''
<syntaxhighlight lang="PHP">
require_once DOL_DOCUMENT_ROOT.'/core/class/doli.class.php';
</syntaxhighlight>

===Add some fields into existing forms===
You may want to provide a module that adds 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 to disable the "New element" menu entry and adding yours, and disable tab that shows 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 [[#Define your entries in the menu (optional)]] and [[#The tab management (optional)]] if this solution suits you (this solution is more powerful since you can change everything you want into the 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 ...

*First thing is to add a table, owned by your module, to store the value of new fields. This table will have only one column called "rowid" (will contain the 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 [[#Create your SQL tables and the PHP DAO class]].
*Next step is to add a hook into your module to add the new fields into the form. See chapter [[Hooks_system#Implement_the_Hook]] for generic documentation to use hooks.

If you follow this tutorial, to be able to add fields into category forms, you must do:
{{ToComplete}}

===Add/replace part of fields supported by hooks===
See chapter [[Hooks_system#Implement_the_Hook]] 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 the database inside your 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:

<syntaxhighlight lang="PHP">
$db->begin(); // Start transaction
$db->query("My SQL request insert, update or delete");
$db->commit(); // Validate transaction
or $db->rollback() // Cancel transaction
</syntaxhighlight>

To read:

<syntaxhighlight lang="PHP">
$resql=$db->query("My select request");
if ($resql)
{
$num = $db->num_rows($resql);
$i = 0;
if ($num)
{
while ($i < $num)
{
$obj = $db->fetch_object($resql);
if ($obj)
{
// You can use here results
print $obj->field1;
print $obj->field2;
}
$i++;
}
}
}
</syntaxhighlight>

===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:
<syntaxhighlight lang="PHP">
$form=new Form($db);
$form->select_date('','mykey',0,0,0,"myform");
</syntaxhighlight>
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:
<syntaxhighlight lang="PHP">
$mydate = dol_mktime(12, 0 , 0, $GETPOST('mykeymonth', 'int'), GETPOST('mykeyday', 'int'), GETPOST('mykeyyear', 'int'));
print strftime('%A %d %B %Y', $mydate);
</syntaxhighlight>

==Add your own setup page (optional)==
'''When''': If your module needs parameters, which are to be provided by the user, for proper setting up of the module.

===Create your page to edit parameters===
If your module needs several parameters to be setup, you must create a page to edit options (these options will be saved in the [[Table llx_const|table '''llx_const''']]).
Create a page named '''mymodule_setuppage.php''' that shows a form for possible options to update them into the above-mentioned table.
It is necessary to take an example from a page of the directory '''/admin''' that will show you the way to read/save your parameters.
Put this PHP page into the directory '''/admin''' of your module (e.g. mymodule/admin/mymodule_setuppage.php).

===Modify the descriptor file of your module===
Then, within the descriptor file of your module, modify the variable '''config_page_url''' to set the name of this PHP page.
If the page is in the directory '''admin/''', then the path is not required, e.g. like this:
<syntaxhighlight lang="PHP">
$this->config_page_url = array("mymodule_setuppage.php");
</syntaxhighlight>
If the page is in the directory '''mymodule/admin/''', then like this:
<syntaxhighlight lang="PHP">
$this->config_page_url = array("mymodule_setuppage.php@mymodule");
</syntaxhighlight>

===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 declares 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:
<syntaxhighlight lang="PHP">
// Main menu entries
$this->menu = array(); // List of menus to add
$r=0;

// Add here entries to declare new menus
// Example to declare the Top Menu entry:
$this->menu[$r]=array( 'fk_menu'=>0, // Put 0 if this is a top menu
'type'=>'top', // This is a Top menu entry
'titre'=>'MyModule top menu',
'mainmenu'=>'mymodule',
'leftmenu'=>'mymodule',
'url'=>'/mymodule/pagetop.php',
'langs'=>'mylangfile', // Lang file to use (without .lang) by module. File must be in langs/code_CODE/ directory.
'position'=>100,
'enabled'=>'1', // Define condition to show or hide menu entry. Use '$conf->mymodule->enabled' if entry must be visible if module is enabled.
'perms'=>'1', // Use 'perms'=>'$user->rights->mymodule->level1->level2' if you want your menu with a permission rules
'target'=>'',
'user'=>2); // 0=Menu for internal users, 1=external users, 2=both
$r++;

// Example to declare a Left Menu entry:
$this->menu[$r]=array( 'fk_menu'=>'fk_mainmenu=xxx', // Use 'fk_mainmenu=xxx' or 'fk_mainmenu=xxx,fk_leftmenu=yyy' where xxx is mainmenucode and yyy is a leftmenucode of parent menu
'type'=>'left', // This is a Left menu entry
'titre'=>'MyModule left menu 1',
'mainmenu'=>'xxx',
'leftmenu'=>'yyy',
'url'=>'/mymodule/pagelevel1.php',
'langs'=>'mylangfile', // Lang file to use (without .lang) by module. File must be in langs/code_CODE/ directory.
'position'=>100,
'enabled'=>'1', // Define condition to show or hide menu entry. Use '$conf->mymodule->enabled' if entry must be visible if module is enabled.
'perms'=>'1', // Use 'perms'=>'$user->rights->mymodule->level1->level2' if you want your menu with a permission rules
'target'=>'',
'user'=>2); // 0=Menu for internal users,1=external users, 2=both
$r++;
</syntaxhighlight>

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

===Test your menu entries===
Disable and re-enable your module under the 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
<syntaxhighlight lang="PHP">
$this->rights_class = 'mymodule'
</syntaxhighlight>
with correct value for mymodule.

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

<syntaxhighlight lang="PHP">
$this->rights[$r][0] = 10001;
$this->rights[$r][1] = 'Label by default of permission';
$this->rights[$r][2] = 'r';
$this->rights[$r][3] = 1;
$this->rights[$r][4] = 'action';
$this->rights[$r][5] = 'subaction';
$r++;
</syntaxhighlight>

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][1], put a label by default for permission (This label will be used if no translation can be found into the file '''admin.lang''' Translation key should be "Permission10001=My permission Label").
Into $this->rights[$r][2], types of the permission. There are three type of permission, 'r' for read, list or expert permission, 'w' for write or update permission and 'd' for delete permission.
Into $this->rights[$r][3], put 1 if this permission must be granted automatically by default to any newly created user.
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:

<syntaxhighlight lang="PHP">
if ($user->rights->mymodule->action->subaction) ...
</syntaxhighlight>

==Define your own box (optional)==
'''When''': If your module needs 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:''
<syntaxhighlight lang="PHP">
$this->boxes[0]['file']='mybox0.php@mymodule'
$this->boxes[0]['note']='My box 0'
...
$this->boxes[n]['file']='myboxn.php@mymodule'
$this->boxes[n]['note']='My box n'
</syntaxhighlight>

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 activate. Activate the box and go on the home page to see if the box is showing correctly.

==Define your own export (optional)==
'''When''': If your module provides 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 a 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 several CSS files 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 files only if you need absolutely to add not already existing styles.

Once your style sheets are ready, declare them into your module descriptor file by modifying the property '''$this->modules_parts'''.
Value to put here must be an array of relative URLs to your CSS files.
For example
<syntaxhighlight lang="PHP">
$this->module_parts = array('css' => array('/mymodule/css/mymodule.css.php','/mymodule/css/myother.css'));
</syntaxhighlight>

===Test your style sheet===
Disable and enable your module.

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

You should see into the HTML header, a line that declares 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 :
<syntaxhighlight lang="PHP">
$morejs=array("/mymodule/js/mymodule.js");
llxHeader('','Titre','','','','',$morejs,'',0,0);
</syntaxhighlight>

==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 the 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 are 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".

=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 marketplace.
But you can use it to have a package easy to distribute on your own 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 a list of file names for all new files you created for your module (module descriptor, new sql tables files, php page, images, etc...)

*Run the script via Perl (need the Perl version 5.0 or later):

<syntaxhighlight lang="bash">
perl makepack-dolibarrmodule.pl
</syntaxhighlight>
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.

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

<syntaxhighlight lang="bash">
tar -xvf mymodule.zip
</syntaxhighlight>

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

=Enabling/activation condition of external module on DoliStore=

See [[Module_Dolistore_Validation_Rules|Validation Rules]]
[[Category:Development]]

Desarrollo de un módulo

2022-06-22T09:30:10Z

Alograg: /* Crear un descriptor de Módulo (obligatorio) */ Ruta a laplantilla

[[en:Module_development]]
[[fr:Développement_module]]
[[de:Modul_Entwicklung]]
[[zh:模块开发]]


[[Category:Básico]]
{{TemplateDocDesarrollo}}
Para crear un nuevo módulo hay distintas fases a seguir. Este tutorial tiene como meta describir cada una de estas fases con el fin de ayudar a comprender las posibilidades de Dolibarr, como por ejemplo añadir una o varias de las siguientes funcionalidades:

*Añadir nuevas tablas a la base de datos.
*Añadir sus propias entradas en los menús.
*Añadir pantallas de edición/consulta de nuevas tablas.
*Añadir o eliminar pestañas en las páginas de vista/edición de objetos (factura, producto, pedido, evento, etc.)
*Añadir exportaciones predefinidas a la función “Exportar”.
*Añadir variables de substitución
*Añadir nuevas cajas a la página de inicio.
*Definir nuevos permisos.
*Activar código automático sobre una acción particular de Dolibarr.
*Insertar nuestro código mediante los hooks de Dolibarr
*Añadir un módulo de numeración
*Añadir un modelo de documento
*Añadir un nuevo tema

etc.

=[[File:Art.png]] Crear un módulo=
Los capítulos siguientes describen las acciones a realizar para crear un módulo Dolibarr. Los primeros capítulos son obligatorios cualquiera que sea la vocación de los módulos, los siguientes dependerán de lo que deba hacer el módulo

==[[File:Art.png]] Crear un descriptor de Módulo (obligatorio)==
'''Cuándo''': Obligatorio cada vez que se desarrolla una extensión, cualquiera que sea su finalidad.

===Crear su descriptor===
La primera fase es la de crear un fichero descriptor del módulo. Para ello:

*Crear el directorio '''/htdocs/''mimodulo''/core/modules'''. Seguidamente ir al directorio '''htdocs/modulebuilder/template''' y copiar el archivo modMyModule.class.php en el directorio '''htdocs/''mimodulo''/core/modules'''.

A continuación, modificar el contenido del archivo, reemplazando:

*los "modMyModule" por un valor que corresponda a la finalidad de su módulo. Este valor debe siempre comenzar por mod.

ATENCIÓN: El MiModulo debe estar compuesto por una serie de caracteres, siendo los únicos permitidos [A-Za-z_] con longuitud max de MyModule de 12 caracteres.

*$this->numero = 100000 por un número de módulo que esté libre. Ver [[List of modules id|Listado de los id de módulos]]
*Modificar eventualmente otras variables definidas por los desarrolladores (ver el comentario en el código del esqueleto para ver su significado)
*Crear el directorio /htdocs/mimodulo/

Ahora su fichero descriptor está configurado.

===Probar su descriptor===
Ejecute Dolibarr y vaya a la página "Configuración > Módulo". Debería aparecer una nueva línea con su nuevo módulo y la posibilidad de activarlo o no (eche un vistazo a todas las pestañas de cada categoría para encontrarlo). Es el valor $this->special el que determina en qué pestaña se encuentra su módulo.

==[[File:Art.png]] Árbol de un nuevo módulo==
Crear un directorio 'mimodulo' que contendrá los archivos del módulo. Este directorio debe de estar en el directorio '''htdocs''' y contendrá los siguientes subdirectorios:
{{TemplateModuleTreeSimple}}

==[[File:Art.png]] Crear sus tablas SQL y la clase PHP con los métodos de acceso (opcional)==
'''Cuándo:''' Si su módulo necesita gestionar sus propios datos.

===Crear sus ficheros .sql===
Si su módulo de verdad requiere administrar datos que no existen en la base de datos en la versión estándar de Dolibarr, será necesario definir ciertas tablas SQL para registrar esos datos.

Revisa que en el descriptor de archivo (mymodule/core/modules/mymodule.class.php) la línea
<syntaxhighlight lang="PHP">
$this->_load_tables('/mymodule/sql/');
</syntaxhighlight>
esté descomentada y correctamente configurada.

Cree un subdirectorio sql en el directorio de su módulo (por ejemplo, htdocs/mimodulo/sql), con el fin de colocar los scripts sql que va a crear.

''Regla a respetar:''

*Agregue los archivos de orden de creación de sus tablas siguiendo el principio de un fichero '''llx_mitabla.sql'' por tabla, eventualmente acompañado del archivo '''''<nowiki/>''llx_mitabla.key.sql'<nowiki/>'' (ver los archivos existentes en ''install/mysql/tables'', para tomar ejemplo).
*The recommended type and name for SQL fields are defined into page [[Language_and_development_rules#Table_and_fields_structures]].
*En términos de orden de gestión de datos, todos deben estar en un archivo llamado '''data.sql''' situado en la misma carpeta '''/mimodulo/sql/'''.

Ejemplo de contenido de un fichero data.sql
<syntaxhighlight lang="sql">
delete from llx_const where name='MYMODULE_IT_WORKS' and entity='__ENTITY__';
insert into llx_const (name, value, type, note, visible, entity) values ('MYMODULE_IT_WORKS','1','chaine','A constant vor my module',1,'__ENTITY__');
</syntaxhighlight>

Las órdenes SQL de los archivos deben de ser operacionales para la base de datos '''mysql'''.
Nota: Los archivos de otras bases de datos no se mantienen. Se leen y se convierten al vuelo por el driver de la base de datos.

===Probar su archivo .sql===
Una vez que los archivos estén listos, puede volver a Dolibarr para desactivar el módulo, eliminar las tablas de la base de datos y reactivar el módulo. Las tablas deben ser recreadas por la activación del módulo. Si no es así, verifique sus scripts o consulte los logs Dolibarr.

===Generar la clase PHP de acceso (DAO)===
Una vez que sus tablas estén creadas en la base de datos, vaya al directorio '''dev/skeletons''', copie el archivo '''build_class_from_table.php''' en el directorio sql/ de su módulo module, y ejecute el script
<syntaxhighlight lang="bash">
php build_class_from_table.php nombretabla
</syntaxhighlight>
Nota: Si el comando no funciona, intente con php-cli en lugar de php.

Esto genera un archivo '''out.nombretabla.class.php''' que contiene la clase de gestión de la tabla “nombretabla”. En esta clase se encuentran los métodos CRUD (Create/Read/Update/Delete) ya operativos para hacer un ''insert'', un ''fetch'' (''select''), un ''update'', y un ''delete'' de una línea de la tabla. Suprima justo el "out" del nombre del archivo y póngalo en un subdirectorio de '''htdocs''' propio en su módulo (Por ejemplo en '''htdocs/mimodulo''').

Un archivo '''out.nombretabla_script.php''' se genera igualmente y contiene un ejemplo de código para utilizar la clase para cada uno de los cuatro métodos CRUD.

==Visualización de pestañas (opcional)==

===Añadir o eliminar pestañas en las fichas entidad===
'''Cuándo''' : Para añadir su propia pestaña en las pestañas estándar de una ficha entidad (factura, pedido, presupuesto, miembro...)

Para ello, vaya al archivo descriptor del módulo creado anteriormente y modifique la tabla $this->tabs:
<syntaxhighlight lang="PHP">
// Array to add new pages in new tabs or remove existing one
$this->tabs = array('objecttype:+tabname1:Title1:@mymodule:/mymodule/mynewtab1.php?id=__ID__', // To add a new tab identified by code tabname1
'objecttype:+tabname2:Title2:@mymodule:/mymodule/mynewtab2.php?id=__ID__', // To add another new tab identified by code tabname2
'objecttype:-tabname'); // To remove an existing tab identified by code tabname
</syntaxhighlight>

La tabla debe contener una lista de cadena, cada cadena representa una nueva pestaña.
El formato de la cadena se compone de 4 partes separadas por ":"

*Parte 1: El código de la entidad (objecttype) en la que debe aparecer la pestaña siendo el valor de ella misma:
{{TemplateModuleTabs-es}}

*Parte 2: El título de la pestaña. Puede ser una etiqueta directa o mejor un código de traducción de un archivo lang.
*Parte 3: El nombre del archivo .lang (sin la extensión .lang) que contiene la correspondencia entre el código de traducción y la etiqueta a mostrar. Si el nombre empieza con @, Dolibarr buscará el archivo en el directorio lang del propio módulo, es decir, htdocs/mimodulo/langs/code_CODE/mimodulo.lang, de lo contrario Dolibarr buscará el archivo de en /langs/code_CODE/mimodulo.lang

*Parte 4: La url de la página a mostrar cuando se haga click en las pestaña. La cadena __ID__ será reemplazada automáticamente por el Id de la entidad concerniente.

Para alimentar el contenido de la pestaña con los datos de la base de datos, vea el capítulo siguiente.

===Añadir pestañas de una ficha entidad en su propia página===
'''Cuándo''' : Para mostrar las pestañas estándar de ficha entidad (producto, tercero, etc.) en su propia pestaña de una entidad.

Hay que hacer lo siguiente :

'''1. Incluir los archivos que definen las funciones útiles dentro de sus archivos'''

Para cada ficha entidad, hay que incluir dos archivos con la instrucción
<syntaxhighlight lang="PHP">require_once($url_fichier) ;</syntaxhighlight>

Aquí le mostramos la lista de estos archivos (DOL_DOCUMENT_ROOT correspondiente al directorio '''dolibarr/htdocs/''') :

*Entidad tercero (thirdparty) :
**DOL_DOCUMENT_ROOT/societe/class/societe.class.php
**DOL_DOCUMENT_ROOT/core/lib/company.lib.php
*Entidad producto (product) :
**DOL_DOCUMENT_ROOT/product.class.php
**DOL_DOCUMENT_ROOT/lib/product.lib.php
*Entidad factura (invoice) :
**DOL_DOCUMENT_ROOT/facture.class.php
**DOL_DOCUMENT_ROOT/lib/invoice.lib.php

'''2. Crear y cargar el objeto a mostrar en su pestaña'''

Crear el objeto de la clase deseada, y recuperar los datos del objeto a partir de la base de datos. Para ello deberá utilizar las funciones fetch() de la clase correspondiente, pasando el parámetro del indentificador del objeto que recupera desde la url (ej : /mononglet.php?id=1).

''Ejemplo :''
<syntaxhighlight lang="PHP">
$id=$_GET["id"];
$product = new Product($db) ;
$result = $product->fetch($id) ; //Tester $result pour vérifier que l'accès à la base s'est bien passé
</syntaxhighlight>

'''3. Recuperar la lista de pestañas correspondientes a la entidad seleccionada'''

Usar la función XXX_prepare_head($obj), donde XXX es le nombre de la entidad, para crear una tabla que contiene las definiciones de las pestañas a mostrar. El parámetro a pasar es el objeto del que desea mostrar las pestañas.

La tabla devuelta se compone de la siguiente manera :
<syntaxhighlight lang="PHP">
$head // Tableau des onglets
$head[$h] // Élément décrivant un onglet. Il y aura autant de $h que d'onglets à afficher
$head[$h][0] // Url de la page affichée quand on clique sur l'onglet
$head[$h][1] // Titre de l'ongLet
$head[$h][2] // Code de l'onglet, à utiliser pour choisir quel onglet sera 'actif' (voir paragraphe suivant)
</syntaxhighlight>

''Ejemplo :''
<syntaxhighlight lang="PHP">
$head = product_prepare_head($product, $user) ; //le paramètre $user n'est pas présent sur certaines fonctions
</syntaxhighlight>

'''4. Mostrar las pestañas en su pestaña'''

Use la función dol_fiche_head() que muestra las pestañas contenidas en la tabla $head devuelta por XX_prepare_head().

<syntaxhighlight lang="PHP">
dol_fiche_head($links, $active='0', $title='', $notab=0, $picto='')
$links // Tableau des onglets, appelé $head plus haut.
$active // Onglet actif (mettre le nom de l'onglet défini dans votre fichier de module, ou un nom contenu dans $head[$h][2]). Cet onglet sera mis en surbrillance
$title // ?
$notab // Mettre ce paramètre à 1 permet de ne pas afficher de zone bleue en dessous des onglets.
$picto // Nom de l'image à utiliser au début de la barre des onglet. Les choix suivant sont possibles :
// product
// service
// company
</syntaxhighlight>

Esta función muestra las pestañas deseadas y abre un elemento ''< div class="" >'' que corresponde a la zona azul bajo las pestañas (si el parámetro $notab = 0). Para cerrar la zona azul, simplemente cierre el elemento ''< /div >'' en el código PHP.

''Nota'':
Para más detalles, consulte la [http://www.dolibarr.fr/doxygen/ documentación Doxygen] o directamente el código de Dolibarr.

==Crear sus páginas pantalla PHP (opcional)==
'''Cuándo:''' Si su módulo consiste en añadir funcionalidades que necesitan nuevas pantallas.

===Crear una página pantalla PHP===
Debe crear a continuación pantallas PHP que se basen en los datos de sus tablas utilizando los esqueletos como ejemplo del directorio '''modulebuilder'''. (Para el desarrollo de un script en línea de comandos, ver [[Desarrollo de scripts]]).

Para crear una nueva página de usuario, cree un subdirectorio de '''htdocs''' (si es que no existe ya) propio en su módulo (En '''htdocs/mimodulo''', por ejemplo), con el fin de ubicar en él las páginas que va a crear.

Copie allí el archivo '''myobject_page.php''', que va a servir de punto de partida a su página. Modifique el archivo para que la ruta relativa de
<syntaxhighlight lang="PHP">
// Load Dolibarr environment
$res=0;
// Try main.inc.php into web root known defined into CONTEXT_DOCUMENT_ROOT (not always defined)
if (! $res && ! empty($_SERVER["CONTEXT_DOCUMENT_ROOT"])) $res=@include($_SERVER["CONTEXT_DOCUMENT_ROOT"]."/main.inc.php");
// Try main.inc.php into web root detected using web root caluclated from SCRIPT_FILENAME
$tmp=empty($_SERVER['SCRIPT_FILENAME'])?'':$_SERVER['SCRIPT_FILENAME'];$tmp2=realpath(__FILE__); $i=strlen($tmp)-1; $j=strlen($tmp2)-1;
while($i > 0 && $j > 0 && isset($tmp[$i]) && isset($tmp2[$j]) && $tmp[$i]==$tmp2[$j]) { $i--; $j--; }
if (! $res && $i > 0 && file_exists(substr($tmp, 0, ($i+1))."/main.inc.php")) $res=@include(substr($tmp, 0, ($i+1))."/main.inc.php");
if (! $res && $i > 0 && file_exists(dirname(substr($tmp, 0, ($i+1)))."/main.inc.php")) $res=@include(dirname(substr($tmp, 0, ($i+1)))."/main.inc.php");
// Try main.inc.php using relative path
if (! $res && file_exists("../main.inc.php")) $res=@include("../main.inc.php");
if (! $res && file_exists("../../main.inc.php")) $res=@include("../../main.inc.php");
if (! $res && file_exists("../../../main.inc.php")) $res=@include("../../../main.inc.php");
if (! $res) die("Include of main fails");
</syntaxhighlight>

sea la correcta, en función de la profundidad del directorio en el que se encuentra el archivo (quitando o añadiendo "../"). Es en el "main" donde se carga el entorno técnico y las habilitaciones. Los objetos variables se posicionan ahora:

*$user – El objeto que contiene las características del usuario y sus derechos.
*$conf – El objeto que contiene la configuración de Dolibarr.
*$db – El objeto que contiene el gestor de conexión abierto a la base de datos.
*$langs – El objeto que contiene el idioma del usuario.

*La inclusión de una clase o una biblioteca dedicada al módulo, sin saber a dónde se llamará el archivo, se realiza mediante una función de Dolibarr (no directamente mediante include_once):

''Ejemplo :''
<syntaxhighlight lang="PHP">
dol_include_once('/mimodulo/class/miclass.class.php', 'MiClass');
</syntaxhighlight>

*Las clases de llamadas Dolibarr utilice la siguiente sintaxis:

''Ejemplo :''
<syntaxhighlight lang="PHP">
require_once DOL_DOCUMENT_ROOT.'/core/class/doli.class.php';
</syntaxhighlight>

===Acceso a la base de datos===
Si necesita realizar modificaciones en su tabla de la base de datos, utilice la clase generada más arriba.

Si de todos modos quiere acceder a las tablas sin objeto PHP dedicado, esto es posible (por ejemplo para recuperar una lista de registros). En ese caso, piense en seguir estos ejemplos.

Para un ''insert'', ''update'' o ''delete'':
<syntaxhighlight lang="PHP">
$db->begin(); // Debut transaction
$db->query("Ma requete insert, update ou delete");
$db->commit(); // Valide
o $db->rollback() // Annule
</syntaxhighlight>

Para una lectura:
<syntaxhighlight lang="PHP">
$resql=$db->query("Ma requete select");
if ($resql)
{
$num = $db->num_rows($resql);
$i = 0;
if ($num)
{
while ($i < $num)
{
$obj = $db->fetch_object($resql);
if ($obj)
{
// You can use here results
print $obj->field1;
print $obj->field2;
}
$i++;
}
}
}
</syntaxhighlight>

===Definición de estilos===
Para que el aspecto de la página guarde coherencia con el tema Dolibarr, es necesario utilizar los estilos CSS de Dolibarr.

Por ejemplo:

*class="liste_titre"1 en las etiquetas tr y td para una línea de título de tabla.
*class=”pair” o class=”impair” en las etiquetas tr y td de las líneas de datos de la tabla.
*class=”flat” en todos los campos en los que se teclea (input, select, textarea...)
*class=”button” en los objetos de tipo input type=”submit”.

===Utilizar el selector de fechas de Dolibarr===
Si quiere, puede beneficiarse del selector de fechas en las pantallas Dolibarr. Para ello, utilice la siguiente línea:
<syntaxhighlight lang="PHP">
$form=new Form($db);
$form->select_date('','mykey',0,0,0,"myform");
</syntaxhighlight>

La cadena "mikey" identifica el campo fecha. Hace falta introducir un valor diferente en caso de que haya varios campos. La cadena "myform" es el nombre del campo "FORM" (en el formulario, name="myform" de la página html). La visualización de un selector de fecha debe por tanto estar integrada en un formulario html.

Para recuperar el valor, a la herencia de POST, el comando es:
<syntaxhighlight lang="PHP">
$mydate = dol_mktime(12, 0 , 0, $_POST['mykeymonth'], $_POST['mykeyday'], $_POST['mykeyyear']);
print strftime('%A %d %B %Y', $mydate);
</syntaxhighlight>

==Definir su página de configuración (opcional)==
'''Cuándo:''' Si su módulo ofrece varias opciones parametrizables.

===Crear su página de edición de configuración===
Si su módulo ofrece varias opciones parametrizables, es necesario crear una página PHP para editar las opciones (que serán guardadas en la [[Table llx_const|tabla '''llx_const''']]). Cree una página PHP llamada '''mimodulo_setuppage.php''', que registre las opciones posibles y las ponga al día. Es necesario tomar como ejemplo una página de '''/admin''' que le muestre el método para leer o guardar en la base de datos su opción. Coloque esta página de configuración también en el directorio '''/admin'''. A continuación, en el descriptor del módulo, modifique la variable para indicar el nombre de esta página PHP (no es necesario modificar la ruta, ya que la página estará forzosamente en el directorio '''/admin''').
<syntaxhighlight lang="PHP">
$this->config_page_url = array("monmodule_setuppage.php");
</syntaxhighlight>

===Probar su página===
Vaya a la página '''Configuración > módulo'''. Debería aparecer un icono que permite acceder a la página de configuración, y debería poder modificar estas opciones y verlas en la base de datos.

==Definir sus entradas de menú (opcional)==
'''Cuándo:''' Si ha creado páginas PHP, es necesario que estas pantallas sean accesibles desde el menú Dolibarr.

===Definir sus entradas de menú===
Para ello, hace falta definir en el archivo descriptor de menú de tabla this->menu, que declara los menús.
Esta tabla contiene todas las entradas que aparecerán en los menús una vez que el módulo sea activado. Los archivos de descriptor de módulo contienen un ejemplo de cómo se declara el menú superior, así como las entradas correspondientes en el menú de la derecha

He aquí un ejemplo de declaración de entradas de menú en el fichero descriptor:
<syntaxhighlight lang="PHP">
// Main menu entries
$this->menu = array(); // List of menus to add
$r=0;

// Add here entries to declare new menus
// Example to declare the Top Menu entry:
$this->menu[$r]=array( 'fk_menu'=>0, // Put 0 if this is a top menu
'type'=>'top', // This is a Top menu entry
'titre'=>'MyModule top menu',
'mainmenu'=>'mymodule',
'leftmenu'=>'mymodule',
'url'=>'/mymodule/pagetop.php',
'langs'=>'mylangfile', // Lang file to use (without .lang) by module. File must be in langs/code_CODE/ directory.
'position'=>100,
'enabled'=>'1', // Define condition to show or hide menu entry. Use '$conf->mymodule->enabled' if entry must be visible if module is enabled.
'perms'=>'1', // Use 'perms'=>'$user->rights->mymodule->level1->level2' if you want your menu with a permission rules
'target'=>'',
'user'=>2); // 0=Menu for internal users, 1=external users, 2=both
$r++;

// Example to declare a Left Menu entry:
$this->menu[$r]=array( 'fk_menu'=>'fk_mainmenu=xxx', // Use 'fk_mainmenu=xxx' or 'fk_mainmenu=xxx,fk_leftmenu=yyy' where xxx is mainmenucode and yyy is a leftmenucode of parent menu
'type'=>'left', // This is a Left menu entry
'titre'=>'MyModule left menu 1',
'mainmenu'=>'xxx',
'leftmenu'=>'yyy',
'url'=>'/mymodule/pagelevel1.php',
'langs'=>'mylangfile', // Lang file to use (without .lang) by module. File must be in langs/code_CODE/ directory.
'position'=>100,
'enabled'=>'1', // Define condition to show or hide menu entry. Use '$conf->mymodule->enabled' if entry must be visible if module is enabled.
'perms'=>'1', // Use 'perms'=>'$user->rights->mymodule->level1->level2' if you want your menu with a permission rules
'target'=>'',
'user'=>2); // 0=Menu for internal users,1=external users, 2=both
$r++;
</syntaxhighlight>

Para condicionar el acceso al menú segun los permisos, modificar la propiedad '''perms''' de la tabla. Ver el capítulo sobre permisos, un poco más abajo, para saber como realizar los permisos.

===Probar sus entradas de menú===
Desactive y reactive su módulo bajo Dolibarr. Las entradas del menú deberían aparecer después de hacerlo (si la condición 'enabled' está activada).

==Definir sus propios permisos (opcional)==
'''Cuándo:''' Si quiere añadir nuevos permisos.

La definición de permisos que gestionará su módulo se hace en el archivo descriptor creado en la primera fase. Modifique la línea $this->rights_class = 'facture' para que diga:
<syntaxhighlight lang="PHP">
$this->rights_class = 'mimodulo';
</syntaxhighlight>

A continuación, rellene la tabla $this->rights con tantas entradas como permisos diferentes vaya a definir:
<syntaxhighlight lang="PHP">
$this->rights[$r][0] = 10001;
$this->rights[$r][1] = 'Texto por defecto de mi permiso';
$this->rights[$r][3] = 1;
$this->rights[$r][4] = 'accion';
$this->rights[$r][5] = 'subaccion';
$r++;
</syntaxhighlight>

En $this->rights[$r][0], introduzca un id de permiso que no haya sido ocupado ya (para saber qué id están siendo ya utilizadas, ver el menú '''Información del Sistema''' en una instalación de Dolibarr que esté funcionando. En $this->rights[$r][3], introduzca 1 si este permiso se atribuye por defecto a los usuarios según son creados. En $this->rights[$r][1] introduzca un texto por defecto -que será mostrado si no se encuentra traducción para su permiso en el archivo '''admin.lang'''). En $this->rights[$r][4] y $this->rights[$r][5], introduzca una cadena de acción y subacción sin espacios. Después puede probar si un usuario tiene los permisos bien, introduciendo la siguiente secuencia en el código PHP:
<syntaxhighlight lang="PHP">
if ($user->rights->mimodulo->accion->subaccion) ...
</syntaxhighlight>

==Definir sus propios paneles (opcional)==
'''Cuándo:''' Si su módulo tiene uno o varios paneles.

===Defina sus paneles===
Para ello, modifique las tablas $this->boxes del archivo descriptor de módulo. Es suficiente con añadir 2 líneas por cada archivo de panel que se encuentre en el directorio '''htdocs/mimodulo/core/boxes'''.

Ejemplo:
<syntaxhighlight lang="PHP">
$this->boxes[0]['file']='mabox0.php@mimodulo'
$this->boxes[0]['note']='Mi panel 0'
...
$this->boxes[n]['file']='maboxn.php@mimodulo'
$this->boxes[n]['note']='Mi panel n'
</syntaxhighlight>

A continuación cree los archivos '''htdocs/mimodulo/core/boxes/mabox0.php''', '''htdocs/mimodulo/core/boxes/mabox1.php'''... tomando como ejemplo los paneles existentes (en el directorio htdocs/core/boxes)

===Pruebe sus paneles en Dolibarr===
Vaya al menú '''Inico – Configuración – Paneles'''. Sus paneles deben aparecer en la lista de paneles activables. Actívelos, vaya a la página de bienvenida y verifique que se muestran correctamente.

==Definir sus propias exportaciones (opcional)==
'''Cuándo:''' Si su módulo incorpora exportaciones predefinidas de datos (tanto para sus propias tablas o para otras tablas existentes de otros módulos de Dolibarr)

===Definir la exportación===
Para ello, descomente y modifique las tablas $this->export_xxx de su archivo descriptor de módulo.

===Probar la exportación===
Vaya al menú "Herramientas > Exportar" de Dolibarr. Su exportación debería aparecer en la lista de exportaciones predefinidas disponibles (si su módulo ha sido activado correctamente). Deberían aparecer, para que pudiera elegirlos, los campos que definió en la fase anterior en las tablas correspondientes. Seleccione algunos campos y pruebe a generar un archivo de exportación.

==Definir sus estilos CSS (opcional)==
'''Cuándo:''' Si en sus pantallas PHP utiliza clases de estilos distintas a las de los temas de Dolibarr (no recomendado).

Esta funcionalidad todavía no es operativa en la versión 2.4., a pesar de estar ya descrita.

===Crear y declarar su hoja de estilos===
Crear un archivo de estilos llamada '''mimodulo.css''' o '''mimodule.css.php''' y guardarla en el directorio '''''mimodulo''''' dentro de '''htdocs'''. Solo puede haber un archivo css propio a cada módulo.
Recordamos que es mejor usar los estilos ya existentes en Dolibarr (el archivo css usado por Dolibarr es el archivo '''themes/nomtheme/''nombretema''.css.php'''.

Una vez su hoja de estilos esté disponible, declárela en su archivo descriptor de módulo modificando la propiedad '''$this->module_parts'''.
El valor a indicar debe ser la ruta URL relativa de su archivo css.
Por ejemplo
<syntaxhighlight lang="PHP">
$this->module_parts = array('css' => array('/mimodulo/css/mimodulo.css.php'));
</syntaxhighlight>

===Probar su hoja de estilos===
Desactivar y reactivar su módulo.

Ir la página de inicio de Dolibarr. Ver el código de la página HTML.

Debería ver en el encabezado HTML, una línea de declaración de su hoja de estilos.

==Definir sus funciones Javascript (opcional)==
'''Cuando''': Si en sus pantallas en PHP utiliza funciones de Javascript no disponibles en estandard (archivo lib_head.js)

Si en sus pantallas en PHP utiliza funciones javascript, es necesario asegurarse de que las funciones declaradas en un archivo javascript '''htdocs/mimodulo/js/monmodule.js''' sea cargado en la cabecera del head html.

Para pedir a Dolibarr que gestione en la generación de la sección header la inclusión de uno de sus archivos javascript, es necesario proporcionar como parámetro a la función llxHeader(), al inicio de su página, la URL hacia el js a incluir.

Ejemplo para la página /htdocs/mimodulo/mapage.php :
<syntaxhighlight lang="PHP">
require('../main.inc.php');
$morejs=array("/mimomulo/js/monmodule.js");
llxHeader('','Titulo','','','','',$morejs,'',0,0);
</syntaxhighlight>

==Ejecutar código sobre un evento Dolibarr (opcional)==
'''Cuándo:''' Si quiere que se ejecuten acciones particulares al activar ciertas acciones estandar de Dolibarr (por ejemplo, si deseáramos actualizar una tabla de mi módulo cada vez que se crea una factura en Dolibarr), hará falta crear un archivo '''disparador (triggers)'''.

Véase también [[Interfaces Dolibarr hacia el exterior]] e [[Interfaces del Exterior hacia Dolibarr]]

==Insertar su código usando los hooks de Dolibarr (opcional)==
'''Cuándo''': Cuando desee cambiar o añadir otro tipo de código en un evento de negociado (véase lel capítulo anterior para esto).

Véase la página [[El sistema Hooks]].

==Añadir un módulo de numeración (opcional)==
'''Cuándo''': Si quiere añadir una regla de numeración no cubierta por los módulos por defecto.

Véase la página [[Crear un módulo de numeración]].

==Añadir un nuevo módulo de documento (opcional)==
'''Cuándo''': Si quiere añadir un nuevo modelo de documento.

La documentación relativa a la generación de documentos desde los modelos se encuentra disponible en la página [[Crear un modelo de documento PDF]] o [[Crear un modelo de documento ODT]].

==Añadir un tema (opcional)==
'''Cuándo''': Si quiere un interface con colores personalizados.

Véase la página [[Temas]].

=[[File:Art.png]] Algunas reglas de código=
Las reglas de código a seguir se definen en la [[Documentación Desarrolladores| Documentación para desarrolladores]], concretamente en la sección "Lenguaje" del capítulo de "Información General".

=[[File:Art.png]] Crear un paquete para liberar e instalar su módulo=
Este proceso debe ser usado para fabricar un paquete con el fin de enviarlo a la tienda oficial http://www.dolistore.com.

También puede usarlo para distribuir fácilmente su módulo vía su propio método de distribución.

*Vaya al directorio '''/build''' y copie el archivo '''makepack-dolibarrmodules.conf''' como '''makepack-mimodulo.conf'''. Cuidado: este directorio puede no ser suministrado en los paquetes de versión estables. Si es el caso, puede bajarte la última snapshot en la sección de Downloads del sitio de Dolibarr con el nombre “Development Version” (tome en este caso todos los directorios que sean autónomos e independientes de la versión).

Teclee en este archivo la lista de nombres de los nuevos archivos que ha creado para su módulo (descriptor de módulo, nuevos ficheros sql de tablas, páginas php, imágenes, etc...)

*Lance el script vía Perl (necesita la versión 5.0. o superiores de Perl)

<syntaxhighlight lang="bash">
perl makepack-dolibarrmodule.pl
</syntaxhighlight>

El script le pide el nombre de su módulo, su versión mayor y menor. Se va a crear un fichero '''mimodulo.zip''', que incluirá su módulo listo para ser liberado.

*La persona que reciba su módulo deberá ubicar el archivo en el directorio raíz de Dolibarr y ejecutar el comando:

<syntaxhighlight lang="bash">
tar -xvf monmodule.zip
</syntaxhighlight>

*Si desea que su módulo sea aprovechado por todos, puede enviarlo (el fichero zip) al sitio web de Dolibarr, en la sección de descargas: {{LinkToPluginDownload}} (debe de haber creado una cuenta y estar logeado para que aparezca el link "Submit a product").
**Si su módulo está correctamente realizado, será rápidamente validado.
**Si la calidad es suficiente, la licencia lo permite y la funcionalidad del módulo es de interés general, el código podrá añadirse al código fuente de Dolibarr (salvo que no lo desee).

Module development

2022-06-22T08:51:33Z

Alograg: /* Create a Module descriptor for your Module (required) */ Path to template

[[fr:Développement_module]]
[[es:Desarrollo_de_un_módulo]]
[[de:Modul_Entwicklung]]
[[zh:模块开发]]


[[Category:Core]]
{{TemplateDocDevEn}}

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 :

*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 widget 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 rule to generate the reference of objects
*Add a new document template.
*Add a new skin.

etc...

Following chapters presents how to do all of this manually with an easy way.

=Module creation with the module builder=
From Dolibarr 9.0 it is possible to create the main pages of your module with the Module Builder. To activate it:

*Go into the list of module and enable the module "Module Builder",

[[File:Mod_builder_2.png|400px]]

*Then click on the "bug" image in the top right of screen.

[[File:Mod_builder_3.png|400px]]

=Example of Template External Module=
A good model to start development of external module can be found here : [https://github.com/Dolibarr/dolibarr/tree/develop/htdocs/modulebuilder/template GitHub Dolibarr Module Modèle]

=Create your module=
==Create a Module descriptor for your Module (required)==
'''When it is required''': Required as soon as an addon is developed, whatever its goal is (except for adding a skin).

'''Since Dolibarr 9.0, you should use the ModuleBuilder module provided as a standard module to generate the module descriptor'''

===Create your module descriptor===
The first step is to create a file descriptor for the module.

*Create directory '''/htdocs/''mymodule''/core/modules'''. Then copy the file modMyModule.class.php from the directory htdocs/modulebuilder/template into this directory '''htdocs/''mymodule''/core/modules'''. Change the name of the file modMyModule.class.php to the name corresponding to the purpose of your module. Name of the file must start with initial 'mod' and end with .class.php (for example if you want to give the name 'NewName' to this file, then the name should be 'modNewName.class.php').

Next modify the contents of this file as follows:

*Replace all "modMyModule" with a value which corresponds to the purpose of your module. This value must always start with 'mod' and contain only alpha characters (again, if the name given to the file was 'NewName', then replace all "modMyModule" with "modNewName").
*Change the number in: $this->numero = 100000 by a number that designates your module id. To avoid conflicts with other modules, you can consult the page that lists already reserved id numbers: [[List of modules id|List of modules id]].
*Modify any other variables defined in the constructor (see comment in the code skeleton for their meaning).

Your file descriptor for your module is ready. See the next step to activate it.

===Test your descriptor===

Launch Dolibarr and go to page '''Setup->module'''?
If you set the property version in the module description you should see a new line with your new module and the possibility to activate it or not. If you set the property version to "develop" or "experiental", to see your module, you must first go into '''Setup-Others''' and set MAIN_FEATURES_LEVEL to 1 to see "experimental" modules or 2 to see "development" modules.

==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 the second line is mandatory.

{{TemplateModuleTreeSimple}}

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

Scripts for creating tables and loading data by your own module are saved into a subdirectory sql ('''"mymodule/sql"''') of your module. (With ModuleBuilder, the directory and all sql files will be created automatically when you will create a new Object from tab Object).

Then check into your descriptor file, into function '''init''' that the line

<syntaxhighlight lang="PHP">$this->_load_tables('/mymodule/sql/');</syntaxhighlight>

is not commented.

''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).
*The recommended type and name for SQL fields are defined into page [[Language_and_development_rules#Table_and_fields_structures]].
*To manage data, you must create a file called '''data.sql''' inside directory '''/mymodule/sql/''' that contains SQL command to add/edit/delete data.
*Don't use the double quote for strings (eg 'chaine' not "chaine") because the double quote have a specific meaning in PostGreSQL

Example of content of a file data.sql
<syntaxhighlight lang="sql">
delete from llx_const where name='MYMODULE_IT_WORKS' and entity='__ENTITY__';
insert into llx_const (name, value, type, note, visible, entity) values ('MYMODULE_IT_WORKS','1','chaine','A constant vor my module',1,'__ENTITY__');
</syntaxhighlight>

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 the page to enable Dolibarr modules and disable the module, drop those tables in the database (if they already exists) 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===
The DAO PHP files should have been generated by ModuleBuilder after creating an object.

You can however create them manually by copying existing object however using ModuleBuilder is highly recommended. You should find examples into '''htdocs/modulebuilder/templates/class/myobject.class.php'''

In this class, there are already operational CRUD (Create/Read/Update/Delete) methods to perform an insert, a fetch (select), an update, a delete of a table row. Edit the file to use the correct module name, tables and place this file in the class subdirectory of the module. The Module Builder allows you to do this with just a few mouse clicks.

==The tab management (optional)==

===Add or remove 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:

<syntaxhighlight lang="PHP">
// Array to add new pages in new tabs or remove existing one
$this->tabs = array('objecttype:+tabname1:Title1:mylangfile@mymodule:$user->rights->mymodule->read:/mymodule/mypagetab1.php?id=__ID__' // To add a new tab identified by code tabname1
'objecttype:+tabname2:Title2:mylangfile@mymodule:$user->rights->mymodule->read:/mymodule/mypagetab2.php?id=__ID__', // To add a new tab identified by code tabname2
'objecttype:-tabname'); // To remove an existing tab identified by code tabname
</syntaxhighlight>

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 (object type) where the tab should appear is a value from the following:
{{TemplateModuleTabs}}

*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 is followed with @mymodule, Dolibarr will search translation file "*.lang" within the module, so htdocs/mymodule/langs/code_CODE/mylangfile.lang, otherwise Dolibarr will look for file htdocs/langs/code_CODE/mylangfile.lang
*Part 5: A condition to test if tab must be visible. Put 1 to be always visible.
*Part 6: 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.

In order to get the names 'tabname' of existing tabs, you have to check the names used in the function 'product_prepare_head' of the file 'core/lib/module.lib.php' corresponding to section '$head[$h][2]'.

===Show tabs navigation into your own pages===
'''When''': To show all standard tabs of an object (product, 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
<syntaxhighlight lang="PHP">require_once($url_fichier) ;</syntaxhighlight>

This is example of files to include (DOL_DOCUMENT_ROOT is often dolibarr/htdocs/) :

*Object thirdparty (thirdparty) :
**DOL_DOCUMENT_ROOT/societe/class/societe.class.php
**DOL_DOCUMENT_ROOT/core/lib/company.lib.php
*Object product (product) :
**DOL_DOCUMENT_ROOT/product/class/product.class.php
**DOL_DOCUMENT_ROOT/core/lib/product.lib.php
*Object invoice (invoice) :
**DOL_DOCUMENT_ROOT/compta/facture/class/facture.class.php
**DOL_DOCUMENT_ROOT/core/lib/invoice.lib.php

...

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

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

''Example :''
<syntaxhighlight lang="PHP">
$id=GETPOST('id','int');
$ref=GETPOST('ref','alpha');
$product = new Product($db) ;
$result = $product->fetch($id,$ref) ; // Test $result to check the database read is ok
</syntaxhighlight>

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

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

The resulting array has the following structure
<syntaxhighlight lang="PHP">
$head // Array of tabs
$head[$h] // Element to describe one tab.
$head[$h][0] // Url of page to show when you click on tab
$head[$h][1] // Title of tab
$head[$h][2] // Code name to identify the tab
</syntaxhighlight>

''Example :''
<syntaxhighlight lang="PHP">
$head = product_prepare_head($product, $user) ; // parameter $user is present for some function anly
</syntaxhighlight>

'''4. show tabs into your page'''

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

<syntaxhighlight lang="PHP">
dol_fiche_head($links, $active='0', $title='', $notab=0, $picto='')
//$links // Tableau des onglets, appelé $head plus haut.
//$active // Onglet actif (mettre le nom de l'onglet défini dans votre fichier de module, ou un nom contenu dans $head[$h][2]). Cet onglet sera mis en surbrillance
//$title // Title to show (shown into a special tab that you can't click)
//$notab
//$picto // Name of image to show into title. Possible values are:
// product
// service
// company
</syntaxhighlight>

This function will show required tabs and open an html element ''< div class="" >'' 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 '''modulebuilder/myobject_page.php''' (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 '''myobject_page.phpp''' 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.
<syntaxhighlight lang="PHP">
// Load Dolibarr environment
$res=0;
// Try main.inc.php into web root known defined into CONTEXT_DOCUMENT_ROOT (not always defined)
if (! $res && ! empty($_SERVER["CONTEXT_DOCUMENT_ROOT"])) $res=@include($_SERVER["CONTEXT_DOCUMENT_ROOT"]."/main.inc.php");
// Try main.inc.php into web root detected using web root calculated from SCRIPT_FILENAME
$tmp=empty($_SERVER['SCRIPT_FILENAME'])?'':$_SERVER['SCRIPT_FILENAME'];$tmp2=realpath(__FILE__); $i=strlen($tmp)-1; $j=strlen($tmp2)-1;
while($i > 0 && $j > 0 && isset($tmp[$i]) && isset($tmp2[$j]) && $tmp[$i]==$tmp2[$j]) { $i--; $j--; }
if (! $res && $i > 0 && file_exists(substr($tmp, 0, ($i+1))."/main.inc.php")) $res=@include(substr($tmp, 0, ($i+1))."/main.inc.php");
if (! $res && $i > 0 && file_exists(dirname(substr($tmp, 0, ($i+1)))."/main.inc.php")) $res=@include(dirname(substr($tmp, 0, ($i+1)))."/main.inc.php");
// Try main.inc.php using relative path
if (! $res && file_exists("../main.inc.php")) $res=@include("../main.inc.php");
if (! $res && file_exists("../../main.inc.php")) $res=@include("../../main.inc.php");
if (! $res && file_exists("../../../main.inc.php")) $res=@include("../../../main.inc.php");
if (! $res) die("Include of main fails");
</syntaxhighlight>
As you can see, there are several tries to load the main.inc.php (or master.inc.php). The goal is to succeed in the most cases as possible. The minimum is 2 lines: one to try to load the master/main.inc.php into the dolibarr root directory and another one to try to load the file to support the case when the module is deployed into the "custom" directory. But you can have more to deal more situation. The provided example should be able to load the file main/master.inc.php in nearly all situation/setups.

Note that you may add more "../" depending on the depth of the file relative to your module directory tree.

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 Object that contains the characteristics of the user + his permissions.
*$conf Object that contains Dolibarr configuration.
*$db Object that contains an opened connection handler to the database.
*$langs Object that contains the user's language.

Then enter your code to display the page.

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

''Example :''
<syntaxhighlight lang="PHP">
dol_include_once('/mymodule/class/myclass.class.php', 'MyClass');
</syntaxhighlight>

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

''Example :''
<syntaxhighlight lang="PHP">
require_once DOL_DOCUMENT_ROOT.'/core/class/doli.class.php';
</syntaxhighlight>

===Add some fields into existing forms===
You may want to provide a module that adds 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 to disable the "New element" menu entry and adding yours, and disable tab that shows 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 [[#Define your entries in the menu (optional)]] and [[#The tab management (optional)]] if this solution suits you (this solution is more powerful since you can change everything you want into the 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 ...

*First thing is to add a table, owned by your module, to store the value of new fields. This table will have only one column called "rowid" (will contain the 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 [[#Create your SQL tables and the PHP DAO class]].
*Next step is to add a hook into your module to add the new fields into the form. See chapter [[Hooks_system#Implement_the_Hook]] for generic documentation to use hooks.

If you follow this tutorial, to be able to add fields into category forms, you must do:
{{ToComplete}}

===Add/replace part of fields supported by hooks===
See chapter [[Hooks_system#Implement_the_Hook]] 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 the database inside your 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:

<syntaxhighlight lang="PHP">
$db->begin(); // Start transaction
$db->query("My SQL request insert, update or delete");
$db->commit(); // Validate transaction
or $db->rollback() // Cancel transaction
</syntaxhighlight>

To read:

<syntaxhighlight lang="PHP">
$resql=$db->query("My select request");
if ($resql)
{
$num = $db->num_rows($resql);
$i = 0;
if ($num)
{
while ($i < $num)
{
$obj = $db->fetch_object($resql);
if ($obj)
{
// You can use here results
print $obj->field1;
print $obj->field2;
}
$i++;
}
}
}
</syntaxhighlight>

===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:
<syntaxhighlight lang="PHP">
$form=new Form($db);
$form->select_date('','mykey',0,0,0,"myform");
</syntaxhighlight>
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:
<syntaxhighlight lang="PHP">
$mydate = dol_mktime(12, 0 , 0, $GETPOST('mykeymonth', 'int'), GETPOST('mykeyday', 'int'), GETPOST('mykeyyear', 'int'));
print strftime('%A %d %B %Y', $mydate);
</syntaxhighlight>

==Add your own setup page (optional)==
'''When''': If your module needs parameters, which are to be provided by the user, for proper setting up of the module.

===Create your page to edit parameters===
If your module needs several parameters to be setup, you must create a page to edit options (these options will be saved in the [[Table llx_const|table '''llx_const''']]).
Create a page named '''mymodule_setuppage.php''' that shows a form for possible options to update them into the above-mentioned table.
It is necessary to take an example from a page of the directory '''/admin''' that will show you the way to read/save your parameters.
Put this PHP page into the directory '''/admin''' of your module (e.g. mymodule/admin/mymodule_setuppage.php).

===Modify the descriptor file of your module===
Then, within the descriptor file of your module, modify the variable '''config_page_url''' to set the name of this PHP page.
If the page is in the directory '''admin/''', then the path is not required, e.g. like this:
<syntaxhighlight lang="PHP">
$this->config_page_url = array("mymodule_setuppage.php");
</syntaxhighlight>
If the page is in the directory '''mymodule/admin/''', then like this:
<syntaxhighlight lang="PHP">
$this->config_page_url = array("mymodule_setuppage.php@mymodule");
</syntaxhighlight>

===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 declares 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:
<syntaxhighlight lang="PHP">
// Main menu entries
$this->menu = array(); // List of menus to add
$r=0;

// Add here entries to declare new menus
// Example to declare the Top Menu entry:
$this->menu[$r]=array( 'fk_menu'=>0, // Put 0 if this is a top menu
'type'=>'top', // This is a Top menu entry
'titre'=>'MyModule top menu',
'mainmenu'=>'mymodule',
'leftmenu'=>'mymodule',
'url'=>'/mymodule/pagetop.php',
'langs'=>'mylangfile', // Lang file to use (without .lang) by module. File must be in langs/code_CODE/ directory.
'position'=>100,
'enabled'=>'1', // Define condition to show or hide menu entry. Use '$conf->mymodule->enabled' if entry must be visible if module is enabled.
'perms'=>'1', // Use 'perms'=>'$user->rights->mymodule->level1->level2' if you want your menu with a permission rules
'target'=>'',
'user'=>2); // 0=Menu for internal users, 1=external users, 2=both
$r++;

// Example to declare a Left Menu entry:
$this->menu[$r]=array( 'fk_menu'=>'fk_mainmenu=xxx', // Use 'fk_mainmenu=xxx' or 'fk_mainmenu=xxx,fk_leftmenu=yyy' where xxx is mainmenucode and yyy is a leftmenucode of parent menu
'type'=>'left', // This is a Left menu entry
'titre'=>'MyModule left menu 1',
'mainmenu'=>'xxx',
'leftmenu'=>'yyy',
'url'=>'/mymodule/pagelevel1.php',
'langs'=>'mylangfile', // Lang file to use (without .lang) by module. File must be in langs/code_CODE/ directory.
'position'=>100,
'enabled'=>'1', // Define condition to show or hide menu entry. Use '$conf->mymodule->enabled' if entry must be visible if module is enabled.
'perms'=>'1', // Use 'perms'=>'$user->rights->mymodule->level1->level2' if you want your menu with a permission rules
'target'=>'',
'user'=>2); // 0=Menu for internal users,1=external users, 2=both
$r++;
</syntaxhighlight>

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

===Test your menu entries===
Disable and re-enable your module under the 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
<syntaxhighlight lang="PHP">
$this->rights_class = 'mymodule'
</syntaxhighlight>
with correct value for mymodule.

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

<syntaxhighlight lang="PHP">
$this->rights[$r][0] = 10001;
$this->rights[$r][1] = 'Label by default of permission';
$this->rights[$r][2] = 'r';
$this->rights[$r][3] = 1;
$this->rights[$r][4] = 'action';
$this->rights[$r][5] = 'subaction';
$r++;
</syntaxhighlight>

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][1], put a label by default for permission (This label will be used if no translation can be found into the file '''admin.lang''' Translation key should be "Permission10001=My permission Label").
Into $this->rights[$r][2], types of the permission. There are three type of permission, 'r' for read, list or expert permission, 'w' for write or update permission and 'd' for delete permission.
Into $this->rights[$r][3], put 1 if this permission must be granted automatically by default to any newly created user.
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:

<syntaxhighlight lang="PHP">
if ($user->rights->mymodule->action->subaction) ...
</syntaxhighlight>

==Define your own box (optional)==
'''When''': If your module needs 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:''
<syntaxhighlight lang="PHP">
$this->boxes[0]['file']='mybox0.php@mymodule'
$this->boxes[0]['note']='My box 0'
...
$this->boxes[n]['file']='myboxn.php@mymodule'
$this->boxes[n]['note']='My box n'
</syntaxhighlight>

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 activate. Activate the box and go on the home page to see if the box is showing correctly.

==Define your own export (optional)==
'''When''': If your module provides 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 a 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 several CSS files 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 files only if you need absolutely to add not already existing styles.

Once your style sheets are ready, declare them into your module descriptor file by modifying the property '''$this->modules_parts'''.
Value to put here must be an array of relative URLs to your CSS files.
For example
<syntaxhighlight lang="PHP">
$this->module_parts = array('css' => array('/mymodule/css/mymodule.css.php','/mymodule/css/myother.css'));
</syntaxhighlight>

===Test your style sheet===
Disable and enable your module.

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

You should see into the HTML header, a line that declares 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 :
<syntaxhighlight lang="PHP">
$morejs=array("/mymodule/js/mymodule.js");
llxHeader('','Titre','','','','',$morejs,'',0,0);
</syntaxhighlight>

==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 the 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 are 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".

=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 marketplace.
But you can use it to have a package easy to distribute on your own 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 a list of file names for all new files you created for your module (module descriptor, new sql tables files, php page, images, etc...)

*Run the script via Perl (need the Perl version 5.0 or later):

<syntaxhighlight lang="bash">
perl makepack-dolibarrmodule.pl
</syntaxhighlight>
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.

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

<syntaxhighlight lang="bash">
tar -xvf mymodule.zip
</syntaxhighlight>

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

=Enabling/activation condition of external module on DoliStore=

See [[Module_Dolistore_Validation_Rules|Validation Rules]]
[[Category:Development]]