Difference between revisions of "Modules - Règles de packaging et validation DoliStore"

From Dolibarr ERP CRM Wiki
Jump to navigation Jump to search
Tag: 2017 source edit
 
(29 intermediate revisions by 3 users not shown)
Line 1: Line 1:
= [[File:Art.png]] Validation/activation d'un module externe sur Dolistore =
+
<!-- BEGIN interlang links -->
 +
<!-- Do NOT edit this section
 +
    Links below are automatically managed by PolyglotBot
 +
    You can edit links on the English source page : Modules_-_Packaging_rules_and_Dolistore_validation_rules -->
 +
[[en:Modules_-_Packaging_rules_and_Dolistore_validation_rules]]
 +
[[es:Módulos - Packages validación y DoliStore reglas]]
 +
<!-- END interlang links -->
  
Voici les règles qui prévalent lors de la soumission à validation d'un module sur http://www.dolistore.com.
+
=[[File:Art.png]] Introduction=
Ces règles s'appliquent à des soumissions de modules pour Dolibarr. Les fichiers d'autre nature (documentation, outils externes, autres) mis à disposition sur dolistore  ne sont pas concernés.
 
  
=== Structure ===
+
Voici les règles à suivre pour réaliser un module de qualité sur Dolibarr.
Tous les fichiers du module doivent être dans le répertoire du module, voir le modèle [https://github.com/rdoursenaud/dolibarr-module-template GitHub Dolibarr Module Modèle]
+
Ces règles sont contrôlées lors du déploiement d'un module via l'assistant de déploiement en ligne dun module externe. Elles sont aussi vérifier pour valider un module sur https://www.dolistore.com. Note: Les fichiers d'autre nature que des modules (documentation, outils externes, autres), même si mis à disposition sur DoliStore, ne sont pas concernés.
  
=== Inclusion ===  
+
=[[File:Art.png]] Règles =
* Toutes les inclusions de fichier coeur doivent être réalisées par include_once/require_once/include/require DOL_DOCUMENT_ROOT.'/pathtocorefile';
+
===Nommage du package===
* Toutes les inclusions de fichiers spécifiques au module par les pages du modules doivent être faites avec include_once/require_once/include/require './monmoduledir/...';
 
* Toutes les inclusions de fichiers spécifiques à un autre module externe doivent être faites par dol_include_once('/extmoduledir/...');
 
  
=== Lien ===  
+
Tous les modules pour Dolibarr doivent être nommé '''module_mymodulename-VERSION.zip''' (où VERSION peut être x or x.y or x.y.z). Si le module est pour un autre logiciel, le nom du zip doit être '''moduleothersoftware_mymodulename-VERSION.zip''' (par exemple moduleprestashop_mymodulename-1.0.zip).
 +
 
 +
Les packages du type application android, document PDF sont libres d'utiliser le nom de leur choix.
 +
 
 +
Le reste du document ne s'applique que pour les modules Dolibarr uniquement.
 +
 
 +
===Structure===
 +
Le premier répertoire dans le fichier zip '''module_mymodulename-VERSION.zip''' doit s'appeler '''mymodulename'''.
 +
 
 +
Tous les fichiers du module seront ensuite dans ce répertoire, comme fichier ou sous-répertoire, en suivant l'arborescence exemple proposée dans '''htdocs/modulebuilder/template''' :
 +
 
 +
{{TemplateModuleTreeSimple}}
 +
 
 +
===Inclusion des fichiers main ou master===
 +
 
 +
Un module externe de dolibarr doit pouvoir se mettre dans un répertoire '''htdocs/custom''' (cas standard), tout comme dans '''htdocs/''' (cas alternatif), et il doit fonctionner dans les deux cas.
 +
 
 +
 
 +
===Inclusion===
 +
 
 +
*Toutes les inclusions de fichiers du core doivent être réalisées par
 +
 
 +
<source lang="php">
 +
include_once/require_once/include/require DOL_DOCUMENT_ROOT.'/pathtocorefile';
 +
</source>
 +
 
 +
*Toutes les inclusions de fichiers spécifiques au module par les pages du modules doivent être faites avec
 +
 
 +
<source lang="php">
 +
include_once/require_once/include/require './monmoduledir/...';
 +
</source>
 +
 
 +
*Toutes les inclusions de fichiers spécifiques à un autre module externe doivent être faites par
 +
 
 +
<source lang="php">
 +
dol_include_once('/extmoduledir/...');
 +
</source>
 +
 
 +
===Lien===  
 
Tous les liens générés pour le HTML vers les pages spécifiques (href, src,...) du module devraient utiliser getNomURL de la classe d'un object ou à minima utiliser dol_buildpath
 
Tous les liens générés pour le HTML vers les pages spécifiques (href, src,...) du module devraient utiliser getNomURL de la classe d'un object ou à minima utiliser dol_buildpath
  
=== Répertoire Custom ===  
+
===Pas d'écriture dans l'arborescence standard===
Un module externe de dolibarr doit pouvoir se mettre dans un répertoire htdocs/custom, tout comme dans htdocs/, et il doit fonctionner dans les deux cas.
+
Le module ne doit pas écrire dans l'arborescence des fichiers "'''programmes'''" de Dolibarr mais uniquement dans des fichiers situés dans le répertoire "'''documents'''". Y compris pour des fichiers temporaires. Il ne faut pas oublier que sur une installation correcte sécurisée de Dolibarr, l'ensemble de l'arborescence des programmes (à l'exception du répertoire custom) est positionné en lecture seule.
   
+
 
=== Modifications de fichier core Dolibarr ===
+
===Modifications de fichier core Dolibarr===
Si des modifications de fichiers coeur de Dolibarr nécessaire au module sont soumises, elles seront acceptées :
+
Compte tenu du point précédent, si des modifications de fichiers du coeur de Dolibarr sont nécessaires au module, elles doivent être soumises au projet via github. Elles seront acceptées :
* Si elles sont poussées dans la branche dev du GitHub de Dolibarr (cas d'enrichissement de fonctionnalité Dolibarr)
+
 
* Si il s'agit d'ajout de hook, trigger ou fonction, ou ajout de paramètres optionnels à des fonctions existantes.
+
*Si elles sont poussées dans la branche dev du GitHub de Dolibarr (cas d'enrichissement de fonctionnalité Dolibarr)
 +
*Si il s'agit d'ajout de hook, trigger ou fonction, ou ajout de paramètres optionnels à des fonctions existantes. L'ajout de hook permet de permettre à un module externe d'intégrer son propre code n'import où dans le code de Dolibarr.
 +
 
 +
===Publications sur DoliStore===
 +
 
 +
==== MetaPackages ====
 +
Si votre module est un "metapackage", donc un module qui comprend plusieurs modules, vous devez inclure un fichier appelé '''metapackage.conf''' dans le répertoire principal avec le nom de la liste de tous les autres modules fournis par votre package.
 +
Par exemple, l'image de votre module s'appelle "mymetapack". Lors de l'installation de ce module, il installe également les modules "abc" et "def". Vous devez donc inclure dans le zip de votre package un fichier *mymetapack/metapackage.conf* avec le contenu suivant:
 +
<source lang="php">
 +
# Ce fichier décrit tous les modules inclus dans le zip module_metapackage-x.y.zip
 +
mymetapack
 +
abd
 +
def
 +
</source>
 +
 
 +
[[File: Warning.png]] Le déploiement d'un métapackage à partir de l'assistant de déploiement de Dolibarr n'est possible qu'avec Dolibarr v11+
  
=== Information sur la fiche produit  ===
+
====Langue====
==== Langue ====
 
 
La description du produit est obligatoire en Anglais.
 
La description du produit est obligatoire en Anglais.
==== Support ====
+
====Support====
Si votre module est payant, il doit obligatoirement figuré dans la description du produit un mail ou un canal pour le support aux utilisateurs (comme un lien vers un site web de contact)
+
Si votre module est payant, il doit obligatoirement figurer dans la description du produit un mail ou un canal pour le support aux utilisateurs (comme un lien vers un site web de contact)

Latest revision as of 12:13, 14 January 2020


Art.png Introduction

Voici les règles à suivre pour réaliser un module de qualité sur Dolibarr. Ces règles sont contrôlées lors du déploiement d'un module via l'assistant de déploiement en ligne dun module externe. Elles sont aussi vérifier pour valider un module sur https://www.dolistore.com. Note: Les fichiers d'autre nature que des modules (documentation, outils externes, autres), même si mis à disposition sur DoliStore, ne sont pas concernés.

Art.png Règles

Nommage du package

Tous les modules pour Dolibarr doivent être nommé module_mymodulename-VERSION.zip (où VERSION peut être x or x.y or x.y.z). Si le module est pour un autre logiciel, le nom du zip doit être moduleothersoftware_mymodulename-VERSION.zip (par exemple moduleprestashop_mymodulename-1.0.zip).

Les packages du type application android, document PDF sont libres d'utiliser le nom de leur choix.

Le reste du document ne s'applique que pour les modules Dolibarr uniquement.

Structure

Le premier répertoire dans le fichier zip module_mymodulename-VERSION.zip doit s'appeler mymodulename.

Tous les fichiers du module seront ensuite dans ce répertoire, comme fichier ou sous-répertoire, en suivant l'arborescence exemple proposée dans htdocs/modulebuilder/template :

  • mymodule/build/ can contains any file you develop for compiling or building package
  • mymodule/core/modules/ contains module descriptor file modMyModule.class.php
  • mymodule/core/triggers contains triggers provided by module
  • mymodule/admin/ contains pages to setup module
  • mymodule/class/ contains PHP class files provided by module
  • mymodule/css contains CSS files provided by module
  • mymodule/docs to provide doc and licence files
  • mymodule/img contains images files provided by module
  • mymodule/langs/xx_XX contains language files for language xx_XX (try to put at least en_US)
  • mymodule/lib contains libraries provided and used by module
  • mymodule/scripts to provide command line tools or scripts. Note: Command lines script must start with line #!/usr/bin/env php
  • mymodule/sql contains SQL file provided by module to add new tables or indexes
  • mymodule/theme/mytheme if module provide its own theme/skin
  • mymodule/* contains php pages (note that you can also add any other subdir of your choice). Note: If your module is a metapackage (a module that will embed other modules in same zip, you must put here a file metapackage.conf)

Inclusion des fichiers main ou master

Un module externe de dolibarr doit pouvoir se mettre dans un répertoire htdocs/custom (cas standard), tout comme dans htdocs/ (cas alternatif), et il doit fonctionner dans les deux cas.


Inclusion

  • Toutes les inclusions de fichiers du core doivent être réalisées par
include_once/require_once/include/require DOL_DOCUMENT_ROOT.'/pathtocorefile';
  • Toutes les inclusions de fichiers spécifiques au module par les pages du modules doivent être faites avec
include_once/require_once/include/require './monmoduledir/...';
  • Toutes les inclusions de fichiers spécifiques à un autre module externe doivent être faites par
dol_include_once('/extmoduledir/...');

Lien

Tous les liens générés pour le HTML vers les pages spécifiques (href, src,...) du module devraient utiliser getNomURL de la classe d'un object ou à minima utiliser dol_buildpath

Pas d'écriture dans l'arborescence standard

Le module ne doit pas écrire dans l'arborescence des fichiers "programmes" de Dolibarr mais uniquement dans des fichiers situés dans le répertoire "documents". Y compris pour des fichiers temporaires. Il ne faut pas oublier que sur une installation correcte sécurisée de Dolibarr, l'ensemble de l'arborescence des programmes (à l'exception du répertoire custom) est positionné en lecture seule.

Modifications de fichier core Dolibarr

Compte tenu du point précédent, si des modifications de fichiers du coeur de Dolibarr sont nécessaires au module, elles doivent être soumises au projet via github. Elles seront acceptées :

  • Si elles sont poussées dans la branche dev du GitHub de Dolibarr (cas d'enrichissement de fonctionnalité Dolibarr)
  • Si il s'agit d'ajout de hook, trigger ou fonction, ou ajout de paramètres optionnels à des fonctions existantes. L'ajout de hook permet de permettre à un module externe d'intégrer son propre code n'import où dans le code de Dolibarr.

Publications sur DoliStore

MetaPackages

Si votre module est un "metapackage", donc un module qui comprend plusieurs modules, vous devez inclure un fichier appelé metapackage.conf dans le répertoire principal avec le nom de la liste de tous les autres modules fournis par votre package. Par exemple, l'image de votre module s'appelle "mymetapack". Lors de l'installation de ce module, il installe également les modules "abc" et "def". Vous devez donc inclure dans le zip de votre package un fichier *mymetapack/metapackage.conf* avec le contenu suivant:

# Ce fichier décrit tous les modules inclus dans le zip module_metapackage-x.y.zip
mymetapack
abd
def

Warning.png Le déploiement d'un métapackage à partir de l'assistant de déploiement de Dolibarr n'est possible qu'avec Dolibarr v11+

Langue

La description du produit est obligatoire en Anglais.

Support

Si votre module est payant, il doit obligatoirement figurer dans la description du produit un mail ou un canal pour le support aux utilisateurs (comme un lien vers un site web de contact)