xpage 传参_XPage 全接触

XPage 全接触

刘 奇

2009 年 8 月 06 日发布

XPage 全接触

XPages 是 IBM Lotus Notes/Domino 8.5 为 Lotus Domino Web 2.0 应用程序开发人员提供的新技术。与以往发行版相比，它们提供了更大的灵活性，并且更好地控制交付给 Web 浏览器客户机屏幕的内容。本文将带大家全面了解 XPage 的各项功能，图 1 显示了 Lotus Domino Designer 8.5 中 XPage 设计页面。在阅读本文的同时，建议读者阅读文章 在 Lotus Domino Designer 中利用 XPages 的威力，该文章是本文一个很好的补充。

图 1. XPage 设计页面(查看大图)

基本控件和基本属性

Lotus 软件试用下载

立即下载最新版本的 IBM Lotus Notes 和 Domino 试用软件，尝试利用 XPage 技术开发第一个 Domino Web 2.0 应用程序。

Lotus Domino Designer 提供了大量可重用的控件供用户开发 Web 2.0 的程序，它主要分为两种：核心控件和容器控件。顾名思义，核心控件指一些比较基本的 XPage 控件，如编辑框、文本标签等；容器控件则是比较复杂、能够包含其它控件的控件，例如面板、表格、视图等。另外，用户还可以自己定制控件，以供自己或者别人重用。

值得注意的是，通过拖拽控件面板上“Other”将控件放到 XPage 设计页面时，您会发现除了您在控件面板上看到的一些控件之外，“Other Controls”部分多了复选框组、单选按钮组等控件，如 图 2 所示。

图 2. “Other Controls”

下面将分别阐述一下应用程序的属性、XPage 页面属性、控件基本属性以及自定义控件属性。

应用程序属性

点击 图 3 所示的 Application Properties 打开应用程序属性设置页面并点击 XPage Tab，如 图 4 所示。在这里，您可以设置数据验证代码是在服务器端还是在客户端执行，压缩以及编码格式和全球化相关的一些属性。

图 3. “Application Properties”入口

图 4. 应用程序属性页面

XPage 页面属性

图 5 展示了 XPage 页面的属性。除了可以设置数据源、样式(字体及大小、背景色、边距等)之外，还可以添加 CSS 文件和 JavaScript 库。

图 5. XPage 页面属性

控件属性

图 6 显示了 Edit 控件的基本属性，对于不同的控件，它的属性也有所不同。

图 6. Edit 控件属性

自定义控件属性

自定义控件的属性除了具有 XPage 页面所具有的基本属性之外，它还允许用户添加新的属性，读者可以参考“自定义控件与 compositeData”小节了解更多的内容。

图 7. 自定义控件属性

Ajax 和 JavaScript 支持

作为非常流行的交互式网页应用的网页开发技术 — Ajax，其在 XPage 中得到了很好的支持。主要表现在以下几个地方：

Ajax 部分页面刷新适用任意的事件

对于任意事件，在服务器端允许用户选择页面更新的方式：全部更新、部分更新、不更新等。例如，点击“Refresh Panel”链接，将仅仅刷新“compute2”，其源码如 清单 1 所示。

清单 1. 部分更新示例源码<?xml version="1.0" encoding="UTF-8"?>

submit="true" refreshMode="partial" refreshId="compute2">

id="pane1">

value="#{javascript:@UpperCase(@Left(@Unique(),5))}"

style="color:rgb(0,128,192)">

value="#{javascript:@UpperCase(@Left(@Unique(),5))}"

style="color:rgb(255,0,0)">

Pager 控件

XPages 中的 Pager 是用于数据源集合导航的控件，经常跟 View，Repeat，Data Table 等一起使用。如 图 8 所示，选中 Partial Refresh，该 Pager 将仅仅刷新 viewPanel(刷新部分由 Attach to 指定的)的内容；反之，如果 Partial Refresh 没有被选中，则刷新整个页面中的内容。

图 8. Pager 控件部分刷新

Ajax Typeahead

Typeahead 是增强用户体验的一项重要措施，它能够根据用户输入的字符(串)猜测用户接下来可能输入的字符并帮助用户完成数据的输入。Edit 控件属性中有一项是 Type Ahead，如 图 9 所示，您可以在 Suggestions 中输入提示的字符串集，也可以书写 JavaScript 等返回字符串集合，其运行如 图 10 所示。

图 9. Typeahead

图 10. Typeahead 运行示例图

嵌入 Dojo 作为客户端的代码库

XPage 对 JavaScript 也有着非常好的支持。例如，不论是在客户端还是在服务器端，任意事件都支持 JavaScript。又例如，Computed Field 也支持 JavaScript 来计算这个域的值。

在服务器端，XPage 还提供：允许用户使用 @function。

大量的全局对象，例如 applicationScope，session 和 requestScope 等。

大量的全局方法，例如 getComponent，getView，getClientId 等。

允许用户使用函数库 DOM、Domino、Runtime、Standard、XSP 等中的函数。

JavaScript 对控件的操作

获取和设置 XPage 中控件的属性以及值在 XPage 应用程序开发过程中是非常重要的。下面将结合实例来讲述如何分别在客户端和服务器端上获取控件值或者属性：

客户端

创建一个简单的 XPage， 如 图 11 所示，源码如 清单 2 所示。

图 11. XPage 示例

清单 2. XPage 示例源码<?xml version="1.0" encoding="UTF-8"?>

选择“设置编辑框文本”按钮并点击事件，书写事件“onClick”客户端运行的 JavaScript 脚本，如代码清单 3 所示。

清单 3. 客户端 JavaScript 代码(操作控件的值)var editID = '#{javascript:getClientId("textExample")}';

document.getElementById(editID).value = "您好！设置成功！";

其中，getClientId("textExample") 是用来获取编辑框的客户端 ID(如 view:_id1:textExample)，但是仅仅服务器端可以使用这个函数。为了能够在客户端也能使用，需要将它放在 #{javascript: ... } 中。当运行 XPage 时，这个嵌入在 #{javascript: ... } 中的语句首先被执行，并将执行结果返回。点击“设置编辑框文本”按钮，编辑框就会被设成“您好！设置成功！”。

服务器端

对上述例子，也可以书写服务器端脚本，如 清单 4 所示。

清单 4. 服务器端 JavaScript 代码(操作控件的值)var editComponent:javax.faces.component.UIComponent = getComponent("textExample");

editComponent.setValue( "您好！设置成功！");

其中，getComponent("textExample") 是用来获取 XPage 编辑框对象，调用 setValue 方法可以设置其值。

细心的读者可能发现，除了 setValue 之外，还有很多 UIComponent editComponent 方法供使用，例如 图 12 列出了一些设置编辑框属性的方法。

图 12. UIComponent 设置方法列表

XPage 事件模型

XPage 主要有以下几种事件：

Page 事件

如 图 13 所示，Page 事件主要有 beforePageLoad，afterPageLoad，afterRenderResponse，afterRestoreView，beforeRenderResponse，beforeRestoreView 等。

图 13. Page 事件

Control 事件

XPage 控件的事件比较多，如 图 14 所示，它分为鼠标、焦点、键盘三大类。读者可以参考 Lotus Domino Designer 了解各个事件的具体含义。

图 14. Control 事件

Document 事件

Document 事件主要包含 computeDocument，postNewDocument，postOpenDocument，postSaveDocument 等。

View 事件

View 事件包含 postOpenView，queryOpenView。

Validator

Validator 是用来验证 XPage 控件数据的合法性，它能够发生在服务器端，也可以发生在客户端，您有两种方法来设置这个属性：在应用程序级别，可以打开“Application Properties > XPage TAB”来设置，如 图 15 所示。

图 15. 客户端数据验证设置(应用程序级别)

在控件级别，您可以在控件“Properties >All Properties”中来设置，如 图 16 所示。

图 16. 客户端数据验证设置(控件级别)

数据验证在客户端与服务器端执行返回结果的方式有所不同。仍以 图 11 所示例子来说明，我们对编辑框加上一个数据验证，如 图 17 所示，这样当点击按钮时就会提示“数据错误”的信息。

图 17. 设置 Edit 控件数据验证属性

假如在客户端执行数据验证，点击按钮就会弹出如图所示的对话框，如 图 18 所示。

图 18. 数据错误警告框

假如在服务器端执行数据验证，我们需要创建一个“Display Error”控件来显示错误信息。

Java 代码重用

大家可能在想， 能不能重用 Java 代码，并在 JavaScript 中使用呢？答案是肯定的。主要分为以下几个步骤：切换 Lotus Domino Designer 的视图至 Java 视图，如 图 19 所示。

图 19. 切换视图

您可以选择在 Lotus Domino Designer 中创建一个项目，添加您要重用的 Java 代码，并将这个项目导出成一个 JAR 包。右击 项目，选择 “Export …”，并选择 Java -> JAR file。注意：不是一定要求您在 Lotus Domino Designer 中创建项目，您也可以选择在其他地方，例如 Eclipse 中创建项目并导出来。

将导出的 JAR 包放到 XPage 应用程序(NSF 文件)中。选择 WebContent > WEB-INF，您应该能看到文件夹 lib (如果没有，请创建该文件夹)，将 JAR 包放到 lib 文件夹下。这样，您就可以在此 XPage 应用程序中使用 JAR 包中所有的类和相应的方法了。

图 20. 添加 JAR 包

使用 JAR 中的类和方法。例如 清单 5 所示。

清单 5. XPage 中使用 Java 库示例var objectTest = new Test(); -- Test 为 JAR 中包含的类。

objectTest.print();

…

值得注意的是，您需要等待几分钟，JAR 包中包含的类和方法才能在 XPage 中正式生效。

自定义控件与 compositeData

Custom control 是由一系列的控件组成的，能够被当成一个对象来使用和存储，例如将一个公司的标志加到公司的商业文档中组成一个自定义的控件，这个自定义的控件可以永久的存储在 XPage 中，公司其他人员就可以直接使用这个自定义控件来创建一个带有公司标志的商业文档。

XPage 允许用户为“Custom Control”定义新的属性。创建一个 Custom Control，图 21 显示了 Custom Control 的属性。在 TAB “Property Definition”中，用户可以定义新的属性，图中创建了一个新的属性 text。那么如何访问这些自定义的属性呢？XPage 提供了一个对象 — compositeData，允许用户通过“compositeData.属性名”直接来访问和设置属性的值。

图 21. 添加新属性

总结

本文对 XPage 基本控件和基本属性、XPage 对 Ajax 以及 JavaScript 的支持、控件操作、XPage 事件模型等进行了讲述，相信大家已经对 XPage 有了一个基本的了解，并且能够开发一些简单的 XPage Web 2.0 应用程序。如果读者希望能够进一步的学习，可以阅读参考资料中的相关文档。

相关主题查看教程“在 Lotus Domino Designer 中利用 XPages 的威力”，了解 XPage 的基本知识，以及如何构建 View 类型的 XPage、NotesDocument 类型的 XPage、添加 XPage 前端和多文档删除等。

查看教程“在 IBM Lotus Domino Web 应用程序开发中使用 XPages、Themes 和 Mashups”：在本教程将结合使用 XPages 和 Themes 创建一个企业级销售跟踪和任务分配 Lotus Domino Web 应用程序。

XPages in Domino Designer 8.5：阅读 Rob McDonagh 关于 XPages 的博客文章。

下载试用版 Lotus Domino V8.5，立即体验 XPage 的威力。

下载试用版 IBM Lotus Notes 8.5 和 Domino Designer 8.5，尝试利用 XPage 技术开发第一个 Domino Web 2.0 应用程序。