TwoListSelection |
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
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 TwoListSelection component serves the same purpose as the standard HtmlSelectManyListbox in JSF, but has a different appearance and provides a number of extra features. It consists of two list boxes separated by a set of buttons that let the user move selected items from one list to the other and reorder the selected list. The list on the left contains available items which the user can add to (or from) the list on the right to make a selection. Key Features
Specifying ItemsSelection items for the TwoListSelection component are specified in almost the same way as for the standard selection components, i.e. using the standard <f:selectItem> and <f:selectItems> tags.
Note that UISelectItem and UISelectItems are invisible components and should be specified as child components within the TwoListSelection. You can combine them in any order you want. Selected items are specified in the value attribute of the <q:twoListSelection> tag, which must be bound to a list or an array of objects that correspond to the itemValue property of UISelectItem components. The following example demonstrates two ways of specifying list items in the TwoListSelection component. <q:twoListSelection value="#{TLSBean.selectedItems}"> <f:selectItems value="#{TLSBean.items}"/> <f:selectItem itemValue="#ff0000" itemLabel="red"/> <f:selectItem itemValue="#0000ff" itemLabel="blue"/> </q:twoListSelection> Like the JSF UIInput component, the TwoListSelection has the validator, converter, required and immediate attributes. For more information about these attributes, see JavaServer Faces specification, version 1.1 (section 3.2.5 EditableValueHolder). Customizing AppearanceBy default, the lists of the TwoListSelection have no labels. You can specify them using the leftListboxHeader and rightListboxHeader attributes. By default, each list of the TwoListSelection component allows viewing a maximum of 10 items at a time. You can change this number by specifying the size attribute. If there are more items than can fit in the list, the scrollbar will appear. The following example demonstrates the use of these attributes: <q:twoListSelection leftListboxHeader="Available items" rightListboxHeader="Selected items" size="15"> <f:selectItems value="#{TLSBean.items}"/> </q:twoListSelection> Customizing ButtonsBy default, the TwoListSelection component has four buttons to move items between the lists (Add, Add All, Remove, Remove All) and two buttons (Up and Down) to the right of the selected list to reorder its items. Note that it is impossible to change the arrangement and location of the buttons. The Add All and Remove All buttons are often treated as optional. You can hide them by setting allowAddRemoveAll attribute to "false". By default, the buttons in the TwoListSelection component display arrows indicating the direction in which items are to be added and ordered. If necessary, you can set text and tool tip for each of the buttons by using the following attributes:
SortingAn item added to either list of the TwoListSelection component always appears last in that list. To enable the user to quickly find an item in the selected list, you can provide the sorting capability. By default, it is turned off. To turn sorting on, you should first specify the text to be displayed in the header of the selected list and then set the allowSorting attribute to "true". Subsequent clicks on the header changes the sort order from ascending to descending, and vice versa. Note that sorting affects both the presentation and the order in which the items are saved to the backing bean. The following example shows a sortable TwoListSelection component: <q:twoListSelection leftListboxHeader="Available items" rightListboxHeader="Selected items" allowSorting="true"> <f:selectItems value="#{TLSBean.items}"/> </q:twoListSelection> Reordering Selected ItemsThe TwoListSelection component lets the user change the order of selected items. This can be done by selecting one of the items and clicking the Up and Down buttons to move that item by one row up or down respectively. By default, this feature is turned on. To turn it off, set the allowItemsOrdering attribute to "false". In this case, the Up and Down buttons will be unavailable. Note that items are saved to the backing bean in the order they are arranged. The following example demonstrates the TwoListSelection component in which ordering is turned off. <q:twoListSelection allowItemsOrdering="false"> <f:selectItems value="#{TLSBean.items}"/> </q:twoListSelection> Customizing StylesYou can customize styles for any part of the TwoListSelection component such as list boxes, list headers and command buttons by using the following attributes.
Client-Side EventsThe TwoListSelection component supports the following specific client-side events:
Server-Side Event ListenersLike the UIInput component, the TwoListSelection has the valueChangeListener attribute. This attribute is a method-binding expression that must point to the method that accepts a javax.faces.event.ValueChangeEvent. ValueChangeListener for the TwoListSelection works the same way as for the standard UIInput component. You can also add a value change listener to the component by using the <f:valueChangeListener> tag. Client-Side APIThe TwoListSelection component has the following public client API methods:
|
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
© 2007 TeamDev Ltd. | ![]() |