rich:pickList pickList

Component identification parameters

Name | Value
--- | ---
component-type | org.richfaces.PickList
component-class | org.richfaces.component.html.HtmlPickList
component-family | org.richfaces.PickList
renderer-type | org.richfaces.PickListRenderer
tag-class | org.richfaces.taglib.PickListTag

## Creating the Component with a Page Tag

To create the simplest variant on a page use the following syntax:

Example:

    ...
    <rich:pickList value="#{pickBean.targetValues}">
            <f:selectItem itemValue="Bentley" itemLabel="Bentley"/>
            <f:selectItems value="#{pickBean.sourceValues}"/>
    </rich:pickList>
    ...

## Creating the Component Dynamically Using Java

Example:

    import org.richfaces.component.html.HtmlPickList;
    ...
    HtmlPickList myPickList = new HtmlPickList();
    ...

## Details of Usage

The <rich:pickList> component consists of

- 2 item lists. Every item has three different representations: common, selected, active. Combination of these states is possible.

- Move controls set is a set of controls, which performs moving items between lists.

The "value" attribute is the initial value of this component.

The <f:selectItem /> or <f:selectItems /> facets are used to define the values of a source list.

Example:

    ...
    <rich:pickList value="#{pickBean.listValues}">
            <f:selectItem itemValue="Bentley" itemLabel="Bentley"/>
            <f:selectItem itemValue="Audi" itemLabel="Audi"/>
            <f:selectItems value="#{pickBean.sourceList}"/>
    </rich:pickList>
    ...

The "switchByClick" attribute provides an option to copy and remove items between lists by one click. Default value of this attribute is "false", so you need a double click to copy, remove items from one list to another.

Lables of the move controls can be defined with "copyAllControlLabel", "copyControlLabel", "removeControlLabel", "removeAllControlLabel" attributes.

Example:

    ...
    <rich:pickList copyAllControlLabel = "#{pickBean.copyAllLabel}" copyControlLabel = "#{pickBean.copyLabel}" removeControlLabel = "#{pickBean.removeLabel}"
    removeAllControlLabel ="#{pickBean.removeAllLabel}" value="#{pickBean.listValues}">
            <f:selectItem itemValue="Bentley" itemLabel="Bentley"/>
            <f:selectItem itemValue="Audi" itemLabel="Audi"/>
            <f:selectItems value="#{pickBean.sourceList}"/>
    </rich:pickList>
    ...

If you don't want to display labels on the buttons you need to set "showButtonsLabel" to "false".

Move control buttons without labels

Alternative to the given attributes are the following facets: "copyAllControl", "removeAllControl", "copyControl", "removeControl", "copyAllControlDisabled", "removeAllControlDisabled", "copyControlDisabled", "removeControlDisabled", "caption".

It is an example of usage of the facets and it is identical to the previous example.

    ...
    <rich:pickList value="#{pickBean.listValues}">
        <f:facet name="copyAllControl">
            <h:commandButton value="#{pickBean.copyAllLabel}" />
        </f:facet>
        <f:facet name="copyControl">
            <h:commandButton value="#{pickBean.copyLabel}" />
        </f:facet>
        <f:facet name="removeControl">
            <h:commandButton value="#{pickBean.removeLabel}" />
        </f:facet>
        <f:facet name="removeAllControl">
            <h:commandButton value="#{pickBean.removeAllLabel}" />
        </f:facet>
            <f:selectItem itemValue="Bentley" itemLabel="Bentley"/>
            <f:selectItem itemValue="Audi" itemLabel="Audi"/>
            <f:selectItems value="#{pickBean.sourceList}"/>
    </rich:pickList>
    ...

With the help of "moveControlsVerticalAlign" attribute you can align move controls vertically.

The possible value for "moveControlsVerticalAlign" are "top", "bottom" and "center" (default value).

The <rich:pickList> component provides resizing of lists by using such attributes as:

- "listsHeight" defines height of the lists.

- "sourceListWidth" defines width of a source list.

- "targetListWidth" defines width of a target list.

Example:

    ...
    <rich:pickList listsHeight="#{pickBean.listsHeight}" sourceListWidth="#{pickBean.sourceListWidth}" targetListWidth="#{pickBean.targetListWidth}" value="#{pickBean.listValues}">
            <f:selectItem itemValue="Bentley" itemLabel="Bentley"/>
            <f:selectItem itemValue="Audi" itemLabel="Audi"/>
            <f:selectItems value="#{pickBean.sourceList}"/>
    </rich:pickList>
    ...

The <rich:pickList> component allows to use internationalization method to redefine and localize the labels. You could use application resource bundle and define `RICH_PICK_LIST_COPY_ALL_LABEL`, `RICH_PICK_LIST_COPY_LABEL`, `RICH_PICK_LIST_REMOVE_ALL_LABEL`, `RICH_PICK_LIST_REMOVE_LABEL` there.

Keyboard usage for elements selection

Keys and combinations | Description
--- | ---
CTRL+click | Inverts selection for an item
SHIFT+click | Selects all rows from active one to a clicked row if they differ, else select the active row. All other selections are cleared
CTRL+A | Selects all elements inside the list if some active element is already present in a list
Up, Down arrows | Changes the active and selected elements to the next or previous in a list

## Facets

Facets

Facet | Description
--- | ---
copyAllControl | Redefines the "copyAll" label with the control set. Related attribute is "copyAllControlLabel"
removeAllControl | Redefines the "removeAll" label with the control set. Related attribute is "removeAllControlLabel"
copyControl | Redefines the "copy" label with the control set. Related attribute is "copyControlLabel"
removeControl | Redefines the "remove" label with the control set. Related attribute is "removeControlLabel"
copyAllControlDisabled | Redefines the disabled "copyAll" label with the control set.
removeAllControlDisabled | Redefines the disabled "removeAll" label with the control set.
copyControlDisabled | Redefines the disabled "copy" label with the control set.
removeControlDisabled | Redefines the disabled "remove" label with the control set.
caption | Defines the "caption" label with the control set.

## Look-and-Feel Customization

For skinnability implementation, the components use a style class redefinition method. Default style classes are mapped on skin parameters.

There are two ways to redefine the appearance of all <rich:pickList> components at once:

- Redefine the corresponding skin parameters

- Add to your style sheets style classes used by a <rich:pickList> component

## Skin Parameters Redefinition

Skin parameters redefinition for a list

Skin parameters | CSS properties
--- | ---
tableBackgroundColor | background-color

Skin parameters redefinition for a button

Skin parameters | CSS properties
--- | ---
tabBackgroundColorr | background-color
generalTextColor | color
headerFamilyFont | font-family
headerSizeFont | font-size

Skin parameters redefinition for a disabled button

Skin parameters | CSS properties
--- | ---
tabBackgroundColor | background-color
tabDisabledTextColor | color
headerFamilyFont | font-family
headerSizeFont | font-size

Skin parameters redefinition for a pressed button

Skin parameters | CSS properties
--- | ---
tabBackgroundColor | background-color
generalTextColor | color
headerFamilyFont | font-family
headerSizeFont | font-size
tableBorderColor | border-color
tableBorderWidth | border-width

Skin parameters redefinition for a highlighted button

Skin parameters | CSS properties
--- | ---
tabBackgroundColor | background-color
generalTextColor | color
headerFamilyFont | font-family
headerSizeFon | font-size
selectControlColor | border-color
tableBorderWidth | border-width

Skin parameters redefinition for a button selection

Skin parameters | CSS properties
--- | ---
generalTextColor | color

Skin parameters redefinition for a button content

Skin parameters | CSS properties
--- | ---
headerFamilyFont | font-family
headerSizeFont | font-size

Skin parameters redefinition for a source and target items

Skin parameters | CSS properties
--- | ---
generalBackgroundColor | background-color
tableBorderColor | border-color
tableBorderWidth | border-width

Skin parameters redefinition for a source and target cell

Skin parameters | CSS properties
--- | ---
generalTextColor | color
generalSizeFont | font-size
generalFamilyFont | font-family

Skin parameters redefinition for a selected source and target cell

Skin parameters | CSS properties
--- | ---
generalTextColor | color
generalSizeFont | font-size
generalFamilyFont | font-family

Skin parameters redefinition for an active source and target cell

Skin parameters | CSS properties
--- | ---
generalSizeFont | font-size
generalFamilyFont | font-family
generalTextColor | border-top-color
generalTextColor | border-bottom-color

Skin parameters redefinition for a selected source and target row

Skin parameters | CSS properties
--- | ---
additionalBackgroundColor | background-color

Skin parameters redefinition for a controls

Skin parameters | CSS properties
--- | ---
tableBorderColor | border-color

## Definition of Custom Style Classes

The following pictures illustrate how CSS classes define styles for component elements.

Classes names

Classes names that define a list representation

Class name | Description
--- | ---
rich-list-picklist | Defines styles for a wrapper <table> element of a pickList

Classes names that define a source and target items representation

Class name | Description
--- | ---
rich-picklist-source-items | Defines styles for a wrapper <div> element of a source list
rich-picklist-target-items | Defines styles for a wrapper <div> element of a target list
rich-picklist-body | Defines styles for a wrapper <table> element of a list body (source and target)
rich-picklist-list | Defines styles for a (source and target) list
rich-picklist-list-content | Defines styles for a (source and target) list content
rich-picklist-internal-tab | Defines styles for a wrapper <table> element of list items (source and target)

Classes names that define rows representation

Class name | Description
--- | ---
rich-picklist-source-row | Defines styles for a source list row
rich-picklist-source-row-selected | Defines styles for a selected row in a source list
rich-picklist-target-row-selected | Defines styles for a selected row in a target list

Classes names that define a source cell representation

Class name | Description
--- | ---
rich-picklist-source-cell | Defines styles for a cell in a source list
rich-picklist-source-cell-selected | Defines styles for a selected cell in a source list
rich-picklist-source-cell-active | Defines styles for an active cell in a source list

Classes names that define a target cell representation

Class name | Description
--- | ---
rich-picklist-target-cell | Defines styles for a target list cell
rich-picklist-target-cell-selected | Defines styles for a selected cell in a target list
rich-picklist-target-cell-active | Defines styles for an active cell in a target list

Classes names that define a control representation

Class name | Description
--- | ---
rich-picklist-controls | Defines styles for wrapper <div> element of a pickList controls
rich-picklist-control-disabled | Defines styles for a control in a disabled state
rich-picklist-control-copyall | Defines styles for a "copyAll" control
rich-picklist-control-copy | Defines styles for a "Copy" control
rich-picklist-control-remove | Defines styles for a "Remove" control
rich-picklist-control-removeall | Defines styles for a "removeAll" control
rich-picklist-control-img | Defines styles for a control image

Classes names that define a button representation

Class name | Description
--- | ---
rich-list-picklist-button | Defines styles for a button
rich-list-picklist-button-disabled | Defines styles for a disabled button
rich-list-picklist-button-press | Defines styles for a pressed button
rich-list-picklist-button-light | Defines styles for a button highlight
rich-list-picklist-button-selection | Defines styles for a button selection
rich-list-picklist-button-content | Defines styles for a button content

In order to redefine styles for all <rich:pickList> components on a page using CSS, it's enough to create classes with the same names (possible classes could be found in the tables above) and define necessary properties in them.

Example:

    ...
    .rich-picklist-list{
            background-color:#ecf4fe;
    }
    ...

This is a result:

Redefinition styles with predefined classes

In the example the background color for lists is changed.

Also it's possible to change styles of particular <rich:pickList> component. In this case you should create own style classes and use them in the corresponding <rich:pickList> styleClass attributes. An example is placed below:

Example:

    ...
    .myClass{
            font-weight:bold;
    }
    ...

The "styleClass" attribute for <rich:pickList> is defined as it's shown in the example below:

Example:

    <rich:pickList ... styleClass="myClass"/>

This is a result:

Redefinition styles with own classes and styleClass attributes

As it could be seen on the picture above, the font style for buttons is changed.

## Relevant Resources Links

On RichFaces LiveDemo page you can see an example of <rich:pickList> usage and sources for the given example.