Dolibarr Module Template (aka My Module)

This is a full featured module template for Dolibarr. It's a tool for module developers to kickstart their project and give an hands-on sample of which features Dolibarr has to offer for module development.

If you're not a module developer you have no use for this.

Documentation

Module tutorial

Dolibarr development

Translations

Dolibarr uses Transifex to manage it's translations.

This template also contains a sample configuration for Transifex managed translations under the hidden .tx directory.

For more informations, see the translator's documentation.

There is a Transifex project for this module.

Install

Manually

• Make sure Dolibarr (>= 3.3.x) is already installed and configured on your workstation or development server.

• In your Dolibarr installation directory, edit the htdocs/conf/conf.php file

• Find the following lines:

  //$dolibarr_main_url_root_alt ...
  //$dolibarr_main_document_root_alt ...

• Uncomment these lines (delete the leading //) and assign a sensible value according to your Dolibarr installation

  For example :

  • UNIX:

    $dolibarr_main_url_root = 'http://localhost/Dolibarr/htdocs';
    $dolibarr_main_document_root = '/var/www/Dolibarr/htdocs';
    $dolibarr_main_url_root_alt = '/custom';
    $dolibarr_main_document_root_alt = '/var/www/Dolibarr/htdocs/custom';

  • Windows:

    $dolibarr_main_url_root = 'http://localhost/Dolibarr/htdocs';
    $dolibarr_main_document_root = 'C:/My Web Sites/Dolibarr/htdocs';
    $dolibarr_main_url_root_alt = '/custom';
    $dolibarr_main_document_root_alt = 'C:/My Web Sites/Dolibarr/htdocs/custom';

  For more information about the conf.php file take a look at the conf.php.example file.

Note that for Dolibarr versions before 3.5, the $dolibarr_main_url_root_alt has to be an absolute path

• Clone the repository in $dolibarr_main_document_root_alt/mymodule

(You may have to create the htdocs/custom directory first if it doesn't exist yet.)

git clone [email protected]:Dolibarr/dolibarr-module-template.git mymodule

• Install Composer dependencies:

composer install

Follow the final steps.

Using Composer

Require this repository from Dolibarr's composer:

{
  "repositories": [
    {
      "type": "vcs",
      "url": "https://github.com/dolibarr/dolibarr-module-template"
    }
  ],
  "require": {
    "dolibarr/mymodule": "dev-master"
  }
}

Run

composer update

Follow the final steps.

Final steps

From your browser:

• Log into Dolibarr as a super-administrator
• Under "Setup" -> "Other setup", set MAIN_FEATURES_LEVEL to 2
• Go to "Setup" -> "Modules"
• The module is under one of the tabs
• You should now be able to enable the new module and start coding ;)

Provided tools

Starting a new module

A script allows you to rename most of the code to your own module name.
It requires find, sed and rename commands on your system.
Just make sure you provide a CamelCase name.

./dev/newmodule.sh [NewName]

Some work still has to be done manually:

• Rename the directory holding the code
• Maybe rename some other bits (Search for 'my' in filenames and code)
• Update your module ID in the module descriptor
• Update your language files
  • Keywords based on the module ID
  • String referencing the template
• Remove the features you don't plan to use
• Fill the copyright notices at the top of each file
• Add your logo: see images README for specifications
• Start a new GIT history

git checkout --orphan [new_branch_name]

• Build an awesome module ;)

Composer scripts

Only the main commands are listed here.
See the composer comments or the composer.json itself for more informations.

Check

Run a linter, a PHP compatibility version checker and checks coding style.

composer check

Test

Run unit and functional tests.

composer test

Doc

Build code and user documentation.

Release

Run the checks and tests then build a distribution ZIP.

composer release

Git hooks

Optional GIT hooks are provided. These are just wrappers calling composer scripts.
They ensure best practices are followed during module development.

Install:

composer git_hooks_install

Remove:

composer git_hooks_remove

Publishing the module

The de-facto standard for publishing and marketing modules for Dolibarr is the Dolistore.
Templates for required images and texts are provided.
Check the dedicated README for more informations.

Contributions

Feel free to contribute and report defects on our issue tracker.

Licenses

Main code

GPLv3 or (at your option) any later version.

See COPYING for more information.

Other Licenses

Parsedown

Used to display this README in the module's about page.
Licensed under MIT.

GNU Licenses logos

Public domain

Documentation

All texts and readmes.