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

Figure 6.171.  <rich:ListShuttle> component

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:

Figure 6.172. Style classes

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.

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 of <rich:listShuttle> attributes.

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