SuggestionField |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Developer’s Guide Home
Installation and Configuration Common Concepts Components Index Border Layout Panel Calendar Chart Command Button Command Link Confirmation Data Table Date Chooser Day Table Drop Down Field Dynamic Image Folding Panel For Each Graphic Text Hint Label Input Text Input Textarea Layered Pane Popup Layer Popup Menu Select Boolean Checkbox Select Many Checkbox Select One Radio Spinner Suggestion Field Tabbed Pane Tab Set Tree Table Two List Selection Window Focus Load Bundle Scroll Position Ajax Framework Validation Framework Tag Reference API Reference |
Key Features
Specifying List of ItemsTo add the SuggestionField component to a page, use the <o:suggestionField> tag. In order for the input suggestion feature to work properly, you should specify a list of suggestion items. There are three ways of specifying suggestion items. Regardless of the way you choose, each item is assigned a value that becomes a value of the SuggestionField 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 SuggestionField component for selection from a list of Objects rather than Strings. You can use the following ways to specify the list of suggestion items:
<o:suggestionField> <o:dropDownItem value="Red"/> <o:dropDownItem value="Yellow"/> <o:dropDownItem value="Blue"/> </o:suggestionField>
<o:suggestionField> <o:dropDownItem value="#FF0000" > <h:graphicImage url="/important.gif"/> <h:outputText value="Red"/> </o:dropDownItem> <o:dropDownItem value="#FFFF00"> <h:outputText value="Yellow"/> </o:dropDownItem> <o:dropDownItem value="#0000FF"> <h:outputText value="Blue"/> </o:dropDownItem> </o:suggestionField>
<o:suggestionField>
<o:dropDownItems value="#{DropDownBackingBean.dropDownItems}"/>
</o:suggestionField>
Here's how the dropDownItems property is defined in the DropDownBackingBean class: public List getDropDownItems() { List itemValues = Arrays.asList(new String[]{"Red", "Yellow", "Blue"}); return itemValues; }
Like any JSF UIInput component, the SuggestionField component supports the standard validator, required, converter, immediate and disabled attributes. For more information about them, see JavaServer Faces specification (section "EditableValueHolder"). <h:panelGroup id="containerForSuggestionField"> <o:suggestionField value="#{DropDownBackingBean.selectedColor}> <o:dropDownItem value="Red"/> <o:dropDownItem value="Yellow"/> <o:dropDownItem value="Blue"/> </o:suggestionField> </h:panelGroup> Restricting Input to List Items OnlyThe user can type in any value, not necessarily available in the suggestion list. In some cases, it may be required to restrict the input only to the values from the predefined list. The SuggestionField 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 suggestions ("false") or whether it is possible to enter any value ("true"). Entering Non-String ValuesWith the SuggestionField 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 suggestion item values (using <o:dropDownItem> or <o: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 <o:suggestionField> tag. Child components of the <o:suggestionField> tag are used to render each suggestion item. Note that the same child components of the SuggestionField are rendered in every suggestion 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 <o:dropDownItem> tag or an entry in the <o:dropDownItems> collection or array. The name of this variable should be specified using the var attribute of the <o:suggestionField> tag. In the example below, the SuggestionField component is specified using child components: <o:suggestionField value="#{DropDownBean.selectedBGColor}" var="color" converter="#{DropDownBean.colorConverter}"> <o:dropDownItems value="#{DropDownBean.colors}"/> <h:outputText styleClass="colorRect" style="background: #{color.name};"/> <h:outputText value="#{color.name}"/> </o:suggestionField> It is also possible to use child components of the SuggestionField 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 <o:suggestionField> tag. Here is an example of specifying child components of the SuggestionField component with the <o:dropDownItem> tags: <o:suggestionField value="#{DropDownBean.selectedFont}" var="size"> <o:dropDownItem value="9pt"/> <o:dropDownItem value="10pt"/> <o:dropDownItem value="12pt"/> <o:dropDownItem value="14pt"/> <o:dropDownItem value="16pt"/> <o:dropDownItem value="18pt"/> <o:dropDownItem value="20pt"/> <h:outputText value="#{size}" style="font-size: #{size};"/> </o:suggestionField> Note that if you specify child components both for <o:dropDownItem> and <o:suggestionField>, the components specified in the <o:dropDownItem> tag take priority over the components specified for all items, and only the children of the respective <o:dropDownItem> tag are displayed for such items. Creating Multi-Column Suggestion ListThe SuggestionField component lets you specify a suggestion list to be displayed in multiple columns. The list of columns is specified using the <o:column> tags within the <o:suggestionField> tag. Child components of the <o:column> tag are used to render each cell of the current item just like in the 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 <o:column> tag. Also, the <o:column> tag has the width, align and valign attributes that are rendered onto the <col> tag of the respective column. In addition, it is possible to group several columns using the <o:columnGroup> tag and add additional group headers. For more details about the <o:column> and <o:columnGroup> tags, see the DataTable component documentation. Here's an example of specifying a multi-column suggestion list in the SuggestionField component: <o:suggestionField value="#{DropDownBean.selectedBGColor}" var="color" converter="#{DropDownBean.colorConverter}"> <o:dropDownItems value="#{DropDownBean.colors}"/> <o:column width="12px"> <h:outputText styleClass="colorRect" style="background: #{color.name};"/> </o:column> <o:column> <h:outputText value="#{color.name}"/> </o:column> </o:suggestionField> Auto-SuggestionThe SuggestionField component displays a list of suggestions based on the input entered partially by the user. 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 off the auto-suggestion feature with the suggestionMode attribute. By default, this attribute is set to "stringStart". The SuggestionField 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 SuggestionField component using the "searchField" request-scope variable. To retrieve a variable by its name, you can use the org.openfaces.util.Faces.var(String varName) method. The example below shows usage of the "custom" auto-suggestion mode: <o:suggestionField value="#{DropDownBean.city}" converter="#{DropDownBean.cityNameConverter}" suggestionMode="custom"> <o:dropDownItems value="#{DropDownBean.cities}"/> </o:suggestionField> Here is how the above example can be implemented in the backing bean: public List getCities() { String searchString = Faces.var("searchString", String.class); 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: <o:suggestionField value="#{DropDownBean.selectedBGColor}" var="color" suggestionMode="custom" suggestionDelay="200" suggestionMinChars="3" converter="#{DropDownBean.colorConverter}"> ... </o:suggestionField> Auto-CompletionThe SuggestionField 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 <o:dropDownItem> or <o:dropDownItems> tags. When auto-completion is turned on, the SuggestionField component completes partially entered text in the input field. The text is completed to the first suggestion 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". By default it is turned on. 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: <o:suggestionField value="#{DropDownBean.selectedBGColor}" var="color" autoComplete="true" suggestionDelay="200" suggestionMinChars="3" converter="#{DropDownBean.colorConverter}"> ... </o:suggestionField> Keyboard NavigationThe SuggestionField component supports keyboard navigation. After opening a suggestion list, the user can navigate between suggestion 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. By default, the suggestion list is opened only when the user starts typing in the field. You can change this behavior by setting the manualListOpeningAllowed attribute to "true". This attribute specifies whether a suggestion list can be opened using the Down Arrow key. By default, the suggestion list in the SuggestionField component is hidden until the user starts typing (or presses the Down Arrow key). Once the list is opened, it remains visible until the user selects an item. 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 suggestion 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 suggestion list should not be closed automatically. Customizing AppearanceIn most cases, the width of the suggestion list is the same as the width of the SuggestionField component itself. However, if the content of the list is too wide to fit in the SuggestionField, the width of the suggestion list can exceed the width of the component. In this case, you can specify alignment of the suggestion 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 suggestion list is aligned with the left edge of the SuggestionField component. The following example shows the SuggestionField component with a right-aligned suggestion list. <o:suggestionField listAlignment="right">
...
</o:suggestionField>
You can specify the maximum height and width of the suggestion list using the height and width properties of the listStyle attribute. If the number of suggestion items is too large to fit in the height of the suggestion list, a scroll is added. Like the HTML <input> tag, <o:suggestionField> supports the title, tabindex, accesskey, maxlength and size attributes. Note that the maxlength attribute only affects the maximum number of characters that a user can type, but it is still possible to select any text from the drop-down list, no matter how long it is. Customizing StylesYou can apply styles for any part of the SuggestionField 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 one style attribute for the SuggestionField component. .dropDownList { background-color: red; } ... <o:suggestionField style="border-style: solid; border-width: 1px; border-color: silver;" listClass="dropDownList"> <o:dropDownItems value="#{DropDownBackingBean.dropDownItems}"/> </o:suggestionField> When you need to customize styles for grid lines in a multi-column suggestion list, use the following attributes:
Note Here's an example of applying styles to the grid lines of the suggestion list: <o:suggestionField 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"> ... </o:suggestionField> Client-Side EventsThe SuggestionField 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 SuggestionField component except for the suggestion list, while the keyboard events also work for the suggestion list. In addition, the SuggestionField component provides two specific events:
Server-Side Event ListenersGiven that the SuggestionField 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 SuggestionField component are listed below:
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
© 2009 TeamDev Ltd. | ![]() |