TwoListSelection |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Developer’s Guide Home
Installation and Configuration Common Concepts Components Index Border Layout Panel Calendar Chart Command Button Command Link Composite Filter 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 Level Indicator 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
Basic AttributesBeing an input component, the TwoListSelection supports the tabindex attribute. Tabindex is rendered for all nested input fields of the TwoListSelection component (list boxes and buttons). 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 <o: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. <o:twoListSelection value="#{TLSBean.selectedItems}"> <f:selectItems value="#{TLSBean.items}"/> <f:selectItem itemValue="#ff0000" itemLabel="red"/> <f:selectItem itemValue="#0000ff" itemLabel="blue"/> </o:twoListSelection> Like the JSF UIInput component, the TwoListSelection has the validator, converter, required, immediate and disabled attributes. For more information about these attributes, see JavaServer Faces specification (section "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: <o:twoListSelection leftListboxHeader="Available items" rightListboxHeader="Selected items" size="15"> <f:selectItems value="#{TLSBean.items}"/> </o: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: <o:twoListSelection leftListboxHeader="Available items" rightListboxHeader="Selected items" allowSorting="true"> <f:selectItems value="#{TLSBean.items}"/> </o:twoListSelection> Reordering Selected ItemsThe TwoListSelection component lets the user change the order of selected items. This can be done by selecting one or more contiguous items and clicking the Up and Down buttons to move those items 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. <o:twoListSelection allowItemsOrdering="false"> <f:selectItems value="#{TLSBean.items}"/> </o: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:
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
© 2010 TeamDev Ltd. | ![]() |