» 搜索提示 
 
深入研究组件
2006 年 2 月 [修订号:V2-2]  
组件是交互式 Web 页的组块。本教程介绍了充分利用与 IDE 捆绑在一起的组件所需的基本知识。在熟悉了一般性内容之后,您可以进一步学习单个组件的教程以了解更多特定信息。您还可以在组件面板中的任何组件上按 F1 键,以访问该组件的详细信息。

注意:使用本教程之前,请学习 Sun Java Studio Creator 入门指南
 
目录
 
组件的概念
常规信息
输出组件
输入组件
操作和链接组件
布局组件
非可视组件
小结
[spacer] 此页上的内容适用于 Sun Java Studio Creator 2
 
本高级教程详述了 Sun Java Studio Creator 入门指南开发 Web 应用程序中所介绍的概念。
 

组件的概念

 
生成一个静态 HTML 页并不需要花很多时间或需要许多深入的知识。但是,一旦要生成动态的交互式页面,您就进入了一个复杂的领域。您必须知道如何将 JavaScript 用于客户端交互,您还必须编写 Java 代码和 JavaServer Pages (JSP) 标记以用于服务器端的交互和验证。另外,再加上不同浏览器显示标记的方式存在许多不一致性,因此您的生产率可能会降低至零。
 
IDE 提供的基于 JavaServer Faces 的组件降低了生成交互式 Web 页的复杂性,并加快了开发周期。此外,IDE 还可以使您在不必了解错综复杂的 JavaServer Faces 技术的情况下使用这些组件。
 
组件是 steroid 上的标记。即,您不仅仅可以获得呈现标记(如下拉列表),而且还可以获得易于修饰且生成事件(可以使用简单 Java 代码处理这些事件)的好看标记。例如,文本字段组件使用 JavaServer Faces 框架转换和验证输入,以及传播更改和验证事件。
 
此外,仅通过几下单击,您就可以将组件的属性绑定到 Bean 属性或数据源的数据提供器包装器,而不管数据源是数据库、Web 服务、Enterprise JavaBeans 对象、数组还是列表。通过使用绑定功能,您不必编写代码来填充组件值,而且也不必编写代码来将组件值保存到绑定对象。
 
捆绑的组件提供了功能卓越的小部件,它们是使用普通 HTML 标记所无法获得的。例如,下图所示的表组件附带有可排序列和自动分页小部件。
 
图 1:表组件
图 1:表组件
 
本教程主要介绍在组件面板的“基本”、“布局”和“组合”类别中包含的组件,如下图所示。
 
图 2:“基本”、“布局”和“组合”类别
图 2:“基本”、“布局”和“组合”类别
 
注意:组件面板中的“标准”类别包含 JavaServer Faces 引用实现组件。IDE 提供标准组件的目的是为了向后兼容使用早期版本的 IDE 生成的项目。由于标准组件提供的功能较少且需要较多编程工作,因此您应该使用组件面板其他类别中的可视组件。
 
注意:组件面板提供有表单组件。本教程将不讨论表单组件。在大多数情况下,虚拟表单机制(在使用虚拟表单中进行了介绍)是处理页面上多个表单的更佳方法。
 

常规信息

 
此部分提供了适用于大多数组件或所有组件的信息。本教程的其余内容分为五部分(输出组件输入组件操作和链接组件布局组件非可视组件),如下图所示。
 
图 3:五种类型的组件
图 3:五种类型的组件
 
组件属性
 
使用“属性”窗口可以指定组件的外观和行为。例如,使用列表框组件的 rows 属性可以指定呈现的列表框的长度,使用 multiple 属性可以指定页面访问者是否可以选择列表中的多个项。
 
IDE 还为每个组件的常见任务提供了菜单操作。例如,图像组件具有“设置图像”菜单项,静态文本组件具有“编辑文本”菜单项,下拉列表组件具有“编辑标签”菜单项。
 
下表描述了控制组件的行为和外观的公共属性。接下来的各部分将介绍不同类型组件的特定信息。
 
属性 描述
id 每个组件都必须具有一个 id,且 id 对其所在的页面来说是唯一的。IDE 在您将组件添加到页面时创建 id。在以下情况下,您可能希望更改组件的 id:
  • 组件是输入组件。请为组件指定对应于它所绑定到的属性或列的 id,如 personIdDropDown

  • 组件(如按钮)生成操作事件。请将 id 设置为与组件的标签匹配的动词名称,如 submitButton

  • 在页面上具有几个相同类型的组件,而且您需要编写 Java 源代码以设置或访问一些组件的属性值。例如,如果引用 nameTFaddressTF 而不是 textField1textField2,则代码更易于理解。
toolTip 使用此属性可以指定页面访问者将鼠标悬停在组件上时将出现的文本。
style 使用 style 属性可以更改以下设置:
  • 字体
  • 背景
  • 文本块
  • 边框
  • 边距
  • 位置
单击 style 属性的省略号 (...) 按钮将打开样式编辑器,该编辑器可以使您轻松地更改设置和预览结果。有关如何使用此编辑器的描述,请单击编辑器底部的“帮助”按钮。
 
通常,当您调整组件的大小时,IDE 会设置高度、宽度或同时设置两者。如果页面处于网格布局模式,则在您将组件拖放到页面上以及在页面上重新放置该组件时,IDE 会设置位置值。
 
有时,您会看到与样式设置类似的实际属性,如 bgcolorborder。这些是标准的 HTML 4 样式属性。style 属性是对这些标准属性的增强,并提供了配置组件外观的更好机制。
 
通过建立样式设置,可以覆盖主题的大多数(但不是所有)样式功能。例如,您不能使用 style 属性设置表的背景色或设置 label 属性的字体颜色。这尤其适用于设置与组件的主题发生冲突的情况。此外,在一些情况下,特定区域还会被可能具有不同样式设置的其他子组件所遮盖。
 
有关详细信息,请参见将样式添加到组件教程。
styleClass
每个项目都具有一个主题,主题是层叠样式表 (Cascading Style Sheets, CSS)、JavaScript 文件和图标图像的集合。IDE 提供了四个主题,您可以从中进行选择。要将自己的样式添加到主题,请使用样式表编辑器或将样式表放置在项目的 resources 文件夹中。styleClass 属性的下拉列表显示了应用程序使用的所有样式表的所有样式类。通常,除非要从自己的样式表中选择样式类,否则不使用此属性。除了组件的主题样式类之外,还应用 styleClass 设置。
 
有关详细信息,请参见将样式添加到组件教程。
visible visible 属性指定呈现的组件在页面上是否可见。当将组件的 visible 属性设置为 false 时,该组件不出现在呈现的页面上,但是它仍出现在发出的 HTML(页面源代码)中,它的值将被提交,而且该组件的所有转换、验证和事件生成仍会发生。
rendered 如果将组件的 rendered 属性设置为 false,则会从发出的 HTML 中删除该组件,这样该组件对于客户端就是不可用的。此外,您也不能从 JavaScript 引用该组件,而且在提交页时不会发生转换、验证或事件生成。
 
设置组件值
 
所有输入组件和输出组件都是包含值的组件。例如,文本字段组件包含文本,列表框组件包含选定的值。设置输入组件和输出组件的值有以下几种方法:
  • 设置组件的包含值的属性。在“属性”窗口中,单击包含值的属性的省略号按钮 (...) 以打开文本编辑器。此外,对于大多数输入组件和输出组件,可以在可视设计器中选择组件,然后开始键入组件的值。对于组件的可编辑文本,包含值的属性的弹出式菜单包含“编辑”菜单项。

  • 从页面 Bean 的源代码调用组件的 setter 方法。例如,调用 setText 方法可以设置文本字段组件的值,调用 setSelected 方法可以设置列表框组件的值。调用 setter 方法的一些常见位置在 preprocess、prerender、value change 和 action 方法中。

  • 将组件绑定到数据提供器或 Bean 属性。有关将组件绑定到数据的详细信息,请参见下一子部分。
注意:与 JavaServer Pages 实现一样,当服务器从 JSP 源代码构造页时,JSP 源代码中的标记属性设置优先于运行时设置。例如,如果将静态文本组件的 text 属性设置为 "moon",则 IDE 会将 text="moon" 添加到 JSP 文件中静态文本组件的标记。即使此页的 prerender 方法包含 staticText1.setText("sun") 语句,在应用程序呈现此页时,静态文本组件也会显示 "moon"。如果重新呈现此页,则 staticText1.setText("sun") 语句将生效,并且静态文本组件将显示 "sun"。如果先访问其他页然后再返回来访问此页,则服务器将再一次从 JSP 源代码构造此页,并且构造时将优先采用在 JSP 标记属性中设置的值,即此页将显示 "moon"。
 
提示:为确保属性设置代码始终生效,请不要在“属性”窗口中将该属性设置为静态值。
 
绑定到数据
 
您可以将大多数的输入组件和输出组件绑定到数据对象。通过将组件绑定到数据,Web 应用程序可以自动将组件的值与绑定目标的值进行同步。例如,如果将组件绑定到 Bean 属性,则 Web 应用程序在其呈现页时会将组件的值设置为 Bean 属性的值,而在提交页时会更改 Bean 属性的值以便与对组件值进行的更改匹配。
 
IDE 包含数据库表、Web 服务、Enterprise JavaBeans 对象、映射、数组和列表的数据提供器包装器。您可将数据提供器与数据对象关联,并将组件绑定到数据提供器。使用数据提供器的一个优点是:它们提供了访问所有类型数据的公共接口。
 
要为数据库表创建数据提供器,请将数据库表从“服务器”窗口的“数据源”类别拖放到页面上。IDE 将为数据库表创建 CachedRowSet 表数据提供器。对于其他类型的数据提供器,请将数据提供器从组件面板拖动到可视设计器中的页面上或“概要”窗口中的“会话 Bean”节点上,然后在“属性”窗口中配置属性。
 
有关绑定和数据提供器的详细信息,请参见使用数据绑定组件访问数据库教程。使用 EJB 组件教程介绍了如何绑定到 EJB 组件,获取 Web 服务教程介绍了如何绑定到 Web 服务方法。在两个页面之间共享数据教程介绍了如何创建和绑定到 Bean 属性。
 
转换值
 
IDE 提供了几种可以应用于大多数输入组件和输出组件的转换器。转换器将对象的值转换为 String 值,以便可以将该值写入 HTML 响应。相反,转换器将 HTML 请求中的 String 值转换回指定的数据类型,如 BooleanFloat。有关详细信息,请参见使用转换器教程。
 
注意:对于绑定到数据的任何组件,Web 应用程序会自动执行相应的转换。例如,如果将文本字段组件绑定到 Integer 对象,则 Web 应用程序会自动将输入值 (String) 转换为 Integer 值。
 

输出组件

 
IDE 提供了几种输出组件,如下图所示。这些组件分为以下三组:文本、消息和图像。通常,使用输出文本组件可以在页面上布置文本,使用输出消息组件可以响应用户输入或用于其他类型的动态操作,使用图像组件可以显示像素值库,如 jpggif 文件。
 
图 4:输出组件
图 4:输出组件
 
输出文本组件
 
IDE 提供了三种输出文本组件。
 
输出文本组件 用法
静态文本



当希望仅在页面上显示某些文本时,可以使用静态文本组件。
标签



使用标签组件可以将文本与输入组件关联。通过设置标签组件的 for 属性,可以将该标签组件与输入组件关联。将标签组件与输入组件关联时,该标签组件将变得“更智能”。具体说来,如果输入组件的 required 属性为 true,则标签组件将显示一个星号。如果因输入无效而使服务器拒绝了该页面的提交申请,则在页面中突出显示标签组件的文本。
 
尽管输入组件确实具有 label 属性,但是最好使用标签组件,因为在设置输入组件的 label 属性时无法调整该组件的大小或正确对齐它。此外,您在使用标签组件时还具有更多的样式选项。
内联帮助



使用内联帮助组件可以在页面上显示简短的帮助类型信息。通常,将组件的 type 属性设置为 field,以便帮助信息以较小的字体显示,这样就不会占用过多的空间。
 
输出消息组件
 
IDE 提供了以下输出组件以显示各种类型的消息。这些组件(除页面警报组件之外)仅在其值不为空时出现在呈现的页面上。
 
输出消息组件 用法
警报



使用警报组件可以在某个事件完成时显示动态信息,如警告、错误、成功状态或信息性状态。您可以选择错误图标、信息图标、警告图标或成功图标与摘要文本一起显示,也可以选择显示详细文本和超级链接。
 
使用 summarydetail 属性可以设置组件的文本,使用 type 属性可以指定要显示的图标。仅当组件的 summary 属性具有值时,该组件才出现在页面上。
 
通过指定 linkTextlinkURL 值,可以添加可选的超级链接。要指定链接的动态页面导航,请执行以下步骤:
  1. 设置 linkText 属性。
  2. 使用页面导航编辑器绘制一条到目标页的连线,然后为该连线指定一个名称,如 alertOutcome
  3. 切换到可视设计器,然后双击警报组件。IDE 将创建操作事件处理程序方法,并在 Java 编辑器中将插入点置于该方法上。
  4. 更改方法的 return 语句以使其返回为连线指定的名称,如 alertOutcome
请注意,此过程与其他操作组件的步骤(如操作和链接组件中所述)稍有不同。这是因为页面导航仅允许来自页面和来自扩展 UICommand 的组件的连线,而警报组件不扩展 UICommand
页面警报



页面警报组件与警报组件类似,只是它用于在单独页面上显示动态消息。页面警报组件提供了可供选择的错误、警告、信息和成功图标。您可以使用 titlesummarydetail 属性来设置组件的文本,以及使用 type 属性来指定要显示的图标。
 
要在页面警报组件内嵌套组件(如按钮),请先将一个组面板组件拖放到该组件上,然后将按钮组件拖放到组面板组件上。(拖放第一个按钮组件后,您必须选择该按钮组件,然后按 Esc 键再次选择组面板组件。)接下来,您必须编辑 JSP 页,以用 <f:facet name="pageAlertButtons"></.f:facet> 标记包装组面板组件。
 
有关详细信息,请参见使用页面警报组件教程。
消息



使用消息组件可以显示输入组件的错误消息。要将消息组件与输入组件关联,请设置消息组件的 for 属性。应用程序将有关转换和验证错误的消息发送到消息组件。在抛出以下任意一种异常的情况下,应用程序会将您自己的验证消息发送到消息组件:
  • ValidatorException(new FacesMessage(summary))
  • ValidatorException(new FacesMessage(summary, detail))
  • ValidatorException(new FacesMessage(severity, summary, detail))。对于严重性级别参数,您可以传递 FacesMessage.SEVERITY_INFOFacesMessage.SEVERITY_WARNFacesMessage.SEVERITY_ERRORFacesMessage.SEVERITY_FATAL
添加自己的验证处理程序教程介绍了如何创建自己的验证处理程序。
 
有关使用消息组件的详细信息,请参见使用消息组件教程。
消息组



使用消息组组件可以显示运行时错误。您还可以显示单个组件的错误(如验证和转换错误),方法是取消选中 showGlobalOnly 属性的复选框。消息组组件对于诊断编程错误也是很有用的。
 
要将自己的文本写入此组件,请调用 info(String summary)warn(String summary)error(String summary)fatal(String summary)。Web 应用程序根据方法的严重性级别将不同的样式应用于文本。
 
要同时写入摘要消息和详细信息消息,请使用 FacesContext.getCurrentInstance().addMessage(null, new FacesMessage(summary, detail))ValidatorException(new FacesMessage(severity, summary, detail))
 
您必须选中组件的 showDetail 复选框,才能显示详细信息消息。
 
有关使用此组件的详细信息,请参见使用消息组件教程。
 
就像输出文本组件那样,您可以通过编程方式设置页面警报和警报组件的输出值,方法是调用相应属性的 setter 方法。例如,要设置页面警报组件的摘要文本,请调用 setSummary(String)。您还可以将这些属性绑定到受管 Bean 属性和数据提供器字段。
 
图像组件
 
使用图像组件可以显示由 url 属性指定的图形图像,或显示提供的图标之一,如 ALARM_CRITICAL_MEDIUMALERT_OK_SMALL(可以从 icon 属性的下拉列表中进行选择)。
 
图 5:图像组件示例
图 5:图像组件示例
 
url 属性可以包含 Internet 上图像的 URL,或者也可以指向项目 resources 文件夹中的图像文件,如 /resources/images/duke.gif。您还可以将 url 属性绑定到受管 Bean 属性或绑定到返回 String 格式的 URL 路径的数据提供器字段。通过单击 url 属性的省略号 (...) 按钮,您可以选择“使用绑定”单选按钮来将属性绑定到数据对象,或者也可以选择“使用值”单选按钮来指定图像文件。如果图像还没有位于 resources 文件夹中,请单击“添加”以查找该文件,然后将其复制到此文件夹中。或者,您也可以在 url 属性的文本框中键入有效的 URL。
 
提示:在您为与 Web 应用程序包装在一起的图像指定 URL 时,请使用上下文相关的 URL。即,使 URL 以正斜杠 (/) 开头,如 /resources/images/dot.gif。使用上下文相关的 URL 时,在呈现页并将其发送到客户端之前,服务器会将 URL 转换为完整的 URL。如果不在开头加上正斜杠,则会在客户端上进行解释,而且客户端会将当前页位置的 URL 附加到图像 URL 的前面。如果页面位于子文件夹中,则在转发请求(缺省分发机制)时可能无法正确解析 URL。
 

输入组件

 
如下图所示,IDE 提供了几种获取用户输入的不同方法。此部分描述了输入组件,讨论了这些组件的通用功能,并说明了如何获取和处理输入值。
 
图 6:输入组件
图 6:输入组件
 
IDE 提供了以下输入组件。
 
输入组件 用法
文本输入组件



使用文本字段组件可以输入单行文本,使用文本区域组件可以输入多行文本,使用口令字段组件可以生成一个输入字段,该字段可用替代字符回显输入字符以屏蔽输入。
选择组件



单选按钮组组件、复选框组组件、下拉列表组件、列表框组件和添加删除列表组件是非常类似的。它们都提供了项(显示值)的列表,页面访问者可以从中选择一个或多个选项。

选择组件中的每个项都具有一个基础返回值(如果页面访问者选择了该选项,则 selected 属性的值将返回此基础值)。

初始化项列表有以下几种方法:
  • 使用缺省选项组件。当您将选择组件添加到页面时,IDE 会创建缺省选项组件,并将其绑定到选择组件。缺省选项组件将显示在“概要”窗口中。您可以在此组件的 items 属性中查看绑定。要将选项添加到列表,请右键单击组件,然后从弹出式菜单中选择“配置缺省选项”。或者,您也可以将如下所示的代码添加到 init() 方法中:

    代码样例 1:初始化列表选项
    dropDown1DefaultOptions.setOptions(new Option[] {
      new Option("item1", "Item 1"),
      new Option("item2", "Item 2"),
      new Option("item3", "Item 3")}
    );
     
  • items 属性绑定到数据提供器。右键单击组件,然后从弹出式菜单中选择“绑定到数据”。单击“绑定到数据提供器”标签,然后从现有的数据提供器组件列表中进行选择,或单击“添加数据提供器”创建一个新的数据提供器。为返回值选择一个列,然后为显示值选择一个列。

  • items 属性绑定到 com.sun.rave.web.ui.model.Option 数组。通常,将此数组创建为会话 Bean 属性。如果映射的值为 com.sun.rave.web.ui.model.Option 的实例,则也可以将该属性绑定到实现 java.util.Map 的对象。但是,键将被忽略,而且您无法控制显示值的顺序。即,Web 应用程序会随机地显示值。
预先选择项的一种方法是:从 prerender() 方法中调用 setSelectedValue(Object[])setSelectedValue(Object)。这将传入您要预先选择的项的返回值。在设置缺省选项之前,请确保验证 getSelected() 返回空值,否则在传回时将覆盖用户的选择。

如果将选择组件绑定到缺省选项组件,则可以通过从选择组件的弹出式菜单中选择“配置缺省选项”来预先选择项。选中“选择项”复选框,然后选择要预先选择的缺省选项。

注意:下拉列表组件的 forgetValuenavigateToValue 属性对组件的行为没有任何影响。

警告:添加删除列表组件的 Javadoc 和代码完成会显示一个 getSelectedItems() 方法,该方法返回一个 Iterator。请不要使用此方法,因为它仅供内部呈现使用,并不反映实际所选的项。

有关详细信息,请参见使用列表框组件教程。
复选框和单选按钮



单个复选框和单选按钮组件可用于添加到表组件的列。您也可以将复选框和单选按钮组件作为独立的组件添加到页面上。但是,如果要显示可选中选项的列表,则首选单选按钮组和复选框组组件。

如果选中了组件,则 isChecked() 将返回 true。要预先选择组件,请将其 selected 属性设置为 selectedValue 属性的值。缺省情况下,selectedValue 的值为 true

使用单选按钮组件时,利用其 name 属性可以组合列中的所有单选按钮组件。这样做可确保一次只能选择列中的一个单选按钮。
日历



使用日历组件,页面访问者可以通过键入日期或从弹出式日历中选择日期来输入日期。selectedDate 属性值以 java.util.Date 对象的形式包含输入的日期。

要设置弹出式日历的日期范围,请将 minDatemaxDate 属性绑定到类型为 java.util.Date 的 Bean 属性(它们具有开始日期和结束日期的值)。在此版本的 IDE 中,如果未设置 minimumDate 属性,则最小日期缺省为当前日期之后的那一天。

日期格式缺省为语言环境的缺省格式。您可以使用 dateFormatPattern 属性编辑器从日期格式模式列表中进行选择。

要更改在组件的输入字段下面显示的日期格式模式,请编辑 dateFormatPatternHelp 属性。
文件上载



使用文件上载组件,页面访问者可以查找其系统上的文件并将该文件上载到服务器。

组件的 uploadedFile 属性返回类型为 com.sun.rave.web.ui.model.UploadedFile 的值。UploadedFile 接口具有多种方法,用于获取文件的名称和大小、确定文件的 MIME 类型(如 text/plain 或 image/jpeg)、按字节或按 String 获取文件的内容,以及将内容写入磁盘。要了解更多信息,请在 Java 源代码中右键单击声明语句中的 UploadedFile,然后从弹出式菜单中选择“显示 Javadoc”。

缺省情况下,应用程序将上载文件的大小限制为 1 MB。要更改大小限制,请在应用程序的 web.xml 文件中修改 UploadFilter 过滤器的 maxSize 参数。有关详细信息,请参见使用文件上载组件教程。
 
定制输入组件的行为和外观
 
IDE 提供了以下功能来定制输入组件的行为和外观。
  • 标记字段。标记输入组件有以下两种方法:

    • 使用标签属性。通过设置输入组件的 labellabelLevel 属性,可以快速添加标签。
    • 使用标签组件。与标签属性相比,标签组件提供了更多的样式控制。此外,您还可以只单独地对齐标签而不对齐输入组件,而且对标签及其关联输入组件的大小具有更多的控制。

  • 显示错误消息。如前面所述,您可以添加消息和消息组组件以报告转换和验证错误。要将消息组件与输入组件关联,请将消息组件的 for 属性设置为输入组件的 id 属性的值。除非您将消息组组件的 showGlobalOnly 属性设置为 true,否则消息组组件将显示所有的输入转换和输入验证错误消息。

    提示:将消息组组件添加到每个页面是用于诊断编程错误的一种很好的做法。

  • 禁用输入并使输入组件只读。所有输入组件都具有 disabledreadOnly 属性。将组件的 disabled 属性设置为 false,可防止用户通过按 Tab 键移动到该组件,并防止应用程序转换、验证和提交其值。将组件的 readOnly 属性设置为 true,可防止用户输入或更改该组件的值,但应用程序仍可以转换、验证和提交其值。

  • 设置 Tab 键顺序。使用 tabIndex 属性可以指定用户使用 Tab 键在页面上的输入组件中移动的顺序。

  • 去除空白字符。当输入组件的 trim 属性为 true 时,应用程序将从其输入中删除所有的前导空格和后续空格。此删除操作将在转换和验证之前执行。一些输入组件(如日历组件和文件上载组件)没有 trim 属性。应用程序将自动从其输入中去除空白字符。

  • 限制可以输入的字符数。使用 maxLength 属性可以设置页面访问者可在输入字段中键入的最大字符数。应用程序将忽略后续输入的字符。例如,如果 maxLength 的值是 5,而页面访问者键入了 bicycle,则在字段中显示的全部内容是 bicyc

  • 设置字段宽度。通过设置 columns 属性或调整组件的大小,可以设置输入字段的宽度。在调整组件的大小时,IDE 会将宽度和高度设置添加到其 style 值。这些设置优先于 columns 设置。如果您日后决定使用 columns 设置,则必须从 style 属性中删除宽度和高度设置。

  • 使用输入组件提交页。对于大多数输入组件,可以从其弹出式菜单中选择“更改时自动提交”,以使每当输入值发生更改时浏览器就会提交页。此功能的一个典型用法是:每当页面访问者从主要数据的下拉列表中选择一个新项时都提交页,这样就可以同步详细数据以匹配新的主要数据选择。例如,当页面访问者从下拉列表中选择一个新产品时,页面将重新显示该产品的详细数据。

    如果您不希望浏览器在更改组件的值时提交所有输入值,请使用虚拟表单来指示要提交的值。有关详细信息,请参见使用虚拟表单
 
获取和设置输入值
 
下表显示了每个输入组件的包含值的属性。使用包含值的属性的 getter 和 setter 方法可以访问输入值。例如,使用 getSelected 和 setSelected 可以获取和设置将 selected 作为其包含值属性的任何组件的输入值。您还可以将这些包含值的属性绑定到数据,如常规信息部分中所述。
 
组件 包含值的属性 类型 注意事项
文本字段、文本区域、口令字段 text String,或将字段绑定到的对象的类型(如果已绑定)。  
下拉列表 selected 对于 items 属性,为下拉列表中的每个项指定显示标签和返回值。selected 属性返回与返回值类型相同的对象。如果使用缺省选项组件指定项和返回值,则 selected 属性将返回 String 当页面访问者从下拉列表中选择项时,应用程序将组件的 selected 属性设置为选定列表项的返回值。
列表框 selected 对于 items 属性,为列表中的每个项指定显示标签和返回值。selected 属性返回对象,或者在选中 multiple 属性时,返回与返回值类型相同的对象数组。

如果使用缺省选项组件指定项和返回值,则 selected 属性将返回 String,或者在 multiple 属性为 true 时,返回 String 对象数组。
如果 multiple 属性为 false,则组件的 selected 属性的值与选定列表项的返回值匹配。如果 multiple 属性设置为 true(以允许用户选择多个项),则必须将 selected 属性绑定到 Object 数组、基元数组或 java.util.List。如果使用 java.util.List,则必须为列表成员的类型指定转换器,除非这些成员是 String 对象。数组包含与选定项的返回值匹配的值。
单选按钮(不属于组) selected 缺省情况下,类型为 boolean。但是,可以绑定到诸如 BooleanByteCharacterDoubleFloatIntegerLongShortString 之类的包装器类型,绑定到其中一种包装器类型的基元形式,或绑定到应用程序定义的对象值。 使用 isChecked() 方法可以确定是否已选中单选按钮。如果组件的 selected 属性的值与 selectedValue 属性的值匹配,则认为已选中该组件。缺省情况下,selectedValue 设置为 true
单选按钮组 selected 对于 items 属性,为每个单选按钮指定显示标签和返回值。selected 属性返回与返回值类型相同的对象。如果使用缺省选项组件指定项和返回值,则 selected 属性将返回 String 当页面访问者选择单选按钮时,应用程序将单选按钮组的 selected 属性设置为选定单选按钮的返回值。
复选框(不属于组) selected 缺省情况下,类型为 boolean。但是,可以绑定到诸如 BooleanByteCharacterDoubleFloatIntegerLongShortString 之类的包装器类型,绑定到其中一种包装器类型的基元形式,或绑定到应用程序定义的对象值。 使用 isChecked() 方法可以确定是否已选中复选框。如果组件的 selected 属性的值与 selectedValue 属性的值匹配,则认为已选中该组件。缺省情况下,selectedValue 设置为 true
复选框组 selected 对于 items 属性,指定显示标签和返回值。selected 值返回与返回值类型相同的对象数组。如果使用缺省选项组件指定项和返回值,则 selected 属性将返回 String 对象数组。 selected 数组中的值与选中复选框的返回值匹配。
日历 selectedDate java.util.Date  
文件上载 uploadedFile com.sun.rave.web.ui.model.UploadedFile 出于安全考虑,uploadedFile 属性设置为只读。

UploadedFile 接口具有多种方法,用于获取文件的名称和大小、按 String 获取文件的内容,以及将内容写入磁盘。要了解更多信息,请在 Java 源代码中右键单击声明语句中的 UploadedFile,然后从弹出式菜单中选择“显示 Javadoc”。

UploadedFile.getOriginalName() 方法将返回客户端文件系统中的原始文件名,该名称由浏览器提供。在大多数情况下,这是基本文件名,不含路径信息。但是,一些浏览器包含路径信息。

注意:各种浏览器以不同的方式呈现文件上载组件。通常组件在浏览器中看起来比在可视设计器中小。
添加删除列表 selected Object 数组 对于 items 属性,指定显示标签和返回值。selected 数组中的值与选定项的返回值匹配。
 
验证用户输入
 
您可以使用以下功能来验证用户输入。当一个或多个输入字段验证失败时,Web 应用程序将重新呈现页,以红色突出显示无效输入的关联标签(如果有),并将错误消息发送到消息组组件和关联的消息组件(如果它们存在于页面上)。
  • 必需的输入。每个输入组件都提供了一个 required 属性。当该属性设置为 true 时,Web 应用程序将自动验证输入是否具有值。

  • 值转换。常规信息部分中所述,IDE 提供了几个可应用于输入组件的转换器。转换在验证过程开始之前执行。如果页面访问者提供了应用程序无法将其转换为指定数据类型的值,则 Web 应用程序将拒绝输入并发送一条错误消息。此错误消息显示在消息组组件和关联的消息组件(如果它们存在于页面上)中。数值转换器是一种很有用的转换器,因为您可以使用它来指定输入必须匹配的模式。

  • 输入验证。 IDE 提供了三种可以应用于任何输入组件的验证组件:

    • 双精度范围验证器。检查组件的转换值是否在某个范围内。该值必须是浮点型或可转换为浮点型。
    • 长度验证器。检查组件的本地值的长度是否在某个范围内。该值必须是 String
    • 长型范围验证器。检查组件的本地值是否在某个范围内。该值必须为任何数值类型或可以转换为 long 型的 String

    或者,您可以通过右键单击组件并选择“编辑事件处理程序”> "Validate",添加自己的验证方法。此菜单项将创建一种验证方法,并将该方法注册为验证事件侦听程序。该验证方法接受 FacesContextUIComponentObject(值),并抛出 ValidatorException

    与转换错误一样,应用程序也将验证错误消息发送到消息组组件和关联的消息组件(如果它们存在于页面上)。

    注意:您可以将验证器应用于组件,也可以为组件注册验证事件处理程序,但不能同时执行这两种操作。通过以下方法可以应用验证器:将验证器拖放到组件上,或者从组件的 validator 属性的下拉菜单中选择验证器。通过从弹出式菜单中选择“编辑事件处理程序”> "Validate",可以注册验证事件处理程序。任一操作都将设置 validator 属性和 validate 属性。

    Web 应用程序在调用任何值更改侦听程序和操作侦听程序之前执行所有验证。如果出现一个或多个验证错误,则不调用值更改侦听程序和操作侦听程序,而且 Web 应用程序将重新呈现页,以便页面访问者可以更正问题。

  • 更改时立即处理。如果希望浏览器在页面访问者更改组件的值后立即提交页,请右键单击组件,然后从弹出式菜单中选择“更改时自动提交”。

  • 停用转换和验证。有时您可能希望停止对页面上的某些输入组件进行处理(其中包括转换和验证)。您可以使用 IDE 的虚拟表单设置来指定给定操作可处理哪些字段。例如,当有人单击“取消”按钮时,您可能希望绕过对所有输入字段的处理。或者,页面上可能有两个按钮,而且您仅希望根据被单击的按钮来提交字段的子集。

    请注意,您也可以使用 immediate 属性来限制对输入值的处理。但是,虚拟表单的功能则更易于使用。例如,对于在早于其他组件的 JavaServer Faces 生命周期阶段中将其 immediate 属性设置为 true 的组件,Web 应用程序将调用其转换、验证和值更改侦听程序(如果是操作组件,则调用操作侦听程序)。也就是说,在出现常规转换过程之前和在后续进程验证阶段中出现验证之前,将在应用请求值阶段中对 immediate 属性设置为 true 的组件调用这些处理步骤。相反,虚拟表单要简单得多,因为它们不改变 JavaServer Faces 生命周期。有关虚拟表单的详细信息,请参见使用虚拟表单教程。
当页面访问者提交页时,Web 应用程序将按以下顺序执行输入验证:
  1. 转换
  2. 必需的输入
  3. 验证
注意:仅当实际发生值更改且所有验证都成功时,才会出现值更改事件。
 
要了解有关事件处理的详细信息,请参见 Sun Java Studio Creator 2 中的事件处理生命周期技术文章。要了解有关数据转换和验证的详细信息,请查看以下教程:
处理值更改事件
 
当输入组件的验证成功且提交的值与显示的值不同时,使用 IDE 生成的 Web 应用程序将为该输入组件发送值更改事件。您可以将一个方法注册为值更改事件处理程序,用于响应此类事件。例如,您可以编写一个在用户更改主要值时更改详细数据的方法,然后将该方法注册为值更改侦听程序。当页面访问者更改了主要值并提交页时,Web 应用程序将调用该方法,这样就会更新要匹配的详细数据。
 
应用程序按以下顺序引发事件:
  1. 首先引发 immediate 属性设置为 true 的组件的事件(按照深度优先的原则遍历组件树)。

  2. 然后引发 immediate 属性未设置为 true 的输入组件的值更改事件(按照深度优先的原则遍历组件树)。

  3. 最后引发 immediate 属性未设置为 true 的命令组件的操作事件(按照深度优先的原则遍历组件树)。
创建和注册值更改事件处理程序的一种快速方法是:在可视设计器中双击输入组件。执行此操作时,IDE 将创建一个方法,并将该方法注册为组件的值更改事件侦听程序。组件的 valueChange 属性将显示已注册的事件处理程序的名称(如果有)。
 

操作和链接组件

 
使用操作和链接组件可以让页面访问者从一个页面移动到下一个页面以及提交输入。下图显示了组件面板所提供的操作和链接组件。
 
图 7:操作和链接组件
图 7:操作和链接组件
 
简单页面导航
 
如果您希望用户通过单击组件移动到特定页面,但不希望浏览器提交任何用户输入,则可以使用超级链接组件、图像超级链接组件、标签组件或树节点组件,并在组件的 url 属性中键入目标页的路径,如 /faces/Page1.jsp
 
动态页面导航
 
通过页面导航编辑器,您可以指定将用户操作和决策逻辑结果映射到目标页的导航规则。通过将一条已命名的连线从链接或操作组件拖动到目标页,可以指定映射。您还必须为返回结果(此结果为等于连线名称的 String 值)的组件创建操作处理程序。您可以使用组件的 action 属性来创建操作处理程序。
 
当页面访问者单击组件时,浏览器将提交输入(如果有),而且操作处理程序返回结果。服务器在导航规则映射中查找结果,以确定用于响应的页。如果该结果没有导航规则,则服务器将重新显示当前页。您可以编写操作处理程序,使其根据业务逻辑返回不同的结果。
 
注意:当您同时设置了 urlaction 属性时,将优先采用 action 处理程序。
 
注意:在此版本的 IDE 中,必须使用 Portlet 应用程序中的 action 属性来链接到应用程序中的其他页面,因为指向其他页面的 URL 在 Portlet 中不起作用。
 
有关页面导航的详细信息,请参见使用简单页面导航使用动态页面导航教程。有关在 Portlet 中导航的其他信息,请参见开发 Portlet 应用程序教程。
 

布局组件

 
组件面板包含几个布局组件,用于帮助您在页面上排列组件以及按有用的方式显示组件,如下图所示。
 
图 8:布局组件
图 8:布局组件
 
下表说明了每个布局组件的用途,并描述了如何使用各个组件。
 
组件 用法
Breadcrumbs



通过 Breadcrumbs 组件,您可以布置由右尖括号 (>) 分隔的一系列链接组件。通常,您可以使用 Breadcrumbs 组件来向页面访问者显示页面所在部分或分支的分层结构。当您添加 Breadcrumbs 组件时,IDE 将自动为应用程序中的每个页面添加一个嵌套的超级链接组件。您可以使用“概要”窗口来删除、添加和重新排列嵌套的超级链接组件。

或者,您也可以将 pages 属性绑定到 Hyperlink 对象数组,其中每个超级链接都表示一页。为确保正确地显示,每个超级链接组件都必须至少具有 text 属性的值以及 url 属性或 action 属性的值。
页面片段框



通过页面片段框组件,您可以跨若干页重用同一内容。当您更改页面片段的内容时,所做的更改将出现在使用该页面片段的所有页上。

有关详细信息,请参见使用页面片段教程。
页面分隔符



使用页面分隔符组件可以创建用于分隔页面上各项的水平线。您还可以使用页面分隔符组件来分隔网格面板单元格或组面板组件中的各项。
树和树节点



使用树组件和嵌套的树节点组件可以采用树状结构呈现可展开的列表。树通常用于 Web 应用程序中的导航和在嵌套数据(如文件系统结构)中导航。要添加其他节点,请右键单击“概要”窗口中的树组件或树节点组件,然后选择“添加树节点”。节点的缺省图像是文件夹图标或页面图标,具体取决于该节点是否具有子节点(嵌套节点)。

使用 action 属性可以指定页面访问者选择树节点时的操作处理程序。使用 actionListener 属性可以指定页面访问者打开或关闭节点时的处理程序。

提示:缺省情况下,每次页面访问者展开或折叠节点时,浏览器都会向服务器发出请求。要使展开和折叠改为发生在客户端上,请将 clientSide 设置为 true。

有关详细信息,请参见使用树组件教程。
标签集和标签



您可以将标签集组件用作导航工具,或者也可以使用它来显示同一页上的不同布局。要添加标签,请右键单击“概要”窗口中的标签集节点,然后选择“添加标签”。

要将标签集组件用作导航工具,请为每个导航路径添加一个标签,然后使用页面导航编辑器指定每个标签的目标页。

要使用标签集组件显示同一页上的不同布局,请添加所需数目的标签。然后,在可视设计器中选择每个标签,并添加该标签的组件。

标签集组件的 selected 属性显示当前选定标签的 id。

litemini 属性一起使用可以呈现标签的轻量版本。仅当 mini 属性为 true 时,lite 属性才生效。

标签组件包含嵌套的布局面板组件。要将组件添加到标签,请将这些组件拖放到布局面板组件中。
布局面板



此面板类似于一个页面,因为通过设置布局面板组件的 layoutPanel 值可以指定网格布局或流布局。在流模式下,组件从左到右排列。在网格模式下,组件按您拖放它们的位置定位。
属性表单和属性



通过属性表单组件,您可以快速布置一组带标签的组件。属性表单组件可提供并布置标签和类别,您所做的就是添加组件。要添加类别,请右键单击属性表单节点,然后选择“添加属性表单类别”。要添加属性,请右键单击类别节点,然后选择“添加属性”。要将组件添加到属性,请将组件从组件面板拖放到“概要”窗口中的属性节点上。

要在属性表单的顶部显示指向每个类别的链接,请将属性表单组件的 jumpLinks 设置为 true。您可以使用属性组件的 labelAlign 属性将标签左对齐或右对齐。如果不希望标签文本换行,请将 noWrap 设置为 truehelpText 属性的值将出现在属性的嵌套组件的下方。
网格面板



使用网格面板组件可以按行和按列排列组件。在将网格面板组件添加到页面后,将其 columns 属性设置为每行的列数。当您将组件添加到网格面板组件时,IDE 会跨行添加组件,直到填满行为止。IDE 将根据需要添加行。
组面板



使用组面板组件可以在流布局模式下组合嵌套组件。浏览器以彼此相邻的方式放置组件,并根据需要将组件自动换到下一行。当页面访问者调整页面大小时,组件会上移一行或下移一行。组面板组件对于嵌套组件(如在页面警报组件内嵌套按钮组件或在网格面板组件的单元格内嵌套组件)是很有用的。

缺省情况下,block 属性设置为 false,这意味着将使用 <span> 标记呈现组件,并忽略高度和宽度样式设置。如果需要为组件设置特定的高度或宽度,请将 block 属性设置为 true。

如果页面处于流布局模式,则将 block 属性设置为 true 可使浏览器将组件呈现在它自己单独的行上。该组件前后的组件则出现在其他行上。




使用表组件,可以轻松地显示表格数据,如数据库表中的数据或者数组或列表中的信息。填充表组件的最快速方法是:为表格数据创建数据提供器,然后将表组件绑定到该数据提供器,如使用数据绑定组件访问数据库教程中所示。

右键单击表组件,然后选择“表布局”,将显示一个对话框,您可以通过该对话框执行以下操作:
  • 设置表的标题
  • 添加和删除列
  • 设置每列的标题、脚注和组件类型(如静态文本、文本字段或按钮)
  • 启用排序和添加各种排序按钮
  • 启用分页
  • 指定单元格为空时应该显示的文本
使用表的嵌套 TableRowGroup 组件可以处理表的数据值。例如,如果列具有一个按钮,则使用 TableRowGroup 组件的 getRowKey() 可以确定数据的基础行,如下面的代码样例所示。
 
代码样例 2:处理表中的按钮
public String submitTableButton_action() {
  RowKey rowkey = tableRowGroup1.getRowKey();
  getSessionBean1().setSelectedPersonId(
    travelDataProvider.getValue("PERSON.PERSONID", rowkey).toString());
  return "showDetail";
}
 
提示:在可视设计器中使用嵌套组件时,按 Esc 键可以选择其包含(父)组件。您还可以使用“概要”窗口来选择包含父组件以及重新排列嵌套组件的顺序。
 

非可视组件

 
IDE 提供了两种非可视组件。
 
组件 用法
隐藏字段 隐藏字段组件是非可视表单字段。隐藏字段组件的典型用法是存储值以供 JavaScript 使用。由于已提交隐藏字段组件的值,因此服务器端代码(如页面 Bean)可以检查 JavaScript 代码进行的更改。您还可以使用隐藏字段组件将值传递到重新呈现的页面。但是,请求 Bean 属性和会话 Bean 属性也服务于该功能。
锚点 使用锚点组件可以在页面内放置链接目标。锚点组件相当于 HTML <a name=<目标名称>>。该组件的 id 是目标名称。例如,如果锚点组件的 id 是 anchor1,则可以将超级链接的 url 属性设置为 #anchor1 以跳转到该锚点组件的位置。
 

小结

  • 组件面板提供了各种组件,用于显示信息、接受用户输入、启用表单提交和页面导航,以及配置页面布局。
  • 使用“属性”窗口可以配置组件的外观和行为。此外,还可以使用属性的 gettersetter 方法来通过编程方式定义属性的值。
  • 可以将大多数属性绑定到数据。
  • IDE 负责绑定数据的值转换。此外,还可以使用转换器来转换组件值。
  • 用于验证输入的工具包括 required 属性、验证器和验证事件处理。
  • 使用虚拟表单可以简明地控制在提交表单时处理哪些组件。
  • 使用操作方法和 URL 可以定义页面导航。
  • 使用值更改事件处理可以处理输入。

 
此页的最新修改时间:2006 年 2 月 10 日