Module development: Difference between revisions

* Define new permissions

* Execute code automatically triggered by a particular Dolibarr action

etc...

All those operations are possible with version 2.4 or more of Dolibarr.

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

'''When''': Required as soon as an addon is developed, whatever is its goal.

The first step is to create a file descriptor for the module. To do this go into the directory dev/skeletons and copy the file modMyModule.class.php in the directory htdocs/includes/modules.

Then change the contents of this file to replace:

Your file descriptor for your module is ready.

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

Create a directory 'mymodule' that will receive all files of your module. This directory must be inside the '''htdocs''' directory and will contains following subdirectories (only first line is mandatory):

* htdocs/mymodule/themes/mytheme if module provide its own skin

'''When''': If your module needs to manage data of its own

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

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

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

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

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.

'''When''': To add a tab on an object (invoices, orders, proposals, member ...)

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

'''When''': To show all standard tabs of an object (produit, tiers, etc.) on your 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.

'''When''': If the purpose of your module is to add features that require new screens.

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

Then enter your code to display the page.

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

</source>

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

* class="'''button'''" on HTML fields with type ''input type="submit"''.

If you want to use the Dolibarr date selector (with its calendar popup) into your pages, use the following line:

<source lang="php">

</source>

'''When''': If your module need to ask user several parameters.

If your module need several parameters to be setup, you must create a page to edit options (that will be saved into [[Table llx_const|table '''llx_const''']]).

Create a page named '''mymodule_setuppage.php''' that show possibles options and update them into table from a form.

</source>

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.

'''When''': If you have created PHP pages, it is necessary that those pages can be reached from menu entries in Dolibarr menu.

For this, you must define into the module descriptor, the array this->menu that declare all menus added by your module.

This array contains entries that will appear once your module is activated.

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

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

'''When''': If you want to add new permissions.

</source>

'''When''': If your module need to provide one or several new boxes to show on home page.

For this, modify the array $this->boxes into the module descriptor file.

All you have to do is to add one line for each box file you will create into directory '''htdocs/includes/boxes'''

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

Disable and enabled module.

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

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

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

Go into menu Tools -> Export. Your export will appear in the list of available predefined exports (if your module is enabled).

Choose it, you must see list of all possible fields defined in the export arrays.

Choose on field and try to build an export file. If ok, try again with all fields.

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

Create a style sheet CSS named '''mymodule.css''' and put it into directory '''htdocs/mymodule'''. You can have only one CSS file per module.

Remember it's better to use existing styles already available by default into Dolibarr (The CSS file used by Dolibarr is file '''themes/mytheme/''themename''.php.css'''. Create your own CSS file only if you need absolutely to add not already existing styles.

For example '/mymodule/myfile.css'.

Disable and enable your module.

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

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

</source>

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

and [[Interfaces_from_foreign_systems_toward_Dolibarr]]

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

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