禪道常用資料

禪道的目錄結構

一、頂級目錄結構：

bin目錄是存放里禪道的一些命令行腳本； config下面存放了禪道運行的主配置文件和數據庫配置文件。 db下面是歷次升級的數據庫腳本和完整的建庫腳本。 framework里面則是禪道php框架的核心類文件。 lib目錄下面是其他幾個類文件。比如數據庫訪問，發送郵件，數據驗證等。 module下面則是存放了具體的模塊。禪道目前已經有30余個模塊了。 tmp目錄是禪道程序運行時的臨時文件存放目錄。 www目錄則是存放了各種樣式表文件，js文件，圖片文件，以及禪道的入口程序，index.php

二、www目錄

data目錄是上傳附件所在的目錄。 fushioncharts則存放了報表解決方案所需要用到的flash文件。 js目錄下面則是禪道用到的各種jquery插件和相應的功能函數。 theme目錄則是樣式表文件的目錄。 www根目錄下面的index.php是整個禪道程序的入口程序。所有的請求都是通過這個程序進入的。 install.php則是安裝程序。 upgrade.php是升級程序，每次升級的時候需要訪問這個文件。 .htaccess和.ztaccess文件是apache使用的配置文件。可以在rewrite模塊打開的情況下，配置禪道使用靜態方式訪問。

三、module目錄

module目錄下面總共有30多個模塊，分別對應了禪道里面的某一個功能模塊。整個禪道的功能，就是由這些模塊組合而成。讓我們來看一個具體的模塊。

lang目錄下面存放的當前模塊的語言文件。zh-cn對應中文簡體，zh-tw中文繁體，依次類推。如果需要修改禪道里面某些字段的名稱或者配置，則需要打開相應的文件進行修改。 view目錄下面存放了每一個頁面所對應的模板文件。比如bug瀏覽頁面，對應的模板就是browse.html.php。 config.php存放了當前模塊相應的配置項。 control.php則是整個bug模塊所有頁面的入口。也就是說，bug相關的頁面瀏覽都可以在這個文件里面找到相應的方法定義。 model.php則是bug相關數據庫操作的方法列表。

control方法定位(找到要修改的文件)

一、control方法的定位

control方法是每一個頁面的入口，順藤摸瓜，讓我們先來看個例子： bug-browse-1.html 或者是/?m=bug&f=browse&productID=1&t=html。這里面有什么玄機呢？讓我們來揭曉。

bug-browse-1.html，表示是訪問 bug這個模塊的 browse方法，傳遞的第一個參數為 1，訪問的頁面類型是 html。

同樣, /?m=bug&f=browse&productID=1&t=html, m代表了模塊名稱， f代表了方法名稱，后面的則是參數列表。

那么我們就可以對應到禪道的源代碼，module/bug/control.php中的browse方法：

 

二、control方法里面的調用

ok，我們現在已經知道了入口的函數在什么地方，我們來跟到里面看看吧。

$this->bug， 表示的是調用bug模塊的model對象，那么它對應的文件在什么地方呢？聰明的你，應該已經猜到了吧。在 module/bug/model.php

this->loadmoel('tree')->xxx，表示加載tree模塊的model對象，它對應的文件在module/tree/model.php

$this->app->loadClass('pager'),表示加載一個lib類，它對應的文件則在lib/pager/pager.class.php

$this->lang->bug->xxx，它的定義在module/bug/lang/zh-cn.php。后面的zh-cn根據當前用戶的語言而定。

后來看模塊文件。$this->display()之后，調用的是view目錄下面和當前方法同名的模板文件。比如bug的browse方法，它對應的模板文件是module/bug/view/browse.html.php

 

禪道的數據庫結構

禪道的數據庫命名都比較簡明扼要，從字面意思應該都可以猜出來表的用途。如果還不是很清楚的話，可以到每個表對應的模塊下面的語言文件里面查找。

最新版本可以在  禪道 后台---二次開發---數據庫 中查看相應的表介紹。

一、我的地盤相關的表

• zt_todo，待辦事宜表。
• zt_product，記錄了產品相關的信息。
• zt_productplan，記錄了產品的計划信息。
• zt_story，是非常重要的一張表，記錄了系統中所有的需求記錄。
• zt_storyspec，記錄了需求的描述信息。
• zt_storystage，記錄需求的階段信息。
• zt_release，記錄了產品的發布信息。這張表同時也和zt_build互相關聯。
• zt_branch，記錄產品的分支和平台信息。
• zt_project，項目表。
• zt_projectproduct，記錄了項目和產品之間的關聯關系。
• zt_projectstory，記錄了項目中需要做的需求列表。
• zt_task，任務表。
• zt_burn，燃盡圖數據表。燃盡圖就是根據這張表的數據畫出來的。
• zt_team，記錄了項目中的團隊成員。
• zt_build，記錄了項目中產品的版本列表。
• zt_taskestimate，項目任務工時表。
• zt_bug，bug表，也是大家非常熟悉的一張表了。
• zt_case，用例表。記錄了所有的測試用例。
• zt_casestep，則是記錄了用例相關的步驟，包括歷史。
• zt_testtask，測試版本表，記錄了歷次的測試任務。
• zt_testrun，則記錄了每個測試任務所對應的用例執行情況。
• zt_testresult，記錄了每個用例歷次執行的結果。
• zt_testsuite，測試套件表。
• zt_suitecase，套件用例表。
• zt_testreport，測試報告表。
• zt_doclib，記錄了自定義文檔庫列表。
• zt_doc，則記錄了所有的文檔。
• zt_doccontent，文檔的內容表。
• zt_user，用戶表。
• zt_group，分組表。
• zt_usergroup，用戶和分組之間的對應關系。
• zt_grouppriv，分組的權限。
• zt_dept，部門結構表。
• zt_userquery，用戶自定義查詢表。
• zt_usertpl，用戶的自定義模板表。
• zt_usercontact，用戶聯系人表。
• zt_company，這張表記錄了當前公司的信息，也是頂級的一張表。
• zt_action，系統日志表。
• zt_cron，定時任務表，記錄計划任務。
• zt_extension，插件表。
• zt_history，操作歷史表， 記錄對任何一個對象的所有修改記錄， 前后值的變化。
• zt_lang，語言定義表。
• zt_module，也是非常重要的一張表，它維護了禪道系統中的模塊划分數據，比如需求的模塊划分。
• zt_effort，日志表。
• zt_entry，應用表。
• zt_log，接口日志表。
• zt_mailqueue，郵件列隊表。
• zt_module，模塊表，記錄模塊信息。
• zt_notify，提醒信息表，記錄所有的提醒信息。
• zt_score，積分表，記錄積分信息。
• zt_file，附件表。記錄了所有的附件。
• zt_block，區塊表，記錄我的地盤首頁，產品主頁，項目主頁，測試主頁的區塊信息。
• zt_config，系統配置表，記錄所有的基本配置信息。
• zt_webhook，記錄webhook信息。
• zt_webhookdatas，記錄webhook的數據表。

二、產品相關的表

三、項目相關的表

四、測試相關的表

五、文檔庫相關的表

六、組織管理相關的表

七、后台管理相關的表

八、其他模塊相關的表

公用模塊--common

common模塊在禪道中是比較特殊的一個模塊，禪道里面的眾多公用功能都是由common來實現的。

• common/model.php里面，提供了其他模塊都有可能用到的一些方法。比如權限檢查，菜單打印等功能。
• common/view目錄下面，則是提供了公用的模板。比如公用的header.html.php，footer.html.php等。還包含了各種jquery插件的初始化代碼模板。比如colorbox.html.php。
• common/lang下面，則是設置了公用的語言項。

所以，后面如果大家需要修改一些語言項，或者修改公用的模板文件，可以到common模塊下面尋找相應的代碼。

如何登記菜單

擴展禪道遇到的一個問題就是如何將自己增加的功能登記到菜單中，本篇文章來講述如何來實現這個功能。

一、菜單的組成

禪道的導航菜單分為三個部分，頂部菜單、模塊菜單、功能菜單。

 

二、菜單的定義

菜單的代碼定義是在zentao/module/common/lang/zh-cn語言文件中。我們來看下主菜單的定義。

 

2.1 主導航菜單的定義

80 $lang->menu->my = ' 我的地盤|my|index';

81 $lang->menu->product = '產品視圖|product|index';

82 $lang->menu->project = '項目視圖|project|index';

83 $lang->menu->qa = '測試視圖|qa|index';

我們來看下代碼的含義： 83 $lang->menu->qa = '測試視圖|qa|index';

這行代碼定義了測試視圖的代碼，其中的menu->qa定義的是菜單的鍵值，可以根據實際的模塊定義。后面是使用豎線分開的三個參數，分別是菜單的文本，對應到模塊和方法。這句話就表示要定義一個頂級菜單，文本是“測試視圖”，鏈接到qa模塊的index方法。

 

2.2 模塊菜單的定義

我們以產品視圖的模塊菜單為例：

144 $lang->product->menu->list = '%s';

145 $lang->product->menu->story = array('link' => '需求|product|browse|productID=%s', 'subModule' => 'story');

155 $lang->product->menu->create = array('link' => ' 新增產品|product|create', 'float' => 'right');

158 $lang->productplan->menu = $lang->product->menu;

159 $lang->release->menu = $lang->product->menu;

這幾行代碼定義了產品視圖模塊的模塊菜單，這里面出現了一些新的定義方法：

 

2.2.1 使用數組來定義鏈接

145 $lang->product->menu->story = array('link' => '需求|product|browse|productID=%s', 'subModule' => 'story');

這行代碼對鏈接進行定義的時候，使用了數組，分別定義了兩個元素，link和subModule。其中link多增加了一個參數字段：productID=%s，代表產品視圖的“需求”菜單會鏈接到product模塊的browse方法，傳遞的參數是productID=%s，其中的%s會被替換成當前的產品id。

 

2.2.2 使用subModuel來定義子模塊。145 $lang->product->menu->story = array('link' => '需求|product|browse|productID=%s', 'subModule' => 'story');

subModule定義的是它的子模塊，這個需要是用來保持菜單高亮使用。這樣當訪問到story模塊的時候，還會保持“產品視圖”這個定義菜單高亮。

 

2.2.3 使用alias來定義方法別名 151 $lang->product->menu->view = array('link' => '概況|product|view|productID=%s', 'alias' => 'edit');

這個地方的alias代表product的edit頁面和product的view頁面是相同的，這樣當編輯產品的時候，“概況”菜單還是會保持高亮的。

 

2.2.4 定義菜單的位置

所有的菜單默認都是顯示在左側的，如果需要將菜單顯示在右側，則需要定義它的float參數。

155 $lang->product->menu->create = array('link' => ' 新增產品|product|create', 'float' => 'right');

通過設置float參數，可以定義這個新增產品的鏈接顯示在頁面的右側。

 

2.3 功能菜單的定義

功能菜單是在每一個模塊的視圖文件里面打印的，其擴展方法和視圖的擴展相同，后面會講到這一點。

三、菜單順序的定義

前面講述的是禪道菜單的定義，下面來講下禪道菜單順序的定義。在common/lang/下面有一個menuOrder.php的文件，在這個文件中定義了每個菜單的顯示順序。

/* Sort of main menu. */

$lang->menuOrder[5] = 'my';

$lang->menuOrder[10] = 'product';

$lang->menuOrder[15] = 'project';

$lang->menuOrder[20] = 'qa';

$lang->menuOrder[25] = 'doc';

$lang->menuOrder[30] = 'report';

$lang->menuOrder[35] = 'company';

$lang->menuOrder[40] = 'admin';

/* index menu order. */

$lang->index->menuOrder[5] = 'product';

$lang->index->menuOrder[10] = 'project';

四、如何將自己的頁面登記到菜單中

了解了禪道的菜單機制之后，做擴展就非常容易了。我們來說下步驟：

 

1. 在module/common/ext/lang/zh-cn/下面創建一個文件，比如叫做abc.php(文件名可以任意定義)

2. 在這個文件中加上自己的菜單就好了，比如禪道專業版本中的版本庫菜單：

$lang->menu->repo = '版本庫|repo|browse';

$lang->menuOrder[21] = 'repo';

 

$lang->repo->menu->list = '%s' . $lang->arrow;

$lang->repo->menu->browse = array('link' =>'瀏覽|repo|browse|repoID=%s', 'alias' => 'diff, log, view, revision, showsynccomment');

$lang->repo->menu->settings = '設置|repo|settings|repoID=%s';

$lang->repo->menu->delete = array('link' => '刪除|repo|delete|repoID=%s', 'target' => 'hiddenwin');

$lang->repo->menu->create = array('link' => '新增版本庫|repo|create|', 'float' => 'right');

 

 

五、如何將外部鏈加到菜單中

假設我們要在禪道頂級菜單掛一個新浪的網址，並且要在新窗口打開這個網址。

1、在module/common/ext/view下新建文件footer.sina.html.hook.php

2、加入 如下內容保存后，打開禪道即可看到頂級菜單出現新增的鏈接，並且是在新窗口打開的：

 

<script> 

$(document).ready(function()

{

    $("#navbar ul.nav").append('<li><a id="menusina" href="http://www.sina.com.cn"  target="_blank">新浪</ a><\/li>');

});

</script>

 

如何登記權限

本文將介紹如何對新增的module進行權限的設置。

在禪道的開源版中，所有的控制（control）方法的權限都是通過在group/lang/resource.php進行分配控制的，（PS：默認所有的控制方法都是只有管理員可以訪問），通過“組織=>權限”中的分配界面對每個用戶進行訪問權限的設置，如圖。

 

 

 

為了能夠使自己新增的模塊(module)或在現有模塊的基礎上新增的控制(control)方法能夠在界面中顯示並分配權限，則需要對module/group/lang/resource.php進行擴展，以下以對menudemo模塊的index控制方法為例介紹具體操作。

 

1、在module/group/ext/lang/zh-cn/、module/group/ext/lang/zh-tw/、module/group/ext/lang/en/文件夾下分別建立menudemo.php文件

2、在menudemo.php文件中加入以下代碼(group/ext/lang/zh-cn/menudemo.php group/ext/lang/zh-tw/menudemo.php group/ext/lang/en/menudemo.php)

<?php

$lang->resource->menudemo = new stdclass();

$lang->resource->menudemo->index = 'index';

 

 

3、界面顯示名稱聲明

在權限分配界面中，為了能夠直觀的查看到所分配的是什么權限，就必須先對顯示名稱進行聲明。其聲明操作一般都是在lang文件中進行。

module/menudemo/lang/zh-cn.php

$lang->menudemo->common = '導航Demo';

$lang->menudemo->index = '首頁';

$lang->menudemo->methodOrder[5]  = 'index';

 

其中 $lang->menudemo->methodOrder[5] = 'index';是為了控制顯示的先后排序而定義的。

zh-tw.php en.php分別也加入以上內容，否則當切換界面語言時，分配界面將無法顯示信息。

示例：如何修改禪道的語言提示？

下面來看具體的例子吧，以修改bug的優先級列表提示為例：

 

1. 在module/bug/下面創建 ext/lang/zh-cn/目錄，這里面的zh-cn，可以根據實際情況換成相應的語言，比如en, zh-tw。

2. 在這個目錄下面創建一個abc.php，注意， abc的名字是可以隨便定義的。

3. 打開這個文件，重新定義優先級的提示：  

                unset($lang->bug->priList);

$lang->bug->priList[0] = '';

$lang->bug->priList[3] = '3';

$lang->bug->priList[1] = '1';

$lang->bug->priList[2] = '2';

$lang->bug->priList[4] = '4';

注意：

1. 如果你定義的是一個列表格式的數據，需要加上unset這一句。這樣可以保證列表是完全按照你的定義。

2. 請一定按照我們的擴展機制來存放文件，這樣可以保證我們后面升級，不會覆蓋你自己的修改的代碼。

3. windows下面編輯，建議使用ultraedit，保存的時候，保存成utf-8編碼，nobom格式。否則會造成系統不正常。

示例：創建bug時可以設置優先級字段

這個例子用來向大家展示如何使用禪道的擴展機制來對禪道進行各種定制，而不用擔心后續升級之后被覆蓋。

目標：在創建bug的時候，可以直接設置優先級字段。

一、創建目錄

1. 在module/bug/目錄下面建立 ext/view目錄。

2. 將module/bug/view/create.html.php拷貝到ext/view/目錄下面，仍然是create.html.php

3. 修改ext/view/create.html.php

二、修改程序

把模板復制過去之后，需要修改頭文件和footer文件的包含路徑。然后再修改模板文件，在相應的地方加入bug優先級字段即可。

然后訪問bug創建頁面，就會出現優先級字段了。

三、下載插件

我們為大家提供了插件，可以下載： http://www.zentao.net/extension-viewExt-10.html

使用在線擴展編輯器

禪道還提供了web方式的代碼擴展編輯器，可以使用超級管理員登錄禪道，對禪道進行二次擴展：

一、訪問入口

禪道擴展編輯就是后台模塊下的擴展里。

點擊進入后台--二次開發--編輯器，首先看到的是可擴展的模塊列表。

點擊想要擴展的模塊鏈接，右側就會出現該模塊所有可擴展的文件，包括control.php和model.php的方法。

這些文件是有排列順序的，自上而下依次是：

model.php和該文件的方法、

control.php和該文件的方法、

view文件夾下的模板文件、

語言文件、

配置文件config.php

JS

CSS

擴展文件。

擴展文件中的排列順序與上述的排列順序是一致的，這樣可以方便快速的找到要擴展的文件。

在每個文件后面，有相應的操作鏈接，點擊這些鏈接，就可以在線編輯擴展了。

二、在線編輯

2.1 model.php的擴展

可以對model.php的現有方法進行擴展，編輯器可以自動生成簡單代碼。當然也可以對model.php新增方法。

 

 

2.2 control.php的擴展

對control.php的現有方法進行擴展時，會有是否重用代碼的提示

 

如果選擇“確定”的話則會生成一個繼承了該模塊control.php的類，擴展后的方法可以繼承該模塊的control.php的方法。否則的話，則對該方法進行重新定義。

同樣的也可以對control.php新增方法。

 

2.3 模板文件的擴展

對模板文件的擴展也有兩種方式，可以重寫一個模板文件覆蓋原來的。也可以寫一個鈎子腳本，對原來頁面做一下局部修改。

 

2.4 其他文件的擴展

對其他文件擴展時，將會顯示源文件的內容，可以當做擴展的參考。

 

2.5 對擴展文件的編輯

可以對ext目錄下的擴展文件進行編輯和刪除。

三、保存擴展文件

3.1 不必輸入文件名

對control.php的方法進行擴展和覆蓋模板文件時，文件名是一定的不必輸入文件名。

 

3.2 可以輸入文件名

像對model.php的方法擴展、對語言文件、配置文件等的擴展，如果不輸入文件名，則會以默認文件名保存，如果輸入文件名，則會以輸入文件名保存。

3.3 必須輸入文件名

像新增方法、新增頁面、新增鈎子、新增擴展等，則必須輸入文件名才能保存。

備注：

1、保存文件時，要保證程序有讀寫的權限。

2、如果文件名沖突，則不能保存，你可以更改保存的文件名或者勾選覆蓋重復文件選項。

3. 該編輯器還很簡陋，只是為方便擴展而建。可能還有很多問題，希望大家提出。

二次開發編輯器和翻譯功能限制使用說明

說明： 禪道11.7版本開始，因為安全因素考慮，把二次開發的編輯器和翻譯功能拿出來做為插件。

大家需要使用，可以到禪道官網--插件里下載安裝。

禪道插件下載地址： http://www.zentao.net/extension-browse.html

 

禪道從11.6版本開始，后台--二次開發--編輯器和后台--翻譯功能模塊，因為安全考慮，改為只能在 http://127.0.0.1:端口號 下訪問和操作。

下面給大家簡單說明一下怎么使用二次開發編輯和翻譯功能。

一、禪道用的是windows一鍵安裝包

可以直接登錄禪道安裝的機器，使用  http://127.0.0.1:端口號 訪問禪道，就可以到后台--二次開發--編輯器和后台--翻譯里正常訪問和使用該功能。

二、禪道服務器使用的是windows系統

可以遠程登錄禪道服務器，使用禪道服務器本機的瀏覽器，使用  http://127.0.0.1:端口號  訪問禪道。

這樣就可以 到后台--二次開發--編輯器和后台--翻譯里正常訪問和使用該功能。

三、禪道服務器使用的是Linux系統

使用 Linux系統做禪道服務器時，因為端口轉發或橋接等方式連接。即便訪問禪道的地址是   http://127.0.0.1:端口號   ，也會被判斷為當前訪問地址不是   http://127.0.0.1:端口號   ，而使用不了 后台--二次開發--編輯器和后台--翻譯的功能。

可以使用編輯器的SSH隧道來連接訪問禪道，這樣 訪問     http://127.0.0.1:端口號  時就可以使用 后台--二次開發--編輯器和后台--翻譯功能模塊。

1、連接禪道服務器主機

編輯器打開需要連接的禪道服務器主機，點擊屬性。

 

2、設置SSH隧道連接

目標端口請填寫訪問禪道時使用的端口號，設置好后，點擊確定。

然后點擊下面的連接。

備注：設置SSH隧道連接時，如果之前編輯器已經連接了該服務器，請先都斷開連接后，再設置。

 

3、訪問禪道

之前訪問禪道的地址為 http://127.0.0.1:10271 ，設置了SSH隧道連接后，禪道的訪問地址為   http://127.0.0.1:2222 。端口號要改為設置SSH隧道連接時的偵聽端口。

這樣訪問禪道，就可以使用翻譯和二次開發的編輯器功能了。

 

 

四、附錄

1、禪道二次開發編輯器的使用手冊： http://www.zentao.net/book/zentaopmshelp/147.html

2、禪道翻譯功能的使用手冊： http://www.zentao.net/book/zentaopmshelp/346.html

禪道項目管理軟件打包規范1.1版本

大家在二次開發過程中，好的功能也可以打包成插件和大家進行分享。我們整理了禪道項目管理軟件打包規范。

一、可以擴展的元素：

目錄	說明
bin	比如新增的命令行腳本程序。
config	比如可以對配置文件進行修改。
db	db目錄下面可以存放install.sql和uninstall.sql，分別對應安裝時需要執行的sql腳本和卸載時需要執行的sql腳本。
doc	這個插件相關的文檔。
lib	可以新增某一個類，或者對現有的類進行修改。
module	可以新增某一個模塊，也可以對現有的模塊進行功能擴展。
www	可以發布自己的風格。也可以對js文件進行修改。

二、doc目錄應當包含的文檔

doc目錄下面包含了插件的配置信息，按照語言進行存儲，比如英文版本的，存為en.yaml，中文zh-cn.yaml

插件的配置文件采用yaml格式，里面包含了插件的基本信息以及歷次版本的發布信息。共分為下面的信息：

可以參考：http://www.zentao.net/extension-viewExt-1-info-front.html

三、db目錄下面包含的文件：

db目錄下面可以包含install.sql和uninstall.sql。顧名思義,install.sql是當安裝插件的時候執行的sql語句，而uninstall.sql則是當卸載插件的時候需要執行的sql語句。這樣如果你的插件涉及到數據庫的改動，可以將相應的sql語句放在這兩個文件中，禪道的插件管理程序會自動來執行。

四、module下面的文件：

module目錄下面的文件，就按照我們的插件擴展機制 部署相應的目錄結構就可以了。

五、主配置文件的擴展

在實際過程中，可能會需要對全局的配置文件進行擴展，這種情況將擴展的配置文件放在zentao/config/ext/下面就可以了。

六、安裝和刪除的鈎子腳本

如果在安裝之前，安裝之后，卸載之前，卸載之后需要執行一些操作，可以建立一個hook目錄，然后分別在里面創建preinstall.php, postinstall.php, preuninstall.php, postuninstall.php，里面放上你所需要的代碼即可。

七、小結：創建自己的插件：

1. 確定插件的英文名，比如叫做hello。
2. 創建hello目錄。
3. 在hello目錄下面創建doc目錄。
4. 在doc目錄下面創建配置文件yaml文件：
5. 如果有涉及到數據庫的改動，在hello目錄下面創建db目錄，分別寫好install.sql和uninstall.sql
6. 如果需要鈎子腳本，創建hook目錄，創建 preinstall.php, postinstall.php, preuninstall.php, postuninstall.php。
7. 然后部署相應的擴展代碼。在hello目錄下面創建一個module目錄，然后將相應的模塊擴展代碼放在module下面。
8. 打包，使用zip格式將整個hello目錄打包成hello.zip，就可以了。

八、查看示例：

請看我們示例：http://www.zentao.net/extension-viewExt-1.html