EKP表单自定义宝典

文档控制/Document Control
修改记录
日期作者版本备注
2010/8/31 叶中奇 1.0 第一个版本
审阅人
分发
目录
第一章导读............................................... 错误！未定义书签。

1.1从什么地方开始.................................. 错误！未定义书签。

1.2相关资料........................................ 错误！未定义书签。

第二章快速入门........................................... 错误！未定义书签。

2.1第一次使用表单自定义............................ 错误！未定义书签。

2.2表单自定义可以做什么............................ 错误！未定义书签。

2.3表单自定义可以用在什么地方...................... 错误！未定义书签。

2.4表单自定义不能做什么............................ 错误！未定义书签。

第三章使用表单自定义..................................... 错误！未定义书签。

3.1使用表单自定义工具.............................. 错误！未定义书签。

3.2表单自定义的版本功能............................ 错误！未定义书签。

3.3理解表单自定义的数据存储........................ 错误！未定义书签。

3.4使用表单自定义的高级控件........................ 错误！未定义书签。

第四章扩展表单自定义..................................... 错误！未定义书签。

4.1扩展表单自定义中的存储事件...................... 错误！未定义书签。

4.2扩展表单自定义工具中的控件（未展开说明）........ 错误！未定义书签。

第五章在应用中部署表单自定义............................. 错误！未定义书签。

5.1部署说明........................................ 错误！未定义书签。

5.2部署表单模板.................................... 错误！未定义书签。

5.3部署表单主文档.................................. 错误！未定义书签。

5.4部署表单存储映射................................ 错误！未定义书签。

第一章导读
1.1 从什么地方开始
✓若您对表单自定义完全不了解，建议您先查阅“快速入门”章节。

✓若您了解表单自定义的基本概念，想使用表单自定义来完成您的业务需求，那建议您查阅“使用表单自定义”的章节。

温馨提醒：“使用表单自定义”的章节将由浅入深，告诉您如何使用表单自定义，当然，深一点的内容需要有一定的编程基础。

✓当您发现现有的表单自定义满足不了您的业务需求的时候，您期望做一些扩展，那您可以查阅“扩展表单自定义”章节。

温馨提醒：该章节需要有一定的EKP-J编程基础。

✓若您期望在一个新的模块能使用表单自定义的功能，那请查阅“在应用中部署表单自定义”章节。

温馨提醒：该章节需要有一定的EKP-J编程基础。

✓若您是一个表单自定义的使用者，一个非开发人员，建议您查阅本文的所有案例，了解通过表单自定义可以做到什么程度，若您是一个开发人员，建议您通读全文。

1.2 相关资料
本文涉及到公式定义器的相关知识，请参阅详见《公式定义器宝典》
涉及到流程部分的知识，请参阅详见《流程宝典》
第二章快速入门
2.1 第一次使用表单自定义
我们在费用报销的时候经常会碰到一个这样的需求，当报销金额大于10000元的时候，需要高一层的领导进行审批，然后再交给财务审批。

在不开发新模块的情况下，我们一般会用审批流程来完成这个需求。

然而，由于我们需要在流程里面获取到报销金额的字段，所以我们不能采用RTF作为审批的内容，而借助表单自定义的功能，可以很好地解决该问题。

自定义表单定义：
打开审批流程模块模板定义的界面，切换到审批内容标签，我们可以看到表单自定义工具：
操作按钮区
内容编辑区
我们很快就可以定义出这样的界面：
由于报销金额是数字类型，所以我们在字段的属性中，设置“数据类型”为“数字”。

流程定义：
在流程定义里面，我们增加了一个条件分支的节点，通过定义公式：“$报销金额$>10000”作为条件分支的条件公式，实现当报销金额大于10000元的时候，需要高一层的领导进行审批，然后再交给财务审批的需求。

2.2 表单自定义可以做什么
在普通的应用中，每种类型的文档（或记录）都会有自己固有的属性（如标题、创建时间等），若期望添加而外的属性，就必须通过修改代码的方式实现，而EKP-J的表单自定义的功能就是为了打破该限制而产生的。

通过表单自定义，我们可以不通过修改代码，灵活得添加额外的属性，并对界面进行排版。

而这些额外添加的属性，可能会被使用到其它的地方，如流程的判定、统计查询等，因此这些数据的存储必须是结构化的（而不是像RTF一样全部保存）。

此外，客户可能已经知道针对不久的将来，当公司制度发生改革的时候，某些特定表单的内容也会随之改变，客户期望这些表单是“活”的，是可以自己配置的。

而这个时候，表单自定义将是客户需求的最好解决方案。

2.3 表单自定义可以用在什么地方
目前在我们的系统中最常使用表单自定义的是审批流程模块，在该模块中，用户根据不同的业务场景，定义不同的表单，满足各种业务需求。

另外，比如公文模块，大部分客户对公文模块的需求基本上都一致，许多基础的字段基本上都一致，后台的业务逻辑也大同小异，最不一样的地方可能就是公文的展现方式，每个企业可能会有自己的公文表单展现习惯，或者有几个定制化的字段。

若我们可以在公文模块中启用表单自定义的功能，就可以屏蔽掉企业间的差异，用一个标准的公文模块通杀所有企业的公文需求。

还有HR的员工信息等，各个企业都会有一些差异化的字段，这也是一个表单自定义很好的实战场景。

当然，您可以根据您的实际业务需求，把表单自定义“发扬光大”。

2.4 表单自定义不能做什么
从前面的用途我们基本上发现，目前我们的表单自定义都是依附于某个模块实体的（比如审批流程、公文等），通过表单自定义的功能，我们可以在上面灵活地进行属性的扩充，但它并不包含增删查改的功能，也不包含视图展现等，更没有在上面直接部署机制。

所以我们无法通过自定义表单直接“开发”出一个全新的模块。

该限制可能在将来的版本中会有所改动，但至少现在的版本是无法这样做的。

第三章使用表单自定义
3.1 使用表单自定义工具
我们在审批流程的模块–模板设置–审批内容标签中，可以找到表单自定义的工具界面，如下图：
操作按钮区
内容编辑区3.1.1表单自定义使用的小窍门
1、使用百分比定义控件宽度。

当我们定义一个控件的宽度的时候，通过拖拉的方式定义，单位往往是像素，但这样定义往往适应不了终端用户的屏幕分辨率，就会导致宽屏终端显示内容太少，或者窄屏用户出现横向滚动条等现象，为了解决该问题，您可以在属性框中按百分比定义宽度（如：“90%”），这样就可以适应各种终端显示器了。

2、选择界面控件。

通过Ctrl+左键，可以选择多个控件。

当是界面的控件很多，难以点选的时候，还可以点击展现控件树，在控件树中快速
定位到相应的控件。

3、快速创建多个同类型的控件。

若需要创建一个单行文本输入框，我们需要在操作按钮区中选择了单行文本输入框，然后点击内容编辑区。

当我们期望创建多个输入框的时候，我们可以在操作按钮区中选择单行文本输入框，然后按住shift键不放，在内容编辑区的不同地方点击，这样就可以连续创建多个编辑框了，若期望取消，按下Esc就可以了。

4、拷贝整个表单。

若我们前面做好了一个表单，我们可能期望在一个新的表单中使用原来的表单，然后在新表单里面稍微修改一下，做为新的表单使用。

显然，界面里面一个个控件的拷贝太繁
琐，我们可以这样操作。

点击显示高级控件：，旁边会显示“编辑表单HTML
代码”的按钮，点击该按钮，在编辑区域里面就会显示整个表单的HTML代码，这时候，我们可以将所有代码拷贝到另外一个表单中使用，拷贝完毕后，记得点击“设置HTML”
按钮，使您拷贝的HTML代码生效。

注意：除非您对表单的HTML代码非常熟悉，否则不建议您直接通过修改HTML代码的方式修改表单。

3.1.2控件的属性
在我们双击控件的时候，会弹出控件的属性窗口，下面是一个单行文本输入框的属性：
在属性界面中，需要注意的有几个地方：
1、数据类型
表单中每个被存储的数据项都是有数据类型的，数据类型对于后面的公式计算等方面起
看完了这张表以后，您可能会对日期时间型（Date）、组织架构对象类型（SysOrgElement）的概念还比较模糊，没关系，在您往后的使用中，我们会详细地介绍它：若您需要在公式定义器中使用，那《公式定义器宝典》会有详细描述；若您在扩展表单自定义的章节中使用它，那该章节也会为您进行描述。

2、初始值
您可以在初始值输入框中，输入该字段的初始值。

直接手工输入的内容不进行公式计算，若期望初始值通过公式来进行计算，请点击“公式定义”的按钮，在弹出框中输入公式，公式输入完毕后，属性框中的初始值被锁定，不能直接输入，同时下面出现“更新时重新计算”的选项。

若您期望修改为非公式计算的模式，那请再次点击“公式定义”按钮，将公式清空后即可。

公式定义器的使用，详见《公式定义器宝典》。

初始值的计算是有顺序的，顺序是按照界面从上到下，从左到右的顺序执行。

案例1：初始值计算顺序
我们在表单自定义中定义了以下几个字段：
在实际运行中，总额1的初始值计算结果为0（原因是由于在计算总额1的时候，单价和数量的初始值并未初始化），总额2的计算结果为200。

案例2：更新时重新计算
在案例1中，我们可能期望总额是不能让用户自己输入的，而且当单价和数量发生改变的时候，需要重新计算总额这个字段，那我们就可以在总额字段的属性框中将该字段设定为“只读”，而且是“更新时重新计算”
3、ID
ID是该控件的唯一标识，修改时请谨慎，否则可能导致引用地方的错误。

案例1：字段改名对公式的影响
问：我在流程中使用了公式：“$金额$>1000”，后来我把“金额”这个字段名称修改为了“报销金额”，可是我忘记修改了流程中的公式，这时公式的计算是否还能正常运行？
答：公式计算时候引用的是字段的ID，只要ID没有发生改变，公式是能够正常运行的。

但在流程定义的界面中，公式显示的地方可能还是出现“$金额$”这个变量，这只是显示没有更新而已，重新打开公式定义器的页面就会自动更新名称。

但是若您把金额这个字段删除了，那公式运行时就会报错。

案例2：更换控件的展现形式
问：我开始用单行文本输入框定义了一个报销内容的字段，可用了一段时间后，发现单行文本输入框太小了，我想把它换成多行文本输入框，我该如何操作才能兼容以前的数据显示？
答：若您直接删除了单行文本输入框，然后再添加一个单行文本输入框，这个时候系统会认为这两个是不同的字段，所以旧数据是无法显示在新的多行文本输入框中。

要解决该问题，您可以先将单行文本输入框的ID记录下来，再删除单行文本输入框，创建多行文本输入框后，将原来的ID写入到多行文本输入框中，这样系统就会认为这两个字段是同一个。

3.1.3控制表单字段级权限
在一个标准的EKP产品模块中，主文档的数据基本上都是由起草人进行所有字段的信息输入，审批人若有“编辑主文档”的权限，那他就可以进入编辑页面，对文档字段进行修改，但往往在审批过程中，需要控制到字段级的权限。

下面举个员工转正申请的例子说明表单的权限。

3.1.3.1 案例需求
表单内容大概定义如下：
我们需要实现申请人能填写“申请人填写”部分内容，流程中的“部门经理审批”节点处理人可以填写“部门经理填写”部分内容，流程中的“HR经理审批”节点处理人可填写“HR 经理填写”部分内容。

另外，我们还期望HR经理填写的意见，人力资源部和总裁办的所有人可以查阅，其它人不可查阅。

3.1.3.2 案例实现
第一步：插入权限区段
为了实现这个需求，我们需要插入权限区段，将特殊权限的区域放入权限区段中。

插入
后的表单的样子如下：
注意上图的红色小方块就是权限区段的作用范围。

其中，申请人填写部分，由于跟标准的权限一致，所以可以不设置权限区段。

第二步：设置默认权限
定义好区段后，点击显示权限设置按钮，进入权限设置界面：
场景说明：
默认权限：除起草节点外，所有的节点都默认使用“默认权限”的设定，流程审批通过以后也使用“默认权限”的设定。

流程场景-起草节点：该场景下，所有权限区段默认都为编辑权限。

由于我们期望HR 经理填写的意见，人力资源部和总裁办的所有人可以查阅，其它人不可查阅，所以我们可以点击HR 经理意见区左边的第一个小图标，设置该区段的查看人为人力资源部和总裁办。

第三步：设置起草节点的权限
需求：起草节点不能修改“部门经理填写区”和“HR 经理填写区”的内容。

操作：切换到“流程场景 – 起草节点”场景，将所有区段设置为阅读权限，如下图： 小技巧：在流程场景中，权限区段会出现第三个小图标：随默认权限。

由于这几个区段的默认权限都是阅读权限，所以我们可以将第三个图标点亮，这样，将来修改默认权限的时候，起草节点的权限也会随之改变，减少维护工作量。

第四步：设置“部门经理审批”节点权限
需求：部门经理可以填写“部门经理填写区”的内容。

操作：切换到“流程场景 – 部门经理审批”场景，将“部门经理填写区”的权限修改为编辑。

第五步：设置“HR 人事经理审批”节点权限
需求：HR 经理可以填写“HR 经理填写区” 和“HR 经理意见区”的内容。

操作：切换到“流程场景 – HR 人事经理审批”场景，将“HR 经理填写区”和“HR 经理意见区”的权限修改为编辑。

3.1.3.3 案例总结
从上面的案例，总结一下权限设置的思路：
1、 在EKP 的标准应用中，所有的字段都是起草节点可编辑，审批节点不可编辑。

2、 即使您插入了一个权限区段，这个权限区段默认的设置也遵循上一条规则。

3、 您可以通过切换场景的方式，对特殊的场景加以描述，满足实际的需求。

如切换到起草
节点场景，将区段的权限设定为阅读，切换到某个审批节点场景，将某个区段设定为编辑。

点击这里可以切换场景
点击这里控制阅读状态的可访问权限，针对所有场景生效 点击这里切换本场景下的隐藏/阅读/编辑权限
双击这里可以修改区段名称
另外：
1、通过修改“默认权限”的场景，您可以修改所有场景的默认权限状态，包括流程结束后
的状态。

2、通过修改可阅读者，您可以限制某个区段的可阅读者范围（为空则不约束可阅读者范围），
可阅读者仅仅是对阅读权限的扩充，编辑和隐藏权限不受此范围影响。

可阅读者将作用于所有的场景。

3、权限区段可以控制单个字段（如：“HR经理意见区”），也可以控制整个表格（如：“HR
经理填写区”）。

4、权限区段是可以进行嵌套的，在上面的案例中，“HR经理意见区”就嵌入在了“HR经理
填写区”里面，若“HR经理填写区”不可见，那“HR经理意见区”也相应的隐藏了，但“HR经理填写区”一旦可见，那“HR经理意见区”的具体权限就由该区段的设置决定。

3.1.3.4 明细表的权限控制
我们来看两个例子：
案例1：
由于明细表的行是动态添加的，所以当权限区段设定在某个字段的时候，该权限将扩展到明细表的该列的所有同类字段。

从上面的案例看，您可以编辑明细表中所有行的“采购数量”字段。

案例2：
同样的明细表，但这次我们把权限区段扩展到了整个明细表，这时候，您除了可以编辑明细表的所有字段外，还可以进行增加、删除、移动行的操作。

3.2 表单自定义的版本功能
当您对一份已经定义好的表单进行了修改，再次保存的时候会弹出以下提示框：
虽然版本号没有在界面中进行体现，为了描述的方便，我还是加上版本号进行说明。

假如该表单第一次保存的时候，版本号为V1，然后进行了一次修改，选择了保存为新版本，这时
当然，以后新建的文档都会基于V3创建。

举个例子：
我们在自定义表单中定义了一个名字为“金额”的字段，然后创建了一份文档A，接下来我们对表单进行修改，将“金额”字段修改为“报销金额”，这时候，若我们执行的操作是“保存为新版本”，那打开文档A看到的还是“金额”这个名字，但若我们执行的操作是“保存为原版本”，那打开文档A看到的就是“报销金额”这个名字。

一个不能保存为原版本的案例：
我们在自定义表单里面定义了一个名字为“金额”的字段，由于一开始的疏忽，所以将金额的字段设置成了字符串类型，结果在创建文档的时候，不少用户可能就在金额字段里面直接写入了“10万”、“10万元”这样的数据。

后面我们发现这个金额字段无法用于计算，于是我们期望把金额字段修改为数字类型，在输入框后面，我们再加了个“万元”作为单位，提
醒用户的输入，若此时保存为原版本，那系统在打开旧文档的时候，会将“10万”这样的数据转换成数字类型，这种转换明显是无法成功的，系统只能抛出错误，在这种情况下，只能通过“保存为新版本”方式进行保存。

综上所述：
当您期望所做的修改对于旧文档生效的时候，执行“保存为原版本”的操作，否则执行“保存为新版本”的操作，然而当您对数据进行了类型变化的时候，建议还是“保存为新版本”，以便兼容旧数据。

3.3 理解表单自定义的数据存储
温馨提醒：本章节内容需要有一定编程技术。

3.3.1表单自定义数据存储方式介绍
在默认的情况下，表单的数据将以XML（详见，存储到主文档的表中。

这种存储方式虽然为可以保证表单的变动不会影响到数据库表结构，但同时也带来了查询的困难。

具体的内容详见
为了解决查询的问题，表单自定义提供了另外一种存储的扩展：表单数据映射（详见，从而解决了数据的查询问题。

表单数据映射是应查询的需求而产生的，所以加了与EKP-J同一数据库的限制。

为了突破这个限制，系统还提供了另外两种扩展：表单存储事件（详见4.1章节）和流程机器人节点（详见《流程宝典》相关章节），这两种方式可以通过编程或写SQL语句的方式，往异构系统或其它数据库中写入表单数据。

其中表单存储事件是随表单保存触发的，必须通过编程方式实现；流程机器人节点则在流程流转过程中触发，适用于在某种特定条件下写入数据的场景，流程机器人节点可以使用编程或SQL语句方式，往其它系统中写入表单数据。

3.3.2默认存储方式：XML
表单自定义的数据始终会在主文档表中一个大文本字段中以XML的格式保存。

为了方便数据的读写，系统提供了“，屏蔽了对XML数据操作的复杂性，具体的操作可参阅“扩展表单自定义中的存储事件”章节的案例。

3.3.3表单数据映射
前面我们已经知道，表单数据映射是为查询而产生的需求。

通过表单映射，我们可以方便地通过SQL语句，查询到表单自定义中的数据，并进行统计分析。

此外，EKP-J将来会推出自定义表单数据的查询功能，可以查询到表单中进行了数据映射的字段。

什么样的数据适合做数据映射？
一般的，当我们需要进行查询统计的数据，建议进行数据映射。

比如：报销总额、所属区域等。

对一些描述性的字段，如：出差原因等，不建议做数据映射。

虽然数据映射可以方便查询，但一旦将数据写入到数据库表中，就会受到数据库的字段类型、长度等约束，为数据的修改带来很大的困难，所以建议针对“合适”的字段进行映射，对于可能经常发生变动的字段，不做数据映射。

如何做数据映射？
案例：将一个项目报销单的所有字段进行数据映射。

报销单如下：
其中，项目成员是多值字段，是多对多的关系。

步骤：
1、我们得在数据库中创建表，由于上面的表单中有明细表，还有一个多对多的字段，所以
我们需要创建三张表来进行数据映射，表结构如下：
报销明细表：cf_project_cost_detail
体操作步骤略。

整个操作中比较麻烦的是建表的动作，上述的案例中，已经包含了字符型、数字型、日期型、组织架构（单值、多值）、明细表字段的建表。

在后续的流程表单版本中，会提供自动创建表结构的功能，您只需要在IE界面里面填写表名和字段名，系统会自动帮您在数据库中创建相应的表结构。

由于数据库对字段的类型和长度的管理非常严格，删除字段、修改字段类型或长度这些操作可能会导致数据的丢失问题，所以系统不提供删除字段、修改字段类型或长度的功能，若需要执行这些操作，只能是到数据库中直接操作数据库了。

3.4 使用表单自定义的高级控件
3.4.1使用前端计算控件
前端计算控件一般用来做前端的简单计算，如：总额=单价*数量，当单价和数量发生改
变的时候，总额将马上重新计算。

虽然前端计算控件的公式跟公式定义器非常类似，但相比起公式定义器来说，前端计算控件的功能要弱很多：参与计算的值只能是日期型和数字型的值（对于日期型的数据，系统会自动转换成毫秒数），而且返回的结果也只能是数字类型的值。

但由于前端计算控件能即时地将运算结果展现给最终用户，而公式定义器只能在数据提交后才能计算，所以前端计算控件给最终用户带来了更好的体验。

前端计算控件的语法完全是JavaScript的语法，不过即使您对JavaScript语法不熟悉，您同样可以使用里面的简单功能。

毫秒，再转换为天就可以了。

案例2：下面是一个采购申请单的样例，使用了明细表控件。

其中：小计=单价*数量，总额为所有小计的总和。

要理解这两个公式，首先得理解运行的上下文。

第一个公式，小计字段是在明细表里面的，所以“$明细表1.单价$”的值取的是同一行记录中的单价字段，是单值。

第二个公式，总额字段是在明细表外面的，所以“$明细表1.小计$”的取值不是针对单行记录而言，是针对所有记录而言，是多值。

故通过“$列表.求总和$()”函数可以将所有的小计进行求和。

这个案例摘自《公式定义器宝典》，其实前端计算控件的语法和原理基本上一样，只是小计和总额的控件换成前端计算控件而已。

案例3：表单中有个分数的字段，期望通过分数自动计算出等级，等级和分数的对应关系为：90~100：等级1
80~90：等级2
60~80：等级3
40~60：等级4
40以下：等级5。