Create new RichFaces Documentation Jira issue

This will launch the RichFaces Jira page - to complete your feedback please login if needed, and submit the Jira.

JBoss.orgCommunity Documentation

6.11.10.  < rich:suggestionbox > available since 3.0.0

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


There are 3 main component attributes:

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:


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:


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:


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.

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.lengthi++) {
                state = items[i].state;
                }
                document.getElementById('state').innerHTML = "State: "+state;
                }else{
                document.getElementById('state').innerHTML = '';
                }
                }
                </script> 

Here is a result:


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:


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:


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.

Table of <rich:suggestionbox> attributes .





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

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