DropDownField


The DropDownField component is an input component for entering text with an attached drop-down list. The user can type in any text value into the text field (not necessarily available in the drop-down list) or select predefined values from the drop-down list.

Key Features

Specifying the List of Items

To add the DropDownField component to a page, use the <q:dropDownField> tag. There are two ways to specify items in the drop-down list:

  • Create a fixed list of values right on the JSF page. In this case, you should use the <q:dropDownItem> tag to specify each separate item. Each item must have its value attribute defined. This attribute specifies the text that is shown in the text field when this item is selected. The example below shows the DropDownField component containing three items in the list.
<q:dropDownField>
  <q:dropDownItem value="Red"/>
  <q:dropDownItem value="Yellow"/>
  <q:dropDownItem value="Blue"/>
</q:dropDownField>


It is also possible to add child components to the <q:dropDownItem> tag. The following example demonstrates this feature using color definitions along with their names. Note that when a color is selected (for example, "Red"), the text field will display not the name of the color, but its hexidecimal value.

<q:dropDownField>
  <q:dropDownItem value="#FF0000" >
    <h:graphicImage url="/important.gif"/>
    <h:outputText value="Red"/>
  </q:dropDownItem>
  <q:dropDownItem value="#FFFF00">
    <h:outputText value="Yellow"/>
  </q:dropDownItem>
  <q:dropDownItem value="#0000FF">
    <h:outputText value="Blue"/>
  </q:dropDownItem>
</q:dropDownField>
  • Retrieve the list of values from a backing bean. To do this, use the <q:dropDownItems> tag. The value attribute of the <q:dropDownItems> tag should be bound to the collection or array that contains instances of the teamdev.jsf.component.dropdown.DropDownItem class:
    <q:dropDownField>
      <q:dropDownItems value="#{DropDownBackingBean.dropDownItems}"/>
    </q:dropDownField>

You can combine these two approaches by specifying the <q:dropDownItem> and <q:dropDownItems> tags in any order you need.

Like the JSF UIInput component, the DropDownField supports the standard validator, required, converter and immediate attributes. For more details about these attributes, see JavaServer Faces version 1.1 specification (section 3.2.5 EditableValueHolder).

Keyboard Navigation

The DropDownField component supports keyboard navigation. The user can open drop-down list by using Down Arrow key. After opening drop-down list, the user can navigate between drop-down items with Up Arrow and Down Arrow keys and then select item with Enter key. To close the list without changing the value, the user can press the Esc key.

Auto-Closing the List

By default, the behavior of drop-down list in the DropDownField component is like the one of an ordinary combo box, i.e. it is hidden until the user clicks the drop-down button. Once the list is opened, it remains visible until the user selects an item or closes the list explicitly. To close the list without changing the value, the user can either press the Esc key or click outside the component. However, in addition to the ability to close the drop-down list manually, it is possible to specify a time period after which the list is closed automatically. To do so, set the time (in milliseconds) in the timeout attribute. The value of timeout equal to -1 (default) means that the drop-down list should not be closed automatically.

In the following example, the drop-down list closes in 3000 milliseconds (or 3 seconds):

<q:dropDownField timeout="3000">
  <q:dropDownItems value="#{DropDownBackingBean.dropDownItems}"/>
</q:dropDownField>

Customizing the Appearance

You can set an image for the drop-down button by using the buttonImageUrl attribute. The buttonAlignment attribute is used to specify whether the drop-down button is positioned to the right or to the left of the component. This attribute can take the "right" or "left" values only. In the example below, the drop-down button is placed to the left of the text field. The default location of the button is to the right of the text field.

<q:dropDownField buttonAlignment="left"/>

In most cases, the width of the drop-down list is the same as the width of the DropDownField component itself. However, if the content of the list is too wide to fit in the DropDownField, the width of the drop-down list can exceed the width of the component. In this case, you can specify how the drop-down list is to be aligned using the listAlignment attribute. This attribute can take the "left" or "right" values only. By default, listAlignment is set to "left", which means that the left edge of the drop-down list is aligned with the left edge of the DropDownField component.

The following example shows the DropDownField component with a drop-down list right-aligned.

<q:dropDownField listAlignment="right">
...
</q:dropDownField>

Customizing Styles

You can customize styles for any part of the DropDownField component both in the normal and rollover state. The following table lists all style-related attributes:

Part of component Style attributes Class attributes Rollover style attributes Rollover class attributes
Entire DropDownField style styleClass rolloverStyle rolloverClass
Text field fieldStyle fieldClass rolloverFieldStyle rolloverFieldClass
Drop-down button buttonStyle buttonClass rolloverButtonStyle rolloverButtonClass
Pressed drop-down button pressedButtonStyle pressedButtonClass - -
Drop-down list listStyle listClass rolloverListStyle rolloverListClass
List item listItemStyle listItemClass rolloverListItemStyle rolloverListItemClass

This example shows the use of one class attribute and two style attributes.

.dropDownList {
   background-color: red;
   }
...
<q:dropDownField
        style="border-style: solid; border-width: 1px; border-color: silver;"
        listClass="dropDownList"
        rolloverButtonStyle="background-color: #ECECEC;">
  <q:dropDownItems value="#{DropDownBackingBean.dropDownItems}"/>
</q:dropDownField>

Client-Side Events

The DropDownField component supports the following standard client-side events: onchange, onkeypress, onclick, ondblclick, onmousedown, onmouseover, onmouseup, onmouseout, onmousemove, onfocus, onblur, onkeydown, onkeyup.

Please note that the mouse events work for the entire DropDownField component except for the drop-down list, while the keyboard events also work for the drop-down list. In addition, the DropDownField component provides two specific events:

Event name Description
ondropdown Occurs when the drop-down list is opened.
oncloseup Occurs when the drop-down list is closed.

Server-Side Event Listeners

Given the fact that the DropDownField is actually an extended HTMLInputText component, it fires javax.faces.event.ValueChangeEvent just like the HTMLInputText component does. The valueChangeListener attribute should be used to handle a value change event on the server side in the same way as for the HTMLInputText. You can also add a value change listener to the component by using the <f:valueChangeListener> tag.

Client-Side API

All client-side API methods for the DropDownField component are listed in the following table:

DropDownField Methods Public method Description
getValue() q_getDropDownValue(dropDownId) Gets the value from the DropDownField component with the id specified in the dropDownId.
setValue (value, isListItem) q_setDropDownValue(dropDownId, value, isListItem) Sets the value for the DropDownField component with the id specified in the dropDownId parameter. The boolean isListItem parameter defines whether value is one of predefined values from the drop-down list or not.
dropDown() q_dropDown(dropDownId) Opens the drop-down list for the DropDownField component with the id specified in the dropDownId parameter.
closeUp() q_closeUp(dropDownId) Closes the drop-down list for the DropDownField component with the id specified in the dropDownId parameter
isOpened() q_isDropDownOpened(dropDownId) Returns "true" if the drop-down list is opened.
QuipuKit