Module development: Difference between revisions

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

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

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

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

Next modify the contents of this file as follows:

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

is not commented.

Example of content of a file data.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__');

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.

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

// 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

The table should contain a list of strings, each string representing a new tab.  

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

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

''Example :''

$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

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

The resulting array has the following structure

$head        // Array of tabs

$head[$h]    // Element to describe one tab.

$head[$h][1] // Title of tab

$head[$h][2] // Code name to identify the tab

''Example :''

$head = product_prepare_head($product, $user) ; // parameter $user is present for some function anly

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

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

dol_fiche_head($links, $active='0', $title='', $notab=0, $picto='')

//$links  // Tableau des onglets, appelé $head plus haut.

//            service

//            company

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.

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.  

// Load Dolibarr environment

$res=0;

if (! $res && file_exists("../../../main.inc.php")) $res=@include("../../../main.inc.php");

if (! $res) die("Include of main fails");

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.

''Example :''

dol_include_once('/mymodule/class/myclass.class.php', 'MyClass');

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

''Example :''

require_once DOL_DOCUMENT_ROOT.'/core/class/doli.class.php';

===Add some fields into existing forms===

To make an insert, update or delete:

$db->begin();  // Start transaction

$db->query("My SQL request insert, update or delete");

$db->commit();      // Validate transaction

or $db->rollback()  // Cancel transaction

To read:

$resql=$db->query("My select request");

if ($resql)

}

}

===Define style of your pages===

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

  $form=new Form($db);

  $form->select_date('','mykey',0,0,0,"myform");

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

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

$mydate = dol_mktime(12, 0 , 0, $GETPOST('mykeymonth', 'int'), GETPOST('mykeyday', 'int'), GETPOST('mykeyyear', 'int'));

print strftime('%A %d %B %Y', $mydate);

==Add your own setup page (optional)==

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:

$this->config_page_url = array("mymodule_setuppage.php");

If the page is in the directory '''mymodule/admin/''', then like this:

$this->config_page_url = array("mymodule_setuppage.php@mymodule");

===Test your page===

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

// Main menu entries

$this->menu = array(); // List of menus to add

'user'=>2); // 0=Menu for internal users,1=external users, 2=both

$r++;

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.

The way to define permissions that will manage your module is done inside the module descriptor created previously.

Modify line  

$this->rights_class = '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.

$this->rights[$r][0] = 10001;

$this->rights[$r][1] = 'Label by default of permission';

$this->rights[$r][5] = 'subaction';

$r++;

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][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:

if ($user->rights->mymodule->action->subaction) ...

==Define your own box (optional)==

''Example:''

$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'

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''').

Value to put here must be an array of relative URLs to your CSS files.

For example

$this->module_parts = array('css' => array('/mymodule/css/mymodule.css.php','/mymodule/css/myother.css'));

===Test your style sheet===

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

$morejs=array("/mymodule/js/mymodule.js");

llxHeader('','Titre','','','','',$morejs,'',0,0);  

==Run your own code on any Dolibarr event (optional)==

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

perl makepack-dolibarrmodule.pl

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:

tar -xvf mymodule.zip

*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").