模塊開發

要創建新模塊,需要執行以下幾個步驟。本教程旨在向您介紹每一個步驟,以便添加一個模塊來擴展Dolibarr的功能,例如添加以下一個或多個功能:

  • 在數據庫中添加新表
  • 在菜單中添加您自己的菜單項
  • 添加對象和屏幕以輸入/查看新表
  • 在視圖頁上添加或刪除選項卡/編輯對象(發票、產品、訂單、事件等)
  • 為內部導出工具添加預定義的導出
  • 向主頁添加新信息框/widget小組件
  • 添加新的替換變量
  • 定義新權限
  • 自動觸發指定 Dolibarr 操作的代碼
  • 將自定義代碼插入 Dolibarr 的鈎子位置
  • 為所創建的對象的引用添加編號模塊(為數據自動編碼的模塊)
  • 添加PDF文檔模板
  • 添加一個新主題/皮膚

等等...

以下章節介紹了如何以簡單的方式手動完成所有這些操作。對於有經驗的開發人員來說,使用MDA生成的方法也不錯,詳見最後一章。

使用模塊生成器構建模塊

從Dolibarr 9.0開始,您可以使用"模塊生成器"(Module Builder)創建模塊的主要文件。要激活它 :

  • 設置參數 MAIN_FEATURES_LEVEL 的值為 2 ( 設置 / 其他 )(或者修改llx_const表中該項的記錄的value值為2)

 

  • 主頁 - 設置 - 設置-模塊/應用 多模塊工具 中激活「模塊生成器」(ModuleBuilder)

 

  • 點擊屏幕右上角菜單欄中出現的'Bug'圖標

 

  • 運行的ModuleBuilder界面如下:

 

外部模塊模板示例

一個Dolibarr外部模塊的模板/框架:Github Dolibarr模塊

創建模塊

以下章節描述了創建Dolibarr模塊所需的操作。無論模塊的用途如何,第一章描述的操作都是必須要完成的,後續章節描述的操作是否要做將取決於模塊的需求。

創建模塊描述符(必做)

何時:無論其用途如何,開發擴展模塊時都是強制性的。從Dolibarr 9.0開始,您可以使用「模塊生成器」創建模塊的描述符。該工具仍處於開發和完善階段,但其已經可以使用。

使用模塊生成器創建描述符

  • 通過單擊"Bug"圖標啟動模塊生成器

 

  • 在下圖「模塊名稱」處輸入不含空格的模塊名稱(模塊名稱不得包含下劃線 :_),然後單擊"創建"按鈕。

 

  • 已初始化具有第一個文件的模塊。然後,您可以更改模塊描述符的參數:

 

備選方案:手動創建描述符(不使用模塊生成器)

第一步是創建模塊描述文件(描述符)。為此:

  • 創建目錄 htdocs/custom/mymodule/core/modules
  • 進入目錄 htdocs/modulebuilder/template/core/modules 將文件 modMyModule.class.php 複製到目錄 htdocs/custom/mymodule/core/modules 中。
  • 重命名modMyModule.class.php文件,只需修改MyModule部分即可(文件必須以mod開頭)

然後,編輯此文件的內容:

  • 將所有modMyModule替換為與模塊用途相對應的值。此值必須始終以「mod」開頭,並且僅包含字母字符
  • 通過 $this->numero = 100000 設置模塊ID。為避免衝突,您可以參考以下頁面查找已分配的ID:模塊ID清
  • 可能還需要修改構造函數中定義的其他變量(有關其含義,請參閱類文件代碼中的注釋)。

模塊的描述文件(描述符)已準備就緒。請參閱下一步「測試描述符」以激活您的新模塊。

測試描述符

啟動Dolibarr並進入 主頁->設置->模塊/應用 頁面,您應該會看到一個新行,其中包含新模塊以及是否激活它的選項(瀏覽每個模塊類別的所有選項卡,直到找到它)。

$this->special 的值決定了模塊位於哪個類別選項卡中。

注意:如果在模塊描述符中設置了屬性 version ,則應在 模塊/應用 頁面看到包含新模塊的新行以及是否激活它的選項。如果將屬性 version 設置為「develop」或「experiental」,若要查看模塊,必須先進入頁面 「主頁->設置->其他設置」,並將參數 MAIN_FEATURES_LEVEL 設置為 1 以查看「實驗性」(experimental)模塊,或設置為 2 以查看「開發」(development)模塊。

模塊的名稱

模塊名稱不得包含下劃線或下劃線:_

新模塊的樹視圖(必需)

以下是組織模塊文件時要遵循的樹結構(如果使用ModuleBuilder生成文件,則自動採用此樹結構)。

註:zip 文件也必須符合此規則,只有第二行是強制性的。

  • mymodule/* ---------------- 包含php頁面(請注意,您也可以添加您選擇的任何其他子目錄)。注意:如果您的模塊是一個metapackage(一個以zip的形式嵌入其他模塊的模塊),則必須在此處放置一個文件 metapackage.conf。
  • mymodule/build/ ----------- 可以包含用於編譯或構建模塊安裝包而開發的任何文件
  • mymodule/core/modules/ ---- 包含模塊描述符文件 modMyModule.class.php
  • mymodule/core/triggers ---- 包含模塊提供的觸發器
  • mymodule/admin/ ----------- 包含設置模塊的頁面
  • mymodule/class/ ----------- 包含模塊提供的PHP類文件
  • mymodule/css -------------- 包含模塊提供的CSS文件
  • mymodule/js --------------- 包含模塊提供的javascript文件
  • mymodule/docs ------------- 提供doc和licence文件
  • mymodule/img -------------- 包含模塊提供的圖片文件
  • mymodule/langs/xx_XX ------ 包含xx_XX語言的語言文件(至少要放一個 en_US 語言文件)
  • mymodule/lib -------------- 包含模塊提供和使用的庫文件
  • mymodule/scripts ---------- 提供命令行工具或腳本。注意:命令行腳本的第一行必須是:#!/usr/bin/env php
  • mymodule/sql -------------- 包含模塊提供的用於添加新表或索引的SQL文件
  • mymodule/themes/mytheme --- 如果模塊提供了自己的主題/皮膚

一個好的Dolibarr擴展模塊的模板/框架:GitHub Dolibarr Module Modèle

創建數據表和 PHP DAO 類 (可選)

何時:如果您的模塊需要管理自己的數據

創建 .sql 文件

如果您的模塊要處理在Dolibarr標準版中不存在的數據,則需要自定義數據庫表來存儲這些數據。

在模塊的目錄中創建sql子目錄(mymodule/sql),用於放置要創建的sql腳本(使用ModuleBuilder,在"對象"選項卡中創建新對象後,將自動執行此步驟)。

接下來,檢查模塊描述符文件,在 init 函數中是否包括行:

$this->_load_tables('/mymodule/sql/');

並且未被注釋掉。

應遵循的規則

  • 根據每個表1個文件的原則添加表的創建命令文件,命名為 llx_mytable.sql(用於表),可能還附帶 llx_mytable.key.sql 文件(用於索引或外鍵)。示例請參閱 install/mysql/tables 中的現有文件。
  • SQL字段的推薦類型和名稱在 [[1]] 頁中定義。
  • 管理數據:對於添加/操作數據的命令,它們都必須位於同一目錄 /mymodule/sql/ 中名為 data.sql 的文件中。
  • 不要使用雙引號(如 "string"),因為雙引號(")在 PostGreSQL 中有特殊的含義

data.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__');

文件中的SQL語句必須對 mysql 數據庫有效。請注意:不需要維護其他數據庫類型的文件。它們由數據庫驅動程序動態讀取和轉換。

測試 .sql 文件

文件準備就緒後,您可以返回Dolibarr的模塊管理頁面,禁用模塊,刪除數據庫表(如果它們已經存在),然後重新激活模塊。正常情況下,應該可以通過激活模塊來重新創建表。否則,請手動檢查腳本,或查看Dolibarr日誌。

生成 PHP DAO 表訪問類

創建對象時,ModuleBuilder會自動生成對象的PHP DAO類文件。

如果不使用模塊生成器,您將在模塊框架文件htdocs/modulebuilder/templates/class/myobject.class.php 中找到示例。

在這個類中,已經有可調用的 CRUD(Create/Read/Update/Delete)方法來執行表行數據的插入、獲取(select)、更新和刪除。修改此文件以使用正確的模塊名和表名,並將該文件放在模塊的 class 子目錄中。若使用 ModuleBuilder 只需點擊幾下鼠標即可完成此操作。

使用ModuleBuilder生成PHP DAO類文件
  • 使用ModuleBuilder生成PHP DAO類文件,簡單至在下圖中選擇'對象'選項卡,輸入'對象名',然後點擊創建,即可生成相關一切文檔。

 

參見ModuleBuilder用戶手冊

選項卡顯示(可選)

添加或刪除對象表單上的選項卡

何時:在標準對象(發票、訂單、報價單、會員…)的表單中添加您自己的選項卡

要執行此操作,請打開之前創建的模塊描述符文件並編輯 $this->tabs 數組:

	// 用于在新tabs中添加新页面或删除现有页面的数组
	$this->tabs = array('objecttype:+tabname1:Title1:mylangfile@mymodule:$user->rights->mymodule->read:/mymodule/mypagetab1.php?id=__ID__'    // 增加一个由code tabname1标识的新tab
                            'objecttype:+tabname2:Title2:mylangfile@mymodule:$user->rights->mymodule->read:/mymodule/mypagetab2.php?id=__ID__',   // 增加一个由code tabname2标识的新tab
                            'objecttype:-tabname');                                                     // 删除一个由code tabname标识的现有选项卡

該表應包含字符串列表,每個字符串表示一個新選項卡。字符串格式由6個部分組成,由「:」分隔

  • 第1部分:選項卡的元素類型(objecttype),只能是下列值之一:
    • 'categories_x'-------在類別視圖中添加選項卡(將 'x' 替換為類別類型:0=產品;1=供應商;2=客戶/准客戶;3=會員)
    • 'contact'------------在聯繫人/地址視圖中添加選項卡
    • 'contract'-----------在合同視圖中添加選項卡
    • 'group'--------------在用戶組視圖中添加選項卡
    • 'intervention'-------在現場服務視圖中添加選項卡
    • 'invoice'------------在客戶發票視圖中添加選項卡
    • 'invoice_supplier'---在供應商發票視圖中添加選項卡
    • 'member'-------------在會員視圖中添加選項卡
    • 'opensurveypoll'-----在調查視圖中添加選項卡
    • 'order'--------------在客戶訂單視圖中添加選項卡
    • 'order_supplier'-----在供應商訂單視圖中添加選項卡
    • 'payment'------------在客戶付款視圖中添加選項卡
    • 'payment_supplier'---在供應商付款視圖中添加選項卡
    • 'product'------------在產品視圖中添加選項卡
    • 'propal'-------------在報價單視圖中添加選項卡
    • 'project'------------在項目視圖中添加選項卡
    • 'stock'--------------在庫存視圖中添加選項卡
    • 'thirdparty'---------在合作方視圖中添加選項卡
    • 'user'---------------在用戶視圖中添加選項卡
  • 第2部分:用於標識要添加(以+開頭)或刪除(以-開頭)的選項卡的codeName
  • 第3部分:選項卡的標題。這可以是硬編碼的字符串,或者是更好的,lang文件中的翻譯代碼。
  • 第4部分:文件「*.lang」的名稱(不帶.lang擴展名),此文件內有翻譯代碼和要顯示的語言字符串之間的對應關係。如果這個文件名後面跟@mymodule,則Dolibarr將在模塊自己的 lang 目錄中查找翻譯文件,即htdocs/mymodule/langs/code_CODE/mymodule.lang,否則Dolibarr將查找翻譯文件htdocs/langs/code_CODE/mylangfile.lang。
  • 第5部分:判斷選項卡是否可見的條件。設置為「1」,會使其始終可見。
  • 第6部分:單擊選項卡時要顯示的頁面的URL。字符串「__ID__」將自動替換為相關元素的ID。

要使聲明生效,必須禁用並重新激活該模塊。

要使用來自數據庫的數據填充選項卡的內容,請參閱下一章。

為了獲取現有選項卡的名稱「tabname」,您必須檢查文件「core/lib/module.lib.php」的函數「product_prepare_head」中使用的名稱,該文件對應於「$head[$h][2]」部分。

將對象的標準選項卡添加到其自己的表單頁面

何時:在您自己的表單中添加標準對象(產品、合作方…)的選項卡

必須遵循以下步驟:

1. 在代碼中包含定義相關函數的文件

對於每種對象選項卡,都有兩個文件需要使用下列語句:

require_once($url_fichier) ;

以下是要包含的文件示例(DOL_DOCUMENT_ROOT 對應於 dolibarr/htdocs/ 文件夾):

  • 合作方(thirdparty) :
    • DOL_DOCUMENT_ROOT/societe/class/societe.class.php
    • DOL_DOCUMENT_ROOT/core/lib/company.lib.php
  • 產品(product) :
    • DOL_DOCUMENT_ROOT/product/class/product.class.php
    • DOL_DOCUMENT_ROOT/core/lib/product.lib.php
  • 發票 (invoice) :
    • DOL_DOCUMENT_ROOT/compta/facture/class/facture.class.php
    • DOL_DOCUMENT_ROOT/core/lib/invoice.lib.php

...

2. 創建並加載要在自己的表單中顯示的標準對象

創建所需類的對象,並從數據庫中獲取對象數據。為此,您必須使用相應類的fetch()函數,並將從URL(/mytab.php?id=1)獲取的對象id作為參數傳遞。

例如:

$id=GETPOST('id','int');
$ref=GETPOST('ref','alpha');
$product = new Product($db) ;
$result = $product->fetch($id,$ref) ; // Test $result to check the database read is ok

3. 檢索與所選實體對應的選項卡列表

使用函數XXX_prepare_head($obj)(其中XXX是實體名稱)創建一個包含要顯示的選項卡定義的數組。要傳遞的參數是要顯示選項卡的對象。

返回的數組由以下內容組成:

$head        // tabs的数组
$head[$h]    // Element to describe one tab.
$head[$h][0] // Url of page to show when you click on tab
$head[$h][1] // Title of tab
$head[$h][2] // Code name to identify the tab

示例:

$head = product_prepare_head($product, $user) ; // 参数 $user 是要显示选项卡的对象,这就是"产品"对象为"user"对象准备的所有可用的选项卡的数组。

某些函數上不存在$user參數

4. 在您的頁面上顯示選項卡

使用dol_fiche_head()函數,該函數顯示由 XX_prepare_head() 返回的 $head 數組中包含的選項卡。

dol_fiche_head($links, $active='0', $title='', $notab=0, $picto='')
//$links  // tabs的数组,上面称为$head
//$active // 活动选项卡(输入模块文件中定义的选项卡名称,或$head[$h][2]中包含的名称)。此选项卡将突出显示
//$title  // 要显示的标题(显示在无法单击的特殊选项卡中)
//$notab
//$picto  // 要显示到标题中的图片的名称。可能的值为:
//            product
//            service
//            company

此函數將顯示所需的選項卡,並打開一個html元素< div class="" >,該元素對應於選項卡下方的顯示區域(如果參數 $notab=0)。要關閉顯示區域,只需在PHP代碼中使用關閉元素</div>。

註:相關的更多細節,請參閱 Doxygen文檔 或直接參考 Dolibarr 代碼。

創建PHP屏幕頁面(可選)

何時:如果新模塊的目的是添加一個需要新屏幕頁面的功能。

創建原始PHP屏幕頁面

隨後,您可以使用 modulebuilder 目錄中提供的示例模板(myobject_page.php)創建基於表數據的PHP頁面(有關命令行腳本的開發,請參閱 腳本開發 )。同樣,如果您使用的是 ModuleBuilder,則在初始化對象時會自動創建頁面實例(清單、創建頁面、Notes選項卡等)。

要創建新的用戶屏幕頁面,請創建特定於模塊的 htdocs 子目錄(如果尚未創建)(如 htdocs/mymodule ),以便在其中放置要創建的頁面。

從複製文件 myobject_page.php 作為開始。編輯該文件,以便能正確找到並加載 main.inc.php 文件:

// 加载Dolibarr环境
$res=0;
// 尝试include在CONTEXT_DOCUMENT_ROOT(不总是定义的)中定义的已知web根目录中的main.inc.php
if (! $res && ! empty($_SERVER["CONTEXT_DOCUMENT_ROOT"])) $res=@include($_SERVER["CONTEXT_DOCUMENT_ROOT"]."/main.inc.php");
// 尝试include由SCRIPT_FILENAME计算的web根检测到web根的main.inc.php
$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");
// 尝试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 && file_exists("../../../main.inc.php")) $res=@include("../../../main.inc.php");
if (! $res) die("Include of main fails");

如您所見,其多次嘗試加載 main.inc.php(或 master.inc.php)文件。目標是在儘可能多的場景下取得成功。最少為2行:一行用於嘗試將 master/main.inc.php 文件加載到 dolibarr 的根目錄中,另一行用於嘗試加載該文件,以支持模塊部署在「custom」目錄中的場景。但你可能不得不處理更多的場景。上面提供的示例應該能夠在幾乎所有場景/配置下加載 main/master.inc.php 文件。

在3.2之後,為所有版本的Dolibarr開發的擴展模塊可以放置在不同的文件夾中,而不僅僅是「htdocs」,如「htdocs/custom」,為了不必修改模塊的源代碼,我們要做幾個包含,所以這個規則必須被所有模塊使用。

請注意,您可以根據文件相對於模塊目錄樹的深度添加更多的「../」。

main.inc.php文件加載了技術環境變量和權限。然後設置以下對象變量:

  • $user 包含用戶屬性 + 權限的對象
  • $conf 包含 Dolibarr 設置的對象
  • $db 包含數據庫連接句柄的對象
  • $langs 包含用戶語言的對象

然後輸入代碼以顯示頁面。

  • 在不知道從何處調用文件的情況下,使用Dolibarr函數dol_include_once()(而不是直接使用include_once)包含專用於模塊的類或庫

例如:

dol_include_once('/mymodule/class/myclass.class.php', 'MyClass');
  • 另一方面,Dolibarr提供的標準類將使用 require-once 直接調用,語法如下:

例如:

require_once DOL_DOCUMENT_ROOT.'/core/class/doli.class.php';

原因是,儘管dol_include_once很方便,卻因它會掃描每個備用路徑目錄以找到文件,所以它的性能也很差,因為它會在每次調用時生成訪問和磁盤搜索(實際上,PHP集成了已讀文件的緩存,但未集成「未找到」文件的緩存)。由於給定的文件只可能存在於一個樹中,所以總會有一個無此文件的備用樹,這會產生對硬盤的不必要訪問,從而影響性能。與Dolibarr的內部文件一樣,我們總是知道確切的路徑,應該首選帶有該直接路徑的 require_once)。

在已存在的表單上增加新字段

您可能希望提供一個模塊,將更多字段添加到某些元素的表單(錄入和展示)中。

一個繁瑣(但不太糟糕)的解決方案可能是替換用於創建元素的所有頁面(這意味着禁用「新建元素」菜單項並添加您的菜單項,並禁用顯示元素的選項卡,以替換選項卡,該選項卡是您自己的完整頁面(從原始頁面複製/粘貼),使其與原始頁面相同,但被修改為添加字段並將添加的數據存儲到您自己的表中)。如果此解決方案適合您,請前往菜單 #Define your entries in menu (optional)#The tab management (optional)(本解決方案更強大,因為您可以在頁面中改變你想要改變的一切)。

我們將在這裡描述另一種解決方案,該解決方案僅適用於在現有字段的末尾「添加字段」,下面以元素「category」作為示例,但您可以將本教程轉換為發票、報價單...

  • 首先,添加一個由您的模塊擁有的表,以存儲新字段的值。此表將有一個名為「rowid」的列(將包含與元素表的字段rowid相同的值+每一個要添加的新字段。然後為這個新表創建一個具有CRUD(Create/Read/Update/Delete)方法的類。對於這兩項任務,請返回前一章#創建數據表和表的PHP類文件 (可選)
  • 其次,在模塊中添加一個鈎子,以將新字段添加到表單中。有關使用鈎子的通用文檔,請參閱Hooks_system#Implement_the_Hook章節。

如果遵循本教程,則必須執行以下操作才能將字段添加到 category 表單中:

  Page waiting to complete. To complete, create an account, go back and clic on "Modify".
  Page en attente d'être complété. Pour compléter, créez un compte, revenez et cliquez sur "Modifier".
  Página a completar. Para completarla, cree una cuenta, vuelva a la página y haga clic en "editar"
  Seite wartet auf Vervollständigung. Um zu helfen, erstelle ein Konto, gehe zurück und klicke auf "Bearbeiten".
  待完成,欲幫助完成,註冊帳號,點擊「編輯"
  ページは未完成の狀態です。完成させるにはアカウントを作成し、ページに戻って「編集」をクリックして下さい。

用鈎子添加/替換部分字段

請參閱 鈎子系統#實現鈎子 章節,了解如何使用Dolibarr現有的鈎子在Dolibarr鈎子位置添加/替換代碼。

訪問數據庫

如果您需要對自己添加的表進行基本變更,請使用之前生成的類,其中包含用於此目的的方法。

但是,如果您希望在沒有專用PHP對象的情況下訪問表,這仍然是可能的(例如,檢索記錄列表)。在這種情況下,請考慮以下示例:

對於插入、更新或刪除:

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

對於讀取:

$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++;
		}
	}
}

定義頁面樣式

為了使頁面的外觀與 Dolibarr 主題保持一致,必須使用 Dolibarr CSS 樣式。

例如:

  • 在表格標題行的trtd標籤上使用 class="liste_titre"
  • 在表格數據行的trtd標籤上使用 class="pair" 或 class="impair"
  • 在所有輸入域(input, select, textarea...)上使用 class="flat"
  • 在所有 type="submit"input 對象上使用 class="button"

使用 Dolibarr 日期選擇器

如果您願意,您可以使用 Dolibarr 屏幕頁面中的日期選擇器(帶日曆彈出窗口)。為此,請使用以下行:

 $form=new Form($db);
 $form->select_date('','mykey',0,0,0,"myform");

字符串

 $form=new Form($db);
 $form->select_date('','mykey',0,0,0,"myform");

標識表單中的日期選擇器。如果在同一頁面中使用多個日期選擇器,則必須設置不同的值。

字符串myform是FORM區域的名稱(在HTML頁面的form name=「myform」中)。因此,日期選擇器的顯示必須集成到FORM Html區域中。

要在POST結束時檢索值,命令為:

$mydate = dol_mktime(12, 0 , 0, $_POST['mykeymonth'], $_POST['mykeyday'], $_POST['mykeyyear']);
print strftime('%A %d %B %Y', $mydate);

覆蓋模板文件 (tpl)

如果您想覆蓋模塊上的tpl文件,則需要在 module_parts 上聲明它:

'tpl' => 1,

然後您可以在 mymodule/core/tpl 上放置任何tpl文件。

一旦模塊被激活,tpl就會被覆蓋。

設置配置頁面 (可選)

何時:如果您的模塊提供多個可配置選項。

創建配置編輯頁面

如果您的模塊提供了多個可配置選項,則需要創建一個PHP頁面來編輯這些選項(存儲在 llx_const 中)。

創建一個名為 mymodule_setuppage.php 的PHP頁面,顯示可能的選項並更新它們。

有必要以 /admin 中的一個頁面為例,展示讀取或保存選項的方法。將此配置頁面也放在/admin目錄中。

修改模塊的描述符文件

然後,在模塊描述符文件中,修改變量 config_page_url 以指定該PHP頁面的名稱。

如果頁面在目錄 admin/ 中),則:

$this->config_page_url = array("mymodule_setuppage.php");

如果頁面在目錄 mymodule/admin/ 中,則:

$this->config_page_url = array("mymodule_setuppage.php@mymodule");

測試您的頁面

前往「主頁->設置->模塊/應用」頁面,您應該會看到一個齒輪圖標,允許您訪問配置頁面,並且您應該能夠修改這些選項並將其保存到數據庫中。

設置菜單項 (可選)

何時 :如果您創建了PHP頁面,則必須從Dolibarr菜單訪問這些屏幕頁面。

設置菜單項

為此,您需要在模塊描述符文件中定義數組 this->menu,該數組用於聲明菜單。

此數組包含模塊激活後將顯示在菜單中的所有條目。

模塊描述符文件的示例文件 modMyModule.class.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'=>'mymodule',
			'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'=>'fk_mainmenu=xxx',		    // Use 'fk_mainmenu=xxx' or 'fk_mainmenu=xxx,fk_leftmenu=yyy' where xxx is mainmenucode and yyy is a leftmenucode of parent menu
			'type'=>'left',			        // This is a Left menu entry
			'titre'=>'MyModule left menu 1',
			'mainmenu'=>'xxx',
                        'leftmenu'=>'yyy',
			'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++;

若要根據權限限制對菜單的訪問,請更改數組的 perms 屬性。有關如何添加權限的更多信息,請參閱後面有關權限的章節。

測試您的菜單項

在Dolibarr中禁用並重新激活您的模塊,然後應該會出現菜單項(如果 「enabled」為真)。

設置您自己的權限 (可選)

何時: 如果要添加新權限。

模塊將其管理的權限定義,放在第一步中創建的模塊描述符文件中完成。更改行:

$this->rights_class = 'mymodule'

錄入正確的 myModule 值。

然後在 $this->rights 數組中填充與要管理的不同權限一樣多的條目。

$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++;

在$this->rights[$r][0]中,輸入尚未使用的權限ID(請參閱系統信息菜單,在運行Dolibarr的設備上查看已在使用的ID)。

在$this->rights[$r][1]中,輸入默認標籤(如果在 admin.lang 文件中找不到您權限標籤的翻譯字符串,則顯示該標籤。翻譯鍵值為 「Permission10001=我的超級權限的描述」)。

在$this>rights[$r][2]中,輸入權限類型。有三種類型的權限,「r」表示讀取、列出清單或導出權限,「w」表示寫入或更新權限,「d」表示刪除權限。

在$this->rights[$r][3]中,如果任何一個新創建的用戶都會被默認自動分配此權限,則輸入1。

在$this->rights[$r][4]和$this->rights[$r][5]中,輸入不帶空格的操作和子操作字符串。然後,您可以通過以下命令在PHP代碼中測試用戶是否具有正確的權限:

if ($user->rights->mymodule->action->subaction) ...

設置您自己的消息框/widget小組件 (可選)

何時:如果您的模塊附帶提供在主頁上展示的一個或多個消息框。

設置您的消息框

為此,請修改模塊描述符文件中的數組 $this->boxes。

首先為即將在 htdocs/mymodule/core/boxes 目錄中創建的每個box文件添加2行。

例如:

$this->boxes[0]['file']='mybox0.php@mymodule'
$this->boxes[0]['note']='My box 0'
 ...
$this->boxes[n]['file']='myboxn.php@mymodule'
$this->boxes[n]['note']='My box n'

其次,創建文件htdocs/mymodule/core/boxes/mybox0.phphtdocs/mymodule/core/boxes/mybox1.php…,以現有的消息框(在 htdocs/core/boxes 目錄中)為示例。

測試您的消息框是否被 Dolibarr 檢測到

停用並重新激活模塊。

前往菜單 主頁 - 設置 - widget小組件

您的消息框必須顯示在可激活消息框的清單中。激活它們,然後前往主頁並檢查它們是否正確顯示。

定義您自己的導出 (可選)

何時:如果您的模塊附帶提供預定義的數據導出(針對自己的表或來自另一個Dolibarr模塊的現有表)。

定義導出

為此,請取消注釋並修改模塊描述符文件中的 $this->export_xxx 數組。

測試您的導出

前往菜單 工具->導出助手 。您的導出應顯示在可用的預定義導出清單中(如果您的模塊已激活)。選擇它,您將看到在上一步時在表中定義的可能字段。選擇幾個字段並嘗試生成導出文件。

設置CSS樣式 (可選)

何時:在PHP屏幕頁面中,您使用的樣式類不是Dolibarr主題的樣式類(不推薦)。

創建並聲明您的樣式表

創建一個名為 mymodule.cssmymodule.css.php 的CSS樣式文件,並將其放在 htdocs/mymodule 目錄中。每個模塊只能有一個CSS文件。

請記住,最好使用已有的Dolibarr樣式(Dolibarr使用的CSS文件是themes/mytheme/themename.css.php)。僅當您必須處理不存在的樣式時,才創建特定於模塊的CSS文件。

樣式表準備就緒後,通過更改 $this->modules_parts 屬性在模塊描述符文件中聲明樣式表。

此處要輸入的值必須是 CSS 文件 URL 的相對路徑。

例如:

$this->module_parts = array('css' => array('/mymodule/css/mymodule.css.php'));

測試您的樣式表

停用並重新激活模塊。

前往Dolibarr的主頁。查看頁面的HTML源代碼。

您應該在HTML標頭中看到有一行是聲明您的樣式表。

定義Javascript函數 (可選)

何時:當您在PHP屏幕頁面中使用的 javascript 函數不是Dolibarr的標準js函數(在lib_head.js中)。

如果在PHP屏幕頁面上使用 javascript 函數,則必須將在 javascript 文件 htdocs/mymodule/js/mymodule.js 中聲明的函數加載到HTML頭中。

若要求Dolibarr(負責生成 header 部分)包含一個 javascript 文件,必須在頁面開頭調用的llxHeader()函數的參數中提供包含要包含的JS URL的參數。

頁面 /htdocs/mymodule/mypage.php 的示例:

$morejs=array("/mymodule/js/mymodule.js");
llxHeader('','Titre','','','','',$morejs,'',0,0);

在Dolibarr事件上觸發代碼 (可選)

何時:希望在Dolibarr標準操作後觸發執行特定操作時(例如:當在Dolibarr中創建發票時,我想更新模塊中的表),您需要創建一個 triggers 文件。

另請參閱 Dolibarr到外部系統的接口外部系統到Dolibarr的接口

在Dolibarr的hooks處插入代碼 (可選)

何時:當您想更改或添加業務事件以外的代碼時(請參閱上一章)。

請參閱頁面 Hooks系統.

添加編號模塊(可選)

何時:當您想添加默認模塊未涵蓋的編號規則時。

請參閱頁面 創建編號模塊

添加新文檔模板 (可選)

何時:需要添加新文檔模板時。如想要個性化自己生成的 PDF 或 ODT 文檔。

注意:要添加此功能,您無需創建模塊描述符文件。

有關如何從模板生成文檔的詳情,請參閱頁面 創建PDF文檔模板創建ODT文檔模板

添加主題 (可選)

何時:當您想要根據您的情況定製界面(顏色/字體/圖形)時。

注意:要添加此功能,您無需創建模塊描述符。

請參閱頁面 主題

修改開發模塊作者名

在myModule.class.php中查找editor_name

修改以下變量的值以修改作者名稱

$this->editor_name = 'Roger@QQ:12464313';
$this->editor_url = 'https://www.ivnun.cn';

面向開發人員的一些編碼規則和函數

要遵循的編碼規則請參閱 開發語言和編碼規範(PHP, SQL, HTML)

要調用 Dolibarr 供開發人員使用的預定義函數,請參閱 開發文檔 的「內部函數」一節。

創建一個安裝包來分發和安裝您的模塊

必須使用此步驟來製作安裝包,以便將其提交到市場 http://www.dolistore.com。

但您也可以使用它通過自己的分發網絡輕鬆分發模塊。

  • 進入 /build 目錄並將文件 makepack-dolibarrmodules.conf 複製到 makepack-mymodule.conf。請注意,穩定版本包中可能不提供此目錄。如果是這種情況,可以在 Dolibarr 網站的「開發版本」部分供下載的快照中檢索(在這種情況下,請獲取整個 build 目錄,這是一個獨立於版本的目錄)。

在此文件中輸入為模塊創建的新文件的名稱清單(模塊描述符、新表的SQL文件、PHP頁面、圖像等)。

  • 通過 Perl 運行腳本(需要Perl 5.0或更高版本):
perl makepack-dolibarrmodule.pl

該腳本將詢問模塊的名稱、主要版本和次要版本。然後將生成一個 mymodule.zip 文件,其中包含準備部署的模塊。

  • 接收您的模塊的人員必須將該文件放在其 Dolibarr 的安裝根目錄中,並執行以下命令:
tar -xvf mymodule.zip
  • 如果您希望您的模塊惠及所有人,您可以在插件市場 DoliStore.com 上提交它(zip文件)(您必須先創建一個帳戶並登錄,以使用「提交模塊/產品」鏈接)。
    • 如果您的模塊製作正確,文件將很快通過驗證。
    • 如果質量足夠好、許可證允許、並且模塊的功能被證明是普遍感興趣的,則可以將代碼添加到 Dolibarr 的源代碼中(除非您不希望這樣做)。

Dolistore上外部模塊的歸檔和驗證

請參閱 驗證規則