禅道常用资料

禅道的目录结构

一、顶级目录结构：

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