rich:listShuttle listShuttle

## Creating the Component with a Page Tag

Here is a simple example as it could be used on a page:

Example:

    ...
    <rich:listShuttle var="item" sourceValue="#{bean.source}" targetValue="#{bean.target}" converter="listShuttleconverter">
            <f:facet name="sourceCaption">
                    <h:outputText value="Cars Store #1" />
            </f:facet>
            <f:facet name="targetCaption">
    	     <h:outputText value="Cars Store #2" />
            </f:facet>
            <h:column>
    	    <f:facet name="header">
    	            <h:outputText value="Cars" />
    	    </f:facet>
    	    <h:outputText value="#{item.name}" />
            </h:column>
    </rich:listShuttle>
    ...

## Creating the Component Dynamically Using Java

Example:

    import org.richfaces.component.html.listShuttle;
    ...
    HtmllistShuttle mylistShuttle = new HtmllistShuttle();
    ...

## Details of Usage

The <rich:listShuttle> component consists of the following parts:

- two item lists (source and target). List consists of items. Each item has three different representations: common, selected, active
- optional ordering controls set is a set of controls that performs reordering

The "sourceValue" attribute defines the collection to be shown in source list.

The "targetValue" attribute defines the collection to store the value from target list.

The "var" could be shared between both collections to defined lists on the page.

Captions could be added to a list only after it was defined as a "sourceCaption" and "targetCaption" named facets inside the component or defined with the "sourceCaptionLabel" and "targetCaptionLabel" attribute.

The <rich:listShuttle> component provides the possibility to use ordering controls set, which performs reordering in the target item list. Every control has possibility to be disabled.

An ordering controls set could be defined with "topControlLabel", "bottomControlLabel", "upControlLabel", "downControlLabel"attributes.

It is also possible to use "topControl" , "topControlDisabled" , "bottomControl" , "bottomControlDisabled" , "upControl" , "upControlDisabled" , "downControl" , "downControlDisabled" facets in order to replace the default controls with facets content.

Example:

    ...
    <rich:listShuttle var="item" sourceValue="#{bean.source}" targetValue="#{bean.target}" sourceSelection="#{bean.sourceSelection}" targetSelection="#{bean.targetSelection}">
    ...
            <f:facet name="topControl">
                <h:outputText value="Move to top" />
            </f:facet>
            <f:facet name="upControl">
                <h:outputText value="Move up" />
            </f:facet>
            <f:facet name="downControl">
                <h:outputText value="Move down" />
            </f:facet>
            <f:facet name="bottomControl">
                <h:outputText value="Move to bottom" />
            </f:facet>
    <rich:orderingList>
    ...

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 actve 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 element to the next or previous in a list and make it the only selected. Scroll follows the selection to keep it visible

Keyboard usage for elements reordering

Keys and combinations | Description
--- | ---
Home | Moves selected set to the top of a list
End | Moves selected set to the bottomof a list
CTRL+Up arrow | Moves selected item to one position upper
CTRL+Down arrow | Moves selected item to one position lower

## JavaScript API

JavaScript API

Function | Description
--- | ---
Hide() | Hides ordering control
Show() | Shows ordering control
isShown() | Checks if current control is shown
Enable() | Enables ordering control
Disable() | Disables ordering control
isEnabled() | Checks if current control is enabled
moveUp() | Moves up selected item in the list
moveDown() | Moves down selected item in the list
moveTop() | Moves top selected item in the list
moveBottom() | Moves bottom selected item in the list
copy() | Copies selected item from the source list to the target list
remove() | Removes selected item from the target list to the source list
copyAll() | Copies all items from the source list to the target list
removeAll() | Removes all items from the target list to the source list
getSelection() | Returns currently selected item
getItems() | Returns the collection of all items

## 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:listShuttle> components at once:

- Redefine the corresponding skin parameters
- Add to your style sheets style classes used by a <rich:listShuttle> component

## Skin Parameters Redefinition

Skin parameters redefinition for items in the source and target lists

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

Skin parameters redefinition for caption in the source and target lists

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

Skin parameters redefinition for a selected rows in the source and target lists

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

Skin parameters redefinition for a header cell

Skin parameters | CSS properties
--- | ---
headerBackgroundColor | background-color
headerTextColor | color
headerFamilyFont | font-family
headerSizeFont | font-size
tableBorderWidth | border-width
subBorderColor | border-top-color
panelBorderColor | border-bottom-color
panelBorderColor | border-right-color

Skin parameters redefinition for a selected cell

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

Skin parameters redefinition for an active cell

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

Skin parameters redefinition for controls

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

Skin parameters redefinition for a button

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

Skin parameters redefinition for a disabled button

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

Skin parameters redefinition for a button highlight

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

Skin parameters redefinition for a pressed button

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

Skin parameters redefinition for a button content

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

Skin parameters redefinition for a button selection

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

## Definition of Custom Style Classes

On the screenshot there are classes names that define styles for component elements.

Style classes

Classes names that define a list representation

Class name | Description
--- | ---
rich-list-shuttle | Defines styles for a wrapper table element of a listShuttle
rich-list-shuttle-caption | Defines styles for a list caption
rich-shuttle-body | Defines styles for a list body
rich-shuttle-list-content | Defines styles for a list content
rich-shuttle-source-items | Defines styles for a wrapper <div> element for source list
rich-shuttle-target-items | Defines styles for a wrapper <div> element for target list
rich-shuttle-list-header | Defines styles for a lists header
rich-shuttle-header-tab-cell | Defines styles for a header cell

Classes names that define a caption representations in a source and target lists

Class name | Description
--- | ---
rich-shuttle-source-caption | Defines styles for a caption in a source list
rich-shuttle-target-caption | Defines styles for a caption in a target list

Classes names that define a rows representations in a source list

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

Classes names that define a rows representations in a target list

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

Classes names that define a cells representations in a source list

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

Classes names that define a cells representations in a target list

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

Classes names that define controls representations

Class name | Description
--- | ---
rich-shuttle-controls | Defines styles for a controls group
rich-shuttle-top | Defines styles for a "Top" control
rich-shuttle-bottom | Defines styles for a "Bottom" control
rich-shuttle-up | Defines styles for a "Up" control
rich-shuttle-down | Defines styles for a "Down" control
rich-shuttle-copy | Defines styles for a "Copy" control
rich-shuttle-remove | Defines styles for a "Remove" control
rich-shuttle-copyAll | Defines styles for a "copyAll" control
rich-shuttle-removeAll | Defines styles for a "removeAll" control
rich-shuttle-control-disabled | Defines styles for a control in a disabled state

Classes names that define a button representation

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

In order to redefine styles for all <rich:listShuttle> components on a page using CSS, it's enough to create classes with the same names and define necessary properties in them.

To change styles of particular <rich:listShuttle> components, define your own style classes in the corresponding <rich:listShuttle> component attributes.

## Relevant Resources Links

Here you can see an example of <rich:listShuttle> usage and sources for the given example.