RichFaces 简介（5）

look_w

Suggestion Box 组件如果您经常使用论坛和邮件列表，那么您迟早会看到人们如何将数千乃至数百万条目下载到一个下拉列表中。Suggestion Box 组件（参见 ）提供一种方式来显示有效的选择，使用户不必面对那样极端的情况。        实际上，这一点正是我开始研究 RichFaces 和类似套件的主要原因，因为应用程序中有些输入项，例如城市，有太多的可选项，这种情况下下拉列表已经不适用了。Suggestion Box 的功能类似于我们熟悉的很多桌面应用程序中提供的自动完成组件。显然，为了让这种功能有机会在 Web 应用程序中有效地工作，必须借助 Ajax 提交。
显示了该功能所需的三种不同的组件：label 和 input text（注意，这些是标准的 JSF RI 组件）、        <a4j:region>以及        <rich:suggestionbox>。        <h:inputText>使用        getCity()和 setCity()        方法和 managed bean 来为它提供值。字段的输入可以通过键盘，也可以通过从 Suggestion Box 中进行选择。
清单 11. RichFaces Suggestion Box 组件

1 2 3 4 5 6 7 8 9 10 11 12 13

<label for="CityID">#{dWRFD1.city}:</label> <h:inputText name="City" id="CityID" size="10"    value="#{dWRFD1Handler.city}" /> <a4j:region renderRegionOnly="true"> <rich:suggestionbox id="citySuggestionBoxId" for="CityID"    suggestionAction="#{dWRFD1City.suggest}" var="result"    eventsQueue="foo" ignoreDupResponses="true"    selectedClass="selCtl" >    <h:column>      <hutputText value="#{result}" style="font: menu;" />    </h:column> </rich:suggestionbox> </a4j:region>

<a4j:region>表示在 Ajax 提交时发送的一个区域。您需要清楚，通常情况下，如果没有包括任何区域，RichFaces 会假定一个默认区域，这个区域的范围是从        <f:view>到        </f:view>。这实际上就是整个页面。当我第一次使用        <rich:suggestionbox>时，本来一切都正常，但是在单步调试时却发现，所有其他字段也会随之一起提交，也会被验证、转换并经过 JSF 的整个生命周期。简单地说，这对于需要对每次按键都作出响应的组件来说不是件好事。RichFaces Developer Guide（参见 ）中有一段内容讨论了通常情况下适用的另一种形式的 Ajax 提交，应该给出了正确的方法：                                                        

注意，"ajaxSingle"="true" 可以减少将来的传输，但是不会阻止服务器端对其他输入组件的解码。有些 JSF 组件，例如 <h:selectOneMenu>，会重新识别请求映射值中作为 null 值丢失的数据，并尝试通过验证过程并得到失败的结果。因此，必要时可以使用 <a4j:region> 来限制将在服务器端处理的组件树的一部分。

至于 renderRegionOnly属性，RichFaces         Developer Guide 这样描述：

禁止在活动区域以外的 AJAX 响应内容中呈现的标志。如果该属性被设为 “true”，那么区域以外的组件不会包括在 AJAX 响应中。如果该属性被设为 “false”，那么将会在整个树中搜索要加入到响应中的组件。该属性的默认值为 “false”。

在本例中，我们希望惟一回到服务器的元素是        suggestionAction方法请求和它的        Object参数（通过键盘当前输入的        String）。返回时，应该只更新和呈现 Suggestion Box 内容。
Suggestion Box 本身需要的最基本的属性是        suggestionAction、var和至少一个用于显示结果的列。        suggestionAction方法是另一个 managed bean 中的        suggest()，这个 bean 基于 demo 代码中的第二个 Java 类 com.dW.City。该方法的签名为：public List suggest(Object anObject)。
在 demo 代码中，在初始化时首先创建一个以 A 和 J 开头的城市的列表。如果用户在 City 文本域中按下空格键，则返回完整的列表。如果按下 A 键，则返回一个包含以 A 开头的城市的子列表。对于以 J 开头的城市也是如此。每键入一个字符，结果就会随之缩小。在您自己的代码中，只要与输入相符，你可以做任何事情。在实际应用程序中，结果来自一个有限的数据库集合，这也许是最常见的。如果您熟悉这种数据，那么也许可以修改一下这个方法，看能不能优化结果。例如，我曾经碰到一个示例，有些按键是可以忽略的，所以该方法可以直接返回，而不必访问数据库了。
var属性定义一个迭代变量，以便在输出列内容时使用。它与        List Shuttle 组件的 var属性的用法是一样的。
eventsQueue属性不是必需的，但是我建议您也同样对待。您只需添加该属性，并提供一个名称。它会执行两个重要的服务：

• 将方法调用（事件）放入队列，以保证顺序。在队列中，在前一个方法请求返回之前，不会发送下一个方法请求。
• 如果队列中有多个同种类型的事件，那么只发送最新的那个。例如，Suggestion Box 对于每次按键都发送一个请求。如果当之前的请求返回时队列中有多个按键请求，那么只将最新的按键请求发送到服务器。记住，虽然对于每次按键都会发送请求，但是发送的参数是 input text 组件的整个内容。

ignoreDupResponses属性的作用应该是不言而喻的。
selectedClass是应用于该组件的一个 CSS 类。RichFaces 使用皮肤（skin）的概念。这是通过组件上的选择栏实现的。我自己的应用程序有几个 RI 下拉列表在选择栏中使用了系统颜色。Suggestion Box 使用        classic皮肤颜色，这让外观看起来有些不一致。SelCtl类告诉 Suggestion Box         使用系统的高亮显示颜色。
存放标签Tab Panel 组件（参见 ）很容易使用。通常的 RichFaces 属性在该组件中都可以使用，但是您将使用的主要属性是 switchType。该属性的默认值为        server，但是您可能最常用的值反而是        client。ajax属性也可以使用。如 所示，这里使用一个典型的        RichFaces “三明治式” <rich:tabPanel>        元素和堆叠的 “三明治式” <rich:tab>元素来创建一组选项卡式页面：
清单 12. RichFaces Tab Panel 组件

1 2 3 4 5 6 7

<rich:tabPanel switchType="client" > <rich:tab label="#{dWRFD1.info}">    #{dWRFD1.resultText} </rich:tab> <rich:tab label="#{dWRFD1.result}"> </rich:tab> </rich:tabPanel>

label属性用于显示选项卡的名称。在 demo 代码中，和通常一样，label的值是从资源包中提取的。和 Panel Bar Items 类似，选项卡可以包含任何类型的组件。对于 demo，我使用资源包文本作为 Info 选项卡的内容，使用 Simple Toggle Panels 作为 Result 选项卡的内容。
完成我猜您可能在想：“这些都很简单”。这就对了。一旦理解了 RichFaces 的基础，大多数组件使用起来都很简单。因此，对于 Simple Toggle Panel         （参见 和 ）我只讲一点点，其他的就留给您作为练习吧。                                                        
清单 13. RichFaces Simple Toggle Panel 组件

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19

<h:panelGrid columns="1" width="50%"> <rich:simpleTogglePanel switchType="ajax"     label="#{dWRFD1.calComp} #{dWRFD1.value}" opened="false" >    #{dWRFD1Handler.selectedDate} </rich:simpleTogglePanel> <rich:simpleTogglePanel switchType="ajax"     label="#{dWRFD1.lsComp} #{dWRFD1.value}" opened="false" >    #{dWRFD1Handler.orderByTarget} </rich:simpleTogglePanel> <rich:simpleTogglePanel switchType="ajax"     label="#{dWRFD1.sbComp} #{dWRFD1.value}" opened="false" >    #{dWRFD1Handler.city} </rich:simpleTogglePanel> <rich:simpleTogglePanel switchType="ajax"     label="#{dWRFD1.face}" opened="false" >    <img src="images/myphoto.jpg"       height="80" width="64"/> </rich:simpleTogglePanel> </h:panelGrid>

Simple Toggle Panel 由一个条状栏和一个内容显示组成，后者可以是任何组件。通过单击条状栏，可以显示或隐藏内容，这非常像只有一个项目的 Panel Bar。注意，        switchType属性再次出现。        opened属性确定是否在第一次显示时显示内容。对于这个 demo，我将多个 Simple Toggle Panels 放在一个        JSF RI <h:panelGrid>中，后者被放在一个 Tab 中，而这个 Tab 则被放在一个 Tab Panel 中。