From 29ca4b7a0a0b9efa1b328c66d8b12a56d1375055 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Rapha=C3=ABl=20Doursenaud?= Date: Thu, 21 Aug 2014 11:32:39 +0200 Subject: [PATCH 1/3] Enhanced modules parent class properties documentation --- htdocs/core/modules/DolibarrModules.class.php | 201 ++++++++++++++---- 1 file changed, 164 insertions(+), 37 deletions(-) diff --git a/htdocs/core/modules/DolibarrModules.class.php b/htdocs/core/modules/DolibarrModules.class.php index 1215f8e85e2..b730b150c3e 100644 --- a/htdocs/core/modules/DolibarrModules.class.php +++ b/htdocs/core/modules/DolibarrModules.class.php @@ -1,10 +1,11 @@ - * Copyright (C) 2004 Sebastien Di Cintio - * Copyright (C) 2004 Benoit Mortier - * Copyright (C) 2004 Eric Seigne - * Copyright (C) 2005-2013 Laurent Destailleur - * Copyright (C) 2005-2012 Regis Houssin +/* Copyright (C) 2003-2007 Rodolphe Quiedeville + * Copyright (C) 2004 Sebastien Di Cintio + * Copyright (C) 2004 Benoit Mortier + * Copyright (C) 2004 Eric Seigne + * Copyright (C) 2005-2013 Laurent Destailleur + * Copyright (C) 2005-2012 Regis Houssin + * Copyright (C) 2014 Raphaël Doursenaud * * This program is free software; you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by @@ -31,29 +32,161 @@ */ abstract class DolibarrModules { - //! Database handler - var $db; - //! Relative path to module style sheet - var $style_sheet = ''; // deprecated - //! Path to create when module activated - var $dirs = array(); - //! Tableau des boites - var $boxes; - //! Tableau des constantes - var $const; - //! Tableau des droits - var $rights; - //! Tableau des menus - var $menu=array(); - //! Module parts array - var $module_parts=array(); - //! Tableau des documents ??? - var $docs; - - var $dbversion = "-"; - - /** + * @var DoliDb Database handler + */ + public $db; + + /** + * @var string Relative path to module style sheet + * @deprecated + */ + public $style_sheet = ''; + + /** + * @var array Paths to create when module is activated + */ + public $dirs = array(); + + /** + * @var array Module boxes + */ + public $boxes = array(); + + /** + * @var array Module constants + */ + public $const = array(); + + /** + * @var array Module access rights + */ + public $rights; + + /** + * @var string Module access rights family + */ + public $rights_class; + + /** + * @var array Module menu entries + */ + public $menu = array(); + + /** + * @var array Module parts + * array( + * // Set this to 1 if module has its own trigger directory (/mymodule/core/triggers) + * 'triggers' => 0, + * // Set this to 1 if module has its own login method directory (/mymodule/core/login) + * 'login' => 0, + * // Set this to 1 if module has its own substitution function file (/mymodule/core/substitutions) + * 'substitutions' => 0, + * // Set this to 1 if module has its own menus handler directory (/mymodule/core/menus) + * 'menus' => 0, + * // Set this to 1 if module has its own theme directory (/mymodule/theme) + * 'theme' => 0, + * // Set this to 1 if module overwrite template dir (/mymodule/core/tpl) + * 'tpl' => 0, + * // Set this to 1 if module has its own barcode directory (/mymodule/core/modules/barcode) + * 'barcode' => 0, + * // Set this to 1 if module has its own models directory (/mymodule/core/modules/xxx) + * 'models' => 0, + * // Set this to relative path of css file if module has its own css file + * 'css' => '/mymodule/css/mymodule.css.php', + * // Set this to relative path of js file if module must load a js on all pages + * 'js' => '/mymodule/js/mymodule.js', + * // Set here all hooks context managed by module + * 'hooks' => array('hookcontext1','hookcontext2'), + * // Set here all workflow context managed by module + * 'workflow' => array( + * 'WORKFLOW_MODULE1_YOURACTIONTYPE_MODULE2' = >array( + * 'enabled' => '! empty($conf->module1->enabled) && ! empty($conf->module2->enabled)', + * 'picto'=>'yourpicto@mymodule' + * ) + * ) + * ) + */ + public $module_parts = array(); + + /** + * @var string Module documents ? + * @deprecated Seems unused anywhere + */ + public $docs; + + /** + * @var string ? + * @deprecated Seems unused anywhere + */ + public $dbversion = "-"; + + /** + * @var string Error message + */ + public $error; + + /** + * @var int Module unique ID + */ + public $numero; + + /** + * @var string Module name + */ + public $name; + + /** + * @var string Module version + */ + public $version; + + /** + * @var string Module description + */ + public $description; + + /** + * @var string[] Module language files + */ + public $langfiles; + + /** + * @var string Module export code + */ + public $export_code; + + /** + * @var string Module export label + */ + public $export_label; + + /** + * @var string Module import code + */ + public $import_code; + + /** + * @var string Module import label + */ + public $import_label; + + /** + * @var string Module constant name + */ + public $const_name; + + /** + * @var bool Module can't be disabled + */ + public $always_enabled; + + /** + * @var bool Module is enabled globally (Multicompany support) + */ + public $core_enabled; + + /** * Method to enable a module. Insert into database all constants, boxes of module * * @param array $array_sql Array of SQL requests to execute when enabling module @@ -62,7 +195,7 @@ abstract class DolibarrModules */ function _init($array_sql, $options='') { - global $conf, $langs; + global $conf; $err=0; $this->db->begin(); @@ -98,18 +231,13 @@ abstract class DolibarrModules if (! $err) { $val=$array_sql[$i]; - $sql=''; + $sql=$val; $ignoreerror=0; if (is_array($val)) { $sql=$val['sql']; $ignoreerror=$val['ignoreerror']; } - else - { - $sql=$val; - } - // Add current entity id $sql=str_replace('__ENTITY__', $conf->entity, $sql); @@ -152,7 +280,6 @@ abstract class DolibarrModules */ function _remove($array_sql, $options='') { - global $langs; $err=0; $this->db->begin(); @@ -424,7 +551,7 @@ abstract class DolibarrModules */ function _load_tables($reldir) { - global $db,$conf; + global $conf; $error=0; $dirfound=0; From c3b30893fc74a0193cda9f3b256822207223cbe1 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Rapha=C3=ABl=20Doursenaud?= Date: Thu, 21 Aug 2014 12:16:13 +0200 Subject: [PATCH 2/3] Enhanced modules parent class methods documentation --- htdocs/core/modules/DolibarrModules.class.php | 208 ++++++++---------- 1 file changed, 97 insertions(+), 111 deletions(-) diff --git a/htdocs/core/modules/DolibarrModules.class.php b/htdocs/core/modules/DolibarrModules.class.php index b730b150c3e..e4d1f834b4a 100644 --- a/htdocs/core/modules/DolibarrModules.class.php +++ b/htdocs/core/modules/DolibarrModules.class.php @@ -22,13 +22,15 @@ */ /** - * \file htdocs/core/modules/DolibarrModules.class.php - * \brief File of parent class of module descriptor class files + * \file htdocs/core/modules/DolibarrModules.class.php + * \brief File of parent class of module descriptor class files */ /** - * Parent class of module descriptor class files + * Class DolibarrModules + * + * Parent class for module descriptor class files */ abstract class DolibarrModules { @@ -187,12 +189,14 @@ abstract class DolibarrModules public $core_enabled; /** - * Method to enable a module. Insert into database all constants, boxes of module - * - * @param array $array_sql Array of SQL requests to execute when enabling module - * @param string $options String with options when disabling module ('newboxdefonly|noboxes') - * @return int 1 if OK, 0 if KO - */ + * Enables a module. + * Inserts all informations into database + * + * @param string[] $array_sql SQL requests to be executed when enabling module + * @param string $options String with options when disabling module ('newboxdefonly|noboxes') + * + * @return int 1 if OK, 0 if KO + */ function _init($array_sql, $options='') { global $conf; @@ -272,11 +276,12 @@ abstract class DolibarrModules } /** - * Fonction de desactivation. Supprime de la base les constantes et boites du module + * Disable function. Deletes the module constant and boxes from the database. * - * @param array $array_sql Array of SQL requests to execute when disable module - * @param string $options String with options when disabling module ('newboxdefonly|noboxes') - * @return int 1 if OK, 0 if KO + * @param string[] $array_sql SQL requests to be executed when module is disabled + * @param string $options Options when disabling module ('newboxdefonly|noboxes') + * + * @return int 1 if OK, 0 if KO */ function _remove($array_sql, $options='') { @@ -339,10 +344,9 @@ abstract class DolibarrModules /** - * Retourne le nom traduit du module si la traduction existe dans admin.lang, - * sinon le nom defini par defaut dans le module. + * Gives the translated module name if translation exists in admin.lang or the default module name. * - * @return string Nom du module traduit + * @return string Translated module name */ function getName() { @@ -351,22 +355,21 @@ abstract class DolibarrModules if ($langs->trans("Module".$this->numero."Name") != ("Module".$this->numero."Name")) { - // Si traduction du nom du module existe + // If module name translation exists return $langs->trans("Module".$this->numero."Name"); } else { - // If translation of module with its numero does not exists, we take its name + // If module name translation using it's unique id does not exists, we take its name return $this->name; } } /** - * Retourne la description traduite du module si la traduction existe dans admin.lang, - * sinon la description definie par defaut dans le module + * Gives the translated module description if translation exists in admin.lang or the default module description * - * @return string Nom du module traduit + * @return string Translated module description */ function getDesc() { @@ -375,24 +378,23 @@ abstract class DolibarrModules if ($langs->trans("Module".$this->numero."Desc") != ("Module".$this->numero."Desc")) { - // Si traduction de la description du module existe + // If module description translation exists return $langs->trans("Module".$this->numero."Desc"); } else { - // Si traduction de la description du module n'existe pas, on prend definition en dur dans module + // If module description translation using it's unique id does not exists, we take its description return $this->description; } } /** - * Return module version. - * Pour les modules a l'etat 'experimental', retourne la traduction de 'experimental' - * Pour les modules 'dolibarr', retourne la version de Dolibarr - * Pour les autres modules, retourne la version du module + * Gives module version + * For 'experimental' modules, gives 'experimental' translation + * For 'dolibarr' modules, gives Dolibarr version * - * @return string Version du module + * @return string Module version */ function getVersion() { @@ -408,9 +410,9 @@ abstract class DolibarrModules /** - * Return if a module is a core or external module + * Tells if module is core or external * - * @return string 'core', 'external' or 'unknown' + * @return string 'core', 'external' or 'unknown' */ function isCoreOrExternalModule() { @@ -422,9 +424,9 @@ abstract class DolibarrModules /** - * Return list of lang files related to module + * Gives module related language files list * - * @return array Array of lang files + * @return string[] Language files list */ function getLangFilesArray() { @@ -432,10 +434,11 @@ abstract class DolibarrModules } /** - * Return translated label of a export dataset + * Gives translated label of an export dataset * - * @param int $r Index of dataset - * @return string Label of databaset + * @param int $r Dataset index + * + * @return string Translated databaset label */ function getExportDatasetLabel($r) { @@ -456,10 +459,11 @@ abstract class DolibarrModules /** - * Return translated label of an import dataset + * Gives translated label of an import dataset * - * @param int $r Index of dataset - * @return string Label of databaset + * @param int $r Dataset index + * + * @return string Translated dataset label */ function getImportDatasetLabel($r) { @@ -481,9 +485,9 @@ abstract class DolibarrModules /** - * Insert constant to activate module + * Insert constants for module activation * - * @return int Nb of errors (0 if OK) + * @return int Error count (0 if OK) */ function _active() { @@ -516,10 +520,10 @@ abstract class DolibarrModules /** - * Remove activation line + * Module deactivation * - * @return int Nb of errors (0 if OK) - **/ + * @return int Error count (0 if OK) + */ function _unactive() { global $conf; @@ -541,13 +545,13 @@ abstract class DolibarrModules /** - * Create tables and keys required by module. - * Files module.sql and module.key.sql with create table and create keys - * commands must be stored in directory reldir='/module/sql/' - * This function is called by this->init + * Create tables and keys required by module. + * Files module.sql and module.key.sql with create table and create keys + * commands must be stored in directory reldir='/module/sql/' + * This function is called by this->init * - * @param string $reldir Relative directory where to scan files - * @return int <=0 if KO, >0 if OK + * @param string $reldir Relative directory where to scan files + * @return int <=0 if KO, >0 if OK */ function _load_tables($reldir) { @@ -558,7 +562,7 @@ abstract class DolibarrModules if (empty($reldir)) return 1; - include_once DOL_DOCUMENT_ROOT .'/core/lib/admin.lib.php'; + include_once DOL_DOCUMENT_ROOT . '/core/lib/admin.lib.php'; $ok = 1; foreach($conf->file->dol_document_root as $dirroot) @@ -635,14 +639,15 @@ abstract class DolibarrModules /** - * Insert boxes into llx_boxes_def + * Adds boxes * - * @param string $option String with options when disabling module ('newboxdefonly'=insert only boxes definition) - * @return int Nb of errors (0 if OK) + * @param string $option Options when disabling module ('newboxdefonly'=insert only boxes definition) + * + * @return int Error count (0 if OK) */ function insert_boxes($option='') { - require_once DOL_DOCUMENT_ROOT.'/core/class/infobox.class.php'; + require_once DOL_DOCUMENT_ROOT . '/core/class/infobox.class.php'; global $conf; @@ -732,9 +737,9 @@ abstract class DolibarrModules /** - * Delete boxes + * Removes boxes * - * @return int Nb of errors (0 if OK) + * @return int Error count (0 if OK) */ function delete_boxes() { @@ -784,9 +789,9 @@ abstract class DolibarrModules } /** - * Remove links to new module page present in llx_const + * Removes tabs * - * @return int Nb of errors (0 if OK) + * @return int Error count (0 if OK) */ function delete_tabs() { @@ -809,9 +814,9 @@ abstract class DolibarrModules } /** - * Add links of new pages from modules in llx_const + * Adds tabs * - * @return int Number of errors (0 if ok) + * @return int Error count (0 if ok) */ function insert_tabs() { @@ -844,13 +849,7 @@ abstract class DolibarrModules $sql.= ")"; dol_syslog(get_class($this)."::insert_tabs", LOG_DEBUG); - $resql=$this->db->query($sql); - /* Allow duplicate key - if (! $resql) - { - $err++; - } - */ + $this->db->query($sql); } $i++; } @@ -859,9 +858,9 @@ abstract class DolibarrModules } /** - * Insert constants defined into $this->const array into table llx_const + * Adds constants * - * @return int Number of errors (0 if OK) + * @return int Error count (0 if OK) */ function insert_const() { @@ -926,9 +925,9 @@ abstract class DolibarrModules } /** - * Remove constants with tags deleteonunactive + * Removes constants tagged 'deleteonunactive' * - * @return int <0 if KO, 0 if OK + * @return int <0 if KO, 0 if OK */ function delete_const() { @@ -959,11 +958,12 @@ abstract class DolibarrModules } /** - * Insert permissions definitions related to the module into llx_rights_def + * Adds access rights * - * @param int $reinitadminperms If 1, we also grant them to all admin users - * @param int $force_entity Force current entity - * @return int Number of error (0 if OK) + * @param int $reinitadminperms If 1, we also grant them to all admin users + * @param int $force_entity Force current entity + * + * @return int Error count (0 if OK) */ function insert_permissions($reinitadminperms=0, $force_entity=null) { @@ -1055,7 +1055,7 @@ abstract class DolibarrModules if ($reinitadminperms) { if (! class_exists('User')) { - require DOL_DOCUMENT_ROOT.'/user/class/user.class.php'; + require DOL_DOCUMENT_ROOT . '/user/class/user.class.php'; } $sql="SELECT rowid FROM ".MAIN_DB_PREFIX."user WHERE admin = 1"; dol_syslog(get_class($this)."::insert_permissions Search all admin users", LOG_DEBUG); @@ -1099,9 +1099,9 @@ abstract class DolibarrModules /** - * Delete permissions + * Removes access rights * - * @return int Nb of errors (0 if OK) + * @return int Error count (0 if OK) */ function delete_permissions() { @@ -1124,15 +1124,15 @@ abstract class DolibarrModules /** - * Insert menus entries found into $this->menu into llx_menu* + * Adds menu entries * - * @return int Nb of errors (0 if OK) + * @return int Error count (0 if OK) */ function insert_menus() { global $user; - require_once DOL_DOCUMENT_ROOT.'/core/class/menubase.class.php'; + require_once DOL_DOCUMENT_ROOT . '/core/class/menubase.class.php'; $err=0; @@ -1228,9 +1228,9 @@ abstract class DolibarrModules /** - * Remove menus entries + * Removes menu entries * - * @return int Nb of errors (0 if OK) + * @return int Error count (0 if OK) */ function delete_menus() { @@ -1254,9 +1254,9 @@ abstract class DolibarrModules } /** - * Create directories required by module + * Creates directories * - * @return int Nb of errors (0 if OK) + * @return int Error count (0 if OK) */ function create_dirs() { @@ -1312,11 +1312,12 @@ abstract class DolibarrModules /** - * Insert directories in llx_const + * Adds directories definitions * - * @param string $name Name - * @param string $dir Directory - * @return int Nb of errors (0 if OK) + * @param string $name Name + * @param string $dir Directory + * + * @return int Error count (0 if OK) */ function insert_dirs($name,$dir) { @@ -1341,7 +1342,7 @@ abstract class DolibarrModules $sql.= " VALUES (".$this->db->encrypt($name,1).",'chaine',".$this->db->encrypt($dir,1).",'Directory for module ".$this->name."','0',".$conf->entity.")"; dol_syslog(get_class($this)."::insert_dirs", LOG_DEBUG); - $resql=$this->db->query($sql); + $this->db->query($sql); } } else @@ -1355,9 +1356,9 @@ abstract class DolibarrModules /** - * Remove directory entries + * Removes directories * - * @return int Nb of errors (0 if OK) + * @return int Error count (0 if OK) */ function delete_dirs() { @@ -1380,23 +1381,9 @@ abstract class DolibarrModules } /** - * Insert activation of generic parts from modules in llx_const - * Input entry use $this->module_parts = array( - * 'triggers' => 0, // Set this to 1 if module has its own trigger directory (/mymodule/core/triggers) - * 'login' => 0, // Set this to 1 if module has its own login method directory (/mymodule/core/login) - * 'substitutions' => 0, // Set this to 1 if module has its own substitution function file (/mymodule/core/substitutions) - * 'menus' => 0, // Set this to 1 if module has its own menus handler directory (/mymodule/core/menus) - * 'theme' => 0, // Set this to 1 if module has its own theme directory (/mymodule/theme) - * 'tpl' => 0, // Set this to 1 if module overwrite template dir (/mymodule/core/tpl) - * 'barcode' => 0, // Set this to 1 if module has its own barcode directory (/mymodule/core/modules/barcode) - * 'models' => 0, // Set this to 1 if module has its own models directory (/mymodule/core/modules/xxx) - * 'css' => '/mymodule/css/mymodule.css.php', // Set this to relative path of css file if module has its own css file - * 'js' => '/mymodule/js/mymodule.js', // Set this to relative path of js file if module must load a js on all pages - * 'hooks' => array('hookcontext1','hookcontext2') // Set here all hooks context managed by module - * 'workflow' => array('WORKFLOW_MODULE1_YOURACTIONTYPE_MODULE2'=>array('enabled'=>'! empty($conf->module1->enabled) && ! empty($conf->module2->enabled)', 'picto'=>'yourpicto@mymodule') // Set here all workflow context managed by module - * ) + * Adds generic parts * - * @return int Nb of errors (0 if OK) + * @return int Error count (0 if OK) */ function insert_module_parts() { @@ -1465,9 +1452,9 @@ abstract class DolibarrModules } /** - * Remove activation of generic parts of modules from llx_const + * Removes generic parts * - * @return int Nb of errors (0 if OK) + * @return int Error count (0 if OK) */ function delete_module_parts() { @@ -1495,7 +1482,6 @@ abstract class DolibarrModules } } } - return $err; } From 2c1e892efe7f414f0e5c8ad3f3746cce1e907bb5 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Rapha=C3=ABl=20Doursenaud?= Date: Thu, 21 Aug 2014 12:39:17 +0200 Subject: [PATCH 3/3] Enhanced boxes model documentation --- htdocs/core/boxes/modules_boxes.php | 120 +++++++++++++++++++++------- 1 file changed, 90 insertions(+), 30 deletions(-) diff --git a/htdocs/core/boxes/modules_boxes.php b/htdocs/core/boxes/modules_boxes.php index ece19fe222c..275154cd80e 100644 --- a/htdocs/core/boxes/modules_boxes.php +++ b/htdocs/core/boxes/modules_boxes.php @@ -1,6 +1,7 @@ - * Copyright (C) 2005-2012 Regis Houssin +/* Copyright (C) 2004-2013 Laurent Destailleur + * Copyright (C) 2005-2012 Regis Houssin + * Copyright (C) 2014 Raphaël Doursenaud * * This program is free software; you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by @@ -25,31 +26,88 @@ /** - * Parent class of boxes + * Class ModeleBoxes + * + * Boxes parent class */ class ModeleBoxes // Can't be abtract as it is instantiated to build "empty" boxes { - var $db; - var $error=''; - var $max=5; - var $enabled=1; - - var $rowid; - var $id; - var $position; - var $box_order; - var $fk_user; - var $sourcefile; - var $class; - var $box_id; - var $note; - + /** + * @var DoliDB Database handler + */ + public $db; /** - * Constructor + * @var string Error message + */ + public $error = ''; + + /** + * @var int Maximum lines + */ + public $max = 5; + + /** + * @var int Status + */ + public $enabled=1; + + /** + * @var int Box definition database ID + */ + public $rowid; + + /** + * @var int ID + * @deprecated Same as box_id? + */ + public $id; + + /** + * @var int Position? + */ + public $position; + + /** + * @var string Display order + */ + public $box_order; + + /** + * @var int User ID + */ + public $fk_user; + + /** + * @var string Source file + */ + public $sourcefile; + + /** + * @var string Class name + */ + public $class; + + /** + * @var string ID + */ + public $box_id; + + /** + * @var string Alphanumeric ID + */ + public $boxcode; + + /** + * @var string Note + */ + public $note; + + /** + * Constructor * - * @param DoliDB $db Database handler - * @param string $param More parameters + * @param DoliDB $db Database handler + * @param string $param More parameters */ function __construct($db,$param='') { @@ -57,9 +115,9 @@ class ModeleBoxes // Can't be abtract as it is instantiated to build "empty" } /** - * Return last error message + * Return last error message * - * @return string Error message + * @return string Error message */ function error() { @@ -68,10 +126,11 @@ class ModeleBoxes // Can't be abtract as it is instantiated to build "empty" /** - * Load a box line from its rowid + * Load a box line from its rowid * - * @param int $rowid Row id to load - * @return int <0 if KO, >0 if OK + * @param int $rowid Row id to load + * + * @return int <0 if KO, >0 if OK */ function fetch($rowid) { @@ -110,11 +169,12 @@ class ModeleBoxes // Can't be abtract as it is instantiated to build "empty" /** - * Standard method to show a box (usage by boxes not mandatory, a box can still use its own showBox function) + *Standard method to show a box (usage by boxes not mandatory, a box can still use its own showBox function) * - * @param array $head Array with properties of box title - * @param array $contents Array with properties of box lines - * @return void + * @param array $head Array with properties of box title + * @param array $contents Array with properties of box lines + * + * @return void */ function showBox($head, $contents) {