简介： IBM Lotus Forms 是 IBM 推出的电子表单解决方案，用于自动化基于纸质的流程，减少处理时间和出错概率，提高流程处理效率。其中，Webform. Server 和 Viewer 作为用于展现表单的产品，为用户提供了在桌面上和浏览器中查看和操作表单的功能。除此之外，这两个产品还提供了 JavaScript. API，用于 HTML 页面简单方便地与 XFDL 表单进行交互，大大提高了 Lotus Forms 二次开发的速度。
概述
JavaScript. API 是用于通过编程与 Web 页面中嵌入的 XFDL 表单交互的一组工具。通过 JavaScript. API，可以把一个已存在的静态表单转变为交互式的动态表单，非常容易地将 Lotus Forms 与其他应用集成。展示在 IBM Lotus Forms Viewer 和 IBM Lotus Forms Server – Webform. Server 中的表单都可以使用 JavaScript. API 进行控制和操作。JavaScript. API 允许我们使用熟悉的 JavaScript. 工具创建 HTML 页面，与现有的 XFDL 表单进行动态交互，使用脚本在表单中插入或修改数据以及从表单中提取数据。
可以使用 JavaScript. API 直接访问整个表单及其所有元素节点。JavaScript. API 提供了操作表单中的输入框等控件的功能。可以从嵌入 Web 页面中的 XFDL 表单中提取信息，使用 JavaScript. 代码加工处理，然后返回给同一个表单或同一个 Web 页面中的其他表单。另外，也可以从表单中获取数字签名的信息，然后加以验证或进行其他操作。
图 1 展示了在 HTML 页面中使用 JavaScript. API 与 XFDL 表单交互的过程。
图 1. HTML 页面中使用 JavaScript. API 与 XFDL 表单交互的过程
FormNodeP 对象和 XFDL 对象是 JavaScript. API 的主要组成部分，下面将对其进行详细介绍。
回页首
FormNodeP 对象
表单中的每个 XFDL 元素都对应一个 FormNodeP 对象，在加载表单的时候，代表表单本身的 FormNodeP 对象会被添加到 ibmForms 数组中。调用 JavaScript. API 的应用可以使用 ibmForms 数组作为起点。FormNodeP 对象包含了操作和控制表单的方法。可用于添加、修改、删除和验证表单内容。任何使用 FormNodeP 对象中的方法的 Web 页面必须在脚本中包含 LF_FormNodeP.js 文件。FomNodeP 对象中的方法可以分为以下几类：
- 事件相关的方法：JavaScript. API 支持四种事件，即 onBlur、 onChange、 onClick 和 onFocus 事件。在 FormNodeP 对象中包含了对这四类事件的处理函数注册和注销方法。
- 表单页面元素及其属性：可以使用 FormNodeP 中的方法读取、添加和修改表单页面元素及其属性，例如为 combobox、list 或 popup 添加一个选项，复制或删除一个表单页面元素，或者操作表单中的附件等等。
- Form. instance：可以使用 FormNodeP 提供的相关方法获取或更新 form. instance，包括 XForms instance 和 XML model。
- 数字签名：FormNodeP 提供了用于验证或删除表单中的数字签名的功能。
回页首
XFDL 对象
XFDL 对象包含从 Web 页面中注册和注销表单的功能。为了使用 JavaScript. API，必须在脚本文件的开头包含 LF_XFDL.js 文件。
XFDL 中的 registerAPIExceptionHandler 方法用于注册处理 JavaScript. API 抛出的异常的函数。registerForm. 方法用于注册表单，将其添加到 ibmForms 表单数组中，这样 JavaScript. API 可以访问该表单。deregisterForm. 方法用于注销原来注册的表单。调用该方法后，JavaScript. API 不可以继续访问该表单。
回页首
使用 JavaScript. API 创建与 Lotus Forms 表单交互的应用
下面将通过一个实例展示如何使用 JavaScript. API 创建与 Lotus Forms 表单交互的 Web 应用。
实例中的表单是采购系统中的一个简化采购订单表单，当用户选定一个商品时，表单中会自动显示出商品的报价和生产厂商的名称及图标；用户添加需要采购的商品后对表单进行数字签名；HTML 页面获得采购订单的数据和数字签名的状态后提交到后台进行处理。下面将列举本实例中使用 JavaScript. API 的几段代码。
本文中使用的完整表单及代码详见下载部分，可以使用 Lotus Forms Viewer 3.5.1 或 Lotus Forms Webform. Server 3.5.1 来打开该表单。
在使用 JavaScript. API 的脚本的开头部分，包含需要的 JavaScript. API 文件：
清单 1.
<SCRIPT. TYPE="text/javascript" SRC="LF_XFDL.js"></SCRIPT>
<SCRIPT. TYPE="text/javascript" SRC="LF_FormNodeP.js"></SCRIPT> |
清单 2. 在加载表单后，注册商品名称改变事件
var theName = ibmForms["customFormName"].dereferenceEx(null, "PAGE1.LIST1",
0, FormNodeP.UFL_ITEM_REFERENCE, null);
theName.addOnChange(updatePrice);
theName.addOnChange(updateProducer);
theName.addOnChange(updateProducerIcon); |
用户选定一个商品时，显示商品的报价及生产厂商的名称，代码如下。
清单 3. 通过更新 Instance 中的节点更新商品的单价
function updatePrice()
{
ibmForms["customFormName"].
updateXFormsInstance(null,"instance('Generated')/wizardpage2/price",
null,"15.0", XFDL.UFL_XFORMS_UPDATE_REPLACE_TEXT)
} |
清单 4. 通过设置 XFDL 元素的值来更新生产厂商的名称
function updateProducer()
{
ibmForms["customFormName"].setLiteralByRefEx(null,
"PAGE1.producer.value", 0, null, "IBM");
} |
为了显示生产厂商的图标， 我们需要将图标图片的数据以附件的形式添加到表单中，其 JavaScript. API 代码如下。
清单 5. 添加图片文件
function updateProducerIcon()
{
var pageone = ibmForms["customFormName"].dereferenceEx(null,
"PAGE1", 0, FormNodeP.UFL_PAGE_REFERENCE, null);
var imageEncode =
"H4sIAAAAAAAAC3P3dLOwTFRgUGA4xAAC////X8XwoYGh4QPDqg9A/
uxMhtAPij9ZGEGSOiACpJaBuVRi151/BmyGS1uV7t/
VKHcWKHIJ8HL+JfjGdF28zvkSWVGLZvFpgj/
6YvUUnpjyMS5JlNSxau9uDmHMsZnPt+TJqzmF3Vv0r5zeqrC1X/
vI88mLLj8wNa4U/
JaSPLvO36jWSV9AR11as7HJqL2mRkSum0uyr190sikngzUAvLfe4rAAAAA="
var encloseImage = pageone.encloseFile(imageEncode,
"base64-gzip", "image/gif", null, "DATA1");
} |
当用户完成采购订单并进行数字签名后，提交订单，在提交订单前，需要验证数字签名，如果数字签名验证函数的返回值为 FormNodeP.UFL_DS_OK，则表示数字签名有效。
清单 6. 验证数字签名
function verifySign()
{
var signNode = ibmForms["customFormName"]
.dereferenceEx(null, "PAGE1.SIGNATURE1", 0,
FormNodeP.UFL_ITEM_REFERENCE, null);
var ret = ibmForms["customFormName"].verifySignature(signNode, false);
return ret;
} |
该实例中使用的表单和代码祥见附件。
有时，需要在同一个 Web 页面中展示多个 XFDL 表单。当在同一个 Web 页面中同时展示多个 XFDL 表单时，如果使用 JavaScript. API 处理 XFDL 表单，需要使用表单的文件名来区分不同的表单，示例代码如下。
清单 7. 多表单示例代码
if (!ibmForms["customFormName"] || !ibmForms["Form2.xfdl"] || !ibmForms["Form3.xfdl"]) {
alert("You must select a form. before you can start any tests...");
} |
回页首
异常和错误处理
在使用 Lotus Forms Javascript. API 时，有两个发生异常的根源，一个是 JavaScript. 代码，另一个是 Viewer 或 Webform. server 中的底层表单处理代码。
可以使用常规的方式处理 JavaScript. 代码错误。例如，保持浏览器的默认行为或者使用 JavaScript. 的 try-catch 方式进行处理。
JavaScript. API 的错误处理机制用于处理底层表单代码抛出的异常。这些异常可以以 JavaScript. 警告的方式显示，或者传递到自定义的异常处理器。可以使用 XFDL 对象的 registerAPIExceptionHandler 方法注册自定义的异常处理方法。自定义的异常处理方法应该以 JavaScript. 错误对象 ex 做为输入参数 , 实例代码如下。
清单 8. 用户自定义的异常处理示例代码
function apiExceHandler(ex) {
alert("custom error handling");
alert("name: " + ex.name);
var exDesc = ex.description;
alert("description: " + exDesc);
var exMsg = ex.message
alert("message: " + exMsg);
} |
回页首
Viewer 和 Webform. Server 中实现的区别
很多时候，不管表单是由 Viewer 展示还是 Webform. Server，其使用 JavaScript. API 的方式是相同的。但是，有时可能需要根据选择使用 Viewer 还是 Webform. Server 调整应用的设计。
由于实现机制的不同，当使用 Webform. Server 展示表单时，使用 JavaScript. API 的应用可能有以下某些局限。
- Web 页面加载：在表单没有完全加载到浏览器并注册前，不能使用 JavaScript. API。但是，浏览器并不能控制页面中不同部分的加载顺序，即不能保证在 JavaScript. 应用访问表单前表单已经加载完成并注册。对于这种情况，Portlet 和 Servlet 分别有其不同的解决方法。当使用 Portlet 时，可以通过使用两个 Portlet 来解决，一个 Portlet 用于展示 XFDL 表单，另一个 Portlet 中提供用户控制 JavaScript. 应用的初始化的机制。当使用 Servlet 时，可以通过把 Web 页面划分成不同的 frame. 来解决。Frameset 元素的 onload 事件在所有 frame. 加载完成后发生，可以用于控制 JavaScript. 应用的初始化。
- Web 页面重新加载：尽管 Webform. server 中广泛使用了 AJAX，但是某些操作仍然会引起页面刷新，当页面刷新并重新加载后，JavaScript. 的状态信息会丢失，变量值和存储的任何其它数据都会丢失。在 Servlet 中，可以使用 HTML frame. 来处理这种局限。Portlet 中则会比较复杂。需要采取措施以在页面重新加载时保存 JavaScript. 应用的状态。
回页首
总结
本文在介绍了 Lotus Forms JavaScript. API 后，结合实例向用户详细地介绍了如何使用 JavaScript. API 与 XFDL 表单动态交互，进行 Lotus Forms 的二次开发以及与其他系统的集成。本文还总结了 Lotus Forms JavaScript. API 中的异常和错误处理机制。最后，文章列举了使用 Lotus Forms Webform. Server 的 JavaScript. API 的应用需要注意的局限及其解决方法。
原文链接：http://www.ibm.com/developerworks/cn/lotus/forms-javascript-api/index.html
posted on 2011-07-25 12:30
Mon$ter！ 阅读(307)
评论(0) 编辑 收藏