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 extension 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 dev/skeletons et recopier le fichier modMyModule.class.php dans le répertoire htdocs/includes/modules. Ensuite, modifier le contenu de ce fichier afin de remplacer:

• les modMyModule en une valeur qui corresponde a la vocation de votre module. Cette valeur doit toujours commencer par 'mod'.
• $this->numero = 10000 par un numero de module libre (Aller dans la page Accueil -> Infos système -> Dolibarr pour connaitre la liste des id module deja utilises).
• $this->const_name = 'MAIN_MODULE_MYMODULE' par $this->const_name = 'MAIN_MODULE_XXX' où XXX doit correspondre à la valeur choisie pour remplacer MYMODULE et mis en majuscule.

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 (parcourez tous les onglets de chaque catégories de modules jusqu'à le retrouver). C'est la valeur de $this->special qui détermine dans quel onglet se trouve votre module.

Créer vos tables SQL et la classe PHP des accesseurs (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

Une fois votre ou vos tables créées en base, aller dans le répertoire dev/skeletons et lancer le script

php build_class_from_table.php nomtable

Remarque: Si la commande ne fonctionne pas, essayer d'utiliser php-cli plutot que php.

Ceci génèrera un fichier out.nomtable.class.php qui contient la classe de gestion de la table nomtable. Dans cette classe, se trouve des méthodes deja opérationnelles pour faire un insert, un update, un delete et un fetch (select) d'une ligne de la table.

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.

Vous devez ensuite créer 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.

Pour que le look de la page soit aligné avec le theme dolibarr, il est nécessaire d'utiliser les styles des CSS de Dolibarr. Par exemple:

• class="liste_titre" sur les balises tr et td pour une ligne de titre de tableau.
• class="pair" ou class="impair" sur les balises tr et td des lignes de donnees de tableau.
• class="flat" sur tous les champs de saisi (input, select, textarea...).
• class="button" sur les objets de type input type="submit".

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 accessibles depuis le menu Dolibarr.

Pour cela, il vous faut definir dans le fichier descripteur de menu le tableau

$this->menu

Ce tableau contient toutes les entrees qui apparaitront dans les menus une fois le module activé. Rem: Pour l'instant seul le menu haut est géré.

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.

$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';
$r++;

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. Il suffit d'ajouter une ligne par fichier box qui se trouve dans le répertoire htdocs/includes/box

Exemple:

this->boxes[0][1]='mabox0.php'
this->boxes[1][1]='mabox1.php'
this->boxes[2][1]='mabox2.php'
...
this->boxes[n][1]='maboxn.php'

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 non dispo en standard (fichier lib_head.js)

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 de triggers.

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 à l'utilisation, c'est-à-dire à la première utilisation du module.

Si vous créez un module qui utilise des tables qui ne sont pas intégrées en standard dans le code de Dolibarr, veillez à créer vos tables à l'activation du module (pour les tables n'existant pas en standard).