Dolibarr ERP CRM Wiki - User contributions [en]

Alain Ivars

2010-11-24T17:08:48Z

Choiceerp:

[[Category:Everybody]]
[[Category:Admiral]]
[[Category:User Active]]
{{UserInfo|
username=Alain Ivars|
usercountry={{Flag_fr}}|
userlogin=choiceerp|
userdate=2010-11-03|
usercompany=Dippa|
userweb=http://www.dippa.fr|
usergrade={{LinkAdmiral}}|
userstatus=active}}

Alain Ivars

2010-11-24T17:08:05Z

Choiceerp:

Alain Ivars

2010-11-24T13:26:11Z

Choiceerp: Created page with "Category:Everybody Category:Chasseur Category:User Active {{UserInfo| username=Alain Ivars| usercountry={{Flag_fr}}| userlogin=choiceerp| userdate=2010-11-03| usercom..."

[[Category:Everybody]]
[[Category:Chasseur]]
[[Category:User Active]]
{{UserInfo|
username=Alain Ivars|
usercountry={{Flag_fr}}|
userlogin=choiceerp|
userdate=2010-11-03|
usercompany=Dippa|
userweb=www.dippa.fr|
usergrade={{LinkFighter}}|
userstatus=Active|}}

DevCamp Amiens HackWeek 2010 Organization

2010-09-22T06:56:29Z

Choiceerp: /* Origine des participants */

{{TemplateAssoFr}}
[[Category:Association]]

= Nom et Adresse mail du contact relais Dolibarr =

Houssin Régis : regis@dolibarr.fr

= Nombre de participants prévus =

12 participants.

Toutefois, la présence des 12 ne sera pas sur toute la semaine.
Voir ici: http://rdv.dolibarr.pro/meeting/showua/h/8tk27

= Conditions =

Pour le transport, nous privilégions les moyens "éco-responsables", comme le train. Pour ceux qui se déplaceraient en voiture, nous prendrons en compte, pour le remboursement des frais, la base d'un billet de train équivalent.
Pour le train, nous achetons les billets et vous les envoyons par courrier.

S'il y a des cas particuliers ne rentrant pas dans ce cadre, je verrais avec le trésorier.

Concernant l'hébergement et la restauration, ils sont prévus dans les locaux du CREPS, accueillant régulièrement des groupes sportifs.
Si certains des participants ont des contraintes particulières (régime alimentaires, pb de mobilité ...) , merci de nous le signaler pour que nous en tenions compte.

L'urgence est de connaitre rapidement les besoins en transports.
Concernant les journées de présences, je part sur ce sondage : http://rdv.dolibarr.pro/meeting/showua/h/8tk27
En complément, il est nécessaire de savoir si les arrivées se font la veille ou le premier jour de présence et les départs, le jour même ou le lendemain matin.

!! Si l'un d'entre vous est mineur, merci de le préciser !!

= Origine des participants =

*Régis Houssin : 71700 Tournus (sâone et loire)
**jour d'arrivée prévue (un seul pris en charge) :
**jour de départ (un seul pris en charge) :
**moyen de déplacement prévu : TRAIN
**lieu de départ et de retour :
**horaires de départ des trains prévus en aller et retour :
**mineur : non
**contrainte alimentaire:

*Laurent Destailleur : 92500 Rueil Malmaison
**jour d'arrivée prévue (un seul pris en charge) : Mercredi 24/11 vers 14h
**jour de départ (un seul pris en charge) : Dimanche 28/11 vers 15h
**moyen de déplacement prévu : VOITURE
**lieu de départ et de retour : Rueil Malmaison
**horaires de départ des trains prévus en aller et retour : NA
**mineur : non
**contrainte alimentaire: aucune

*Philippe Grand : 45160 Olivet
**jour d'arrivée prévue (un seul pris en charge) :
**jour de départ (un seul pris en charge) :
**moyen de déplacement prévu :
**lieu de départ et de retour :
**horaires de départ des trains prévus en aller et retour :
**mineur : non
**contrainte alimentaire:

*Maxime Longuet : 13014 Marseille
**jour d'arrivée prévue (un seul pris en charge) :
**jour de départ (un seul pris en charge) :
**moyen de déplacement prévu :
**lieu de départ et de retour :
**horaires de départ des trains prévus en aller et retour :
**mineur :
**contrainte alimentaire:

*Cyrille de Lambert : 44300 Nantes
**jour d'arrivée prévue (un seul pris en charge) :
**jour de départ (un seul pris en charge) :
**moyen de déplacement prévu :
**lieu de départ et de retour :
**horaires de départ des trains prévus en aller et retour :
**mineur :
**contrainte alimentaire:

*Erick Bullier : 34000 Montpellier (Hérault)
**jour d'arrivée prévue (un seul pris en charge) :
**jour de départ (un seul pris en charge) :
**moyen de déplacement prévu :
**lieu de départ et de retour :
**horaires de départ des trains prévus en aller et retour :
**mineur :
**contrainte alimentaire:

*Christophe Buffenoir : 31500 Toulouse
**jour d'arrivée prévue (un seul pris en charge) : 21 nov
**jour de départ (un seul pris en charge) : 27 nov
**moyen de déplacement prévu : train
**lieu de départ et de retour : gare de Toulouse Matabiau
**horaires de départ des trains prévus en aller et retour : aller : 9h22 ou 11h17, retour : 9h13
**mineur : non
**contrainte alimentaire: allergie au café (mais pas au thé)

*Stéphane Rivière : 17310 St Pierre d'Oléron
**jour d'arrivée prévue (un seul pris en charge) : 24/11 arrivée au soir
**jour de départ (un seul pris en charge) : 28/11 retour le matin
**moyen de déplacement prévu : train
**lieu de départ et de retour : gare de surgères
**horaires de départ des trains prévus en aller et retour : aller à 11h17, retour 13h45 (au départ de paris)
**mineur :
**contrainte alimentaire:

*Xavier Petit : 17550 Dolus d'Oléron
**jour d'arrivée prévue (un seul pris en charge) : 24/11 arrivée au soir
**jour de départ (un seul pris en charge) : 28/11 retour le matin
**moyen de déplacement prévu : train
**lieu de départ et de retour : gare de surgères
**horaires de départ des trains prévus en aller et retour : aller à 11h17, retour 13h45 (au départ de paris)
**mineur :
**contrainte alimentaire:

*Romain GUILLAUME : 75011 Paris
**jour d'arrivée prévue (un seul pris en charge) :
**jour de départ (un seul pris en charge) :
**moyen de déplacement prévu :
**lieu de départ et de retour :
**horaires de départ des trains prévus en aller et retour :
**mineur :
**contrainte alimentaire:

*Aurélien Imhof : 28240 Champrond en Gâtine
**jour d'arrivée prévue (un seul pris en charge) :
**jour de départ (un seul pris en charge) :
**moyen de déplacement prévu :
**lieu de départ et de retour :
**horaires de départ des trains prévus en aller et retour :
**mineur :
**contrainte alimentaire:

*Alain Ivars :
**jour d'arrivée prévue (un seul pris en charge) :
**jour de départ (un seul pris en charge) :
**moyen de déplacement prévu : VOITURE
**lieu de départ et de retour : 78330 Fontenay-le-fleury
**horaires de départ des trains prévus en aller et retour : NA
**mineur : NON
**contrainte alimentaire: Aucune

= Description du projet =

* Finaliser les développements de la version 3.0 de Dolibarr
* Répartition des tâches pour les développements futurs

= Motivations et objectifs de la semaine =

* Mise au point des règles de développement
* Présentation du fonctionnement du cœur de Dolibarr
* Les objectifs de la version 3
* Coordination entre les membres
* Faire monter en compétence des collaborateurs
* Discussion autour de l'intégration d'un module comptabilité.
* Discussion autour du module de facturation récurrente.
* à compléter ...

= Les besoins (dans la limite du raisonnable) =

* Un tableau blanc (papier ou effaçable)
* Un vidéo projecteur
* Voir pour mettre en place un système de vidéo (et/ou audio) conférence
* à compléter si besoin...

Développement module

2010-04-19T21:56:18Z

Choiceerp: /* File:Art.png Créer un descripteur de Module (obligatoire) */

[[Category:Noyau]]
{{TemplateDocDev}}
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.

Les chapitres suivant vous présentent comment réaliser tout cela en manuel de manière simple. Pour les développeurs très expérimentés, une méthode par génération MDA est en cours de mise au point. Voir le dernier chapitre pour cela.

= [[File:Art.png]] Créer un descripteur de Module (obligatoire) =
'''Quand''': Obligatoire dès qu'une extension est développée, quelque soit sa vocation.

== Nom Interne de votre Module ==
Quand vous allez créé votre classe: "class modXXX extends DolibarrModules" ATTENTION: Le XXX '''DOIT''' être une série de caractère, ex: "MyModule", mais '''les seuls caractères permis sont [A-Za-z] et la longueur MAX de XXX est de 12 caractères '''. Dans la version 2.9 sera ajouter le support du caractère "_" idans le nom de la classe et les caractères permis seront [A-Za-z_].

== 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 -> Modules''' pour connaitre la liste des id module deja utilises).
* Modifier éventuellement les autres variables définies dans le constructeurs (Voir le commentaire dans le code du squelette pour leur signification).

* Créer le répertoire /htdocs/monmodule/

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.

= [[File:Art.png]] Arborescence d'un nouveau module (obligatoire à partir de la version 2.9) =
Créer un répertoire 'monmodule' qui recevra les fichiers du module. Ce répertoire doit etre dans le répertoire '''htdocs''' et contiendra les sous-répertoires suivants:

[[File:Arbo_module.png]]

= [[File:Art.png]] 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 '''sql''' dans le repertoire de votre module (par exemple '''htdocs/monmodule/sql''') afin d'y placer les scripts sql que vous aller créer.

''Règles à respecter:''
* Ajouter les fichiers d'ordre de création de vos tables sur le principe d'un fichier '''llx_matable.sql''' par table accompagné éventuellement du fichier '''llx_matable.key.sql''' (voir les fichiers existants dans '''includes/mysql/tables''' pour exemple).
* Pour ce qui est des ordres de gestion des données, ils doivent tous se trouver dans un fichier nommé '''data.sql''' situé dans le même répertoire '''/monmodule/sql/'''.
Exemple de contenu de fichier data.sql
<source lang="sql">
delete from llx_const where name='MYMODULE_IT_WORKS' and entity='__ENTITY__';
insert into llx_const (name, value, type, note, visible, entity) values ('MYMODULE_IT_WORKS','1','chaine','A constant vor my module',1,'__ENTITY__');
</source>

Les ordres SQL des fichiers doivent être opérationnels pour la base de données '''mysql'''.
Rem: Les fichiers des autres bases ne sont pas à maintenir. Ils sont lus et convertit à la volée par le driver de la base de données.

== 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 (DAO) ==

Une fois votre ou vos tables créées en base, aller dans le répertoire '''dev/skeletons''', copiez le fichier '''build_class_from_table.php''' dans le répertoire sql/ de votre module, et lancez le script
<source lang="bash">php build_class_from_table.php nomtable</source>
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 le 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.

= [[File:Art.png]] Affichage des onglets (optionnel) =

== Ajouter vos onglets sur les fiches entités ==
'''Quand''' : Pour ajouter votre propre onglet parmi les onglets standard d'une fiche entité (facture, commande, proposition commercial, adhérent...)

Pour cela, aller dans le fichier descripteur de module précédemment créé et modifier le tableau $this->tabs:
<source lang="php">
// Array to add new pages in new tabs
$this->tabs = array('product:TabTitle:@mymodule:/mymodule/mynewpage.php?id=__ID__');
// where entity can be
// 'thirdparty' to add a tab in third party view
// 'intervention' to add a tab in intervention view
// 'supplier_order' to add a tab in supplier order view
// 'supplier_invoice' to add a tab in supplier invoice view
// 'invoice' to add a tab in customer invoice view
// 'order' to add a tab in customer order view
// 'product' to add a tab in product view
// 'propal' to add a tab in propal view
// 'member' to add a tab in foundation member view
// 'contract' to add a tab in contract view
</source>

Le tableau doit contenir une liste de chaine, chaque chaine représentant un nouvel onglet.
Le format de la chaine étant composée de 4 parties séparées par ":"
* Partie 1: Le code entité dans lequel doit apparaitre l'onglet qui est une valeur parmi celle-ci:
** 'thirdparty'
** 'intervention'
** 'supplier_order'
** 'supplier_invoice'
** 'invoice'
** 'order'
** 'product'
** 'propal'
** 'member'
** 'contract'
* Partie 2: Le titre de l'onglet. Cela peut être un libellé en dur ou mieux un code traduction présent dans un fichier lang.
* Partie 3: Le nom du fichier .lang (sans l'extension .lang) qui contient la correspondance entre le code traduction et le libellé à afficher. Si ce com est précédé de @, Dolibarr cherche le fichier dansle répertoire lang propre au module, c'est à dire htdocs/mymodule/langs/code_CODE/mymodule.lang, sinon Dolibarr cherche le fichier traduction dans htdocs/langs/code_CODE/mymodyle.lang
* Partie 4: L'url de la page à afficher quand on clique sur l'onglet. La chaine __ID__ sera remplacée automatiquement par l'Id de l'entité concernée.

Pour alimenter le contenu de l'onglet avec des données issues de la base, voir le chapitre suivant.

== Ajouter les onglets d'une fiche entité sur ses propres pages ==
'''Quand''' : Pour afficher les onglets standard d'une fiche entité (produit, tiers, etc.) sur votre propre page onglet d'une entité.

Il faut appliquer la procédure suivante :

'''1. Inclure les fichiers définissant les fonctions utiles dans vos fichiers'''

Pour chaque fiche entité, il y a deux fichiers à inclure avec l'instruction
<source lang="php">require_once($url_fichier) ;</source>

Voici la liste de ces fichiers (DOL_DOCUMENT_ROOT correspond au dossier dolibarr/htdocs/) :
* Entité tiers (thirdparty) :
** DOL_DOCUMENT_ROOT/societe.class.php
** DOL_DOCUMENT_ROOT/lib/company.lib.php
* Entité produit (product) :
** DOL_DOCUMENT_ROOT/product.class.php
** DOL_DOCUMENT_ROOT/lib/product.lib.php
* Entité facture (invoice) :
** DOL_DOCUMENT_ROOT/facture.class.php
** DOL_DOCUMENT_ROOT/lib/invoice.lib.php

'''2. Créer et charger l'objet à afficher dans votre onglet'''

Créer l'objet de la classe voulue, et récupérer les données de l'objet à partir de la base de données. Pour cela il faut utiliser les fonctions fetch() de la classe correspondante, en passant en paramètre l'identifiant de l'objet que vous récupérez depuis l'url (ex : /mononglet.php?id=1).

''Exemple :''
<source lang="php">
$id=$_GET["id"];
$product = new Product($db) ;
$result = $product->fetch($id) ; //Tester $result pour vérifier que l'accès à la base s'est bien passé
</source>

'''3. Récupérer la liste des onglets correspondants à l'entité choisie'''

Utiliser la fonction XXX_prepare_head($obj), ou XXX est le nom de l'entité, permettant de créer un tableau contenant les définitions des onglets à afficher. Le paramètre à passer est l'objet pour lequel vous voulez afficher les onglets.

Le tableau retourné est composé de la façon suivante :
<source lang="php">
$head // Tableau des onglets
$head[$h] // Élément décrivant un onglet. Il y aura autant de $h que d'onglets à afficher
$head[$h][0] // Url de la page affichée quand on clique sur l'onglet
$head[$h][1] // Titre de l'ongLet
$head[$h][2] // Code de l'onglet, à utiliser pour choisir quel onglet sera 'actif' (voir paragraphe suivant)
</source>

''Exemple :''
<source lang="php">
$head = product_prepare_head($product, $user) ; //le paramètre $user n'est pas présent sur certaines fonctions
</source>

'''4. Afficher les onglets sur votre page onglet'''

Utiliser la fonction dol_fiche_head() qui affiche les onglets contenus dans le tableau $head retourné par XX_prepare_head().

<source lang="php">
dol_fiche_head($links, $active='0', $title='', $notab=0, $picto='')
$links // Tableau des onglets, appelé $head plus haut.
$active // Onglet actif (mettre le nom de l'onglet défini dans votre fichier de module, ou un nom contenu dans $head[$h][2]). Cet onglet sera mis en surbrillance
$title // ?
$notab // Mettre ce paramètre à 1 permet de ne pas afficher de zone bleue en dessous des onglets.
$picto // Nom de l'image à utiliser au début de la barre des onglet. Les choix suivant sont possibles :
// product
// service
// company
</source>

Cette fonction affiche les onglets voulus et ouvre un élément ''< div class="" >'' qui correspond à la zone bleue sous les onglets (si paramètre $notab = 0). Pour fermer la zone bleue, il suffit de fermer l'élément ''< /div >'' dans le code PHP.

''Remarque'':
Pour plus de détail, se référer à la [http://www.dolibarr.fr/doxygen/ documentation Doxygen] ou directement au code de Dolibarr.

= [[File:Art.png]] 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 brute ==
Vous pouvez 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 [[Développement de scripts]]).

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.
Modifier le fichier afin que le chemin relatif du
<source lang="php">
include("../../main.inc.php)";
</source>
soit correct, en fonction de la profondeur de répertoire dans laquelle se trouve le fichier (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ées.
* $langs L'objet qui contient la langue de l'utilisateur.

Saisissez ensuite votre code pour afficher la page.

== Créer une page écran PHP par template Smarty ==
=== Compléter votre descripteur de module ===
Dans votre descripteur de module, compléter la déclaration du tableau this->const afin d'ajouter la constante MAIN_MODULE_monmodule_NEEDSMARTY.
<source lang="php">
$this->const=array(1=>array('MAIN_MODULE_MONMODULE_NEEDSMARTY','chaine',1,'Need smarty',0));
</source>

Ceci aura pour effet, lors de l'initialisation de l'objet $conf, de remplir le tableau $conf->need_smarty des modules qui ont besoin de smarty et si au moins un module est requis, le code dans main.inc.php chargera systématiquement les librairies de Smarty.

=== Réaliser vos pages templates ===
Construisez vos pages templates (fichiers '''mespages.tpl''') dans le répertoire '''htdocs/monmodule/templates'''.

=== Réaliser vos pages PHP ===
Réaliser vos pages écrans PHP Dolibarr en suivant le modèle décrit dans cette documentation.
La différence est qu'à la fin, pour afficher la présentation HTML, il vous faut ajouter la séquence suivante:
<source lang="php">
$smarty->template_dir = DOL_DOCUMENT_ROOT.'/monmodule/templates/';
$mc->assign_smarty_values($smarty,$_GET["action"]);
$smarty->display($template);
</source>
L'objet $smarty n'a pas à être initialisé, il est normalement déjà défini (sur la base de Smarty intégré dans Dolibarr), si votre descripteur de module a bien déclaré avoir besoin de smarty et que le module a bien été activé après cela.

== Accès à la base ==
Si vous avez besoin de réaliser des modifications en base dans votre propre table ajoutée, utilisez la classe générée plus haut qui contient les méthodes pour cela.

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:

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

Pour une lecture:

<source lang="php">
$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++;
}
}
}
</source>

== 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"''.

== Utiliser le sélecteur de date de Dolibarr ==

Si vous le désirez, vous pouvez profiter du sélecteur de date dans des écrans Dolibarr. Pour cela, utilisez la ligne suivante:
<source lang="php">
$form=new Form($db);
$form->select_date('','mykey',0,0,0,"myform");
</source>
La chaine mykey identifie la zone date. Il faut y mettre une valeur différente s'il y a plusieurs zones.
La chaine myform est le nom de la zone FORM (dans form name="myform" de la page HTML).
L'affichage d'un sélecteur de date doit donc être intégrée dans une zone FORM Html.

Pour récupérer la valeur, à l'issu du POST, la commande est:
<source lang="php">
$mydate = dol_mktime(12, 0 , 0, $_POST['mykeymonth'], $_POST['mykeyday'], $_POST['mykeyyear']);
print strftime('%A %d %B %Y', $mydate);
</source>

= [[File:Art.png]] 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|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).
<source lang="php">
$this->config_page_url = array("monmodule_setupapage.php");
</source>

== Tester votre page ==
Allez sur la page '''Configuration->module''', vous devez voir apparaitre une icône qui permet d'accéder à la page de configuration et vous devez être capable de modifier ces options et les voir conservées en base.

= [[File:Art.png]] 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 menus ==
Pour cela, il vous faut définir dans le fichier descripteur de module, le tableau this->menu qui déclare les menus.
Ce tableau contient toutes les entrées qui apparaitront dans les menus une fois le module activé.
Le fichier de descripteur de module exemple '''modMyModule.class.php''' possède un exemple de déclaration de menu haut ainsi que de ses entrées menu gauche associées.

Voici un exemple de déclaration d'entrées de menu dans le fichier descripteur:
<source lang="php">
// Main menu entries
$this->menu = array(); // List of menus to add
$r=0;

// Add here entries to declare new menus
// Example to declare the Top Menu entry:
$this->menu[$r]=array( 'fk_menu'=>0, // Put 0 if this is a top menu
'type'=>'top', // This is a Top menu entry
'titre'=>'MyModule top menu',
'mainmenu'=>'mymodule',
'leftmenu'=>'1', // Use 1 if you also want to add left menu entries using this descriptor. Use 0 if left menu entries are defined in a file pre.inc.php (old school).
'url'=>'/mymodule/pagetop.php',
'langs'=>'mylangfile', // Lang file to use (without .lang) by module. File must be in langs/code_CODE/ directory.
'position'=>100,
'enabled'=>'1', // Define condition to show or hide menu entry. Use '$conf->mymodule->enabled' if entry must be visible if module is enabled.
'perms'=>'1', // Use 'perms'=>'$user->rights->mymodule->level1->level2' if you want your menu with a permission rules
'target'=>'',
'user'=>2); // 0=Menu for internal users, 1=external users, 2=both
$r++;

// Example to declare a Left Menu entry:
$this->menu[$r]=array( 'fk_menu'=>'r=0', // Use r=value where r is index key used for the parent menu entry (higher parent must be a top menu entry)
'type'=>'left', // This is a Left menu entry
'titre'=>'MyModule left menu 1',
'mainmenu'=>'mymodule',
'url'=>'/mymodule/pagelevel1.php',
'langs'=>'mylangfile', // Lang file to use (without .lang) by module. File must be in langs/code_CODE/ directory.
'position'=>100,
'enabled'=>'1', // Define condition to show or hide menu entry. Use '$conf->mymodule->enabled' if entry must be visible if module is enabled.
'perms'=>'1', // Use 'perms'=>'$user->rights->mymodule->level1->level2' if you want your menu with a permission rules
'target'=>'',
'user'=>2); // 0=Menu for internal users,1=external users, 2=both
$r++;
</source>

Pour conditionner l'accès au menu selon des permission, modifier la propriété '''perms''' du tableau. Voir le chapitre sur les permissions un peu plus loin pour savoir comment ajouter des permissions.

== Tester vos entrées menus ==
Désactiver et réactiver votre module sous Dolibarr, les entrées menus doivent alors apparaitre (si la condition dans 'enabled' est vraie).

= [[File:Art.png]] 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
<source lang="php">
$this->rights_class = 'monmodule'
</source>
pour y mettre la bonne valeur de monmodule.

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

<source lang="php">
$this->rights[$r][0] = 10001;
$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++;
</source>

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:

<source lang="php">
if ($user->rights->monmodule->action->sousaction) ...
</source>

= [[File:Art.png]] 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:''
<source lang="php">
this->boxes[0][1]='mabox0.php'
this->boxes[1][1]='mabox1.php'
this->boxes[2][1]='mabox2.php'
...
this->boxes[n][1]='maboxn.php'
</source>

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 ==
Désactiver et réactiver le module.

Aller dans le menu '''Accueil - Configuration - Boite'''.

Vos box doivent apparaitre dans la liste des box activables. Activer les puis aller sur la page d'accueil et vérifier qu'elles s'affichent correctement.

= [[File:Art.png]] 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.

= [[File:Art.png]] 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 ==
Désactiver et réactiver votre module.

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.

= [[File:Art.png]] 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.

= [[File:Art.png]] 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'actions 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|Interfaces de Dolibarr vers l'exterieur]]
et [[Interfaces_Exterieur_vers_Dolibarr|Interfaces exterieures vers Dolibarr]]

= [[File:Art.png]] 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 +):
<source lang="bash">
perl makepack-dolibarrmodule.pl
</source>
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:
<source lang="bash">
tar -xvf monmodule.tgz
</source>

* Si vous désirez que votre module profite à tous, vous pouvez le soumettre (le fichier tgz) sur le site web de Dolibarr dans la section téléchargements: http://www.dolibarr.org -> downloads -> contrib -> submit a file (vous devez avoir créer un compte auparavant et être loggué pour que le lien apparaisse).
** Si votre module a été fabriqué correctement, le fichier sera validé rapidement.
** Si la qualité est suffisante, que la licence le permet et que la fonctionnalité du module s'avère être d'un intérêt général, le code pourra être ajouté au code source de Dolibarr (sauf si vous ne le désirez pas).

= [[File:Art.png]] Quelques règles de codage =
Les règles de codage à suivre sont définis dans la [[Documentation Développeur|Documentation développeur]], rubrique "Informations Générales - Langage et normes de développement".

= [[File:Art.png]] Utilisation du MDA =
Une méthode pour générer un module fonctionnel depuis l'UML est en cours de mise au point. Plus d'informations sur la page [[UML2Dolibarr - Générer un module par MDA]].

Module development

2010-04-19T21:10:28Z

Choiceerp: /* File:Art.png Create a descriptor of Module (required) */

[[Category:Core]]
{{TemplateDocDevEn}}

To create a new module/addon for Dolibarr, there is several steps. This tutorial will describe you each of them to build a module to extend Dolibarr features, like one or several of the following :
* Add new tables in database
* Add your own menu entries
* Add new screens to edit new tables
* Add predefined exports for the internal export tool
* Add new information boxes in the home page
* Define new permissions
* Execute code automatically triggered by a particular Dolibarr action
etc...
All those operations are possible with version 2.4 or more of Dolibarr.

Following chapters presents how to do all of this manually with an easy way. For experienced developers, a method to do this using MDA generation is also on the work. See last chapter for this.

= [[File:Art.png]] Create a descriptor of Module (required) =
'''When''': Required as soon as an addon is developed, whatever is its goal.

== Internal Name of your Module ==
When you will create your class "class modXXX extends DolibarrModules" WARNING: The XXX '''MUST''' me set to a serie of alpha character, "MyModule", but '''the only character permit are [A-Za-z] and the MAX len of the XXX is 12 characters'''. In the 2.9 version will be add the support of the character "_" in the class name and the character permit will be [A-Za-z_].

== Create your module descriptor ==
The first step is to create a file descriptor for the module. To do this go into the directory dev/skeletons and copy the file modMyModule.class.php in the directory htdocs/includes/modules.
Then change the contents of this file to replace:

* all "modMyModule" with a value which corresponds to the vocation of your module. This value must always start with 'mod'.
* $this->numero = 10000 by a number of free module (Go to '''Home page -> System Information -> Dolibarr -> Modules''' to know id the list of modules used).
* Modify any other variables defined in the constructor (see comment in the code skeleton for their meaning).
* Create directory /htdocs/mymodule/
Your file descriptor for your module is ready.

== Test your descriptor ==

Launch Dolibarr and go to page '''Setup->module'''? You must see a new line with your new module and the possibility to activate it or not (browse all the tabs of each category of modules to find it). It's value of $this->special that determines in which tab will be your module.

= [[File:Art.png]] Path of a new module (required) =
Create a directory 'mymodule' that will receive all files of your module. This directory must be inside the '''htdocs''' directory and will contains following subdirectories:
[[File:Path.jpg|300px]]

= [[File:Art.png]] Create your SQL tables and the PHP accessor class (optional) =
'''When''': If your module needs to manage data of its own

== Create your .sql file ==
If your module is designed to manage data of its own, which are not available in the standard version of Dolibarr, it is necessary to define SQL tables to store the data.

Files for your own module must be placed in a directory.

Create a subdirectory called "sql" into directory of your module (eg htdocs/mymodule/sql) to put the sql scripts that you will create. Then in the "load_tables" function of your file descriptor module, modify the line

<source lang="php">$dir = DOL_DOCUMENT_ROOT.'/mymodule/sql/';</source>
by
<source lang="php">$dir = DOL_DOCUMENT_ROOT.'/valuechooseformymodule/sql/';</source>

''Rules to follow:''
* Add the files about creating tables commands on the principle of a file '''llx_matable.sql''' per table with a possibly file '''llx_matable.key.sql''' (see existing files in '''includes/mysql/tables''' for examples).

* To manage data, you must create a file called '''data.sql''' inside directory '''/mymodule/sql/''' that contains SQL command to add/edit/delete datas.

Example of content of a file data.sql
<source lang="sql">
delete from llx_const where name='MYMODULE_IT_WORKS' and entity='__ENTITY__';
insert into llx_const (name, value, type, note, visible, entity) values ('MYMODULE_IT_WORKS','1','chaine','A constant vor my module',1,'__ENTITY__');
</source>

Files must be operational for the database mysql. Rem: The files of other databases are not maintained. They will be read and converted on the fly by the driver of the other database.

== Test your .sql files ==

Once the files ready, you can return to Dolibarr to disable the module, dropper tables in database and reactivate the module. The tables should be recreated by the activation of the module. If this is not the case, check your scripts by passing them by hand, or check the Dolibarr logs.

== Generate the accessors PHP class (DAO) ==
Once you have created your tables into the database, move to the dev/skeletons directory and run the script

<source lang="bash">php build_class_from_table.php tablename</source>
Note: If the command does not work, try to use php-cli php instead.

This will generate a file '''out.tablename.class.php''' that contains the class to manage table tablename.
In this class, you can find the CRUD methods (Create / Read / Update / Delete) already working to do an insert, a fetch (select), an update, a delete of a row in table.
Remove just the "out" from the file name and put the file in a subdirectory of '''htdocs''' specific to your module (in htdocs/mymodule for example).

A file '''out.tablename_script.php''' has been generated and contains a sample code to use the class for each of the 4 CRUD methods.

= [[File:Art.png]] Add your own tabs on entities sheets (optional) =
'''When''': To add a tab on an entity (invoices, orders, proposals, member ...)

To do this go into the file descriptor of module previously created and edit the $this->tabs array:

<source lang="php">
// Array to add new pages in new tabs
$this->tabs = array('product:TabTitle:@mymodule:/mymodule/mynewpage.php?id=__ID__');
// where entity can be
// 'thirdparty' to add a tab in third party view
// 'intervention' to add a tab in intervention view
// 'supplier_order' to add a tab in supplier order view
// 'supplier_invoice' to add a tab in supplier invoice view
// 'invoice' to add a tab in customer invoice view
// 'order' to add a tab in customer order view
// 'product' to add a tab in product view
// 'propal' to add a tab in proposal view
// 'member' to add a tab in foundation member view
</source>

The table should contain a list of strings, each string representing a new tab.
The format of the string consisting of 4 parts separated by ":"
* Part 1: The entity code which should appear in the tab is a value from the following:
** 'thirdparty'
** 'intervention'
** 'supplier_order'
** 'supplier_invoice'
** 'invoice'
** 'order'
** 'product'
** 'propal'
** 'member'
* Part 2: The title of the tab. This can be a hard read or better code translation in a file lang.
* Part 3: The name of the file. Lang which contains correspondence between the code translation and language to display. If this name start with @, Dolibarr will search translation file into the lang file of module, so htdocs/mymodule/langs/code_CODE/mymodule.lang, otherwise Dolibarr will look for file htdocs/langs/code_CODE/mymodyle.lang
* Part 4: The url of the page to display when you click on the tab. The __ID__ string will be replaced automatically by the Id of the entity concerned.

To feed the contents of the tab with data from the database, see the next chapter.

= [[File:Art.png]] Create your own PHP screens (optional) =
'''When''': If the purpose of your module is to add features that require new screens.

== Create a PHP screen ==
You must then create your PHP pages that will show/edit data from tables using the skeleton templates provided as an example in the directory '''dev/skeletons''' (For the development of a script from the command line, see [[Script development]]).

To create a new user screen, create a subdirectory of '''htdocs''' (if not already done) for your module (in '''htdocs/monmodule''' for example) to store the pages you will create.

Copy, into that directory, the file '''skeletons_page.php''' that will serve as a starting point for your page file.
Edit the file to have a correct relative path to the main.inc.php file.
<source lang="php">
include("../../main.inc.php)";
</source>
This depends on the depth of the directory in which the file is (Add or remove "../").
It's in the main.inc.php file that is loaded technical environment variables and permissions. The following variables are objects positioned in this file:

* $user Objet that contains the characteristics of the user + his permissions.
* $conf Objet that contains Dolibarr configuration.
* $db Objet that contains an opened connection handler to the database.
* $langs Objet that contains the user's language.

Then enter your code to display the page.

== Database access ==
If you need to edit some data in database inside you own table, use the PHP class generated before.

If you to make access to tables with no dedicated PHP class available, this is always possible (for example if you want to get a list of records with a particular join or filter). In this case, this is a code samples to follow:

To make an insert, update or delete:

<source lang="php">
$db->begin(); // Start transaction
$db->query("My SQL request insert, update or delete");
$db->commit(); // Validate transaction
or $db->rollback() // Cancel transaction
</source>

To read:

<source lang="php">
$resql=$db->query("My select request");
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++;
}
}
}
</source>

== Define style of your pages ==
To have the look of your own pages to match the Dolibarr theme, it is necessary to use the Dolibarr CSS styles.

You can use for example:

* class="'''liste_titre'''" on tags ''tr'' and ''td'' for the head row of a table.
* class="'''pair'''" or class="'''impair'''" on tags ''tr'' and ''td'' of other rows of a table.
* class="'''flat'''" on all input fields (''input, select, textarea''...).
* class="'''button'''" on HTML fields with type ''input type="submit"''.

== Use the Dolibarr date picker ==
If you want to use the Dolibarr date selector (with its calendar popup) into your pages, use the following line:
<source lang="php">
$form=new Form($db);
$form->select_date('','mykey',0,0,0,"myform");
</source>
The string mykey will identify the date selector in the form. You must use different values if you use several date selectors in same page.
The string myform is the name of the FORM in which the selector is included (value found in the form name="myform" in HTML page).
This means a date selector must be included necessarily into an html FORM.

To get value after the POST of your form, the command is:
<source lang="php">
$mydate = dol_mktime(12, 0 , 0, $_POST['mykeymonth'], $_POST['mykeyday'], $_POST['mykeyyear']);
print strftime('%A %d %B %Y', $mydate);
</source>

= [[File:Art.png]] Add your own setup page (optional) =
'''When''': If your module need to ask user several parameters.

== Create your page to edit parameters ==
If your module need several parameters to be setup, you must create a page to edit options (that will be saved into [[Table llx_const|table '''llx_const''']]).
Create a page named '''mymodule_setuppage.php''' that show possibles options and update them into table from a form.
It is a necessary to take an example from a page into directory '''/admin''' that will show you the way to read/save your parameter.
Put this page into directory '''/admin'''.
Then, into the descriptor file of your module, modify the variable config_page_url to set name of this PHP page (without the path that is not necesary if page is inside directory admin).
<source lang="php">
$this->config_page_url = array("mymodule_setuppage.php");
</source>

== Test your page ==
Go into page '''Home->Setup->Modules''', you should see a picture at the end of the line of your module to reach your setup page. Click on it, you should be able to view/edit parameters from your page.

= [[File:Art.png]] Define your entries in menu (optional) =
'''When''': If you have created PHP pages, it is necessary that those pages can be reached from menu entries in Dolibarr menu.

== Define your menu entries ==
For this, you must define into the module descriptor, the array this->menu that declare all menus added by your module.
This array contains entries that will appear once your module is activated.
The example module descriptor file '''modMyModule.class.php''' contains an example to declare a top menu and also its left menu entries.

This is the example of code to declare your own menu entries in a module descriptor file:
<source lang="php">
// Main menu entries
$this->menu = array(); // List of menus to add
$r=0;

// Add here entries to declare new menus
// Example to declare the Top Menu entry:
$this->menu[$r]=array( 'fk_menu'=>0, // Put 0 if this is a top menu
'type'=>'top', // This is a Top menu entry
'titre'=>'MyModule top menu',
'mainmenu'=>'mymodule',
'leftmenu'=>'1', // Use 1 if you also want to add left menu entries using this descriptor. Use 0 if left menu entries are defined in a file pre.inc.php (old school).
'url'=>'/mymodule/pagetop.php',
'langs'=>'mylangfile', // Lang file to use (without .lang) by module. File must be in langs/code_CODE/ directory.
'position'=>100,
'enabled'=>'1', // Define condition to show or hide menu entry. Use '$conf->mymodule->enabled' if entry must be visible if module is enabled.
'perms'=>'1', // Use 'perms'=>'$user->rights->mymodule->level1->level2' if you want your menu with a permission rules
'target'=>'',
'user'=>2); // 0=Menu for internal users, 1=external users, 2=both
$r++;

// Example to declare a Left Menu entry:
$this->menu[$r]=array( 'fk_menu'=>'r=0', // Use r=value where r is index key used for the parent menu entry (higher parent must be a top menu entry)
'type'=>'left', // This is a Left menu entry
'titre'=>'MyModule left menu 1',
'mainmenu'=>'mymodule',
'url'=>'/mymodule/pagelevel1.php',
'langs'=>'mylangfile', // Lang file to use (without .lang) by module. File must be in langs/code_CODE/ directory.
'position'=>100,
'enabled'=>'1', // Define condition to show or hide menu entry. Use '$conf->mymodule->enabled' if entry must be visible if module is enabled.
'perms'=>'1', // Use 'perms'=>'$user->rights->mymodule->level1->level2' if you want your menu with a permission rules
'target'=>'',
'user'=>2); // 0=Menu for internal users,1=external users, 2=both
$r++;
</source>

To show menu or not depending on a permission, modify property '''perms''' in array. See chapter on permissions later to see how to add permissions.

== Test your menu entries ==
Disable and reenable your module under Dolibarr module setup page, menus entries must appear (if property 'enabled' is declaration array is ok).

= [[File:Art.png]] Add your own permissions (optional) =
'''When''': If you want to add new permissions.

The way to define permissions that will manage your module is done inside the module descriptor created previously.
Modify line
<source lang="php">
$this->rights_class = 'mymodule'
</source>
with correct value for mymodule.

Then you must fill the array $this->rights with as many entries than different permissions you need to manage.

<source lang="php">
$this->rights[$r][0] = 10001;
$this->rights[$r][1] = 'Label by default of permission';
$this->rights[$r][3] = 1;
$this->rights[$r][4] = 'action';
$this->rights[$r][5] = 'subaction';
$r++;
</source>

Into $this->rights[$r][0], put a permission id not already used (See into menu '''System info''' on a working installation of Dolibarr to know list of id already used by standard modules.
Into $this->rights[$r][3], put 1 if this permission must be granted automatically by default to any new created user.
Into $this->rights[$r][1], put a label by default for permission (This label will be used if no translation can be found into the file '''admin.lang''').
Into $this->rights[$r][4] and $this->rights[$r][5], put an action and subaction string without spaces. You will be able to test if a user has the permission in your PHP source code with the sequence:

<source lang="php">
if ($user->rights->mymodule->action->subaction) ...
</source>

= [[File:Art.png]] Define you own box (optional) =
'''When''': If your module need to provide one or several new boxes to show on home page.

== Define your box ==
For this, modify the array $this->boxes into the module descriptor file.
All you have to do is to add one line for each box file you will create into directory '''htdocs/includes/boxes'''

''Example:''
<source lang="php">
this->boxes[0][1]='mybox0.php'
this->boxes[1][1]='mybox1.php'
this->boxes[2][1]='mybox2.php'
...
this->boxes[n][1]='myboxn.php'
</source>

Then create files mybox0.php, mybox1.php... by copying an example from an existing box file (into directory htdocs/include/boxes).

== Test if your box is detected by Dolibarr ==
Disable and enabled module.

Go into menu '''Home - Setup - Boxes'''.

Your boxes must appear in the list of boxes you can activated. Activate the box and go on home page to see if the box is showing correctly.

= [[File:Art.png]] Define your own export (optional) =
'''When''': If your module provide new predefined database export profiles (for its own tables or for already existing tables of another module).

== Define export ==
For this uncomment and modify arrays $this->export_xxx in your module descriptor file.

== Test your export ==
Go into menu Tools -> Export. Your export will appear in the list of available predefined exports (if your module is enabled).
Choose it, you must see list of all possible fields defined in the export arrays.
Choose on field and try to build an export file. If ok, try again with all fields.

= [[File:Art.png]] Define your CSS styles (optional) =
'''When''': If in your PHP pages, you use class styles that are not defined inside Dolibarr themes CSS (not recommanded).

== Create and declare your style sheet ==
Create a style sheet CSS named '''mymodule.css''' and put it into directory '''htdocs/mymodule'''. You can have only one CSS file per module.
Remember it's better to use existing styles already available by default into Dolibarr (The CSS file used by Dolibarr is file '''themes/mytheme/''themename''.php.css'''. Create your own CSS file only if you need absolutely to add not already existing styles.
Once your style sheet is ready, declare it into your module descriptor file by modifying the property '''$this->style_sheet'''.
Value to put here must be a relative URL to your CSS file.
For example '/mymodule/myfile.css'.

== Test your style sheet ==
Disable and enable your module.

Go on home page (index.php). Show the HTML source of the page.

You should see into the HTML header, a line that declare your style sheet.

= [[File:Art.png]] Define you Javascript functions (optional) =
'''When''': If in your PHP pages, you use javascript functions not available in Dolibarr (in file lib_head.js)

If you need to use your own javascript functions inside your PHP pages, it is necessary to have your functions defined into a javascript file '''mymodule.js''' to be included inside the HTML HEAD section.
To ask Dolibarr that forge this header to include your own javascript file, you must just declare your file inside the module descriptor.

This feature is not yet available.

= [[File:Art.png]] Run your own code on any Dolibarr event (optional) =
'''When''': If you want to execute your own code once a common Dolibarr event has occurred (example: I want to update a table in my module when an invoice is created into Dolibarr), you must create a '''triggers'''.

See also [[Interfaces_Dolibarr_toward_foreign_systems]]
and [[Interfaces_from_foreign_systems_toward_Dolibarr]]

= [[File:Art.png]] Create a package to distribute and install your module =

* Go into the directory '''/build''' and copy the file '''makepack-dolibarrmodules.conf''' into '''makepack-mymodule.conf'''. Warning, this directory may not be provided in some packages of stable versions. If so, it can be retrieved from the CVS snapshot available for download on the Dolibarr website in area "Development version" (taken in this case the whole build directory which is autonomous and independent directory).

Edit this file to add list of file names for all new files you created for your module (module descriptor, new sql tables files, php page, images, etc...)

* Run the script via Perl (need the Perl version 5.0 or later):
<source lang="bash">
perl makepack-dolibarrmodule.pl
</source>
The script asks you the name of your module, its major and minor version. A file '''mymodule.tgz ''' will then be manufactured containing your module ready to be deployed.

* The person who receives your module must then place the file in the root directory of a Dolibarr installation and perform the command:
<source lang="bash">
tar -xvf monmodule.tgz
</source>

* If you want your module to be public, you can submit it (the tgz file) on Dolibarr web site on download area: http://www.dolibarr.org -> downloads -> contrib -> submit a file (you must create an account and be logged to have link appeared).
** If your module was build correctly, file will be validated later.
** If quality is enough and license permits it, code might be added inside main Dolibarr sources (except if you disagree for that).

= [[File:Art.png]] Some coding rules =
The coding rules to be followed are defined in the [[Developer documentation]], under section "General Information - Language and standards development".

= [[File:Art.png]] Using MDA =
A method to generate a functional module from a UML model has been developed. More information on the page [[UML2Dolibarr - Build a module using MDA]].