6.59.  < rich:listShuttle >

6.59.1. Description

The <rich:listShuttle> component is used for moving chosen items from one list into another with their optional reordering there.

<rich:ListShuttle> component

Figure 6.140.  <rich:ListShuttle> component


6.59.2. Key Features

  • Highly customizable look and feel

  • Reordering possibility for lists items

  • Multiple selection of lists items

  • Keyboard support

Table 6.260. rich : listShuttle attributes

Attribute NameDescription
activeItemStores active item
ajaxKeysDefines row keys that are updated after an Ajax request
bindingThe attribute takes a value-binding expression for a component property of a backing bean
bottomControlClassCSS class for bottom control
bottomControlLabelDefines a label for a bottom control
columnClassesComma-separated list of CSS classes for columns
componentStateIt defines EL-binding for a component state for saving or redefinition
controlsTypeDefines type of a control: button or none.
controlsVerticalAlignCustomizes vertically a position of move/copy and order controls relatively to lists
converterId of Converter to be used or reference to a Converter
copyAllControlClassCSS class for copy all control
copyAllControlLabelDefines a label for a copyAll control
copyControlClassCSS class for copy control
copyControlLabelDefines a label for a copy control
disabledControlClassCSS class for a disabled control
downControlClassCSS class for down control
downControlLabelDefines a label for a down control
fastMoveControlsVisibleIf "false", 'Copy All' and 'Remove All' controls aren't displayed
fastOrderControlsVisibleIf "false", 'Top' and 'Bottom' controls aren't displayed.
firstA zero-relative row number of the first row to display
idEvery component may have a unique id that is automatically created if omitted
immediateA flag indicating that this component value must be converted and validated immediately (that is, during Apply Request Values phase), rather than waiting until a Process Validations phase
listClassCSS class for a list
listsHeightDefines height of the list
moveControlsVisibleIf "false", 'Copy' and 'Remove' controls aren't displayed
onbottomclickA JavaScript event handler; a button "Bottom" is clicked
onclickHTML: a script expression; a pointer button is clicked
oncopyallclickA JavaScript event handler; a button "Copy All" is clicked
oncopyclickHTML: a script expression; a button "Copy" is clicked
ondblclickHTML: a script expression; a pointer button is double-clicked
ondownclickA JavaScript event handler; a button "Down" is clicked
onlistchangedA JavaScript event handler called on a list change operation
onmousemoveHTML: a script expression; a pointer is moved within
onmouseoutHTML: a script expression; a pointer is moved away
onmouseoverHTML: a script expression; a pointer is moved onto
onorderchangedHTML: script expression; called after ordering action
onremoveallclickA JavaScript event handler; a button "Remove All" is clicked
onremoveclickA JavaScript event handler; a button "Remove" is clicked
ontopclickA JavaScript event handler; a button "Top" is clicked
onupclickHTML: a script expression; a button "Up" is clicked
orderControlsVisibleIf "false", 'Up' and 'Down' controls aren't displayed.
removeAllControlClassCSS class for remove all control
removeAllControlLabelDefines a label for a removeAll control
removeControlClassCSS class for remove control
removeControlLabelDefines a label for a remove control
renderedIf "false", this component is not rendered
requiredIf "true", this component is checked for non-empty input
rowClassesCSS class for a row
rowKeyRowKey is a representation of an identifier for a specific data row
rowKeyConverterConverter for a row key object
rowKeyVarThe attribute provides access to a row key in a Request scope
rowsA number of rows to display, or zero for all remaining rows in the table
showButtonLabelsShows a label for a button
sourceCaptionLabelDefines source list caption representation text
sourceListWidthDefines width of a source list
sourceRequiredsourceRequired
sourceSelectionManages selection in a source list from the server side
sourceValueDefines a List or Array of items to be shown in a source list
styleCSS style(s) is/are to be applied when this component is rendered
styleClassCorresponds to the HTML class attribute
switchByClickIf "true", dragging between lists realized by click
targetCaptionLabelDefines target list caption representation text
targetListWidthDefines width of a target list
targetRequiredtargetRequired
targetSelectionManages selection in a target list from the server side
targetValueDefines a List or Array of items to be shown in a target list
topControlClassCSS class for top control
topControlLabelDefines a label for a "Top" control
upControlClassCSS class for up control
upControlLabelDefines a label for an "Up" control
validatorMethodBinding pointing at a method that is called during Process Validations phase of the request processing lifecycle, to validate the current value of this component
valueChangeListenerListener for value changes
varDefines a list on the page

6.59.3. Creating the Component with a Page Tag

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

Example:


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

6.59.4. Creating the Component Dynamically Using Java

Example:


import org.richfaces.component.html.HtmlListShuttle;
... 
HtmlListShuttle myListShuttle = new HtmlListShuttle();
...

6.59.5. 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 caption element

  • optional ordering controls set is a set of controls that performs reordering

  • move controls set is a set of controls, which performs moving items between lists

The "sourceValue" attribute defines a List or Array of items to be shown in the source list.

The "targetValue" attribute defines a List or Array of items to be shown in the target list.

The "var" attribute could be shared between both Lists or Arrays to define lists on the page.

The "converter" attribute is used to convert component data to a particular component's value. For example, when you select items in a list, a converter is used to format a set of objects to a strings to be displayed.

Note

It is necessary to override the "equals" and "hashCode" methods in your own class!

The "sourceSelection" attribute stores the collection of items selected by you in the source list. The "targetSelection" attribute stores the collection of items selected by you in the target list.

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.


...
<rich:listShuttle var="item" sourceValue="#{bean.source}" targetValue="#{bean.target}" sourceSelection="#{bean.sourceSelection}" 
                        targetSelection="#{bean.targetSelection}" 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>
        <rich:column>
                <h:outputText value="#{items.name}" />
        </rich:column>
</rich:listShuttle>
...

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}" converter="listShuttleconverter">
...                  
        <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:listShuttle>
...

The <rich:listShuttle> component also provides 4 predefined controls in move controls set for moving items between source and target lists. Every control has possibility to be disabled.

A move controls set could be defined with "copyControlLabel" , "removeControlLabel" , "copyAllControlLabel" , "removeAllControlLabel" attributes.

It is also possible to use "copyControl" , "removeControl" , "copyAllControl" , "removeAllControl" facets in order to replace the default controls with facets content.


...
<rich:listShuttle var="item" sourceValue="#{bean.source}" targetValue="#{bean.target}" converter="listShuttleconverter"
                        copyControlLabel="Copy" removeControlLabel="Remove"
                        copyAllControlLabel="Copy all" removeAllControlLabel="Remove all">
        <h:column>
                <f:facet name="header">
                        <h:outputText value="Cars" />
                </f:facet>
                <h:outputText value="#{item.name}" />
        </h:column>
</rich:listShuttle>
...

Controls rendering is based on the "controlsType" attribute. Possible types are button and none.

Note

Currently the button controls type is based on <div> element.

The <rich:listShuttle> component allows to use internationalization method to redefine and localize the labels. You could use application resource bundle and define RICH_SHUTTLES_TOP_LABEL, RICH_SHUTTLES_BOTTOM_LABEL, RICH_SHUTTLES_UP_LABEL, RICH_SHUTTLES_DOWN_LABEL RICH_LIST_SHUTTLE_COPY_ALL_LABEL, RICH_LIST_SHUTTLE_COPY_LABEL, RICH_LIST_SHUTTLE_REMOVE_ALL_LABEL, RICH_LIST_SHUTTLE_REMOVE_LABEL there.

You could also pack org.richfaces.renderkit.listShuttle resource bundle with your JARs defining the same properties.

Table 6.261. Keyboard usage for elements selection

Keys and combinations Description
CTRL+clickInverts selection for an item
SHIFT+clickSelects all rows from active one to a clicked row if they differ, else select the actve row. All other selections are cleared
CTRL+ASelects all elements inside the list if some active element is already present in a list
Up, Down arrowsChanges 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

Table 6.262. Keyboard usage for elements reordering

Keys and combinations Description
HomeMoves selected set to the top of a list
EndMoves selected set to the bottomof a list
CTRL+Up arrowMoves selected item to one position upper
CTRL+Down arrowMoves selected item to one position lower

6.59.6. JavaScript API

Table 6.263. JavaScript API

FunctionDescription
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

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

6.59.8. Skin Parameters Redefinition

Table 6.264. Skin parameters redefinition for items in the source and target lists

Skin parametersCSS properties
generalBackgroundColorbackground-color
tableBorderColorborder-color
tableBorderWidthborder-width

Table 6.265. Skin parameters redefinition for caption in the source and target lists

Skin parametersCSS properties
headerFamilyFontfont-family
headerSizeFontfont-size
headerWeightFontfont-weight

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

Skin parametersCSS properties
additionalBackgroundColorbackground-color

Table 6.267. Skin parameters redefinition for a header cell

Skin parametersCSS properties
headerBackgroundColorbackground-color
headerTextColorcolor
headerFamilyFontfont-family
headerSizeFontfont-size
tableBorderWidthborder-width
subBorderColorborder-top-color
panelBorderColorborder-bottom-color
panelBorderColorborder-right-color

Table 6.268. Skin parameters redefinition for a selected cell

Skin parametersCSS properties
generalTextColorcolor
generalFamilyFontfont-family
generalSizeFontfont-size

Table 6.269. Skin parameters redefinition for an active cell

Skin parametersCSS properties
generalSizeFontfont-size
generalFamilyFontfont-family

Table 6.270. Skin parameters redefinition for controls

Skin parametersCSS properties
tableBorderColorborder-color

Table 6.271. Skin parameters redefinition for a button

Skin parametersCSS properties
trimColorbackground-color
generalTextColorcolor
headerFamilyFontfont-family
headerSizeFontfont-size

Table 6.272. Skin parameters redefinition for a disabled button

Skin parametersCSS properties
trimColorbackground-color
tabDisabledTextColorcolor
headerFamilyFontfont-family
headerSizeFontfont-size

Table 6.273. Skin parameters redefinition for a button highlight

Skin parametersCSS properties
trimColorbackground-color
selectControlColorborder-color
tableBorderWidthborder-width
headerFamilyFontfont-family
headerSizeFontfont-size
generalTextColorcolor

Table 6.274. Skin parameters redefinition for a pressed button

Skin parametersCSS properties
additionalBackgroundColorbackground-color
tableBorderColorborder-color
tableBorderWidthborder-width
headerFamilyFontfont-family
headerSizeFontfont-size
generalTextColorcolor

Table 6.275. Skin parameters redefinition for a button content

Skin parametersCSS properties
headerFamilyFontfont-family
headerSizeFontfont-size

Table 6.276. Skin parameters redefinition for a button selection

Skin parametersCSS properties
generalTextColorcolor

6.59.9. Definition of Custom Style Classes

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

Style classes
Style classes

Figure 6.141. Style classes


Table 6.277. Classes names that define a list representation

Class nameDescription
rich-list-shuttleDefines styles for a wrapper table element of a listShuttle
rich-list-shuttle-captionDefines styles for a list caption
rich-shuttle-bodyDefines styles for a list body
rich-shuttle-list-contentDefines styles for a list content
rich-shuttle-source-itemsDefines styles for a wrapper <div> element for source list
rich-shuttle-target-itemsDefines styles for a wrapper <div> element for target list
rich-shuttle-list-headerDefines styles for a lists header
rich-shuttle-header-tab-cellDefines styles for a header cell

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

Class nameDescription
rich-shuttle-source-captionDefines styles for a caption in a source list
rich-shuttle-target-captionDefines styles for a caption in a target list

Table 6.279. Classes names that define a rows representations in a source list

Class nameDescription
rich-shuttle-source-rowDefines styles for a row in a source list
rich-shuttle-source-row-selectedDefines styles for a selected row in a source list
rich-shuttle-source-row-activeDefines styles for an active row in a source list

Table 6.280. Classes names that define a rows representations in a target list

Class nameDescription
rich-shuttle-target-rowDefines styles for a row in a target list
rich-shuttle-target-row-selectedDefines styles for a selected row in a target list
rich-shuttle-target-row-activeDefines styles for an active row in a target list

Table 6.281. Classes names that define a cells representations in a source list

Class nameDescription
rich-shuttle-source-cellDefines styles for a cell in a source list
rich-shuttle-source-cell-selectedDefines styles for a selected cell in a source list
rich-shuttle-source-cell-activeDefines styles for an active cell in a source list

Table 6.282. Classes names that define a cells representations in a target list

Class nameDescription
rich-shuttle-target-cellDefines styles for a cell in a target list
rich-shuttle-target-cell-selectedDefines styles for a selected cell in a target list
rich-shuttle-target-cell-activeDefines styles for an active cell in a target list

Table 6.283. Classes names that define controls representations

Class nameDescription
rich-shuttle-controlsDefines styles for a controls group
rich-shuttle-topDefines styles for a "Top" control
rich-shuttle-bottomDefines styles for a "Bottom" control
rich-shuttle-upDefines styles for a "Up" control
rich-shuttle-downDefines styles for a "Down" control
rich-shuttle-copyDefines styles for a "Copy" control
rich-shuttle-removeDefines styles for a "Remove" control
rich-shuttle-copyAllDefines styles for a "copyAll" control
rich-shuttle-removeAllDefines styles for a "removeAll" control
rich-shuttle-control-disabledDefines styles for a control in a disabled state

Table 6.284. Classes names that define a button representation

Class nameDescription
rich-list-shuttle-buttonDefines styles for a button
rich-list-shuttle-button-disabledDefines styles for a disabled button
rich-list-shuttle-button-lightDefines styles for a button highlight
rich-list-shuttle-button-pressDefines styles for a pressed button
rich-list-shuttle-button-contentDefines styles for a button content
rich-list-shuttle-button-selectionDefines 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 (possible classes could be found in the tables above) and define necessary properties in them.

Example:


...
.rich-shuttle-source-row-active{
        
background-color:#FFE4B5;
}    
...

This is a result:

Redefinition styles with predefined classes

Figure 6.142. Redefinition styles with predefined classes


In the example an active row background color in the source list was changed.

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

Example:


...
.myClass{
        
font-style:italic;
}
...

The "rowClasses" attribute for <rich:listShuttle> is defined as it’s shown in the example below:

Example:


<rich:listShuttle ... rowClasses="myClass"/>

This is a result:

Redefinition styles with own classes and styleClass attributes

Figure 6.143. Redefinition styles with own classes and styleClass attributes


As it could be seen on the picture above, font style for row items was changed.

6.59.10. Relevant Resources Links

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