TwoListSelection

The TwoListSelection component provides an alternative interface for selecting a list of items. It displays two lists of data and allows the user moving items between them thus constructing a list of selected items in one of them. As opposed to the ordinary selection components such as the standard HtmlSelectManyListbox it also allows the user to reorder the selected items.


API Reference | Tag Reference
Online Demo

Key Features

Basic Attributes

Being 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 Items

Selection 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.

  • The UISelectItem component represents a single list item which you can specify using the following attributes:
Attribute Description
itemLabel The label of the item that is actually displayed for the user.
itemValue An object associated with this item.
itemDisabled Indicates whether the item is disabled. If an item is disabled, the user cannot move it to the other list. Note that disabled items can be present in both lists.
value Delegates storing of the item's data to another item. Must be a SelectItem object (or a value-binding expression for a SelectItem object). Note that if this property is set, itemLabel and itemValue are not used.
itemDescription Standard attribute. Not used.
  • The UISelectItems component represents a collection of list items which you should assign through the value attribute as a value-binding expression that references an array or collection of SelectItem instances, or a Map.

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 Appearance

By 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 Buttons

By 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:

Button Text Tool tip
Add addText addHint
Add All addAllText addAllHint
Remove removeText removeHint
Remove All removeAllText removeAllHint
Up moveUpText moveUpHint
Down moveDownText moveDownHint

Note
An item can also be moved to the other list by double-clicking on it.

Sorting

An 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 Items

The 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 Styles

You can customize styles for any part of the TwoListSelection component such as list boxes, list headers and command buttons by using the following attributes.

Part of TwoListSelection Attributes
Entire component style and styleClass
List boxes listStyle and listClass
List headers headerStyle and headerClass
Command buttons buttonStyle and buttonClass

Client-Side Events

The TwoListSelection component supports the following specific client-side events:

Event name Description
onadd Occurs when an item(s) is added to the selected list.
onremove Occurs when an item(s) is removed from the selected list.

Server-Side Event Listeners

Like 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 API

The TwoListSelection component has the following public client API methods:

Method Description
getValue() Returns the value as an array of string values from the TwoListSelection component on which this method is invoked.
setValue(value) Sets the value for the TwoListSelection component on which this method is invoked. The value parameter is an array of string values.
selectAll() Selects all items, which results in all items on the left to be moved to the right list.
unselectAll() Unselects all items, which results in all items on the right to be moved to the left list.
OpenFaces