JBoss.orgCommunity Documentation
The <rich:comboBox> is a component creates combobox element with built-in Ajax capability.
Client-side suggestions
Browser like selection
Smart user-defined positioning
Seam entity converter support
Highly customizable look and feel
Disablement support
Table 6.357. rich : comboBox attributes
Table 6.358. 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:
...
<rich:comboBox value="#{bean.state}" suggestionValues="#{bean.suggestions}" />
...
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
...
<rich:comboBox value="#{bean.state}" suggestionValues="#{bean.suggestions}" />
...
Using the <f:selectItem /> or <f:selectItems /> JSF components.
...
<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>
...
These JSF components consider only the "value" attribute for this component.
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.
...
<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.
...
<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.
...
<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.
...
<rich:comboBox value="#{bean.state}" suggestionValues="#{bean.suggestions}" defaultLabel="Select a city..." disabled="true" />
...
This is a result:
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.
Table 6.359. 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.360. Skin parameters redefinition for a popup list
Skin parameters | CSS properties |
---|---|
tableBackgroundColor | background |
panelBorderColor | border-color |
Table 6.361. 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.362. Skin parameters redefinition for a button
Skin parameters | CSS properties |
---|---|
panelBorderColor | border-top-color |
panelBorderColor | border-left-color |
Table 6.363. Skin parameters redefinition for an inactive button
Skin parameters | CSS properties |
---|---|
panelBorderColor | border-top-color |
panelBorderColor | border-left-color |
Table 6.364. Skin parameters redefinition for a disabled button
Skin parameters | CSS properties |
---|---|
panelBorderColor | border-top-color |
panelBorderColor | border-left-color |
Table 6.365. Skin parameters redefinition for a hovered button
Skin parameters | CSS properties |
---|---|
selectControlColor | border-color |
Table 6.366. Skin parameters redefinition for a font
Skin parameters | CSS properties |
---|---|
generalSizeFont | font-size |
generalFamilyFont | font-family |
generalTextColor | color |
Table 6.367. Skin parameters redefinition for a font in inactive state
Skin parameters | CSS properties |
---|---|
generalSizeFont | font-size |
generalFamilyFont | font-family |
generalTextColor | color |
Table 6.368. Skin parameters redefinition for a font in disabled state
Skin parameters | CSS properties |
---|---|
headerFamilyFont | font-size |
headerFamilyFont | font-family |
Table 6.369. Skin parameters redefinition for an input field
Skin parameters | CSS properties |
---|---|
controlBackgroundColor | background-color |
panelBorderColor | border-bottom-color |
panelBorderColor | border-right-color |
Table 6.370. 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.371. 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.372. Skin parameters redefinition for an item
Skin parameters | CSS properties |
---|---|
generalSizeFont | font-size |
generalFamilyFont | font-family |
generalTextColor | color |
Table 6.373. 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.374. 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.375. 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.376. 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.377. 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.378. 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.379. 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.
Visit the ComboBox page at RichFaces LiveDemo for examples of component usage and their sources.