DropDownField |
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
Key Features
Specifying the List of ItemsTo add the DropDownField component to a page, use the <q:dropDownField> tag. There are two ways to specify items in the drop-down list:
<q:dropDownField> <q:dropDownItem value="Red"/> <q:dropDownItem value="Yellow"/> <q:dropDownItem value="Blue"/> </q:dropDownField>
<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>
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 NavigationThe 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 ListBy 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 AppearanceYou 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 StylesYou 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:
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 EventsThe 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:
Server-Side Event ListenersGiven 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 APIAll client-side API methods for the DropDownField component are listed in the following table:
|
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
© 2007 TeamDev Ltd. | ![]() |