JBoss.orgCommunity Documentation

6.61.  < rich:listShuttle >

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


Table 6.276. 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. Default value is "button".
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. Default value is "true".
fastOrderControlsVisibleIf "false", 'Top' and 'Bottom' controls aren't displayed. Default value is "true".
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. Default value is "140".
moveControlsVisibleIf "false", 'Copy' and 'Remove' controls aren't displayed. Default value is "true".
onblurHTML: script expression; the element lost the focus
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
onfocusHTML: script expression; the element got the focus
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. Default value is "true".
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. Default value is "true".
sourceCaptionLabelDefines source list caption representation text
sourceListWidthDefines width of a source list. Default value is "140".
sourceRequiredDefines the case when source value is being validated. If the value is "true", there should be at least one item in the source list
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. Default value is "140".
targetRequiredDefines the case when target value is being validated. If the value is "true", there should be at least one item in the target list
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

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:

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 "sourceRequired" and "targetRequired" attributes define the case when source and target values are being validated. If the value of both attributes is "true" there should be at least one item in source and target lists. Otherwise validation fails.

Example:


...
<h:form id="myForm">
        <rich:messages>
                <f:facet name="errorMarker">
                        <h:graphicImage value="/images/ajax/error.gif" />   
                </f:facet>
        </rich:messages>
        <rich:listShuttle id="myListShuttle" sourceValue="#{toolBar.freeItems}" targetValue="#{toolBar.items}"  
                                sourceRequired = "true" targetRequired = "true" var="items" converter="listShuttleconverter"
                                sourceCaptionLabel="Source List" targetCaptionLabel="Target List">
                <rich:column>
                        <h:graphicImage value="#{items.iconURI}" />
                </rich:column>
                <rich:column>
                        <h:outputText value="#{items.label}" />
                </rich:column>
        </rich:listShuttle>
        <a4j:commandButton value="Submit" />
</h:form>
...

In the example above the source list is empty. If you submit the form validation fails and error message appears on a page.

This is the result:


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.




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:














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










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.