Développement module

Pour créer un nouveau module, il existe plusieurs étapes. Ce didacticiel apour but de vous décrire chacune d'elle afin d'ajouter de réaliser un module permettant d'étendre les possibilités de Dolibarr, comme par exemple ajouter une ou plusieurs des fonctionnalités suivantes:

Développer de nouvelles permissions
Ajouter de nouvelles boites
Ajouter des entrées menu
Ajouter des écrans
Ajouter des exports prédéfinis
Déclencher du code automatiquement sur une action Dolibarr particulière

etc...

Créer un descripteur de Module (obligatoire)

Quand: Obligatoire dès qu'une extention est développée, quelque soit sa vocation.

La première étape est donc de créer un fichier descripteur du module. Pour cela, aller dans le répertoire htdoc/includes/modules et recopier le fichier modFactures.php en modMonModule.php. Ensuite, modifier le contenu de ce fichier afin de remplacer:

les 'modFactures' en 'modMonModule'.
$this->id = 'invoice' par $this->id = 'monmodule'
$this->numero = 30 par $this->numero = 100000 (mettre un id libre pris par aucun module)
$this->const_name = 'MAIN_MODULE_FACTURE' par $this->const_name = 'MAIN_MODULE_MONMODULE'

Tester votre descripteur: Lancer Dolibarr et aller sur la page Configuration->module, vous devez voir apparaitre une nouvelle ligne avec votre nouveau module et la possibilité de l'activer ou non.

Créer vos tables SQL (optionnel)

Quand: Si votre module a besoin de gérer des données qui lui sont propres

Si votre module a vocation à gérer des données bien a lui, il est nécessaire de définir des tables SQL pour stocker ces données.

Ajouter la définition de vos tables sur le principe d'un fichier par table dans mysql/tables/ (voir les fichiers existants pour exemples). Ce sont les fichiers pour mysql qui font fois. Les fichiers des autres bases sont générés, au moment d'une release, à partir de ces derniers via le script:

build/dolibarr_mysql2autrebase.pl

Créer vos pages PHP (optionnel)

Quand: Si l'objet de votre module est d'ajouter des fonctionnalités qui nécessite des nouveaux écrans.

Dans un second temps, créez vos pages PHP qui se basent sur les données de vos tables en utilisant les squelettes fournis comme exemple dans le repertoire dev/skeletons.

Définir votre page de configuration (optionnel)

Quand: Si votre module offre plusieurs options paramétrables.

Si votre module offre plusieurs options paramétrables, il est nécessaire de créer une page PHP pour editer les options (qui sont stockées dans la table llx_const). Créer une page PHP nommée monmodule_setupapage.php qui offre les options possibles et les met à jour, sur le modèle des pages dans /admin. Placer cette page de configuration dans le répertoire /admin également. Ensuite dans le descripteur de module, modifier la variable pour indiquer le nom de cette page

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

Tester votre page: Aller sur la page Configuration->module, vous devez voir apparaitre un icone qui permet d'accéder à la page de configuration.

Définir vos entrées de menu (optionnel)

Quand: Si vous avez créer des pages PHP, il est nécessaire que ces écrans soient accessible depuis le menu Dolibarr.

Cette fonctionnalité n'est pas encore possible. Il faut modifier le code Dolibarr pour l'instant.

Définir vos propres permissions (optionnel)

Quand: Si vous voulez ajouter de nouvelles permissions.

La définition des permissions que gèrera votre module se fait dans le fichier descripteur créé dans la première étape. Modifier la ligne $this->rights_class = 'facture' par

$this->rights_class = 'monmodule'

Ensuite remplisser le tableau $this->rights avec autant d'entrée que de permissions différentes à gérer.

$r++;
$this->rights[$r][0] = 9999;
$this->rights[$r][1] = 'Libelle par defaut de ma permission';
$this->rights[$r][3] = 1;
$this->rights[$r][4] = 'action';
$this->rights[$r][5] = 'sousaction';

Dans $this->rights[$r][0], mettre un id de permission non déjà pris (Voir dans le menu Infos Système sur une installation de Dolibarr opérationnelle pour connaitre les id déjà utilisés. Dans $this->rights[$r][3], mettre 1 si cette permission est attribué d'office par défaut quand un utilisateur est créé. Dans $this->rights[$r][1], mettre un libellé par défaut (il sera affiché si aucune traduction n'est trouvé pour votre permission dans le fichier admin.lang). Dans $this->rights[$r][4] et $this->rights[$r][5], mettre une chaine action et sousaction sans espaces. Vous pourrez alors tester dans le code PHP si un utilisateurs a bien les droits par la séquence suivante:

$user->getrights('monmodule');
if ($user->rights->action->sousaction)

Définir vos propres box (optionnel)

Quand: Si votre module amène avec lui une ou plusieurs Boxes.

Pour cela, modifier les tableaux $this->boxes du fichier descripteur de module.

Définir vos propres exports (optionnel)

Quand: Si votre module amène avec lui des exports prédéfini de données (pour ces propres tables ou des tables déjà existante d'un autre module de Dolibarr).

Pour cela, modifier les tableaux $this->export_xxx du fichier descripteur de module.

Définir vos styles CSS (optionnel)

Quand: Si dans vos écrans PHP, vous utiliser des classes de styles qui ne sont pas celle des themes de Dolibarr (non recommendé).

Cette fonctionnalité n'est pas encore possible.

Définir vos fonctions Javascript (optionnel)

Quand: Si dans vos écrans PHP, vous utiliser des fonctions javascript.

Si dans vos écrans PHP, vous utiliser des fonctions javascript, il est nécessaire de faire en sorte que vos fonctions déclarés dans un fichiers javascript monmodule.js soit chargées dans l'entete head html. Pour demander à Dolibarr qui gère la génération de la section header d'inclure un de vos fichiers javascript, il est nécessaire de déclarer votre fichier javascript dans le descripteur de module.

Cette fonctionnalité n'est pas encore possible.

Déclencher du code sur un evenement Dolibarr (optionnel)

Quand: Si vous voulez que des actions particulières s'exécutent suite au déclenchement d'action s standards de Dolibarr (exemple: je veux mettre à jour une table de mon module quand une facture se crée dans Dolibarr), il vous faut créer un fichier trigger.

Voir aussi Interfaces_Dolibarr_vers_exterieur et Interfaces_Exterieur_vers_Dolibarr

Créer un package pour livrer et installer mon module

Aller dans le répertoire /build et modifier le fichier makepack-dolibarrmodules.conf afin de saisir la liste des nouveaux noms de fichiers que vous avez créé pour votre module (descripteur de module, nouveaux fichiers sql de tables, page php, etc...)
Lancer le script via perl (besoin de la version Perl 5.0 ou +):

perl makepack-dolibarrmodule.pl

Un fichier monmodule.tgz va alors etre fabriqué contenant votre module prêt pour être déployé.

La personne qui recoit votre module doit alors placer le fichier dans son répertoire racine d'installation de dolibarr et réaliser la commande:

tar -xvf monmodule.tgz

Règles

Voici quelques règles à suivre dans la réalisation d'un module

Ne pas créer de table dynamiquement, c'est-à-dire à la première utilisation du module. Si vous créez un module qui utilise des tables qui ne sont pas encore intégrées en standard dans le code de Dolibarr, veillez à créer vos tables à l'installation ou l'upgrade de Dolibarr, ou mieux à l'activation du module.