10.11. <rich:pickList>

⁠10.11. `<rich:pickList>`

The <rich:pickList> is a component for selecting items from a list. Additionally, it allows for the selected items to be ordered (client-side). From the client side perspective, items are added/removed from the source list, and removed/added to the target list. However it is important to note that the server-side source of items is never modified, and always represents the list of all items available for selection. If the list of unselected items is required, it can be determined by subtracting the collection of all selected items from the collection of all available items.

⁠

Figure 10.9. <rich:select>

⁠10.11.1. Basic usage

To use the <rich:pickList> bind the value attribute to the target list, where the selected items will be stored. The list of source items is provided by nesting a SelectItem source, such as a <f:selectItems> tag, or a list of <f:selectItem> tags. If the itemValue of the SelectItem is not of type String, a converter must be specified for this itemValue using either the converter attribute, or a nested <f:converter> tag.

⁠

Example 10.12. Simple pickList use

Using the default SelectItem itemLabel to generate the pickList source and target items.

<rich:pickList value="#{listSelectBean.selectedCapitals}"
               sourceCaption="Available cities" targetCaption="Selected cities"
               listWidth="170px" listHeight="100px"
               orderable="true">
    <f:selectItems value="#{listSelectBean.capitals}" var="capital" itemValue="#{capital}" itemLabel="#{capital.name}" />
    <f:converter converterId="CapitalsConverter" />
</rich:pickList>

The items in the target list can be ordered client-side by setting the orderable attribute of the <rich:pickList> tag to true. The arrow keys on a keyboard can then be used to highlight different items in the target list, and pressing the ctrl modifier with the arrow keys will move the selected item up or down within the target list.

⁠10.11.2. Column Layout

In addition to the above simple SelectItem itemLabel display, the <rich:pickList> supports a columnar layout of the items to be selected. This is achieved by adding a var attribute used to represent the collection of nested SelectItems, and nesting <rich:column> tags within the pickList. The var attribute of the <f:selectItem> is then referenced from within the <rich:column> EL.

⁠

Example 10.13. Nested <rich:column> tags

Using <rich:column> tags nested within the <rich:pickList>

<rich:pickList value="#{listSelectBean.selectedCapitals}" var="capital" listHeight="200px">
    <f:selectItems value="#{listSelectBean.capitals}" />
    <f:converter converterId="CapitalsConverter" />
    <rich:column>
        <f:facet name="header">Flag</f:facet>
        <h:graphicImage value="#{capital.stateFlag}" alt="flag" width="33"/>
    </rich:column>
    <rich:column>
        <f:facet name="header">Name</f:facet>
        #{capital.name}
    </rich:column>
    <rich:column>
        <f:facet name="header">State</f:facet>
        #{capital.state}
    </rich:column>
</rich:pickList>

⁠10.11.3. JavaScript API

The <rich:pickList> component can be controlled through the JavaScript API. The JavaScript API provides the following functions:

getSourceList(): Returns the javascript list object backing the <rich:pickList> source list. This list can be used to select/unselect item(s).
getTargetList(): Returns the javascript list object backing the <rich:pickList> target list. This list can be used to select/unselect item(s).
add(): Add the currently selected items to the target list, removing them from the source list.
addAll(): Add all the source items to the target list, removing them from the source list.
remove(): Remove the currently selected items from the target list, adding them to the source list.
removeAll(): Remove all the source items from the target list, adding them to the source list.
toggleButtons(): Activate/de-activate the pickList buttons based on the current component item state.

⁠10.11.4. Reference data

component-type: org.richfaces.PickList
component-class: org.richfaces.component.UIPickList
component-family: org.richfaces.SelectMany
renderer-type: org.richfaces.PickListRenderer

⁠10.11.5. Style classes and skin parameters

⁠

Table 10.11. Style classes (selectors) and corresponding skin parameters

Class (selector)	Skin Parameters	Mapped CSS properties
`.rf-pick` This class defines styles for the pickList control itself.	No skin parameters.
`.rf-pick-src-cptn, .rf-pick-tgt-cptn` These classes define styles for the source and target captions of the pickList control.	`headerTextColor`	color
	`headerSizeFont`	font-size
	`headerFamilyFont`	font-family
	`headerWeightFont`	font-weight
`.rf-pick-lst` This class defines styles for the items list of the pickList control.	No skin parameters.
`.rf-pick-hdr` This class defines styles for the header of the items list.	`headerBackgroundColor`	background-color
	`headerTextColor`	color
	`headerSizeFont`	font-size
	`headerFamilyFont`	font-family
	`headerWeightFont`	font-weight
`.rf-pick-opt` This class defines styles for an option in the pickList control.	`generalTextColor`	color
	`generalSizeFont`	font-size
	`generalFamilyFont`	font-family
`.rf-pick-sel` This class defines styles for the selected option of the pickList control.	`generalTextColor`	border-color
`.rf-pick-dflt-lbl` This class defines styles for the default label of the pickList control.	No skin parameters.
`.rf-pick-btn` This class defines styles for the button of the pickList control.	`headerBackgroundColor`	background-color
	`panelBorderColor`	border-left-color
`.rf-pick-btn-dis` This class defines styles for the button of the pickList control when it is disabled.	No skin parameters.
`.rf-pick-lst-scrl` This class defines styles for the list scrollbar.	No skin parameters.