6.25.  < rich:comboBox >

6.25.1. Description

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

<rich:comboBox> component

Figure 6.13.  <rich:comboBox> component


6.25.2. Key Features

  • Highly customizable look and feel
  • Disablement support
  • Browser like selection
  • Smart user-defined positioning
  • Multicolumn suggestion popup list
  • Seam entity converter support

Table 6.76. rich : comboBox attributes

Attribute NameDescription
accesskeyThis 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
alignleft|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
altFor 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
bindingThe attribute takes a value-binding expression for a component property of a backing bean
buttonClass 
buttonDisabledClass 
buttonDisabledStyle 
buttonIconURI
buttonIconDisabledURI
buttonIconInactiveURI
buttonInactiveClass 
buttonInactiveStyle 
buttonStyle 
converterId of Converter to be used or reference to a Converter
converterMessageconverterMessage
defaultLabel 
directInputSuggestionsnot implemented
disabledWhen set for a form control, this boolean attribute disables the control for your input
enableManualInputenabled for keybord input
filterNewValues 
hideDelay 
idEvery component may have a unique id that is automatically created if omitted
immediateA 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 
inputDisabledClass 
inputDisabledStyle 
inputInactiveClass 
inputInactiveStyle 
inputStyle 
itemClass 
listClass 
listHeight 
listStyle 
listWidth 
localValueSetlocalValueSet
maxlengthWhen 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
onblurHTML: script expression; the element lost the focus
onchangeHTML: script expression; the element value was changed
onclickHTML: a script expression; a pointer button is clicked
ondblclickHTML: a script expression; a pointer button is double-clicked
onfocusHTML: script expression; the element got the focus
onitemselected 
onkeydownHTML: a script expression; a key is pressed down
onkeypressHTML: a script expression; a key is pressed and released
onkeyupHTML: a script expression; a key is released
onlistcall 
onmousedownHTML: script expression; a pointer button is pressed down
onmousemoveHTML: a script expression; a pointer is moved within
onmouseoutHTML: a script expression; a pointer is moved away
onmouseoverHTML: a script expression; a pointer is moved onto
onmouseupHTML: script expression; a pointer button is released
onselectHTML: 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
renderedIf "false", this component is not rendered
requiredIf "true", this component is checked for non-empty input
requiredMessagerequiredMessage
selectFirstOnUpdate 
showDelay 
sizeThis 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 
styleClass 
suggestionValuessuggestionValues
tabindexThis 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
validvalid
validatorMethodBinding pointing at a method that is called during Process Validations phase of the request processing lifecycle, to validate the current value of this component
validatorMessagevalidatorMessage
valueThe initial value to set when rendered for the first time
valueChangeListenerListener for value changes
width 

Table 6.77. Component identification parameters

NameValue
component-typeorg.richfaces.ComboBox
component-classorg.richfaces.component.html.HtmlComboBox
component-familyorg.richfaces.ComboBox
renderer-typeorg.richfaces.renderkit.ComboBoxRenderer

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> component consists of an input field, the button and the popup list of suggestions attached to input. If you want to see the popup list you can press the button or type the first letter of suggested word in the input field. 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 /> components

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:

<rich:comboBox> with "directInputSuggestions" attribute.

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. Also nothing could be selected after the mouse is out the list.

Example:


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

This is a result:

<rich:comboBox> with "selectFirstOnUpdate" attribute.

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:

<rich:comboBox> with "defaultLabel" attribute.

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}" disabled="true" />            
...

This is a result:

<rich:comboBox> with "disabled" attribute.

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


The <rich:comboBox> component provides the possibility to use specific event attribute "onlistcall" which is fired before the list opening.

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

  • "listWidth" and "listHeight" attributes specify popup list sizes with values in pixels
  • "inputSize" attribute customizes the size of input element with values in symbols as for standard input field.

6.25.6. JavaScript API

Table 6.78. JavaScript API

FunctionDescription
showList()Shows the popup list
hideList()Hides the popup list
enable()Enables the control for input
disable()Disables the control for input

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 parametersCSS properties
generalBackgroundColorbackground
buttonBorderColorborder-color

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

Skin parametersCSS properties
generalBackgroundColorbackground-color

Table 6.81. Skin parameters redefinition for an inactive button

Skin parametersCSS properties
buttonBorderColorborder-top-color
buttonBorderColorborder-left-color

Table 6.82. Skin parameters redefinition for a disabled button

Skin parametersCSS properties
buttonBorderColorborder-top-color
buttonBorderColorborder-left-color

Table 6.83. Skin parameters redefinition for a hovered button

Skin parametersCSS properties
buttonBorderColorborder-color

Table 6.84. Skin parameters redefinition for a font

Skin parametersCSS properties
itemSizeFontfont-size
itemFamilyFontfont-family
itemTextColorcolor

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

Skin parametersCSS properties
itemSizeFontfont-size
itemFamilyFontfont-family
itemTextColorcolor

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

Skin parametersCSS properties
itemSizeFontfont-size
itemFamilyFontfont-family

Table 6.87. Skin parameters redefinition for an input field

Skin parametersCSS properties
generalBackgroundColorbackground-color
inputFieldBorderColorborder-bottom-color
inputFieldBorderColorborder-right-color

Table 6.88. Skin parameters redefinition for an inactive input field

Skin parametersCSS properties
generalBackgroundColorbackground-color
inputFieldBorderColorborder-bottom-color
inputFieldBorderColorborder-right-color

Table 6.89. Skin parameters redefinition for a disabled input field

Skin parametersCSS properties
generalBackgroundColorbackground-color
inputFieldBorderColorborder-bottom-color
inputFieldBorderColorborder-right-color

Table 6.90. Skin parameters redefinition for an item

Skin parametersCSS properties
itemSizeFontfont-size
itemFamilyFontfont-family
itemTextColorcolor

Table 6.91. Skin parameters redefinition for a selected item

Skin parametersCSS properties
itemSizeFontfont-size
itemFamilyFontfont-family
itemTextColorcolor

6.25.9. Definition of Custom Style Classes

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

Classes names

Figure 6.18. Classes names


Table 6.92. Classes names that define popup list representation

Class nameDescription
rich-combobox-list-decorationDefines styles for a list

Table 6.93. Classes names that define button representation

Class nameDescription
rich-combobox-button-inactiveDefines styles for an inactive button
rich-combobox-button-disabledDefines styles for a button in disabled state
rich-combobox-button-hoveredDefines styles for a hovered button
rich-combobox-button-backgroundDefines styles for a button background
rich-combobox-button-background-inactiveDefines styles for an inactive button background
rich-combobox-button-pressed-backgroundDefines styles for a pressed button background

Table 6.94. Classes names that define font representation

Class nameDescription
rich-combobox-fontDefines styles for a font
rich-combobox-font-inactiveDefines styles for an inactive font
rich-combobox-font-disabledDefines styles for a disabled font

Table 6.95. Classes names that define input field representation

Class nameDescription
rich-combobox-inputDefines styles for an input text
rich-combobox-input-disabledDefines styles for an input text in disabled state
rich-combobox-input-inactiveDefines styles for an inactive input text

Table 6.96. Classes names that define item representation

Class nameDescription
rich-combobox-itemDefines styles for an item
rich-combobox-item-selectedDefines styles for a selected item

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:

Redefinition styles with predefined classes

Figure 6.19. 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:

Redefinition styles with own classes and "listClass" attributes

Figure 6.20. Redefinition styles with own classes and "listClass" 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.