JBoss.org Community Documentation

- Prev
- Next

## 6.25. < rich:comboBox >

### 6.25.1. Description

The <rich:comboBox> is a component, that provides editable combo box element on a page.

Figure 6.13. <rich:comboBox> component

### 6.25.2. Key Features

- Client side suggestions

- Browser like selection

- Smart user-defined positioning

- Seam entity converter support

- Highly customizable look and feel

- Disablement support

Table 6.76. rich : comboBox attributes

Attribute Name | Description
--- | ---
accesskey | This attribute assigns an access key to an element. An access key is a single character from the document character set. Note: Authors should consider the input method of the expected reader when specifying an accesskey
align | Deprecated. This attribute specifies the horizontal alignment of its element with respect to the surrounding context. The possible values are "left", "center", "right" and "justify". The default depends on the base text direction. For left to right text, the default is align="left", while for right to left text, the default is align="right".
binding | The attribute takes a value-binding expression for a component property of a backing bean
buttonClass | Style Class attribute for the button
buttonDisabledClass | Style Class attribute for the disabled button
buttonDisabledStyle | CSS style rules to be applied to disabled button
buttonIcon | Defines icon for the button element
buttonIconDisabled | Defines disabled icon for the button element
buttonIconInactive | Defines inactive icon for the button element
buttonInactiveClass | Style Class attribute for the inactive button
buttonInactiveStyle | CSS style rules to be applied to inactive button
buttonStyle | CSS style rules to be applied to button
converter | Id of Converter to be used or reference to a Converter
converterMessage | A ValueExpression enabled attribute that, if present, will be used as the text of the converter message, replacing any message that comes from the converter
defaultLabel | Defines default label for the input field element
directInputSuggestions | Defines the first value from the suggested in input field. Default value is "false".
disabled | When set for a form control, this boolean attribute disables the control for your input
enableManualInput | Enables keyboard input, if "false" keyboard input will be locked. Default value is "true"
filterNewValues | Defines the appearance of values in the list. Default value is "true".
hideDelay | Delay between losing focus and pop-up list closing. Default value is "0".
id | Every component may have a unique id that is automatically created if omitted
immediate | A flag indicating that this component value must be converted and validated immediately (that is, during Apply Request Values phase), rather than waiting until a Process Validations phase
inputClass | Style Class attribute for the input field
inputDisabledClass | Style Class attribute for the disabled input
inputDisabledStyle | CSS style rules to be applied to disabled input
inputInactiveClass | Style Class attribute for the inactive input
inputInactiveStyle | CSS style rules to be applied to inactive input
inputStyle | CSS style rules to be applied to input field
itemClass | Style Class attribute for the items
itemSelectedClass | Style Class attribute for the selected item
listClass | Style Class attribute for the popup list
listHeight | Defines height of file pop-up list. Default value is "200px".
listStyle | CSS style rules to be applied to popup list
listWidth | Defines width of file popup list
onblur | HTML: script expression; the element lost the focus
onchange | HTML: script expression; the element value was changed
onclick | HTML: a script expression; a pointer button is clicked
ondblclick | HTML: a script expression; a pointer button is double-clicked
onfocus | HTML: script expression; the element got the focus
onkeydown | HTML: a script expression; a key is pressed down
onkeypress | HTML: a script expression; a key is pressed and released
onkeyup | HTML: a script expression; a key is released
onlistcall | A JavaScript event handler called on a list call operation
onmousedown | HTML: script expression; a pointer button is pressed down
onmousemove | HTML: a script expression; a pointer is moved within
onmouseout | HTML: a script expression; a pointer is moved away
onmouseover | HTML: a script expression; a pointer is moved onto
onmouseup | HTML: script expression; a pointer button is released
onselect | HTML: script expression; The onselect event occurs when you select some text in a text field. This attribute may be used with the INPUT and TEXTAREA elements
rendered | If "false", this component is not rendered
required | If "true", this component is checked for non-empty input
requiredMessage | A ValueExpression enabled attribute that, if present, will be used as the text of the validation message for the "required" facility, if the "required" facility is used
selectFirstOnUpdate | Defines if the first value from suggested is selected in pop-up list. Default value is "true".
showDelay | Delay between event and pop-up list showing. Default value is "0".
style | CSS style(s) is/are to be applied when this component is rendered
styleClass | Corresponds to the HTML class attribute
suggestionValues | Defines the suggestion collection
tabindex | This attribute specifies the position of the current element in the tabbing order for the current document. This value must be a number between 0 and 32767. User agents should ignore leading zeros
validator | MethodBinding pointing at a method that is called during Process Validations phase of the request processing lifecycle, to validate the current value of this component
validatorMessage | A ValueExpression enabled attribute that, if present, will be used as the text of the validator message, replacing any message that comes from the validator
value | The current value of this component
valueChangeListener | Listener for value changes
width | Width of the component. Default value is "150".

Table 6.77. Component identification parameters

Name | Value
--- | ---
component-type | org.richfaces.ComboBox
component-class | org.richfaces.component.html.HtmlComboBox
component-family | org.richfaces.ComboBox
renderer-type | org.richfaces.renderkit.ComboBoxRenderer
tag-class | org.richfaces.taglib.ComboBoxTag

### 6.25.3. Creating the Component with a Page Tag

Here is a simple example as it could be used on a page:

Example:

    ...

    <rich:comboBox value="#{bean.state}" suggestionValues="#{bean.suggestions}" />

    ...

### 6.25.4. Creating the Component Dynamically Using Java

Example:

    import org.richfaces.component.html.HtmlComboBox;

    ...

    HtmlComboBox myComboBox = new HtmlComboBox();

    ...

### 6.25.5. Details of Usage

The <rich:comboBox> is a simplified suggestion box component, that provides input with client side suggestions. The component could be in two states:

- Default - only input and button is shown

- Input, button and a popup list of suggestions attached to input is shown

There are two ways to get values for the popup list of suggestions:

- Using the "suggestionValues" attribute, that defines the suggestion collection

  Example:

      ...

      <rich:comboBox value="#{bean.state}" suggestionValues="#{bean.suggestions}" />

      ...

- Using the <f:selectItem /> or <f:selectItems /> facets which considers only "value" attribute.

  Example:

      ...

      <rich:comboBox value="#{bean.state}" valueChangeListener="#{bean.selectionChanged}">

              <f:selectItems  value="#{bean.selectItems}"/>

              <f:selectItem itemValue="Oregon"/>

              <f:selectItem itemValue="Pennsylvania"/>

              <f:selectItem itemValue="Rhode Island"/>

              <f:selectItem itemValue="South Carolina"/>

      </rich:comboBox>

      ...

Popup list content loads at page render time. No additional requests could be performed on the popup calling.

The "value" attribute stores value from input after submit.

The "directInputSuggestions" attribute defines, how the first value from the suggested one appears in an input field. If it's "true" the first value appears with the suggested part highlighted.

Example:

    ...

    <rich:comboBox value="#{bean.state}" suggestionValues="#{bean.suggestions}" directInputSuggestions="true" />

    ...

This is a result:

Figure 6.14. <rich:comboBox> with "directInputSuggestions" attribute.

The "selectFirstOnUpdate" attribute defines if the first value from suggested is selected in a popup list. If it's "false" nothing is selected in the list before a user hovers some item with the mouse.

Example:

    ...

    <rich:comboBox value="#{bean.state}" suggestionValues="#{bean.suggestions}" selectFirstOnUpdate="false" />

    ...

This is a result:

Figure 6.15. <rich:comboBox> with "selectFirstOnUpdate" attribute.

The "defaultLabel" attribute defines the default label of the input element. Simple example is placed below.

Example:

    ...

    <rich:comboBox value="#{bean.state}" suggestionValues="#{bean.suggestions}" defaultLabel="Select a city..." />

    ...

This is a result:

Figure 6.16. <rich:comboBox> with "defaultLabel" attribute.

With the help of the "disabled" attribute you can disable the whole <rich:comboBox> component. See the following example.

Example:

    ...

    <rich:comboBox value="#{bean.state}" suggestionValues="#{bean.suggestions}" defaultLabel="Select a city..." disabled="true" />

    ...

This is a result:

Figure 6.17. <rich:comboBox> with "disabled" attribute.

The "enableManualInput" attribute enables/disables input field, so when `enableManualInput = "false"` , user can only pick the value manually and has no possibility to type in the value (default value is "false").

The <rich:comboBox> component provides to use specific event attributes:

- "onlistcall" which is fired before the list opening and gives you a possibility to cancel list popup/update

- "onselect" which gives you a possibility to send AJAX request when item is selected

The <rich:comboBox> component allows to use sizes attributes:

- "listWidth" and "listHeight" attributes specify popup list sizes with values in pixels

- "width" attribute customizes the size of input element with values in pixels.

### 6.25.6. JavaScript API

Table 6.78. JavaScript API

Function | Description
--- | ---
showList() | Shows the popup list
hideList() | Hides the popup list
enable() | Enables the control for input (to be implemented)
disable() | Disables the control for input (to be implemented)

### 6.25.7. Look-and-Feel Customization

For skinnability implementation, the components use a style class redefinition method. Default style classes are mapped on skin parameters.

There are two ways to redefine the appearance of all <rich:comboBox> components at once:

- Redefine the corresponding skin parameters

- Add to your style sheets style classes used by a <rich:comboBox> component

### 6.25.8. Skin Parameters Redefinition

Table 6.79. Skin parameters redefinition for a popup list

Skin parameters | CSS properties
--- | ---
tableBackgroundColor | background
panelBorderColor | border-color

Table 6.80. Skin parameters redefinition for a button background, inactive button background, button background in pressed and disabled state

Skin parameters | CSS properties
--- | ---
tabBackgroundColor | background-color

Table 6.81. Skin parameters redefinition for a button

Skin parameters | CSS properties
--- | ---
panelBorderColor | border-top-color
panelBorderColor | border-left-color

Table 6.82. Skin parameters redefinition for an inactive button

Skin parameters | CSS properties
--- | ---
panelBorderColor | border-top-color
panelBorderColor | border-left-color

Table 6.83. Skin parameters redefinition for a disabled button

Skin parameters | CSS properties
--- | ---
panelBorderColor | border-top-color
panelBorderColor | border-left-color

Table 6.84. Skin parameters redefinition for a hovered button

Skin parameters | CSS properties
--- | ---
selectControlColor | border-color

Table 6.85. Skin parameters redefinition for a font

Skin parameters | CSS properties
--- | ---
generalSizeFont | font-size
generalFamilyFont | font-family
generalTextColor | color

Table 6.86. Skin parameters redefinition for a font in inactive state

Skin parameters | CSS properties
--- | ---
generalSizeFont | font-size
generalFamilyFont | font-family
generalTextColor | color

Table 6.87. Skin parameters redefinition for a font in disabled state

Skin parameters | CSS properties
--- | ---
headerFamilyFont | font-size
headerFamilyFont | font-family

Table 6.88. Skin parameters redefinition for an input field

Skin parameters | CSS properties
--- | ---
controlBackgroundColor | background-color
panelBorderColor | border-bottom-color
panelBorderColor | border-right-color

Table 6.89. Skin parameters redefinition for an inactive input field

Skin parameters | CSS properties
--- | ---
controlBackgroundColor | background-color
panelBorderColor | border-bottom-color
panelBorderColor | border-right-color

Table 6.90. Skin parameters redefinition for a disabled input field

Skin parameters | CSS properties
--- | ---
controlBackgroundColor | background-color
panelBorderColor | border-bottom-color
panelBorderColor | border-right-color

Table 6.91. Skin parameters redefinition for an item

Skin parameters | CSS properties
--- | ---
generalSizeFont | font-size
generalFamilyFont | font-family
generalTextColor | color

Table 6.92. Skin parameters redefinition for a selected item

Skin parameters | CSS properties
--- | ---
headerBackgroundColor | background-color
headerBackgroundColor | border-color
generalTextColor | color

### 6.25.9. Definition of Custom Style Classes

On the screenshot there are classes names that define styles for component elements.

Figure 6.18. Classes names

Figure 6.19. Classes names

Table 6.93. Classes names that define popup list representation

Class name | Description
--- | ---
rich-combobox-shell | Defines styles for a wrapper <div> element of a list
rich-combobox-list-position | Defines position of a list
rich-combobox-list-decoration | Defines styles for a list
rich-combobox-list-scroll | Defines styles for a list scrolling

Table 6.94. Classes names that define font representation

Class name | Description
--- | ---
rich-combobox-font | Defines styles for a font
rich-combobox-font-inactive | Defines styles for an inactive font
rich-combobox-font-disabled | Defines styles for a disabled font

Table 6.95. Classes names that define input field representation

Class name | Description
--- | ---
rich-combobox-input | Defines styles for an input field
rich-combobox-input-disabled | Defines styles for an input field in disabled state
rich-combobox-input-inactive | Defines styles for an inactive input field

Table 6.96. Classes names that define item representation

Class name | Description
--- | ---
rich-combobox-item | Defines styles for an item
rich-combobox-item-selected | Defines styles for a selected item

Table 6.97. Classes names that define button representation

Class name | Description
--- | ---
rich-combobox-button | Defines styles for a button
rich-combobox-button-inactive | Defines styles for an inactive button
rich-combobox-button-disabled | Defines styles for a button in disabled state
rich-combobox-button-hovered | Defines styles for a hovered button
rich-combobox-button-background | Defines styles for a button background
rich-combobox-button-background-disabled | Defines styles for a disabled button background
rich-combobox-button-background-inactive | Defines styles for an inactive button background
rich-combobox-button-pressed-background | Defines styles for a pressed button background
rich-combobox-button-icon | Defines styles for a button icon
rich-combobox-button-icon-inactive | Defines styles for an inactive button icon
rich-combobox-button-icon-disabled | Defines styles for a disabled button icon

Table 6.98. Classes names that define shadow representation

Class name | Description
--- | ---
rich-combobox-shadow | Defines styles for a wrapper <div> element of a shadow
rich-combobox-shadow-tl | Defines styles for a top-left element of a shadow
rich-combobox-shadow-tr | Defines styles for a top-right element of a shadow
rich-combobox-shadow-bl | Defines styles for a bottom-left element of a shadow
rich-combobox-shadow-br | Defines styles for a bottom-right element of a shadow

In order to redefine styles for all <rich:comboBox> components on a page using CSS, it's enough to create classes with the same names (possible classes could be found in the tables above) and define necessary properties in them.

Example:

    ...

    .rich-combobox-list-decoration{

            background-color:#ecf4fe;

    }

    ...

This is a result:

Figure 6.20. Redefinition styles with predefined classes

In the example background color for popup list was changed.

Also it's possible to change styles of particular <rich:comboBox> component. In this case you should create own style classes and use them in corresponding <rich:comboBox> styleClass attributes. An example is placed below:

Example:

    ...

    .myClass{

            font-weight:bold;

    }

    ...

The "listClass" attribute for <rich:comboBox> is defined as it's shown in the example below:

Example:

    <rich:comboBox ... listClass="myClass"/>

This is a result:

Figure 6.21. Redefinition styles with own classes and "styleClass" attributes

As it could be seen on the picture above, the font weight for items was changed.

### 6.25.10. Relevant Resources Links

Here you can see an example of <rich:comboBox> usage and sources for the given example.

- Prev6.24. < rich:calendar >
- Top of page
- Front page
- Next6.26. < rich:componentControl >