8
edits
Changes
m
Improve troubleshooting for SQL scripts (based on my personal experience)
Line 6:
Line 6:
Following chapters presents how to do all of this manually with an easy way.+* 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.+ + +Next modify the contents of this file as follows:+Once you have created your tables into the database, move to the dev/skeletons directory and run the script+
−<syntaxHighlight lang="bash">php build_class_from_table.php tablename modulename</syntaxHighlight>
−Note: If the command does not work, try to use php-cli php instead.
−This will generate a file '''out.tablename.class.php''' that contains the class to manage table tablename. +In this class, you can find the CRUD methods (Create / Read / Update / Delete) already working to do an insert, a fetch (select), an update, a delete of a row in table.
−Remove just the "out" from the file name and put the file in a subdirectory of '''htdocs''' specific to your module (in htdocs/mymodule for example).
−A file '''out.tablename_script.php''' has been generated and contains a sample code to use the class for each of the 4 CRUD methods.+
−'''Since Dolibarr 6.0, the file dev/skeletons/build_class_from_table.php is no more provided. To build a class from a table you should use the ModuleBuilder modules provided as a standard module.'''
{{ToComplete}}
−===Replace parts of screen that are templated (version 3.3+)===
−Some parts of Dolibarr screen are isolated into native PHP template files.
−You can develop a module to overwrite such templates with yours.
+ 'leftmenu'=>'yyy',+You should see into the HTML header, a line that declares your style sheet.+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.+
[[de:Modul_Entwicklung]]
[[de:Modul_Entwicklung]]
[[zh:模块开发]]
[[zh:模块开发]]
+[[ja:モジュール_開発]]
<!-- END interlang links -->
<!-- END interlang links -->
Line 11:
Line 12:
{{TemplateDocDevEn}}
{{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 :
+To create a new module/addon for Dolibarr, there are several steps. This tutorial will describe each of them to let you build a module that extends Dolibarr features, such as:
*Add new tables in database.
*Add new tables in database.
Line 29:
Line 30:
etc...
etc...
−The following chapters explain how to do all of this manually in an easy way.
=Module creation with the module builder=
=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:
+From Dolibarr v. 12.0 it is possible to create the main pages of your module with the Module Builder. To activate it:
−Go into the list of modules and enable the "Module Builder" module:
+[[File:Module Builder.png|alt=Module Builder|thumb|none]]
−Then click on the "bug" image in the top right of screen.[[File:Module Builder icon.png|alt=Module Builder icon|left|thumb]]
−<br />
−[[File:Mod_builder_3.png|400px]]
+=Template of an 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 Template]
−=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 your module=
==Create a Module descriptor for your Module (required)==
==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).
+'''When it is required''': Required as soon as an addon is developed, whatever its goal is (only adding a skin does not require a module descriptor file).
'''Since Dolibarr 9.0, you should use the ModuleBuilder module provided as a standard module to generate the module descriptor'''
'''Since Dolibarr 9.0, you should use the ModuleBuilder module provided as a standard module to generate the module descriptor'''
Line 54:
Line 53:
The first step is to create a file descriptor for the module.
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 dev/skeletons 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').
+*Create directory '''/htdocs/custom/''mymodule''/core/modules''' (for an external module) or '''/htdocs/''mymodule''/core/modules''' if you plan to have this module an official core module of Dolibarr. Then copy the file <code>modMyModule.class.php</code> from the directory '''htdocs/modulebuilder/template''' into this directory. Change the name of the file <code>modMyModule.class.php</code> to the name corresponding to the purpose of your module. Name of the file must start with <code>mod</code> and end with <code>.class.php</code> (for example if you want to give the name 'NewName' to this file, then the name should be <code>modNewName.class.php</code>).
−Then, 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").
+*Replace all occurrences of "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]].
+*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 module IDs]].
*Modify any other variables defined in the constructor (see comment in the code skeleton for their meaning).
*Modify any other variables defined in the constructor (see comment in the code skeleton for their meaning).
Line 85:
Line 84:
Then check into your descriptor file, into function '''init''' that the line
Then check into your descriptor file, into function '''init''' that the line
−<syntaxHighlight lang="php">$this->_load_tables('/mymodule/sql/');</syntaxHighlight>
+<syntaxhighlight lang="php">$this->_load_tables('/mymodule/sql/');</syntaxhighlight>
is not commented.
is not commented.
Line 91:
Line 90:
''Rules to follow:''
''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).
+*Add the files about creating tables commands on the principle of an '''llx_mytable.sql''' file per table, with an optional '''llx_mytable.key.sql''' file (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]].
*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.
*To manage data, you must create a file called '''data.sql''' inside directory '''/mymodule/sql/''' that contains SQL command to add/edit/delete data.
Line 97:
Line 96:
Example of content of a file data.sql
Example of content of a file data.sql
−<syntaxHighlight lang="sql">
+<syntaxhighlight lang="sql">
delete from llx_const where name='MYMODULE_IT_WORKS' and entity='__ENTITY__';
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__');
insert into llx_const (name, value, type, note, visible, entity) values ('MYMODULE_IT_WORKS','1','chaine','A constant vor my module',1,'__ENTITY__');
−</syntaxHighlight>
+</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.
+Files must be operational for the database mysql. Note: 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===
===Test your .sql files===
−Once the files ready, you can return to Dolibarr to disable the module, drop those tables in the database and reactivate the module. The tables should be recreated by the activation of the module. If this is not the case, check your scripts by passing them by hand, or check the Dolibarr logs.
+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 exist) and reactivate the module. The tables should be recreated by the activation of the module. If this is not the case, check the Dolibarr logs, or as a first step try running your scripts manually on your database (because SQL errors from your scripts may not show up in the Dolibarr logs).
===Generate the PHP DAO class===
===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)==
==The tab management (optional)==
Line 129:
Line 121:
To do this go into the file descriptor of module previously created and edit the $this->tabs array:
To do this go into the file descriptor of module previously created and edit the $this->tabs array:
−<syntaxHighlight lang="php">
+<syntaxhighlight lang="php">
// Array to add new pages in new tabs or remove existing one
// 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
$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:+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
'objecttype:-tabname'); // To remove an existing tab identified by code tabname
−</syntaxHighlight>
+</syntaxhighlight>
The table should contain a list of strings, each string representing a new tab.
The table should contain a list of strings, each string representing a new tab.
Line 142:
Line 134:
{{TemplateModuleTabs}}
{{TemplateModuleTabs}}
−*Part 2: A code to identify tab to add (start with +) or to remove (start with -)
+*Part 2: A code to identify tab to add (start with +tabname1) or to remove (start with -tabname1)
−*Part 3: The title of the tab. This can be a hard read or better code translation in a file lang.
+*Part 3: The title of the tab(Title1). This can be a hardcoded read or better a code translation in module lang file .
−*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 4: The name of the file "*.lang" (mylangfile@mymodule) 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 in htdocs/custom/mymodule/langs/code_CODE/mylangfile.lang, otherwise Dolibarr will look for file in htdocs/langs/code_CODE/mylangfile.lang
−*Part 5: A condition to test if tab must be visible. Put 1 to be always visible.
+*Part 5: A condition to test if tab must be visible($user->rights->mymodule->read) '''or''' 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.
+*Part 6: The URL of the page to display when you click on the tab (/mymodule/mypagetab1.php). 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.
To feed the contents of the tab with data from the database, see the next chapter.
Line 160:
Line 152:
For each object type, there are two files to include with line
For each object type, there are two files to include with line
−<syntaxHighlight lang="php">require_once($url_fichier) ;</syntaxHighlight>
+<syntaxhighlight lang="php">require_once($url_fichier) ;</syntaxhighlight>
This is example of files to include (DOL_DOCUMENT_ROOT is often dolibarr/htdocs/) :
This is example of files to include (DOL_DOCUMENT_ROOT is often dolibarr/htdocs/) :
Line 181:
Line 173:
''Example :''
''Example :''
−<syntaxHighlight lang="php">
+<syntaxhighlight lang="php">
$id=GETPOST('id','int');
$id=GETPOST('id','int');
$ref=GETPOST('ref','alpha');
$ref=GETPOST('ref','alpha');
$product = new Product($db) ;
$product = new Product($db) ;
$result = $product->fetch($id,$ref) ; // Test $result to check the database read is ok
$result = $product->fetch($id,$ref) ; // Test $result to check the database read is ok
−</syntaxHighlight>
+</syntaxhighlight>
'''3. Get a list of all tabs to show for your object type'''
'''3. Get a list of all tabs to show for your object type'''
Line 193:
Line 185:
The resulting array has the following structure
The resulting array has the following structure
−<syntaxHighlight lang="php">
+<syntaxhighlight lang="php">
$head // Array of tabs
$head // Array of tabs
$head[$h] // Element to describe one tab.
$head[$h] // Element to describe one tab.
Line 199:
Line 191:
$head[$h][1] // Title of tab
$head[$h][1] // Title of tab
$head[$h][2] // Code name to identify the tab
$head[$h][2] // Code name to identify the tab
−</syntaxHighlight>
+</syntaxhighlight>
''Example :''
''Example :''
−<syntaxHighlight lang="php">
+<syntaxhighlight lang="php">
$head = product_prepare_head($product, $user) ; // parameter $user is present for some function anly
$head = product_prepare_head($product, $user) ; // parameter $user is present for some function anly
−</syntaxHighlight>
+</syntaxhighlight>
−'''4. show tabs into your page'''
+'''4. show tabs on your page'''
−Use function dol_fiche_head() to show all tabs defined into array $head returned by XX_prepare_head().
+Use the <code>dol_fiche_head()</code> function to show all tabs defined in the <code>$head</code> array returned by <code>XX_prepare_head()</code>.
−<syntaxHighlight lang="php">
+<syntaxhighlight lang="php">
dol_fiche_head($links, $active='0', $title='', $notab=0, $picto='')
dol_fiche_head($links, $active='0', $title='', $notab=0, $picto='')
//$links // Tableau des onglets, appelé $head plus haut.
//$links // Tableau des onglets, appelé $head plus haut.
Line 220:
Line 212:
// service
// service
// company
// company
−</syntaxHighlight>
+</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.
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.
Line 232:
Line 224:
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.
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.
+Copy, into that directory, the file '''myobject_page.php''' that will serve as a starting point for your page file.
Edit the file to have a correct relative path to the main.inc.php file.
Edit the file to have a correct relative path to the main.inc.php file.
−<syntaxHighlight lang="php">
+<syntaxhighlight lang="php">
// Load Dolibarr environment
// Load Dolibarr environment
$res=0;
$res=0;
Line 249:
Line 241:
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");
if (! $res) die("Include of main fails");
−</syntaxHighlight>
+</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.
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.
Line 266:
Line 258:
''Example :''
''Example :''
−<syntaxHighlight lang="php">
+<syntaxhighlight lang="php">
dol_include_once('/mymodule/class/myclass.class.php', 'MyClass');
dol_include_once('/mymodule/class/myclass.class.php', 'MyClass');
−</syntaxHighlight>
+</syntaxhighlight>
*To include classes provided with Dolibarr, use the following syntax:
*To include classes provided with Dolibarr, use the following syntax:
''Example :''
''Example :''
−<syntaxHighlight lang="php">
+<syntaxhighlight lang="php">
require_once DOL_DOCUMENT_ROOT.'/core/class/doli.class.php';
require_once DOL_DOCUMENT_ROOT.'/core/class/doli.class.php';
−</syntaxHighlight>
+</syntaxhighlight>
===Add some fields into existing forms===
===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.
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).
+A heavy solution (but not so bad) may be to replace all pages used to create element (this means disabling the "New element" menu entry and adding yours, and disabling the tab that shows the 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 ...
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]].
+*First thing is to add a table, owned by your module, to store the value of new fields. This table will only have one column called <code>rowid</code> (will contain the same value as the <code>rowid</code> column in the 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 those two tasks, go back to the previous chapter [[#Create your SQL tables and the PHP DAO class (optional)]].
*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.
*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:
If you follow this tutorial, to be able to add fields into category forms, you must do:
−{{ToComplete}}
{{ToComplete}}
Line 305:
Line 292:
To make an insert, update or delete:
To make an insert, update or delete:
−<syntaxHighlight lang="php">
+<syntaxhighlight lang="php">
$db->begin(); // Start transaction
$db->begin(); // Start transaction
$db->query("My SQL request insert, update or delete");
$db->query("My SQL request insert, update or delete");
$db->commit(); // Validate transaction
$db->commit(); // Validate transaction
or $db->rollback() // Cancel transaction
or $db->rollback() // Cancel transaction
−</syntaxHighlight>
+</syntaxhighlight>
To read:
To read:
−<syntaxHighlight lang="php">
+<syntaxhighlight lang="php">
$resql=$db->query("My select request");
$resql=$db->query("My select request");
if ($resql)
if ($resql)
Line 335:
Line 322:
}
}
}
}
−</syntaxHighlight>
+</syntaxhighlight>
===Define style of your pages===
===Define style of your pages===
Line 349:
Line 336:
===Use the Dolibarr date picker===
===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:
If you want to use the Dolibarr date selector (with its calendar popup) into your pages, use the following line:
−<syntaxHighlight lang="php">
+<syntaxhighlight lang="php">
$form=new Form($db);
$form=new Form($db);
$form->select_date('','mykey',0,0,0,"myform");
$form->select_date('','mykey',0,0,0,"myform");
−</syntaxHighlight>
+</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 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).
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).
Line 358:
Line 345:
To get value after the POST of your form, the command is:
To get value after the POST of your form, the command is:
−<syntaxHighlight lang="php">
+<syntaxhighlight lang="php">
−$mydate = dol_mktime(12, 0 , 0, $_POST['mykeymonth'], $_POST['mykeyday'], $_POST['mykeyyear']);
+$mydate = dol_mktime(12, 0 , 0, $GETPOST('mykeymonth', 'int'), GETPOST('mykeyday', 'int'), GETPOST('mykeyyear', 'int'));
print strftime('%A %d %B %Y', $mydate);
print strftime('%A %d %B %Y', $mydate);
−</syntaxHighlight>
+</syntaxhighlight>
+===Overwrite template file (tpl)===
+If you want to overwrite tpl file on your module, you need to declare it on the module_parts :
+<syntaxhighlight lang="php">
+'tpl' => 1,
+</syntaxhighlight>
+Then you can put any tpl file on '''mymodule/core/tpl'''
+as soon as the module is activate, the tpl will be overwrited
==Add your own setup page (optional)==
==Add your own setup page (optional)==
Line 375:
Line 370:
Then, within the descriptor file of your module, modify the variable '''config_page_url''' to set the name of this PHP page.
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:
If the page is in the directory '''admin/''', then the path is not required, e.g. like this:
−<syntaxHighlight lang="php">
+<syntaxhighlight lang="php">
$this->config_page_url = array("mymodule_setuppage.php");
$this->config_page_url = array("mymodule_setuppage.php");
−</syntaxHighlight>
+</syntaxhighlight>
If the page is in the directory '''mymodule/admin/''', then like this:
If the page is in the directory '''mymodule/admin/''', then like this:
−<syntaxHighlight lang="php">
+<syntaxhighlight lang="php">
$this->config_page_url = array("mymodule_setuppage.php@mymodule");
$this->config_page_url = array("mymodule_setuppage.php@mymodule");
−</syntaxHighlight>
+</syntaxhighlight>
===Test your page===
===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.
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)==
+==Define your entries in the menu (optional)==
'''When''': If you have created PHP pages, it is necessary that those pages can be reached from menu entries in Dolibarr menu.
'''When''': If you have created PHP pages, it is necessary that those pages can be reached from menu entries in Dolibarr menu.
Line 395:
Line 390:
This is the example of code to declare your own menu entries in a module descriptor file:
This is the example of code to declare your own menu entries in a module descriptor file:
−<syntaxHighlight lang="php">
+<syntaxhighlight lang="php">
// Main menu entries
// Main menu entries
$this->menu = array(); // List of menus to add
$this->menu = array(); // List of menus to add
Line 421:
Line 416:
'titre'=>'MyModule left menu 1',
'titre'=>'MyModule left menu 1',
'mainmenu'=>'xxx',
'mainmenu'=>'xxx',
− 'leftmenu'=>'yyy',
'url'=>'/mymodule/pagelevel1.php',
'url'=>'/mymodule/pagelevel1.php',
'langs'=>'mylangfile', // Lang file to use (without .lang) by module. File must be in langs/code_CODE/ directory.
'langs'=>'mylangfile', // Lang file to use (without .lang) by module. File must be in langs/code_CODE/ directory.
Line 430:
Line 425:
'user'=>2); // 0=Menu for internal users,1=external users, 2=both
'user'=>2); // 0=Menu for internal users,1=external users, 2=both
$r++;
$r++;
−</syntaxHighlight>
+</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.
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.
Line 442:
Line 437:
The way to define permissions that will manage your module is done inside the module descriptor created previously.
The way to define permissions that will manage your module is done inside the module descriptor created previously.
Modify line
Modify line
−<syntaxHighlight lang="php">
+<syntaxhighlight lang="php">
$this->rights_class = 'mymodule'
$this->rights_class = 'mymodule'
−</syntaxHighlight>
+</syntaxhighlight>
with correct value for mymodule.
with correct value for mymodule.
Then you must fill the array $this->rights with as many entries than different permissions you need to manage.
Then you must fill the array $this->rights with as many entries than different permissions you need to manage.
−<syntaxHighlight lang="php">
+<syntaxhighlight lang="php">
$this->rights[$r][0] = 10001;
$this->rights[$r][0] = 10001;
$this->rights[$r][1] = 'Label by default of permission';
$this->rights[$r][1] = 'Label by default of permission';
Line 457:
Line 452:
$this->rights[$r][5] = 'subaction';
$this->rights[$r][5] = 'subaction';
$r++;
$r++;
−</syntaxHighlight>
+</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][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.
Line 465:
Line 460:
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:
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">
+<syntaxhighlight lang="php">
if ($user->rights->mymodule->action->subaction) ...
if ($user->rights->mymodule->action->subaction) ...
−</syntaxHighlight>
+</syntaxhighlight>
==Define your own box (optional)==
==Define your own box (optional)==
Line 477:
Line 472:
''Example:''
''Example:''
−<syntaxHighlight lang="php">
+<syntaxhighlight lang="php">
$this->boxes[0]['file']='mybox0.php@mymodule'
$this->boxes[0]['file']='mybox0.php@mymodule'
$this->boxes[0]['note']='My box 0'
$this->boxes[0]['note']='My box 0'
Line 483:
Line 478:
$this->boxes[n]['file']='myboxn.php@mymodule'
$this->boxes[n]['file']='myboxn.php@mymodule'
$this->boxes[n]['note']='My box n'
$this->boxes[n]['note']='My box n'
−</syntaxHighlight>
+</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''').
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''').
Line 506:
Line 501:
==Define your CSS styles (optional)==
==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).
+'''When''': If in your PHP pages, you use class styles that are not defined inside Dolibarr themes CSS (not recommended).
===Create and declare your style sheet===
===Create and declare your style sheet===
Line 513:
Line 508:
Once your style sheets are ready, declare them into your module descriptor file by modifying the property '''$this->modules_parts'''.
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.
+Value to put here must be an array of relative URLs of your CSS files.
For example
For example
−<syntaxHighlight lang="php">
+<syntaxhighlight lang="php">
$this->module_parts = array('css' => array('/mymodule/css/mymodule.css.php','/mymodule/css/myother.css'));
$this->module_parts = array('css' => array('/mymodule/css/mymodule.css.php','/mymodule/css/myother.css'));
−</syntaxHighlight>
+</syntaxhighlight>
===Test your style sheet===
===Test your style sheet===
Line 524:
Line 519:
Go on the home page (index.php). Show the HTML source of the page.
Go on the home page (index.php). Show the HTML source of the page.
−In the HTML header, you should see a line that declares your style sheet.
−==Add your Javascript functions (optional)==
+==Add your JavaScript functions (optional)==
'''When''': If in your PHP pages, you use javascript functions not available in Dolibarr (in file lib_head.js)
'''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.
+If you need to use your own JavaScript functions inside your PHP pages, it is necessary to define your functions in your JavaScript file '''htdocs/mymodule/js/mymodule.js''', included in the HTML <code><head/></code> section.
−Dolibarr is responsible for building that HTML section. In order to ask it to include your JavaScript file, you just need to provide it to the llxHeader() function called by your page.
Example for page /htdocs/mymodule/mypage.php :
Example for page /htdocs/mymodule/mypage.php :
−<syntaxHighlight lang="php">
+<syntaxhighlight lang="php">
$morejs=array("/mymodule/js/mymodule.js");
$morejs=array("/mymodule/js/mymodule.js");
llxHeader('','Titre','','','','',$morejs,'',0,0);
llxHeader('','Titre','','','','',$morejs,'',0,0);
−</syntaxHighlight>
+</syntaxhighlight>
==Run your own code on any Dolibarr event (optional)==
==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'''.
+'''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 '''trigger'''.
See also [[Interfaces_Dolibarr_toward_foreign_systems]]
See also [[Interfaces_Dolibarr_toward_foreign_systems]]
Line 556:
Line 551:
==Add your document template (optional)==
==Add your document template (optional)==
−'''When''': When you want to personalized your own generated PDF or ODT documents.
+'''When''': When you want to personalize your own generated PDF or ODT documents.
−Note: To add this feature you don't need to create a module descriptor.
+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]].
Documentation to add your own template is available on page [[Create_a_PDF_document_template]] or [[Create_an_ODT_document_template]].
Line 565:
Line 560:
'''When''': When you want to personalized your colors/fonts/images.
'''When''': When you want to personalized your colors/fonts/images.
−Note: To add this feature you don't need to create a module descriptor.
+Note: To add this feature, you don't need to create a module descriptor.
To add your own skin, read page [[Skins]].
To add your own skin, read page [[Skins]].
Line 584:
Line 579:
*Run the script via Perl (need the Perl version 5.0 or later):
*Run the script via Perl (need the Perl version 5.0 or later):
−<syntaxHighlight lang="bash">
+<syntaxhighlight lang="bash">
perl makepack-dolibarrmodule.pl
perl makepack-dolibarrmodule.pl
−</syntaxHighlight>
+</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 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:
*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">
+<syntaxhighlight lang="bash">
tar -xvf mymodule.zip
tar -xvf mymodule.zip
−</syntaxHighlight>
+</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 you want your module to be public, you can submit it (the zip file) on the Dolibarr marketplace website: {{LinkToPluginDownload}} (you must first create an account and be logged in to use the "Submit a module/product" link).
**If your module was built correctly, the file will be validated later.
**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).
+**If quality is sufficient 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=
=Enabling/activation condition of external module on DoliStore=