rich标签：suggestionbox的用法

6.11.10< rich:suggestionbox>，从3.0.0开始可用

6.11.10.1描述

该组件为任何输入文本组件如<h:inputText>添加按钮建议能力。

图6.164.<rich:suggestionbox>组件。

6.11.10.2主要功能

l为任何输入文本组件添加按钮建议能力。

l可以渲染表作为一个弹出建议。

l可以指向任何Ajax请求页面状态指示符。

l轻松可定制观感。

l完全可换肤组件。

l以Ajax请求提交组件管理区。

l通过属性在Ajax请求管理后，灵活地更新组件列表。

l设置Ajax请求生成限制。

l键盘导航支持

6.11.10.3使用细节

6.11.10.3.1主要属性

有三个主要的组件属性：

l"for"，包含一个输入组件的ID，为它提供建议支持。

l"suggestionAction"，定义一个方法，用于请求获取一个建议数据集合。

l"var"，定义一个集合名，在迭代时它提供对当前行的一个访问。

要在一个页面上创建一个最简单的变体，使用以下的语法：

...

<h:inputText id="city"value="#{capitalsBean.capital}" />

<rich:suggestionbox for="city"var="result"

suggestionAction="#{capitalsBean.autocomplete}">

<h:column>

<h:outputText value="#{result.name}"/>

</h:column>

</rich:suggestionbox>

...

下面是管理的bean:

...

public class SBbean {

privateArrayList<Capital> capitals = newArrayList<Capital>();

privateArrayList<String> capitalsNames = newArrayList<String>();

privateList<SelectItem> capitalsOptions =new ArrayList<SelectItem>();

private String capital = "";

public List<Capital>autocomplete(Object suggest) {

String pref = (String) suggest;

ArrayList<Capital>result = newArrayList<Capital>();

Iterator<Capital>iterator = getCapitals().iterator();

while (iterator.hasNext()) {

Capital elem = ((Capital) iterator.next());

if ((elem.getName() != null&&elem.getName().toLowerCase().indexOf(pref.toLowerCase()) == 0)||"".equals(pref)) {

result.add(elem);

}

}

return result;

}

public SBbean() {

URL rulesUrl =getClass().getResource("capitals-rules.xml");

Digester digester =DigesterLoader.createDigester(rulesUrl);

digester.push(this);

try {

digester.parse(getClass().getResourceAsStream("capitals.xml"));

} catch (IOException e) {

throw new FacesException(e);

} catch (SAXException e) {

throw new FacesException(e);

}

capitalsNames.clear();

for (Capital cap : capitals) {

capitalsNames.add(cap.getName());

}

capitalsOptions.clear();

for (Capital cap : capitals) {

capitalsOptions.add(new SelectItem(cap.getName(),cap.getState()));

}

}

public String addCapital(Capital capital) {

capitals.add(capital);

return null;

}

}

在上面的例子中，当建议项目（city）被选时，它被作为<h:inputTextid="city"/>的一个值被设置。

结果：

图6.165. 简单的<rich:suggestionbox>。

<rich:suggestionbox>可以获得任何集合，并且在一个弹出列表中以多列方式输出它。如果从建议列表中，一个特定的行被选或者点击，"fetchValue"属性指向被插入到输入字段的数据。因此，当选取某些字符串时，输入收到正确的值。

...

<h:inputText id="city"value="#{capitalsBean.capital}" />

<rich:suggestionbox for="city"var="result" fetchValue="#{result.state}"suggestionAction="#{capitalsBean.autocomplete}">

<h:column>

<h:outputTextvalue="#{result.name}" />

</h:column>

<h:column>

<h:outputTextvalue="#{result.state}" />

</h:column>

</rich:suggestionbox>

...

在上面的例子中，如果你选择任何字符串，输入字段会从包含#{result.state}的第二列收到相应的值。

结果：

图6.166.使用了多列输出的<rich:suggestionbox>。

有一个名为"tokens"非常重要的属性，它指定在某些字符串队列组后定义分隔符，作为一个新的前缀，从这个分隔符开始，而不从前面的字符开始。

例子：

...

<h:inputText id="city"value="#{capitalsBean.capital}" />

<rich:suggestionbox for="city"var="result"

suggestionAction="#{capitalsBean.autocomplete}"

tokens=",">

<h:column>

<h:outputTextvalue="#{result.name}" />

</h:column>

</rich:suggestionbox>

...

这个例子显示，当一个城市被选取时，输入一个逗号和一个首字母，会再次调用Ajax请求，但它根据最新的令牌提交一个值。

图6.167.使用了选择字母的<rich:suggestionbox>。

对于多个定义，使用" , . ; []"之一的语法作为"tokens"属性的一个值，或者链接一个参数到某些bean特性，它们传送分隔符集合。

6.11.10.3.2JavaScript API

<rich:suggestionbox>组件有这样一种功能，以对象作为选择。如果你想在客户端边获得到以对象为选择的项目，你应该设置"usingSuggestObjects"属性的值为"true"。然后，你应该在"onobjectchange"属性中指定JavaScript方法，并且传递suggestion对象作为一个参数：

...

<h:inputText id="city"value="#{capitalsBean.capital}" />

<rich:suggestionbox for="city"var="result" suggestionAction="#{capitalsBean.autocomplete}"onobjectchange="processObjects(suggestion)"usingSuggestObjects="true">

<h:column>

<h:outputText value="#{result.name}"/>

</h:column>

</rich:suggestionbox>

<h:panelGroup>

<divid="state"></div>

</h:panelGroup>

...

当项目被选择时，你可以在客户端边把它作为一个对象获得，并且使用getSelectedItems()方法访问任何对象的属性：

<scripttype="text/javascript">

function processObjects(suggestionBox) {

var items = suggestionBox.getSelectedItems();

var state;

if (items&&items.length > 0) {

for ( var i = 0; i < items.length;i++) {

state = items[i].state;

}

document.getElementByIdx_x('state').innerHTML ="State: "+state;

}else{

document.getElementByIdx_x('state').innerHTML ='';

}

}

</script>

结果：

图6.168getSelectedItems()方法的用法。

6.11.10.3.3其他的属性和facets

除了普通的用于Ajax动作组件，并限制请求数量和频率的属性之外，<rich:suggestionbox>自己多了一个限制请求的属性："minChars"属性。在调用Ajax请求处理建议之后，这个属性限定输入到一个字段的字符数量。

如果自动完成返回空的列表，也可以定义显示什么。属性"nothingLabel"或者有相同名字的facet也可用于这个目的：

...

<rich:suggestionbox for="city"var="result" suggestionAction="#{capitalsBean.autocomplete}"nothingLabel="No cities found">

<h:column>

<h:outputText value="#{result.name}"/>

</h:column>

</rich:suggestionbox>

...

结果：

图6.169.使用空列表的<rich:suggestionbox>。

为更进一步定制<rich:suggestionbox>，你可以使用facets：

<h:inputText id="city"value="#{capitalsBean.capital}" />

<rich:suggestionbox for="city"var="result"suggestionAction="#{capitalsBean.autocomplete}">

<f:facetname="nothingLabel">

<h:outputText value="No citiesfound" />

</f:facet>

<f:facetname="header">

<h:outputText value="Select yourcity" />

</f:facet>

<h:column>

<h:outputText value="#{result.name}"/>

</h:column>

</rich:suggestionbox>

..

结果：

图6.170.<rich:suggestionbox>facets

有关"process"属性的用法信息，你可以在“决定处理什么”章节找到。

有关其他特性的例子，你可以在维基文章“其他特性”找到[http://wiki.jboss.org/wiki/RichFacesSuggestionGettingAdditionalProperties]

6.11.10.4参考数据

<rich:suggestionbox>属性表[../../tlddoc/index.htmlrich/suggestionbox.html]。

表6.202组件关联的参数

表6.203. Facets

表6.204带有相应皮肤参数的样式类（选择器）

表6.205无皮肤参数的样式类（选择器）

有关样式类重定义的所有需要的信息，你可以在“定制样式类的定义”章节找到。

6.11.10.5关联的资源链接

组件的用法以及它们的例子和资源，请浏览在RichFacesLivedemo的<rich:suggestionbox>页面：[http://livedemo.exadel.com/richfaces-demo/richfaces/suggestionBox.jsf?c=suggestionBox]

在JBoss Portal的RichFacescookbook包含了使用<rich:suggestionbox>的各方面的一些文章：

l"动态创建建议框"[http://www.jboss.org/community/docs/DOC-11851]。

l"从<rich:suggectionbox>得到其他特性"[http://www.jboss.org/community/docs/DOC-11865]。

爱华网本文地址 » http://www.aihuau.com/a/25101011/64170.html