Difference between revisions of "Modules - Packaging rules and Dolistore validation rules"

From Dolibarr ERP CRM Wiki
Jump to navigation Jump to search
(Update template URL)
Tags: Mobile web edit, Mobile edit
 
(43 intermediate revisions by 3 users not shown)
Line 1: Line 1:
= [[File:Art.png]] Enabling/activation condition of external module on DoliStore =
+
<!-- BEGIN origin interlang links -->
Here are the rules that will be apply by Dolibarr team on validation/activation of external module on [www.dolistore.com www.dolistore.com]
+
<!-- You can edit this section but do NOT remove these comments
 +
    Links below will be automatically replicated on translated pages by PolyglotBot -->
 +
[[fr:Modules - Règles de packaging et validation DoliStore]]
 +
[[es:Módulos - Packages validación y DoliStore reglas]]
 +
<!-- END interlang links -->
 +
 
 +
= [[File:Art.png]] Introduction =
 +
Here are the rules that you must apply to have a good quality external module on Dolibarr.
 +
Most of this rules are checked when you deploy your module from the online deployment feature. It is also checked when you try to submit your external module on https://www.dolistore.com
 +
 
 +
= [[File:Art.png]] Rules =
 +
 
 +
=== Name ===
 +
All modules that are Dolibarr modules must be called '''module_mymodulename-VERSION.zip''' (where VERSION is version can be x or x.y or x.y.z)
 +
 
 +
If the module is for another software then Dolibarra, the name of zip must be '''moduleothersoftware_mymodulename-VERSION.zip''' (for example moduleprestashop_mymodulename-1.0.zip)
 +
 
 +
The packages that are Android application, PDF or ODx documents are free to use the name of their choice. The extension however must follow the type of file (.app, .txt, .pdf, .odt, ...)
 +
 
 +
The rest of the document applies for Dolibarr modules only.
  
 
=== Structure ===
 
=== Structure ===
All module files have to be inside module directory, check this template [https://github.com/Dolibarr/dolibarr-module-template GitHub Dolibarr Module Template]
+
All modules must follow a structure similar to the one provided into '''htdocs/modulebuilder/template'''
 +
 
 +
{{TemplateModuleTreeSimple}}
 +
 
 +
Note: When you build your zip file, the directory '''mymodule''' must be in the root of the zip.
 +
 
 +
=== Custom directory management - Inclusion of main or master files ===
 +
 
 +
An external module called '''mymodule''' can be installed into '''htdocs/custom/mymodule''' (the default) as well as in '''htdocs/mymodule'''. It must works in both cases. Because all modules must work correctly when they are installed into root directory or into a personalized custom subdirectory.
 +
 
 +
For this reason, when you try to load the Dolibarr environment by including the main.inc.php or '''master.inc.php''' file, you must include 2 ways to include them:
 +
 
 +
We recommend to use the method suggested in the examples in htdocs/modulebuilder/*.php files and presented here to load the '''main.inc.php''', but you can replace the '''main.inc.php''' with '''master.inc.php''' for command line scripts.
 +
This portion of code is known to work in all situations (using Apache, Nginx, IIS, using virtual host of sub-directories, after a proxy redirect or not, if the web root is auto-detected or forced by conf file, and any combination of this).
 +
 
 +
<source lang="php">
 +
// Load Dolibarr environment
 +
$res = 0;
 +
// Try main.inc.php into web root known defined into CONTEXT_DOCUMENT_ROOT (not always defined)
 +
if (!$res && !empty($_SERVER["CONTEXT_DOCUMENT_ROOT"])) $res = @include $_SERVER["CONTEXT_DOCUMENT_ROOT"]."/main.inc.php";
 +
// Try main.inc.php into web root detected using web root calculated from SCRIPT_FILENAME
 +
$tmp = empty($_SERVER['SCRIPT_FILENAME']) ? '' : $_SERVER['SCRIPT_FILENAME']; $tmp2 = realpath(__FILE__); $i = strlen($tmp) - 1; $j = strlen($tmp2) - 1;
 +
while ($i > 0 && $j > 0 && isset($tmp[$i]) && isset($tmp2[$j]) && $tmp[$i] == $tmp2[$j]) { $i--; $j--; }
 +
if (!$res && $i > 0 && file_exists(substr($tmp, 0, ($i + 1))."/main.inc.php")) $res = @include substr($tmp, 0, ($i + 1))."/main.inc.php";
 +
if (!$res && $i > 0 && file_exists(dirname(substr($tmp, 0, ($i + 1)))."/main.inc.php")) $res = @include dirname(substr($tmp, 0, ($i + 1)))."/main.inc.php";
 +
// Try main.inc.php using relative path
 +
if (!$res && file_exists("../main.inc.php")) $res = @include "../main.inc.php";
 +
if (!$res && file_exists("../../main.inc.php")) $res = @include "../../main.inc.php";
 +
if (!$res && file_exists("../../../main.inc.php")) $res = @include "../../../main.inc.php";
 +
if (!$res) die("Include of main fails");
 +
</source>
 +
 
 +
=== Inclusion of php files ===
 +
Once the Dolibarr environment has been loaded (see previous chapter), loading other files is more easy, since we have a variable/constant defined to tell us where are exactly installed the files.
  
=== Inclusion ===
 
 
* To include a core file, use
 
* To include a core file, use
 
<source lang="php">
 
<source lang="php">
Line 21: Line 72:
 
</source>
 
</source>
  
=== Link ===  
+
=== Link to Dolibarr core object ===  
All link to a page of a standard dolibarr object (an invoice, an order, a bank account, ...) should be included into your module page using the '''getNomUrl''' method of the class of the object.
+
All link to a page of a standard dolibarr object (an invoice, an order, a bank account, ...) should be included into the code using the '''getNomUrl''' method of the class of the object.
  
=== Custom directory management ===  
+
=== No writing in standard tree===
An external module called '''mymodule''' can be installed into '''htdocs/custom/mymodule''' as well as in '''htdocs/mymodule'''. It must works in both cases
+
The module must not write in Dolibarr's "'''programs'''" but only into files located into the directory "'''documents'''". Including for temporary files. It should be remembered that on a proper secured installation of Dolibarr, the entire program tree (with the exception of the custom directory) is set to read-only.
  
 
=== Core file modifications ===
 
=== Core file modifications ===
 
Your module MUST NOT change or overwrite any files provided by standard Dolibarr distribution. If some Dolibarr core files need to me modified to have your module working, you must submit this change to core team. They will be accepted :
 
Your module MUST NOT change or overwrite any files provided by standard Dolibarr distribution. If some Dolibarr core files need to me modified to have your module working, you must submit this change to core team. They will be accepted :
 
* If they are pushed to dolibarr '''develop''' branch on GitHub
 
* If they are pushed to dolibarr '''develop''' branch on GitHub
* If what you push is adding hooks or triggers, or optionnal parameter to existing functions, it should be accepted with no condition. For other change, it may depends if change keeps old code compatible and is interesting for everybody.
+
* If what you push is adding hooks or triggers, or optional parameter to existing functions, it should be accepted with no condition. For other change, it may depends if change keeps old code compatible and is interesting for everybody.
 +
 
 +
=== Publishing to DoliStore ===
 +
 
 +
First, you must check you are able to publish your module using the feature "Deploy an external module" of Dolibarr (available in menu Home - Setup - Modules). If not, just don't try to publish it on DoliStore, your module will be refused.
 +
 
 +
==== MetaPackages ====
 +
If your module is a "metapackage", so a module that includes several modules, you must include a file called '''metapackage.conf''' into the main directory with name of list of all other modules provided by your package.
 +
For example, imagine your module is called "mymetapack". When installating this module, it should also install the module "abc" and "def". So you must include in the zip of your package a file *mymetapack/metapackage.conf* with the following content:
 +
<source lang="php">
 +
# This file describes all the modules that are included in the zip module_metapackage-x.y.zip
 +
mymetapack
 +
abd
 +
def
 +
</source>
 +
 
 +
[[File:Warning.png]] Deploying a metapackage from the Dolibarr online deployer is possible only with Dolibarr v11+
  
=== Support ===
+
==== Language ====
If your module is not free you have to give a email adress for support (or a website that allow customers to contact you)
+
Product description on Dolistore is mandatory in English. If not defined for other languages, english will be used.
  
Product description is mandatory in English, French, Spanish (and support email as well)
+
==== Support ====
 +
If your module is not free, you have to give an email address for support (or a website that allow customers to contact you)

Latest revision as of 10:26, 15 January 2020


Art.png Introduction

Here are the rules that you must apply to have a good quality external module on Dolibarr. Most of this rules are checked when you deploy your module from the online deployment feature. It is also checked when you try to submit your external module on https://www.dolistore.com

Art.png Rules

Name

All modules that are Dolibarr modules must be called module_mymodulename-VERSION.zip (where VERSION is version can be x or x.y or x.y.z)

If the module is for another software then Dolibarra, the name of zip must be moduleothersoftware_mymodulename-VERSION.zip (for example moduleprestashop_mymodulename-1.0.zip)

The packages that are Android application, PDF or ODx documents are free to use the name of their choice. The extension however must follow the type of file (.app, .txt, .pdf, .odt, ...)

The rest of the document applies for Dolibarr modules only.

Structure

All modules must follow a structure similar to the one provided into 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)

Note: When you build your zip file, the directory mymodule must be in the root of the zip.

Custom directory management - Inclusion of main or master files

An external module called mymodule can be installed into htdocs/custom/mymodule (the default) as well as in htdocs/mymodule. It must works in both cases. Because all modules must work correctly when they are installed into root directory or into a personalized custom subdirectory.

For this reason, when you try to load the Dolibarr environment by including the main.inc.php or master.inc.php file, you must include 2 ways to include them:

We recommend to use the method suggested in the examples in htdocs/modulebuilder/*.php files and presented here to load the main.inc.php, but you can replace the main.inc.php with master.inc.php for command line scripts. This portion of code is known to work in all situations (using Apache, Nginx, IIS, using virtual host of sub-directories, after a proxy redirect or not, if the web root is auto-detected or forced by conf file, and any combination of this).

// Load Dolibarr environment
$res = 0;
// Try main.inc.php into web root known defined into CONTEXT_DOCUMENT_ROOT (not always defined)
if (!$res && !empty($_SERVER["CONTEXT_DOCUMENT_ROOT"])) $res = @include $_SERVER["CONTEXT_DOCUMENT_ROOT"]."/main.inc.php";
// Try main.inc.php into web root detected using web root calculated from SCRIPT_FILENAME
$tmp = empty($_SERVER['SCRIPT_FILENAME']) ? '' : $_SERVER['SCRIPT_FILENAME']; $tmp2 = realpath(__FILE__); $i = strlen($tmp) - 1; $j = strlen($tmp2) - 1;
while ($i > 0 && $j > 0 && isset($tmp[$i]) && isset($tmp2[$j]) && $tmp[$i] == $tmp2[$j]) { $i--; $j--; }
if (!$res && $i > 0 && file_exists(substr($tmp, 0, ($i + 1))."/main.inc.php")) $res = @include substr($tmp, 0, ($i + 1))."/main.inc.php";
if (!$res && $i > 0 && file_exists(dirname(substr($tmp, 0, ($i + 1)))."/main.inc.php")) $res = @include dirname(substr($tmp, 0, ($i + 1)))."/main.inc.php";
// Try main.inc.php using relative path
if (!$res && file_exists("../main.inc.php")) $res = @include "../main.inc.php";
if (!$res && file_exists("../../main.inc.php")) $res = @include "../../main.inc.php";
if (!$res && file_exists("../../../main.inc.php")) $res = @include "../../../main.inc.php";
if (!$res) die("Include of main fails");

Inclusion of php files

Once the Dolibarr environment has been loaded (see previous chapter), loading other files is more easy, since we have a variable/constant defined to tell us where are exactly installed the files.

  • To include a core file, use
include_once/require_once/include/require DOL_DOCUMENT_ROOT.'/pathtofile';
  • To include a file of module into a file of same module, use
include_once/require_once/include/require './mymoduledir/...';
  • To include a file of another external module into a module file, use
dol_include_once('/otherextmoduledir/...');

Link to Dolibarr core object

All link to a page of a standard dolibarr object (an invoice, an order, a bank account, ...) should be included into the code using the getNomUrl method of the class of the object.

No writing in standard tree

The module must not write in Dolibarr's "programs" but only into files located into the directory "documents". Including for temporary files. It should be remembered that on a proper secured installation of Dolibarr, the entire program tree (with the exception of the custom directory) is set to read-only.

Core file modifications

Your module MUST NOT change or overwrite any files provided by standard Dolibarr distribution. If some Dolibarr core files need to me modified to have your module working, you must submit this change to core team. They will be accepted :

  • If they are pushed to dolibarr develop branch on GitHub
  • If what you push is adding hooks or triggers, or optional parameter to existing functions, it should be accepted with no condition. For other change, it may depends if change keeps old code compatible and is interesting for everybody.

Publishing to DoliStore

First, you must check you are able to publish your module using the feature "Deploy an external module" of Dolibarr (available in menu Home - Setup - Modules). If not, just don't try to publish it on DoliStore, your module will be refused.

MetaPackages

If your module is a "metapackage", so a module that includes several modules, you must include a file called metapackage.conf into the main directory with name of list of all other modules provided by your package. For example, imagine your module is called "mymetapack". When installating this module, it should also install the module "abc" and "def". So you must include in the zip of your package a file *mymetapack/metapackage.conf* with the following content:

# This file describes all the modules that are included in the zip module_metapackage-x.y.zip
mymetapack
abd
def

Warning.png Deploying a metapackage from the Dolibarr online deployer is possible only with Dolibarr v11+

Language

Product description on Dolistore is mandatory in English. If not defined for other languages, english will be used.

Support

If your module is not free, you have to give an email address for support (or a website that allow customers to contact you)