EAS费用报销模块web二次开发指南

EAS 费用报销模块 Web 二次开发指南 EAS HR 系统部 作者 李大伟，贺鹏辉 整理 陈昕 导读 本文从头开始介绍了 EAS 费用报销 Web 表单的二次开发方法，同时也说明了开发环境的安装 和配置方法。可供机构开发人员对费用报销 web 表单进行二次开发时参考。 适用范围 EAS 费用报销模块 web 二次开发人员 请注意：本文件只作为产品介绍之用，不属于您与金蝶签署的任何协议。本文件仅包括金蝶既定策略、产品及功 能方面的信息，不能以本文件作为要求金蝶履行商务条款、产品策略以及开发义务的依据。本文件内容可能随时 变更，恕不另行通知。 目目 录录 概述概述.4 目的目的4 范围范围4 定义、首字母缩写词和缩略语定义、首字母缩写词和缩略语.4 环境准备环境准备.4 JDK安装安装 .4 PT环境准备环境准备.4 统一的统一的WEB开发目录开发目录 W:WEBDEV.4 统一开发工作区间统一开发工作区间 WEBDEV/WORKSPACE.4 W:WEBDEVAPUSICSTUDIO-5.1 为开发工具，双击为开发工具，双击STUDIO.CMD启动开发工具启动开发工具.5 更新和部署更新和部署 AOM.5 部署部署EASWEB.EAR.5 修改修改 W:EASSERVERSERVERDEPLOYEASWEB.EAREAS_WEB.WARWEB-INF 下下OPERAMASKS.XML.6 启动服务器，以协同办公费用报销单为例：可以通过启动服务器，以协同办公费用报销单为例：可以通过.7 新建新建 WEB 工程工程.7 新建新建 APUSIC标准工程标准工程.7 添加添加WEB模块模块.8 新建新建FACES页面页面.13 添加添加 APUSIC服务器服务器.16 运行我们的应用运行我们的应用.18 定义及发布元数据定义及发布元数据.19 实体的定义和发布实体的定义和发布.19 查询的定义和发布查询的定义和发布.19 生成生成 WEB 界面代码界面代码.19 设置设置WEB界面代码路径界面代码路径.19 生成生成WEB界面代码界面代码.20 添加库文件添加库文件.23 添加用户库添加用户库.23 添加添加WAF包包.23 添加业务逻辑类引用添加业务逻辑类引用.23 WEB 界面代码的修正界面代码的修正.25 * EDITBEAN.JAVA的修正的修正 .25 *EDIT.XHTML文件的修正文件的修正.25 *LIST.XHTML文件的修正文件的修正.27 部署及启动部署及启动 EAS WEB 应用应用 .27 部署部署 EAS WEB.27 PT环境下启动环境下启动 EAS 服务服务.27 二次开发应用二次开发应用.28 修改业务单元修改业务单元.28 发布业务单元发布业务单元.28 执行升级脚本执行升级脚本.29 搭建搭建WEB开发环境开发环境.29 修改修改WEB页面页面.29 修改修改MANAGEDBEAN.29 部署二次开发应用部署二次开发应用.30 常见问题常见问题.30 #MESSAGE* EL EXPRESSION 错误错误 .30 编辑界面单据体（分录部分）无法显示编辑界面单据体（分录部分）无法显示.30 如何检查调用类的物理路径如何检查调用类的物理路径.30 下载文件时会在线打开，且出现乱码（如何进行文件的下载）下载文件时会在线打开，且出现乱码（如何进行文件的下载）.30 表单编辑页中点击新增分录时出错表单编辑页中点击新增分录时出错.33 在在 EDITBEAN或或 LISTBEAN中，通过中，通过IBOSBIZCTRL设置了某个接口（如：设置了某个接口（如：IBOSBIZCTRL PRIVATE IDOCRECEIVE SERVICE;），但发现在使用该接口），但发现在使用该接口SERVICE时，时，SERVICE为为NULL.33 在在VIEW上找不到上找不到MANAGEDBEAN.33 按钮或者其他控件的状态被缓存，如单据查看时某按钮被置灰后，新增时按钮仍是置灰的。按钮或者其他控件的状态被缓存，如单据查看时某按钮被置灰后，新增时按钮仍是置灰的。.33 WEB 主界面开发方法主界面开发方法.33 编制编制JSP页面。页面。 .33 配置配置PORTLET模板信息。模板信息。 .34 PORTLET业务配置信息设置。业务配置信息设置。.34 PORTLET基础定义设置。基础定义设置。.34 页签配置页签配置.35 参考资料参考资料.35 概述概述 目的目的 根据标准 web 单据开发流程，描述以下内容： 环境准备 Web 工程的创建 元数据的定义和发布 Web 界面代码的生成 Web 界面代码的修正 EAS web 的部署和运行 二次开发应用 Web 主界面的开发方法 范围范围 适用版本：Kingdee EAS 6.0，Kingdee BOS 6.0 定义、首字母缩写词和缩略语定义、首字母缩写词和缩略语 AOM：Apusic OperaMask，金蝶中间件公司的 Web 开发框架 AAS：Apusic Application Server：金蝶中间件公司的 J2EE 应用服务器产品 Ext JS：一套基于 Java Script 的浏览器端 UI 组件库 环境准备环境准备 jdk 安装安装 jdk 要求 5.0 以上版本。 pt 环境准备环境准备 pt 搭建一个 gui 的开发环境。 统一的统一的 web 开发目录开发目录 w:webdev 统一开发工作区间统一开发工作区间 webdev/workspace 如图所示： W:webdevapusicstudio-5.1 为开发工具，双击为开发工具，双击 studio.cmd 启动开发工具启动开发工具 Apusicstudio 可以到 更新和部署更新和部署 AOM 可以到 /dist/aom/snap/binaries/获取 AOM 最新版本 部署部署 easweb.ear 修改部署文件 W:apusicdomainsserver1configserver.xml 加入 如图所示： easweb.ear 结构如图： 修改修改 W:easServerserverdeployeasweb.eareas_web.warWEB-INF 下下 operamasks.xml 开发那个项目将哪个项目的 jar 包配置项删掉。如开发协同费用报销就将 cp_bc_web.jar删除掉。 如图： 将从 cvs 上获得的或开发完成的 view (即 xXXX.xhtml)拷贝到 W:easServerserverdeployeasweb.eareas_web.war 将从 cvs 上获得的开发完成的 ManagedBean（即 XXXXBean）拷贝到 W:easServerserverdeployeasweb.eareas_web.warWEB-INFclasses 注：以上路径没有包含包名，拷贝时需要将自己加上包路径，如 cpbc 如图所示： 启动服务器，以协同办公费用报销单为例：可以通过启动服务器，以协同办公费用报销单为例：可以通过 http:/localhost:6888/easweb/cp/bc/bizAccountBillList.jsf 访问。 新建新建 web 工程工程 由于 WAF 目前混合使用 Apusic Studio（Web UI 开发）与 BOS Studio（Web 元数据定义与框架代 码发布） ，所以是先进行 web 工程的新建还是先进行 EAS 元数据的定义，我们并没有严格的限制， 可根据个人熟悉程度决定。 新建新建 Apusic 标准工程标准工程 我们使用 Apusic 作为我们的 web 容器，所以我们从新建 Apusic 标准工程开始我们的标准单 据开发的旅程。 在 Apusic studio 中点击“文件新建Apusic 标准工程” ，如下图： 包含以下几个点的定义：项目名称，空间及存储位置选择，服务器选择，域选择及 J2EE 版本的选择，输出文件夹。 我们可以在此进行本地服务器的新建也可以在后续过程中添加服务器，为不影响新建流 程的顺畅，我们将在后续步骤中单独描述。 J2EE 版本的选择应该引起注意，我们须要选择 5.0 以上的版本。 定义好上述内容后点击完成，我们可以在打开包视图查看工程目录结构如下： 添加添加 web 模块模块 点击新建工程根目录，右键选择“新建web 模块”： 打开对话框如下： 需要注意源文件夹（用来存放源代码）及 web 内容文件夹（用来存放页面，配置信息等资源文件） 。点击下一步： EAS web 应用框架建立在 AOM 基础上，所以我们不得取消“支持 AOM”的选项。AOM 的配置 中需要注意 url 后缀的配置，该配置意味该后缀的请求都将由 AOM 处理。我们按习惯修改成 *.jsf，定义好以后我们将可以在 web.xml 中发现相应的配置内容： Faces Servlet *.jsf 完成上述步骤，点击完成 web 模块的新建，我们发现工程目录下增加了 src 及 WebContent 目 录： 新建新建 faces 页面页面 选择“文件新建Faces 页面”： 选择是否生成 managebean，以及 managebean 设置，如果只是新建一个静态视图，那么可以 不进行 managebean 的定义。 点击完成页面新建。 添加添加 Apusic 服务器服务器 前面在新建工程中已经提到服务器的选择，在此将对服务器新建做进一步描述。在新建或增 加服务器之前请确保已正确安装了 Apusic 服务器，Apusic 服务器的安装再次不再累述。 打开 Apusic 服务器列表视图，在视图中点击右键，并选择增加服务器： 添加服务器后我们需要为我们的应用指定对应的 Apusic 服务器，打开工程属性对话框如下图： 运行我们的应用运行我们的应用 服务器启动过程中我们可以在控制台看到相应信息，部分截图如下： 可以看到服务器已成功启动，我们定义的上下文根目录是 mydemo，接下来我们使用 http:/localhost:6888/mydemo/hello.jsf 进行访问，结果如下图： 至此，web 工程的新建完成。 定义及发布元数据定义及发布元数据 元数据的定义在此特指单据实体及查询的定义，因为只有实体及查询才能发布成 web 界面，生成 web 界面代码。实体及查询的定义与非 web 应用中实体及查询的定义一样，没有差别。 实体的定义和发布实体的定义和发布 与一般实体的定义和无差别 查询的定义和发布查询的定义和发布 与一般查询的定义和无差别 生成生成 web 界面代码界面代码 设置设置 web 界面代码路径界面代码路径 生成 web 界面代码前我们需要对生成代码的存放位置进行设置，在 BOS Studio 中通过“窗口 首选项”进入首选项配置页，左侧树形菜单中选择“BOS生成 web 界面代码”： 将代码路径设置成我们 web 工程的源文件路径，将页面路径设置成我们 web 工程的 web 内 容文件夹路径，点击确定完成设置。 生成生成 web 界面代码界面代码 接下来我们可以生成 web 界面代码：选择要生成界面代码的实体或查询，点击右键并选择 “生成 web 界面代码”： 回到 Apusic studio 并刷新工程，我们可以看到工程目录如下图： Comment p1: 后续将做个表格，对生 成的代码及页面文件进行说明 增加了相应的页面文件及逻辑代码。通常一个实体通过上述步骤会生成以下几个文件： 编辑逻辑 managebean 及分录 bean 及相应属性文件： 编辑页面文件： 查询元数据生成 web 界面的过程与实体生成 web 界面的过程一样，只是结果文件不同： 列表逻辑 managebean 及相应属性文件： 序时薄页面文件： 至此，web 界面代码的生成过程已经完成。至于生成的代码内容大家可以打开相应文件细看， 我们也将在后续部分中插述部分重要内容。 添加库文件添加库文件 添加用户库添加用户库 发布 web 界面代码并刷新 web 工程后我们的 web 工程出现了诸多错误，让我们看看究竟是什么 原因引起了错误：发布的界面代码找不到依赖的业务逻辑类。我们需要添加用户自定义库。在 web 工程的构建路径中引入 W:easdev 下的 boslib_for_eas.userlibraries 和 easlib_for_eas.userlibraries 添加添加 WAF 包包 从 W:easServerserverdeployeasweb.eareas_web.warWEB-INFlib 下拷贝以下文件到工程目 录的WebContentWEB-INFlib 中，当然你也可以通过在构建路径中引入外部 jar 包的方式配 置。 添加业务逻辑类引用添加业务逻辑类引用 这里指的业务逻辑相关类即发布元数据时生成的类文件。 我们有多种方式去引用这些类，由于业务的需要，我们可能需要修正这些类中的部分代码， 所以打包加载的方式有些不方便，故建议在构建路径的源代码一项中添加关联目录： 选择元数据发布的源代码目录。 Web 界面代码的修正界面代码的修正 * EditBean.java 的修正的修正 在 EditBean 的 pageOnload()中有类似语句： 我们须要修正为： *Edit.xhtml 文件的修正文件的修正 将#messages*形式的表达式都直接换成相应的信息，如 #messagescreator替换为creator 或“创建人”。 将messagesentries.seq替换为entries_seq 或其他。 将修改为 去除了多余字段。 将重新定义分录操作界面： 把 biz:billEntryActions 标签的内容替换为分录操作的自定义部分，可以如下： 修正前： 界面效果（点击操作按钮出错，且无具体提示信息）： 修正后： 界面效果（新增）： *List.xhtml 文件的修正文件的修正 将#messages*形式的表达式都直接换成相应的信息，如#messagescreator替换为 creator 或“创建人” 。 将 messagesentries.seq替换为 entries_seq 或其他。 部署及启动部署及启动 eas web 应用应用 部署部署 EAS WEB EAS web 应用必须与 EAS 应用服务（非 web）场景同时使用， Eas 统一的应用部署路径为 W:easServerserverdeployeas.eareas_web.war 访问路径 http:/localhost:6888/easweb，我们需要做 以下几个步骤的部署： 拷贝工程下的 scm_channel_web webWebContentWEB-INFclasses 到 W:easServerserverdeployeas.eareas_web.warWEB-INFclasses 拷贝 scm_channel_web webWebContent 下的相关文件 到 W:easServerserverdeployeas.eareas_web.war 该部分的拷贝比较繁琐麻烦，我们提供了相应的批处理文件进行处理。 Pt 环境下启动环境下启动 EAS 服务服务 运行 W:easServerserverprofilesserver1bindebugserver.bat 访问单据编辑页http:/localhost:6888/easweb/mydemo/phInWarehouseBillEdit.jsf 访问 http:/localhost:6888/easweb/mydemo/phInWarehouseBillList.jsf 二次开发应用二次开发应用 修改业务单元修改业务单元 打开金蝶 bos，切换到金蝶 bos 业务建模透视图 打开需要二次开发修改的单据，使用选用板添加字段，以报销单为例，如图所示： 发布业务单元发布业务单元 在费用报销单界面里，单击右键，选择单据信息，确认不生成生成实现类，如图所示： 在菜单选择费用报销单，单击右键，单击发布业务单元/报表即可。 执行升级脚本执行升级脚本 在管理控制台或直接数据库中执行升级脚本，将新加字段添加到数据库相应的数据表中。 搭建搭建 web 开发环境开发环境 按照 2、3、4、5 步骤搭建 web 开发环境 修改修改 web 页面页面 将 easServerserverdeployeasweb.eareas_web.warcpbcbizAccountBillEdit.xhtml 的页面 内容,覆盖步骤 5 中生成 bizAccountBillEdit.xhtml 页面。 在页面间将新添加的字段绑定，如下： 修改修改 managedBean 将 easServerserverdeployeasweb.eareas_web.warWEB-INFlibcp_bc_web_jar 解压缩，反编译 BizAccountBillEditBean.class,将内容覆盖步骤 5 生成的代码。 修改代码逻辑 部署二次开发应用部署二次开发应用 将修改的 bizAccountBillEdit.xhtml，覆盖 easServerserverdeployeasweb.eareas_web.warcpbcbizAccountBillEdit.xhtml 将修改的 BizAccountBillEditBean 后编译生成的 BizAccountBillEditBean.class 重新拖入 easServerserverdeployeasweb.eareas_web.warWEB-INFlibcp_bc_web_jar 包中， 替换原来的 class 文件。 常见问题常见问题 #message* EL Expression 错误错误 目前不支持该种表达式显示信息，我们需要替换该表达式为实际要使用的信息，如： 将#messages*形式的表达式都直接换成相应的信息，如#messagescreator 替换为creator。 同样，我们需要将messagesentries.seq替换为entries_seq 或其他。 编辑界面单据体（分录部分）无法显示编辑界面单据体（分录部分）无法显示 将编辑页面的将修改为 如何检查调用类的物理路径如何检查调用类的物理路径 在调试过程中，在 Display 试图中如下调用方式： this.getClass().getResource(/com/kingdee/eas/cp/bc/web/TravelAccountBillListBean.class) 下载文件时会在线打开，且出现乱码（如何进行文件的下载）下载文件时会在线打开，且出现乱码（如何进行文件的下载） AOM 使用原生态 AJAX 后文件下载出现该问题的解决，且不论在服务端中对 response 做何 处理。如果你去除 f:view 中 renderKitId=AJAX的设置，且保证不会影响页面其他功能，那当然 是最好的解决。此外可以通过重定向到下载页进行下载。 解决 AOM 的文件下载问题有两种方式，由于我们的实际应用场景中不是已存在文件的下载，需 要与数据库等的交互，中断 jsf 生命周期的方式不可取。故我使用了重定向新页面进行下载的方 式，即在需要引入引出功能的页面上加入 iframe 框，并引用文件下载页面资源： 在单一文件下载页面中不使用 AOM 的原生态 ajax： 下载效果如下： 点击引出模板，将出现下载页面如下图： 表单编辑页中点击新增分录时出错表单编辑页中点击新增分录时出错 首先点击增加分录按钮时出错： #phdemo.PhStockBalanceBillEntryBean.appendRow: /phdemo/phStockBalanceBillEdit.xhtml 117,65 action=#phdemo.PhStockBalanceBillEntryBean.appendRow: java.lang.NullPointerException at _expression_(0)。 解决办法：在w:editDataGrid 下 增加 jsvar=editEntryGrid 相关内容请查看 operamasks 文档： onents-widget-editDataGrid.html 在在 EditBean 或或 ListBean 中，通过中，通过IBOSBizCtrl 设置了某个接口（如：设置了某个接口（如：IBOSBizCtrl private IDocReceive service;），但发现在使用该接口），但发现在使用该接口 service 时，时，service 为为 null 这时，需要检查 APUSIC 运行环境中的 metas/entity_perties 是否存在该 service 对 应的 entity. 因为，在发布元数据时，有可能没有将 eneity_perties 发布到 apusic/metas，或没 有将 entity 加入到 entity_perties 文件中 在在 view 上找不到上找不到 managedBean 检查 managedBean 的目录和 bean 的名称是否符合规范， 如果包名不一致或者文件名不一致都回出现此问题， 如 HR 的绩效模块（performance） ，新增一个 View 时， xhtml 命名为 MyPerf.xhtml, 必须存在 WebContent/hr/performance 下， 而且对应的 ManagedBean 为 com.kingdee.eas.hr.performance.MyPerfBean. 按钮或者其他控件的状态被缓存，如单据查看时某按钮被置灰后，新增时按钮仍是置灰的。按钮或者其他控件的状态被缓存，如单据查看时某按钮被置灰后，新增时按钮仍是置灰的。 要在置灰状态的地方，将不符合置灰条件的按钮再显示的变亮。 因为 managedBean 可能定义为 session 的，所以存在会缓存状态的可能。 Web主界面开发方法主界面开发方法 编制编制 jsp 页面。页面。 在目录 W:easServerserverdeployeas.earcp_web.warhtmlportlet 新建一个目录，并在新 建目录下创建一个 jsp 文件。 内容为： 注：src=./easweb/cp/index.jsf就指向 portlet 的内容页。 配置配置 portlet 模板信息。模板信息。 打开文件 W:easServerserverdeployeas.earcp_web.warWEB-INF portlets.xml 添加内容如下： 43 协同办公 view portlet.cp_index Portlet 业务配置信息设置。业务配置信息设置。 打开文件 w:easserverdeployeas.earcp_web.warWEB-INFtiles-defs.xml 添加内容如下： Portlet 基础定义设置。基础定义设置。 通过上述配置后，还需要通过 EAS 管理控制台执行如下脚本，在数据库中插入一条记 录，sql 语句如下： Insert Into T_Porta