6.11.10. < rich:suggestionbox > available since 3.0.0

### Create new RichFaces Documentation Jira issue

Summary
255 characters left
Description
Environment
This will launch the RichFaces Jira page - to complete your feedback please login if needed, and submit the Jira.

JBoss.org Community Documentation

- Prev
- Next

### 6.11.10. < rich:suggestionbox > available since 3.0.0

expand all

#### 6.11.10.1. Description

The component adds on-keypress suggestions capabilities to any input text component like <h:inputText> .

Figure 6.164. <rich:suggestionbox> component

#### 6.11.10.2. Key Features

- Adds "onkeypress" suggestions capabilities to any input text component

- Possible to render table as a popup suggestion

- Can be pointed to any Ajax request status indicator of the page

- Easily customizable look-and-feel

- Fully skinnable component

- Managing area of components submitted on Ajax request

- Flexible list of components to update after Ajax request managed by attributes

- Setting restriction to Ajax request generation

- Keyboard navigation support

#### 6.11.10.3. Details of Usage

expand all

##### 6.11.10.3.1. Main attributes

There are 3 main component attributes:

- "for" contains an ID of an input component for which the suggestion support is provided

- "suggestionAction" defines the method to get a collection of suggestion data on request

- "var" defines a collection name that provides an access for the current row while iterating through

To create the simplest variant on a page use the following syntax:

    ...

                    <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>

                    ...

There is a managed bean:

    ...

                    public class SBbean {

                    private ArrayList&lt;Capital&gt; capitals = new ArrayList&lt;Capital&gt;();

                    private ArrayList&lt;String&gt; capitalsNames = new

                    ArrayList&lt;String&gt;();

                    private List&lt;SelectItem&gt; capitalsOptions = new

                    ArrayList&lt;SelectItem&gt;();

                    private String capital = "";

                    public List&lt;Capital&gt; autocomplete(Object suggest) {

                    String pref = (String) suggest;

                    ArrayList&lt;Capital&gt; result = new ArrayList&lt;Capital&gt;();

                    Iterator&lt;Capital&gt; iterator = getCapitals().iterator();

                    while (iterator.hasNext()) {

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

                    if ((elem.getName() != null &amp;&amp; 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;

                    }

                    }

In the example above when suggestion item (city) is selected it is set as a value of `<h:inputText id="city"/>` .

Here is a result:

Figure 6.165. Simple <rich:suggestionbox>

The <rich:suggestionbox> component could get any collection and outputs it in a popup in several columns. The "fetchValue" attribute points to the data that is inserted into the input field if a particular row is selected or clicked from the suggested list. Therefore when some string is chosen input receives the proper value.

    ...

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

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

                    fetchValue="#{result.state}"

                    suggestionAction="#{capitalsBean.autocomplete}">

                    <h:column>

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

                    </h:column>

                    <h:column>

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

                    </h:column>

                    </rich:suggestionbox>

                    ...

In the example above if you choose any string input will receive the corresponding value from the second column containing `#{result.state}` .

Here is a result:

Figure 6.166. <rich:suggestionbox> with output in several columns

There is also one more important attribute named "tokens" that specifies separators after which a set of some characters sequence is defined as a new prefix beginning from this separator and not from the string beginning.

Example:

    ...

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

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

                    suggestionAction="#{capitalsBean.autocomplete}"

                    tokens=",">

                    <h:column>

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

                    </h:column>

                    </rich:suggestionbox>

                    ...

This example shows that when a city is chosen and a comma and first letter character are input, Ajax request is called again, but it submits a value starting from the last token:

Figure 6.167. <rich:suggestionbox> with chosen word

For a multiple definition use either " `,.;[]` " syntax as a value for "tokens" attribute or link a parameter to some bean property that transmits separators collection.

##### 6.11.10.3.2. JavaScript API

There is such feature of the <rich:suggestionbox> component as object selection . If you want to get the selected item as object on the client side you should set the value of the "usingSuggestObjects" attribute to "true". After that you should specify JavaScript method in the "onobjectchange" attribute and pass the `suggestion` object as a parameter:

    ...

                    <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>

                    <div id="state"></div>

                    </h:panelGroup>

                    ...

When the item is selected you can get it as an object on the client side and use `getSelectedItems()` method to access any object properties:

    <script

                    type="text/javascript">

                    function processObjects(suggestionBox) {

                    var items = suggestionBox.getSelectedItems();

                    var state;

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

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

                    state = items[i].state;

                    }

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

                    }else{

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

                    }

                    }

                    </script>

Here is a result:

Figure 6.168. Usage of `getSelectedItems()` method

##### 6.11.10.3.3. Other attributes and facets

In addition to attributes common for Ajax action components and limiting requests quantity and frequency, the <rich:suggestionbox> has one more its own attribute limiting requests: the "minChars" attribute. This attribute defines characters quantity inputted into a field after which Ajax requests are called to perform suggestion.

There is possibility to define what is shown if the autocomplete returns empty list. Attribute "nothingLabel" or facet with the same name could be used for this purpose.

Example:

    ...

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

                    suggestionAction="#{capitalsBean.autocomplete}"

                    nothingLabel="No cities found">

                    <h:column>

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

                    </h:column>

                    </rich:suggestionbox>

                    ...

Here is a result:

Figure 6.169. <rich:suggestionbox> with empty list

You can also use facets for the further <rich:suggestionbox> customization:

    ...

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

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

                    suggestionAction="#{capitalsBean.autocomplete}">

                    <f:facet name="nothingLabel">

                    <h:outputText value="No cities found" />

                    </f:facet>

                    <f:facet name="header">

                    <h:outputText value="Select your city" />

                    </f:facet>

                    <h:column>

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

                    </h:column>

                    </rich:suggestionbox>

                    ...

Here is a result:

Figure 6.170. <rich:suggestionbox> facets

Information about the "process" attribute usage you can findin the "Decide what to process" guide section.

In RichFaces Wiki article about Additional Properties you can find example of getting additional properties.

#### 6.11.10.4. Reference Data

Table of <rich:suggestionbox> attributes .

Table 6.202. Component Identification Parameters

Name | Value
--- | ---
component-type | org.richfaces.SuggestionBox
component-class | org.richfaces.component.html.HtmlSuggestionBox
component-family | org.richfaces.SuggestionBox
renderer-type | org.richfaces.SuggestionBoxRenderer
tag-class | org.richfaces.taglib.SuggestionBoxTag

Table 6.203. Facets

Facet name | Description
--- | ---
nothingLabel | Redefines the content item if the autocomplete returns empty list. Related attribute is "nothingLabel"
popup | Redefines the content for the popup list of the suggestion
header | Defines the header content
footer | Defines the footer content

Table 6.204. Style classes (selectors) with the corresponding skin parameters

Class name | Description | Skin Parameters | CSS properties
--- | --- | --- | ---
.rich-sb-int | Defines the styles for a suggestion box table rows <tr> | generalSizeFont | font-size
generalFamilyFont | font-family
generalTextColor | color
.rich-sb-int-sel | Defines styles for a selected row | headerBackgroundColor | background-color
generalSizeFont | font-size
generalFamilyFont | font-family
headerTextColor | color
.rich-sb-ext-decor-2 | Defines styles for the second wrapper <div> element of a suggestion box exterior | panelBorderColor | border-color
additionalBackgroundColor | background-color
.rich-sb-shadow | Defines styles for a suggestion box shadow | shadowBackgroundColor | background-color
shadowBackgroundColor | border-color
shadowOpacity | opacity

Table 6.205. Style classes (selectors) without skin parameters

Class name | Description
--- | ---
.rich-sb-common-container | Defines styles for a wrapper <div> element of a suggestion container
.rich-sb-ext-decor-1 | Defines styles for the first wrapper <div> element of a suggestion box exterior
.rich-sb-ext-decor-3 | Defines styles for the third wrapper <div> element of a suggestion box exterior
.rich-sb-overflow | Defines styles for a inner wrapper <div> element
.rich-sb-int-decor-table | Defines styles for a suggestion box table
.rich-sb-cell-padding | Defines the styles for suggestion box table cells <td>

You can find all necessary information about style classes redefinition in Definition of Custom Style Classes section.

#### 6.11.10.5. Relevant Resources Links

Visit <rich:suggestionbox> page at RichFaces Livedemo for examples of component usage and sources.

RichFaces cookbook at JBoss Portal includes some articles that cover different aspects of working with <rich:suggestionbox> :

- " Creating suggestion box dynamically ";

- " Getting additional properties from <rich:suggectionbox> ".

- Prev6.11.9. < rich:inputNumberSpinner > ...
- Top of page
- Front page
- Next6.12. Rich Selects