The <rich:comboBox> is a component, that provides editable combo box element on a page.
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 | left|center|right|justify [CI] Deprecated. This attribute specifies the horizontal alignment of its element with respect to the surrounding context. Possible values: * left: text lines are rendered flush left. * center: text lines are centered. * right: text lines are rendered flush right. * justify: text lines are justified to both margins. 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 |
alt | For a user agents that cannot display images, forms, or applets, this attribute specifies alternate text. The language of the alternate text is specified by the lang attribute |
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 |
disabled | When set for a form control, this boolean attribute disables the control for your input |
enableManualInput | enabled for keybord input, if "false" keybord input will be locked |
filterNewValues | Defines the appearance of values in the list |
hideDelay | Delay between losing focus and popup list closing |
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 popup list |
listStyle | CSS style rules to be applied to popup list |
listWidth | Defines width of file popup list |
maxlength | When the type attribute has the value "text" or "password", this attribute specifies the maximum number of characters you may enter. This number may exceed the specified size, in which case the user agent should offer a scrolling mechanism. The default value for this attribute is an unlimited number |
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 popup list |
showDelay | Delay between event and popup list showing |
size | This attribute tells the user agent the initial width of the control. The width is given in pixels except when type attribute has the value "text" or "password". In that case, its value refers to the (integer) number of characters |
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 |
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 |
Here is a simple example as it could be used on a page:
Example:
...
<rich:comboBox value="#{bean.state}" suggestionValues="#{bean.suggestions}" />
...
Example:
import org.richfaces.component.html.HtmlComboBox;
...
HtmlComboBox myComboBox = new HtmlComboBox();
...
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:
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:
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:
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:
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.
Table 6.78. JavaScript API
Function | Description |
---|---|
showList() | Shows the popup list |
hideList() | Hides the popup list |
enable() | Enables the control for input |
disable() | Disables the control for input |
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
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 |
On the screenshot there are classes names that define styles for component elements.
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:
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:
As it could be seen on the picture above, the font weight for items was changed.
Here you can see an example of <rich:comboBox> usage and sources for the given example.