Home Page

Developing a module for Dolibarr has been quite a journey. Modules are incredibly easy to build, once you understand how to do it. Unfortunately, the documentation doesn't explain every step. It can be overwhelming to attempt to create a module without any prior knowledge, or a guide to follow. In this blog post, I will walk you through developing a simple module for Dolibarr.

Enabling Module Development

Enabling Module and Application Builder


The first step to developing a module begins with enabling the "Module and Application Builder" tool in the admin settings page.

1. Login as a user with Administrator privileges.
2. From the home page, select the "Setup" link located in the left menu.
3. Select the "Setup -> Modules/Applications" link.
4. You should see a page listing multiple modules that you can enable. Navigate down to the "Multi-modules tools" section.
5. Under this section, search for the "Module and Application Builder" tool and enable it.

When you complete these steps, a "bug" icon will appear at the top right of the screen, next to your username. This button is used to access the module development page.

Making A New Module

Dolibarr allows for custom modules to be rapidly created. An interface is given for users to define how data is stored in the module. There is quick access to files defining the module page layout, and sql files describing the database. Objects can be easily created, with a nice interface for adding fields.

Because you enabled the "Module and Application Builder", you can now begin developing your first module! To begin, select the bug icon at the top right of the screen, next to your username.

Accessing the Module Builder Page
Module And Application Builder Page

This page provides a simple interface for starting a new module. To begin, follow the steps below.

1. Select the "New+" button.
2. In the "Module Key" Field, enter in a name for your new module. Hit create to create your module.

Congratulations! You have created your first module. Because you generated a new module, you need to enable it.

1. Navigate back to the "Setup -> Modules/Applications" page.
2. Navigate to the bottom section of the page titled "Other".
3. Search for the name of your module, and enable the module.

Enabling Your Custom Module

Finally, your custom module should now appear in the top menu of your page. You can click this link to navigate to the home page of your module.

Creating Objects

Now that you created an empty module, you need to fill it with Objects. Objects are useful for storing pertinent information related to your module. For instance, if you were to create a module for storing patient data, you could create an object called "patient". This object would contain information such as age, gender, and weight.

1. Navigate back to the "Module and Application Builder" page by clicking the bug next to your username.
2. Select the module that you just created, for instance, I chose my module, "TestModulePleaseIgnore".
3. Select the objects tab.
4. Select the "New" option.

From here you can generate a new object to be added to your module. Now that you created an object, you need to customize it by defining what fields will be associated with it.

1. Select the object that you just created.
2. Navigate to the table at the bottom of the page.
3. Add a new field, using the "Property" column for the code variable name, the Label field for what the user sees when they add new instances of your object, and type as the type of data your field contains. There are other customizable fields as well that I won't go over in detail here.

Once you are done defining your field, you can go ahead and hit "add". This will add the field to your object. In the next section, I will go over how you can make your object available for users to interact with.

To enable your changes, you need to deactivate your module and reactivate it.

I have found that this tool for adding fields to an object is pretty straight forward and intuitive. My only complaint is that there doesn't seem to be any straightforward documentation on what "types" you can choose for your field. To come up with ideas, I have had to look at example objects.

Adding Menu Links For Objects

Note: This step is only useful if you have more than one object in your module!

If your module has only one object, Dolibarr will automatically create menu links for it. However, if you create more than one object, you will have to manually create PHP links. This is one aspect of Dolibarr that I find odd. If it auto generates the links for your first object, it should do the same for every subsequent object.

Menu links are customizable in Dolibarr using PHP. I have never developed in PHP (Unless you count the one week I went over PHP in my web development course at college). What's nice about Dolibarr is that you really don't need to have a strong background in PHP in order to customize your menu.

There are two kinds of links I will discuss in this section. The first is a "List" link, and the other is a "New Object Entry" link. A list link is a link to a page which contains every entry in your Object. For instance, if I created a patient object, it would contain every patient in the system. A "New Object Entry" link, is a page which allows you to create new entry's in your object (i.e adding patients to the system).

The steps below show how to create a "list link".


1. Navigate to your module's "Menus" page (Remember, we should be in the module and application builder site.)
2. You should see a "Descriptor file of module" file located on the page. Hit the edit button (To the right of the file name).
3. Because you hit the edit button, you will see PHP code which defines the menus. Navigate to line 265. This array is what is used to define links in the your module's menu page, in addition to the top navigation bar.
4. Search for the code comment which looks like:
/* BEGIN MODULEBUILDER LEFTMENU MODULENAMEHERE

5. After this comment, you should see template code that is commented out. You can use this template for creating a menu link. Fill out the appropriate fields in this array with your module name and object name. Add your code to the file, after the "BEGIN MODULEBUILDER LEFTMENU ..." comment. It will look something like this:

/* BEGIN MODULEBUILDER LEFTMENU MODULENAMEHERE
$this->menu[$r++]=array(
        'fk_menu'=>'fk_mainmenu=MODULENAMEHERE',        
        'type'=>'left',                            
        'titre'=>'List OBJECTNAMEHERE',
        'mainmenu'=>'MODULENAMEHERE',
        'leftmenu'=>'MODULENAMEHERE_OBJECTNAMEHERE',
        'url'=>'/MODULENAMEHERE/OBJECTNAMEHERE_list.php',
        'langs'=>'MODULENAMEHERE@MODULENAMEHERE',            
        'position'=>1000+$r,
        'enabled'=>'$conf->MODULENAMEHERE->enabled',  
        'perms'=>'1',                            
        'target'=>'',
        'user'=>2,                                
    );

Once you have a "list link", you can now create a new entry link for your object. To do so, use the following template that can also be found in the comments in your PHP file:

Note: The commented out "code template" isn't exactly what you need. You will need to match the code here on this blog, listed below.

$this->menu[$r++]=array(
            'fk_menu'=>'fk_mainmenu=MODULENAMEHERE,
             fk_leftmenu=MODULENAMEHERE_OBJECTNAMEHERE',
            'type'=>'left',			                
            'titre'=>'New OBJECTNAMEHERE',
            'mainmenu'=>'MODULENAMEHERE',
            'leftmenu'=>'MODULENAMEHERE_OBJECTNAMEHERE',
            'url'=>'/MODULENAMEHERE/OBJECTNAMEHERE_card.php?action=create',
            'langs'=>'MODULENAMEHERE@MODULENAMEHERE',	        
            'position'=>1000+$r,
            'enabled'=>'$conf->MODULENAMEHERE->enabled',  
            'perms'=>'1',			              
            'target'=>'',
            'user'=>2,				                
        );

Now that you have edited your PHP files, you need to restart your module. To do so, deactivate and reactivate the module using the sliding activation toggle.

Object Relationships

Dolibarr makes it easy to define relationships between your module objects. The trick is understanding how Dolibarr wants you to define those relationships.

Lets say that we have a patient, and we want to link this patient to another object called Doctor. In other words, the doctor would have a one to many relationship with patients.

1. To create such a link, navigate to the object page (in my case Doctor), which you would like to have a one to many relationship with another object.
2. Create a foreign key field inside your object, prefixing the Property with fk_ , followed by the name of the object your referencing. In my case, I did fk_patient because the doctor object contains a foreign key to my patient object.
3. Now that you have completed that step, you need to set the type of your foreign key field. This part is a bit tricky. An example template is shown below.

integer:FOREIGNOBJECTNAMEHERE:custom/MODULENAMEHERE/class/FOREIGNOBJECTNAMEHERE.class.php

If I wanted to create foreign key to a patient object, I would set its type to the code shown below.

integer:Patient:custom/accenderosample/class/patient.class.php

Conclusion

Dolibarr provides an easy to use tool for creating simple, customizable objects. It's easy to generate a new module. A nice interface is provided for adding objects, and customizing menu links. Defining relationships between objects is as simple as defining the type on object fields. Despite the simplicity of Dolibarr, it feels as though there is much more to it that is simply undocumented. Once you understand Dolibarr's features, it is a powerful tool for developing ERP modules.