⁠10.9. <rich:select>

The <rich:select> component provides a drop-down list box for selecting a single value from multiple options. The <rich:select> component can be configured as a <rich:autocomplete>, where it will accept typed input. The component also supports keyboard navigation. The <rich:select> component functions similarly to the JSF UISelectOne component.
The <rich:select> can optionally be used in an auto-completing mode, where the values in the drop-down list are provided dynamically using either the autocompleteMethod or autocompleteList attributes. If these attributes are omitted, the component operates in the traditional non-auto-completing mode. Refer to the individual attribute documentation to see which attributes are applicable only with an auto-completing select list. Additionally refer to Section 10.1, “<rich:autocomplete>” for details on configuring the ajax behaviour of the <rich:select> component.
⁠
<rich:select>

Figure 10.7. <rich:select>

⁠10.9.1. Basic usage

Simple usage of the <rich:select> component requires the value attribute to store the selected value. Additionally, child tags to manage the list of selections are required. The child tags can either be a number of <f:selectItem> tags or a <f:selectItems> tag which points to a data model containing a list of selection items. The value attribute is used to store the current selection.
⁠

Example 10.9. Selection items

Using multiple <f:selectItem> tags
​<rich:select>
​   <f:selectItem itemValue="0" itemLabel="Option 1" />
​   <f:selectItem itemValue="1" itemLabel="Option 2" />
​   <f:selectItem itemValue="2" itemLabel="Option 3" />
​   <f:selectItem itemValue="3" itemLabel="Option 4" />
​   <f:selectItem itemValue="4" itemLabel="Option 5" />
​</rich:select>
Using a single <f:selectItems> tag
​<rich:select>
​   <f:selectItems value="#{bean.options}" />
​</rich:select>
The arrow keys on a keyboard can be used to highlight different items in the list. If the control loses focus or the Enter key is pressed, the highlighted option is chosen as the value and the list is closed. Pressing the Esc key will close the list but not change the value.

⁠10.9.2. Using manual input

The <rich:select> component allows the user to type into a text field to scroll through or filter the list. By default, the <rich:select> component functions as a drop-down list with no manual input. To add keyboard support for manual input, set enableManualInput="true".
Once the user begins typing, the first available matching option is highlighted. If the typed text does not match any values in the list, no value is chosen and the drop-down list displays as empty. Other keyboard interaction remains the same as the basic drop-down list.
The standard JSF <h:selectOne> component does not offer this extended keyboard support. However, since the <rich:select> component is still based on the JSF UISelectOne component, it will not accept a value that does not match any items in the drop-down list. If an invalid value is entered, it is highlighted as erroneous and validation messages appear with the submission.

⁠10.9.3. Advanced options

Use the defaultLabel attribute to set a place-holder label, such as defaultLabel="select an option".
Server-side processing occurs in the same manner as for an <h:selectOneMenu> component. As such, custom objects used for selection items should use the same converters as for an <h:selectOneMenu> component.

⁠10.9.4. JavaScript API

The <rich:select> component can be controlled through the JavaScript API. The JavaScript API provides the following functions:
getValue()
Get the current value of the text field.
setValue(newValue)
Set the value of the text field to the newValue string passed as a parameter.
getLabel()
Return the default label of the control.
showPopup()
Show the pop-up list of completion values.
hidePopup()
Hide the pop-up list.

⁠10.9.5. Reference data

  • component-type: org.richfaces.Select
  • component-class: org.richfaces.component.UISelect
  • component-family: org.richfaces.Select
  • renderer-type: org.richfaces.SelectRenderer
  • handler-class: org.richfaces.view.facelets.AutocompleteHandler

⁠10.9.6. Style classes and skin parameters

⁠

Table 10.9. Style classes (selectors) and corresponding skin parameters

Class (selector) Skin Parameters Mapped CSS properties
.rf-sel
This class defines styles for the select control itself.
No skin parameters.
.rf-sel-cntr
This class defines styles for the container of the select control.
panelBorderColor
border-color
.rf-sel-inp
This class defines styles for the select control input field.
controlBackgroundColor
background-color
.rf-sel-fld-err
This class defines styles for the input field when an error occurs.
No skin parameters.
.rf-sel-opt
This class defines styles for an option in the select control.
generalTextColor
color
generalSizeFont
font-size
generalFamilyFont
font-family
.rf-sel-sel
This class defines styles for the selected option of the select control.
generalTextColor
border-color
.rf-sel-dflt-lbl
This class defines styles for the default label of the select control.
No skin parameters.
.rf-sel-btn
This class defines styles for the button of the select control.
headerBackgroundColor
background-color
panelBorderColor
border-left-color
.rf-sel-btn-arrow
This class defines styles for the arrow on the button.
No skin parameters.
.rf-sel-btn-dis
This class defines styles for the button of the select control when it is disabled.
No skin parameters.
.rf-sel-lst-scrl
This class defines styles for the list scrollbar.
No skin parameters.
.rf-sel-shdw
This class defines styles for the select control shadow.
No skin parameters.
.rf-sel-shdw-t, .rf-sel-shdw-b, .rf-sel-shdw-l, .rf-sel-shdw-r
These classes define the top, bottom, left, and right edge of the select control shadows.
No skin parameters.