Difference between revisions of "Développement module"

From Dolibarr ERP CRM Wiki
Jump to navigation Jump to search
Line 282: Line 282:
  
 
== Quelques règles de codage ==
 
== Quelques règles de codage ==
Voici quelques règles à suivre dans la réalisation d'un module
+
Les règles de codage à suivre sont définis dans la documentation général du développeur
 
 
* 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 à suivre ce didacticiel qui explique comment joindre des tables qui se crée à l'activation du module et non à son utilisation (voir plus haut).
 
* Ajouter des traces dans votre code avec la fonction
 
dolibarr_syslog($yourmessage, LOG_INFO|LOG_DEBUG|LOG_ERR);
 
* Si vous avez besoin de créer un répertoire de travail, dans votre code, faites référence à ce répertoire par
 
DOL_DATA_ROOT.'/monmodule'.
 
Le répertoire peut être créer dans votre code à l'exécution par le code suivant:
 
<pre>
 
$mymoduledir=DOL_DATA_ROOT.'/monmodule';
 
if (! is_dir($mymoduledir)) create_exdir($mymoduledir);
 
</pre>
 
 
 
Si vous avez besoin d'un répertoire qui contiendra des données temporaire, ce répertoire doit être DOL_DATA_ROOT.'/monmodule/temp'
 

Revision as of 14:11, 25 August 2008

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

  • Ajouter de nouvelles tables en base
  • Ajouter vos propres entrées dans les menus
  • Ajouter des écrans de saisie/consultation de nouvelle tables
  • Ajouter des exports prédéfinis pour la fonction export
  • Ajouter de nouvelles boites pour la home page
  • Définir de nouvelles permissions
  • Déclencher du code automatiquement sur une action Dolibarr particulière

etc... Toutes ces opérations ne sont possibles qu'avec la version 2.4 ou plus de Dolibarr.


Créer un descripteur de Module (obligatoire)

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

Créer votre descripteur

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.
  • $dir = DOL_DOCUMENT_ROOT.'/mysql/tables/mymodule/'; par $dir = DOL_DOCUMENT_ROOT.'/mysql/tables/xxxxxxxx/'; ou xxxxxxxx représente le nom de votre module (sans espaces).
  • Modifier éventuellement les autres variables définies dans le constructeurs (Voir le commentaire dans le code du squelette pour leur signification).

Votre fichier descripteur de votre module est alors en place.

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

Créer vos fichiers .sql

Si votre module a vocation à gérer des données bien a lui, qui n'existent pas en base dans la version standard de Dolibarr, il est nécessaire de définir des tables SQL pour stocker ces données.

Créer un sous-répertoire de htdocs/mysql/tables propre à votre module (Par exemple htdocs/mysql/tables/monmodule/) afin d'y placer les scripts sql que vous aller créer. Ensuite dans votre descripteur de module, modifier la ligne

$dir = DOL_DOCUMENT_ROOT.'/mysql/tables/mymodule/';

par

$dir = DOL_DOCUMENT_ROOT.'/mysql/tables/monmodule/';

Règle à respecter: Ajouter les fichiers d'ordre de création de vos tables sur le principe d'un fichier par table (voir les fichiers existants dans htdocs/mysql/tables pour exemple). Les fichiers doivent être opérationnel pour la base de données mysql. Rem: Les fichiers des autres bases ne sont pas maintenus mais sont générés, au moment d'une release, à partir de ces derniers via le script:

build/dolibarr_mysql2autrebase.pl

Tester vos fichier .sql

Une fois les fichiers prêts, vous pouvez retourner sous Dolibarr puis désactiver le module, dropper les tables en base et réactiver le module. Les tables doivent alors être recréées par l'activation du module. Si tel n'est pas le cas, vérifiez vos scripts en les passant à la main, ou consultez les logs Dolibarr.

Générer la classe PHP d'accès

Une fois votre ou vos tables créées en base, aller dans le répertoire dev/skeletons et lancez 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 CRUD (Create/Read/Update/Delete) déjà opérationnelles pour faire un insert, un fetch (select), un update, un delete d'une ligne de la table. Supprimer juste le "out" du nom de fichier et placer votre fichier dans un sous-répertoire de htdocs propre à votre module (Dans htdocs/monmodule par exemple).

Un fichier out.nomtable_script.php a également été généré et contient un exemple de code pour utiliser la classe pour chacune des 4 méthodes CRUD.

Créer vos pages écran PHP (optionnel)

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

Créer une page écran PHP

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 répertoire dev/skeletons (Pour le développement d'un script en ligne de commande, voir Developpement_script).

Pour créer une nouvelle page écran utilisateur, créer un sous-répertoire de htdocs (si non déjà fait) propre à votre module (Dans htdocs/monmodule par exemple) afin d'y placer les pages que vous aller créer.

Y recopier le fichier skeletons_page.php qui va servir de point de départ à votre page ainsi que le fichier pre.inc.php. Modifier le fichier pre.inc.php afin que le chemin relatif du

include("../../main.inc.php)";

soit correct, en fonction de la profondeur de répertoire dans laquelle se trouve le fichier pre.inc.php (Enlever ou supprimer des "../"). C'est dans le main qu'est chargé l'environnement technique ainsi que les habilitations. Les variables objets suivantes sont alors positionnées:

  • $user L'objet qui contient les caractéristiques de l'utilisateur + ses droits.
  • $conf L'objet qui contient la configuration de Dolibarr.
  • $db L'objet qui contient le handler de connexion ouvert à la base de donnée.
  • $langs L'objet qui contient la langue de l'utilisateur.

Saisissez ensuite votre code pour afficher la page.

Accès à la base

Si vous avez besoin de réaliser des modifications en base dans votre propre table ajouté, utilisez la classe générée plus haut.

Si toutefois vous voulez faire des accès dans des tables sans objet PHP dédié, ceci reste possible (par exemple pour récupérer une liste d'enregistrement). Dans ce cas, pensez à suivre ces exemples:

Pour un insert, update ou delete:

$db->begin();   // Debut transaction
$db->query("Ma requete insert, update ou delete");
$db->commit();       // Valide
ou $db->rollback()  // Annule

Pour une lecture:

$resql=$db->query("Ma requete select");
if ($resql)
{
	$num = $db->num_rows($resql);
	$i = 0;
	if ($num)
	{
		while ($i < $num)
		{
			$obj = $db->fetch_object($resql);
			if ($obj)
			{
				// You can use here results
				print $obj->field1;
				print $obj->field2;
			}
			$i++;
		}
	}
}

Définition du style

Pour que le look de la page soit aligné avec le thème 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 saisie (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.

Creer votre page d'édition de configuration

Si votre module offre plusieurs options paramétrables, il est nécessaire de créer une page PHP pour éditer les options (qui sont stockées dans la table llx_const). Créer une page PHP nommée monmodule_setupapage.php qui affiche les options possibles et les met à jour. Il est nécessaire de prendre exemple sur une page dans /admin qui vous montre la méthode pour lire ou sauvegarder en base votre option. 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 PHP (sans le chemin qui n'est pas nécessaire, la page étant forcément dans le rep admin).

$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 configuratione tvous devez etre capable de modifier ces options et les voir conservé en base.

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

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

Définissez vos entrées

Pour cela, il vous faut définir dans le fichier descripteur de menu le tableau

$this->menu

Ce tableau contient toutes les entrées qui apparaitront dans les menus une fois le module activé. Les fichiers de descripteur de module exemple possède un exemple de déclaration de menu haut ainsi que de ces entrées menu gauche correspondantes.

Tester vos entrées menus

Désactiver et réactiver votre module sous Dolibarr, les entrées menus doivent alors apparaitre.

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 remplissez 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 défaut 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.

Définissez vos box

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/boxes

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'

Ensuite creer les fichiers mabox0.php, mabox1.php... en prenant exemple sur des box existantes (dans le répertoire htdocs/include/boxes

Tester la présence de vos box dans Dolibarr

Aller dans le menu Accueil - Configuration - Boite. Vos boxs doivent apparaitre dans la liste des box activables. Avticer les, aller sur la page d'accueil et vérifier qu'elles s'affichent correctement.

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

Définissez l'export

Pour cela, décommenter et modifier les tableaux $this->export_xxx du votre fichier descripteur de module.

Tester votre export

Aller dans le menu outils -> export de Dolibarr. Votre export doit apparaitre dans la liste des exports prédéfinis disponible (si votre module est bien activé). Le choisir, vous devez alors voir les champs possible définis dans le tableau à l'étape précédente. Choisir quelques champs et tenter une génération du fichier export.

Définir vos styles CSS (optionnel)

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

Cette fonctionnalité est décrite mais pas encore opérationnel en 2.4

Créer et déclarer votre feuille de style

Créer un fichier de style css nommé monmodule.css et le placer dans le répertoire monmodule dans htdocs. Il ne peut y avoir qu'un fichier css propre à chaque module. Rappelons qu'il vaut mieux utiliser les styles déjà existant de Dolibarr (le fichier css utilisé par Dolibarr étant le fichier themes/nomtheme/nomtheme.php.css. Ne créer un fichier css propre à votre module que si vous devez absolument gérer des styles non déjà existants. Une fois votre feuille de style prête, déclarer la dans votre fichier descripteur de module en modifiant la propriété $this->style_sheet. La valeur à renseigner ici doit être le chemin relatif de l'URL de votre fichier css. Par exemple '/monmodule/monfichier.css'.

Tester votre feuille de style

Assurez vous que votre module est actif. Appelez la page d'accueil de Dolibarr. Afficher la source de la page HTML. Vous devriez voir dans l'entête HTML, une ligne déclarant votre feuille de style.

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 utilisez des fonctions javascript, il est nécessaire de faire en sorte que vos fonctions déclarées dans un fichiers javascript monmodule.js soit chargées dans l'entête 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 évènement 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 votre module

  • Aller dans le répertoire /build et recopier le fichier makepack-dolibarrmodules.conf en makepack-monmodule.conf. Attention, ce répertoire peut ne pas être fourni dans les packages de versions stables. Si c'est le cas, il peut être récupéré dans le snapshot CVS disponible en téléchargement sur le site web Dolibarr dans la rubrique Version de développement (prendre dans ce cas tout le répertoire build qui est un répertoire autonome et indépendant de la version).

Saisissez dans ce fichier la liste des noms des nouveaux fichiers que vous avez créé pour votre module (descripteur de module, nouveaux fichiers sql de tables, page php, images, etc...)

  • Lancer le script via Perl (besoin de la version Perl 5.0 ou +):
perl makepack-dolibarrmodule.pl

Le script vous demande le nom de votre module, sa version majeure et mineure. Un fichier monmodule.tgz va alors être fabriqué contenant votre module prêt pour être déployé.

  • La personne qui reçoit 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

Quelques règles de codage

Les règles de codage à suivre sont définis dans la documentation général du développeur