The <rich:listShuttle> component is used for moving chosen items from one list into another with their optional reordering there.
Highly customizable look and feel
Reordering possibility for lists items
Multiple selection of lists items
Keyboard support
Table 6.260. rich : listShuttle attributes
Attribute Name | Description |
---|---|
activeItem | Stores active item |
ajaxKeys | Defines row keys that are updated after an Ajax request |
binding | The attribute takes a value-binding expression for a component property of a backing bean |
bottomControlClass | CSS class for bottom control |
bottomControlLabel | Defines a label for a bottom control |
columnClasses | Comma-separated list of CSS classes for columns |
componentState | It defines EL-binding for a component state for saving or redefinition |
controlsType | Defines type of a control: button or none. |
controlsVerticalAlign | Customizes vertically a position of move/copy and order controls relatively to lists |
converter | Id of Converter to be used or reference to a Converter |
copyAllControlClass | CSS class for copy all control |
copyAllControlLabel | Defines a label for a copyAll control |
copyControlClass | CSS class for copy control |
copyControlLabel | Defines a label for a copy control |
disabledControlClass | CSS class for a disabled control |
downControlClass | CSS class for down control |
downControlLabel | Defines a label for a down control |
fastMoveControlsVisible | If "false", 'Copy All' and 'Remove All' controls aren't displayed |
fastOrderControlsVisible | If "false", 'Top' and 'Bottom' controls aren't displayed. |
first | A zero-relative row number of the first row to display |
id | Every component may have a unique id that is automatically created if omitted |
immediate | A 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 |
listClass | CSS class for a list |
listsHeight | Defines height of the list |
moveControlsVisible | If "false", 'Copy' and 'Remove' controls aren't displayed |
onbottomclick | A JavaScript event handler; a button "Bottom" is clicked |
onclick | HTML: a script expression; a pointer button is clicked |
oncopyallclick | A JavaScript event handler; a button "Copy All" is clicked |
oncopyclick | HTML: a script expression; a button "Copy" is clicked |
ondblclick | HTML: a script expression; a pointer button is double-clicked |
ondownclick | A JavaScript event handler; a button "Down" is clicked |
onlistchanged | A JavaScript event handler called on a list change operation |
onmousemove | HTML: a script expression; a pointer is moved within |
onmouseout | HTML: a script expression; a pointer is moved away |
onmouseover | HTML: a script expression; a pointer is moved onto |
onorderchanged | HTML: script expression; called after ordering action |
onremoveallclick | A JavaScript event handler; a button "Remove All" is clicked |
onremoveclick | A JavaScript event handler; a button "Remove" is clicked |
ontopclick | A JavaScript event handler; a button "Top" is clicked |
onupclick | HTML: a script expression; a button "Up" is clicked |
orderControlsVisible | If "false", 'Up' and 'Down' controls aren't displayed. |
removeAllControlClass | CSS class for remove all control |
removeAllControlLabel | Defines a label for a removeAll control |
removeControlClass | CSS class for remove control |
removeControlLabel | Defines a label for a remove control |
rendered | If "false", this component is not rendered |
required | If "true", this component is checked for non-empty input |
rowClasses | CSS class for a row |
rowKey | RowKey is a representation of an identifier for a specific data row |
rowKeyConverter | Converter for a row key object |
rowKeyVar | The attribute provides access to a row key in a Request scope |
rows | A number of rows to display, or zero for all remaining rows in the table |
showButtonLabels | Shows a label for a button |
sourceCaptionLabel | Defines source list caption representation text |
sourceListWidth | Defines width of a source list |
sourceRequired | sourceRequired |
sourceSelection | Manages selection in a source list from the server side |
sourceValue | Defines a List or Array of items to be shown in a source list |
style | CSS style(s) is/are to be applied when this component is rendered |
styleClass | Corresponds to the HTML class attribute |
switchByClick | If "true", dragging between lists realized by click |
targetCaptionLabel | Defines target list caption representation text |
targetListWidth | Defines width of a target list |
targetRequired | targetRequired |
targetSelection | Manages selection in a target list from the server side |
targetValue | Defines a List or Array of items to be shown in a target list |
topControlClass | CSS class for top control |
topControlLabel | Defines a label for a "Top" control |
upControlClass | CSS class for up control |
upControlLabel | Defines a label for an "Up" control |
validator | MethodBinding pointing at a method that is called during Process Validations phase of the request processing lifecycle, to validate the current value of this component |
valueChangeListener | Listener for value changes |
var | Defines a list on the page |
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>
...
Example:
import org.richfaces.component.html.HtmlListShuttle;
...
HtmlListShuttle myListShuttle = new HtmlListShuttle();
...
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.
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.
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+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 |
Table 6.262. 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 |
Table 6.263. 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 |
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
Table 6.264. Skin parameters redefinition for items in the source and target lists
Skin parameters | CSS properties |
---|---|
generalBackgroundColor | background-color |
tableBorderColor | border-color |
tableBorderWidth | border-width |
Table 6.265. Skin parameters redefinition for caption in the source and target lists
Skin parameters | CSS properties |
---|---|
headerFamilyFont | font-family |
headerSizeFont | font-size |
headerWeightFont | font-weight |
Table 6.266. Skin parameters redefinition for a selected rows in the source and target lists
Skin parameters | CSS properties |
---|---|
additionalBackgroundColor | background-color |
Table 6.267. 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 |
Table 6.268. Skin parameters redefinition for a selected cell
Skin parameters | CSS properties |
---|---|
generalTextColor | color |
generalFamilyFont | font-family |
generalSizeFont | font-size |
Table 6.269. Skin parameters redefinition for an active cell
Skin parameters | CSS properties |
---|---|
generalSizeFont | font-size |
generalFamilyFont | font-family |
Table 6.270. Skin parameters redefinition for controls
Skin parameters | CSS properties |
---|---|
tableBorderColor | border-color |
Table 6.271. Skin parameters redefinition for a button
Skin parameters | CSS properties |
---|---|
trimColor | background-color |
generalTextColor | color |
headerFamilyFont | font-family |
headerSizeFont | font-size |
Table 6.272. Skin parameters redefinition for a disabled button
Skin parameters | CSS properties |
---|---|
trimColor | background-color |
tabDisabledTextColor | color |
headerFamilyFont | font-family |
headerSizeFont | font-size |
Table 6.273. 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 |
Table 6.274. 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 |
Table 6.275. Skin parameters redefinition for a button content
Skin parameters | CSS properties |
---|---|
headerFamilyFont | font-family |
headerSizeFont | font-size |
Table 6.276. Skin parameters redefinition for a button selection
Skin parameters | CSS properties |
---|---|
generalTextColor | color |
On the screenshot there are classes names that define styles for component elements.
Table 6.277. 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 |
Table 6.278. 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 |
Table 6.279. 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 |
Table 6.280. 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 |
Table 6.281. 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 |
Table 6.282. 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 |
Table 6.283. 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 |
Table 6.284. 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 (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:
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:
As it could be seen on the picture above, font style for row items was changed.
Here you can see an example of <rich:listShuttle> usage and sources for the given example.