TwoListSelection

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

<q:twoListSelection leftListboxHeader="Available items"
       rightListboxHeader="Selected items"
       size="15">
    <f:selectItems value="#{TLSBean.items}"/>
</q: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:

<q:twoListSelection leftListboxHeader="Available items"
                    rightListboxHeader="Selected items"
                    allowSorting="true">
  <f:selectItems value="#{TLSBean.items}"/>
</q:twoListSelection>

Reordering Selected Items

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

TwoListSelection method Public method Description
getValue() q_getTLSValue(tlsId) Gets the value as an array of string values from the TwoListSelection component with the id specified in the tlsId parameter.
setValue(value) q_setTLSValue(tlsId, value) Sets the value for the TwoListSelection component with the id specified in the tlsId parameter. The value parameter is an array of string values.
QuipuKit