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
The component adds on-keypress suggestions capabilities to any input text component like <h:inputText> .
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
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<Capital> capitals = new ArrayList<Capital>();
private ArrayList<String> capitalsNames = new
ArrayList<String>();
private List<SelectItem> capitalsOptions = new
ArrayList<SelectItem>();
private String capital = "";
public List<Capital> autocomplete(Object suggest) {
String pref = (String) suggest;
ArrayList<Capital> result = new ArrayList<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;
}
}
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 && 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:
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 .
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.
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> :
