DropDownField |
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Developer’s Guide Home
Installation and Configuration Components Index Calendar Chart Confirmation Data Table Date Chooser Drop Down Field Dynamic Image Folding Panel Hint Label Popup Layer Suggestion Field Tab Set Tabbed Pane Tree Table Two List Selection Utility Components Validation Framework Tag Reference |
The DropDownField component is an input component where the user can either type in a value or select one of the values from an attached drop-down list. The DropDownField component also provides a way to show a list of suggestions based on user input and offers the ability to auto-complete user input right in the input field. There are both client-side and Ajax-based suggestion modes. Key Features
Specifying List of ItemsTo add the DropDownField component to a page, use the <q:dropDownField> tag. There are three ways to specify items that will be displayed in the drop-down list. Regardless of the way you choose, each item is assigned a value that becomes a selected value of the DropDownField component once an appropriate item is selected. The item value can either be a String or an arbitrary Object. See the Entering Non-String Values section for details of setting up the DropDownField component for selection from a list of Objects rather than Strings. You can specify drop-down list items in the following ways:
<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>
A selected value of the DropDownField component can be maintained using the value attribute of <q:dropDownItems> tag. The usage of this attribute is similar to that in standard JSF input components such as <h:inputText> or <h:selectOneMenu>. This attribute should be bound to either a String or an Object attribute depending on the type of item value objects. See the Entering Non-String Values section for details of entering non-string values in the DropDownField component. Here's an example of using the value attribute. <q:dropDownField value="#{DropDownBackingBean.selectedColor}> <q:dropDownItem value="Red"/> <q:dropDownItem value="Yellow"/> <q:dropDownItem value="Blue"/> </q:dropDownField> Like any JSF UIInput component, the DropDownField component supports the standard validator, required, converter and immediate attributes. For more information about them, see JavaServer Faces version 1.1 specification (section 3.2.5 EditableValueHolder). Restricting Input to List ItemsThe DropDownField component is an input component where the user can enter a value either by typing it in or by selecting it from the drop-down list. So it acts as a combination of an ordinary input field (such as <h:inputText>) and a combo-box component (such as <h:selectOneMenu>). Therefore, unlike the usual combo-box component, the user can type in any value, not necessarily available in the drop-down list. In some cases, it may be required to restrict the input only to the values from the predefined list, which means that a component should act like a combo-box. The DropDownField component provides this ability while also enabling you to use features like auto-suggestion and auto-completion and many others. This behavior can be triggered by setting the customValueAllowed attribute to "false". This attribute defines whether it is possible to specify only a value that exists in the list of drop-down items ("false") or whether it is possible to enter any value ("true"). Entering Non-String ValuesWith the DropDownField component, you can enter non-string values, too. For instance, you may need to select an object from a set of JavaBean objects read from the database. In this case, you will need to specify these non-string objects as the drop-down list item values (using <q:dropDownItem> or <q:dropDownItems> tags). In addition, the following requirements must be met:
Specifying Child ComponentsFrom the previous section, you already know that you can specify any child components within the DropDownItem component. However, DropDownItem components are used only when you have a fixed number of items. For a dynamic or big set of items, it is more suitable to use the DropDownItems component, which cannot include child components. However, if you need to specify a set of components that should be rendered inside of all items, you can specify these components as children of the <q:dropDownField> tag. Child components of the <q:dropDownField> tag are used to render each drop-down item. Note that the same child components of the DropDownField are rendered in every drop-down item. So in order for these components to display different data for each respective item, you should use a request-scope variable referring to the current item value object. The item value object is an object that you specify in the corresponding <q:dropDownItem> tag or an entry in the <q:dropDownItems> collection or array. The name of this variable should be specified using the var attribute of the <q:dropDownField> tag. The following example shows the DropDownField component specified using child components: <q:dropDownField value="#{DropDownBean.selectedBGColor}" var="color" converter="#{DropDownBean.colorConverter}"> <q:dropDownItems value="#{DropDownBean.colors}"/> <h:outputText styleClass="colorRect" style="background: #{color.name};"/> <h:outputText value="#{color.name}"/> </q:dropDownField> It is also possible to use child components of the DropDownField component with the DropDownItem components. The values of the DropDownItem components are available using a request-scope variable specified in the var attribute of the <q:dropDownField> tag. Here is an example of specifying child components of the DropDownField component with the <q:dropDownItem> tags: <q:dropDownField value="#{DropDownBean.selectedFont}" var="size"> <q:dropDownItem value="9pt"/> <q:dropDownItem value="10pt"/> <q:dropDownItem value="12pt"/> <q:dropDownItem value="14pt"/> <q:dropDownItem value="16pt"/> <q:dropDownItem value="18pt"/> <q:dropDownItem value="20pt"/> <h:outputText value="#{size}" style="font-size: #{size};"/> </q:dropDownField> Note that if you specified child components both for <q:dropDownItem> and <q:dropDownField>, the components specified in the <q:dropDownItem> tag take priority over the components specified for all items, and only the children of the respective <q:dropDownItem> tag are displayed for such items. Creating Multi-Column Drop-Down ListThe DropDownField component lets you specify a drop-down list to be displayed in multiple columns. The list of columns is specified using the <q:column> tags within the <q:dropDownField> tag. Child components of the <q:column> tag are used to render each cell of the current item just like in the <q:dataTable> component. As in case of specifying child components described in the previous section, you should use a request-scope variable referring to the current item data in order for child components to display different data for each respective item. You can specify the "header" and "footer" facets , styles and client-side events for the <q:column> tag. Also, the <q:column> tag has the width, align and valign attributes that are rendered onto the <col> tag of the respective column. For more details about the <q:column> tag, see the DataTable component documentation. Here's an example of specifying a multi-column drop-down list in the DropDownField component: <q:dropDownField value="#{DropDownBean.selectedBGColor}" var="color" converter="#{DropDownBean.colorConverter}"> <q:dropDownItems value="#{DropDownBean.colors}"/> <q:column width="12px"> <h:outputText styleClass="colorRect" style="background: #{color.name};"/> </q:column> <q:column> <h:outputText value="#{color.name}"/> </q:column> </q:dropDownField> Auto-SuggestionThe DropDownField component can be configured to display a list of suggestions based on the input entered partially by the user. When this feature is turned on, the list of suggestions is updated on-the-fly as the user types text, and the user can select one of the provided suggestions any time when appropriate. This feature makes it easier to find items by typing only part of their text. You can turn on the auto-suggestion feature with the suggestionMode attribute. By default, this attribute is set to "none", which means that this feature is turned off. The DropDownField component supports different auto-suggestion modes, each of which can be specified using one of the following values:
The first four auto-suggestion modes work on client side and can be used to introduce the most robust suggestion functionality because no server round-trips are required in this case. However, this way is not efficient in case of large lists, because all of the suggestions must be preloaded on the client in these modes. To avoid resource-intensive preloading as well as to implement more flexible auto-suggestion scenarios, you can take advantage of the "custom" suggestion mode. When you use the "custom" suggestion mode, the value attribute of the DropDownItems components should be bound to the method that returns the list of suggestions corresponding to the entered string. You can get the entered value from the DropDownField component using the "searchField" request-scope variable. To retrieve a request-scope variable by its name, you can use the teamdev.jsf.component.util.FacesUtil.getRequestMapValue method. The example below shows usage of the "custom" auto-suggestion mode: <q:dropDownField value="#{DropDownBean.city}" converter="#{DropDownBean.cityNameConverter}" suggestionMode="custom"> <q:dropDownItems value="#{DropDownBean.cities}"/> </q:dropDownField> Here is how the above example can be implemented in the backing bean: public List getCities() { String searchString = (String) FacesUtil.getRequestMapValue("searchString"); List filteredCities = myCitiesDB.findCitiesStartingWithText(searchString); return filteredCities; }
You can set a delay that should elapse after the last key press before starting auto-suggestion and auto-completion. The time period for this delay should be specified for the suggestionDelay attribute in milliseconds (by default, "350"). This attribute is particularly useful when it's necessary to avoid too many Ajax requests that are sent to the server while the user is typing text. With the suggestionDelay attribute, you send only one Ajax request when the user has stopped typing. Here's an example of using the suggestionMinChars and suggestionDelay attributes: <q:dropDownField value="#{DropDownBean.selectedBGColor}" var="color" suggestionMode="custom" suggestionDelay="200" suggestionMinChars="3" converter="#{DropDownBean.colorConverter}"> ... </q:dropDownField> Auto-CompletionThe DropDownField component provides the auto-completion feature which in addition to auto-suggestion can be used to simplify selection of a value among the items specified with the <q:dropDownItem> or <q:dropDownItems> tags. When auto-completion is turned on, the DropDownField component completes partially entered text in the input field. The text is completed to the first drop-down item that starts with the typed text. The part added as a result of auto-completion is marked as selected. The auto-completion feature can be turned on by setting the autoComplete attribute to "true" (default is "false"). Auto-completion, like the auto-suggestion feature, also depends on the suggestionMinChars and suggestionDelay attributes, described in the previous section. Below is an example of using the autoComplete attribute: <q:dropDownField value="#{DropDownBean.selectedBGColor}" var="color" autoComplete="true" suggestionDelay="200" suggestionMinChars="3" converter="#{DropDownBean.colorConverter}"> ... </q:dropDownField> Keyboard NavigationThe DropDownField component supports keyboard navigation. The user can open a drop-down list by using the Down Arrow key. After opening a drop-down list, the user can navigate between drop-down items with the Up Arrow, Down Arrow, Home, End, Page Up, Page Down keys and then select an item with the Enter key. To close the list without changing the value, the user can press the Esc key. Auto-Closing Drop-Down ListBy default, the drop-down list in the DropDownField component behaves like 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 anywhere outside of the component. However, in addition to the ability to close the drop-down list manually, you can 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 example below, the drop-down list closes in 3000 milliseconds (or 3 seconds): <q:dropDownField timeout="3000"> <q:dropDownItems value="#{DropDownBackingBean.dropDownItems}"/> </q:dropDownField> Customizing AppearanceYou can set an image for the drop-down button by using the buttonImageUrl attribute. The buttonAlignment attribute lets you 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. The default location of the button is to the right of the input field. In the example below, the drop-down button is left aligned: <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 alignment of the drop-down list with the listAlignment attribute by setting its value to "left" (default) or "right". The default left alignment 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 right-aligned drop-down list. <q:dropDownField listAlignment="right">
...
</q:dropDownField>
You can specify the maximum height and width of the drop-down list using the height and width properties of the listStyle attribute. If the number of drop-down items is too large to fit in the height of the drop-down list, a scroll is added. Customizing StylesYou can apply styles for any part of the DropDownField component, both when it's in the normal and rollover states. The table below lists all style attributes:
This example shows usage of one class attribute and two style attributes for the DropDownField component. .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> When you need to customize styles for grid lines in a multi-column drop-down list, use the following attributes:
Note Here's an example of applying styles to the grid lines of the drop-down list: <q:dropDownField value="#{DropDownBean.selectedColor}" horizontalGridLines="1px dotted gray" verticalGridLines="1px dotted gray" headerHorizSeparator="3px solid gray" headerVertSeparator="1px solid gray" footerHorizSeparator="3px solid gray" footerVertSeparator="1px solid gray"> ... </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 that the DropDownField component is a UIInput component, it can fire javax.faces.event.ValueChangeEvent just like any other UIInput component does. To handle a value change event on the server side, the valueChangeListener attribute should be used in the same way as for the HTMLInputText component. 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 below:
|
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
© 2007 TeamDev Ltd. | ![]() |