Create new RichFaces Documentation Jira issue

This will launch the RichFaces Jira page - to complete your feedback please login if needed, and submit the Jira.

JBoss.orgCommunity Documentation

6.12.1.  < rich:listShuttle > available since 3.1.3

Table 6.477. rich : listShuttle attributes

Attribute Name Description
activeItemStores active item
ajaxKeysDefines row keys that are updated after an Ajax request
binding JSF: The attribute takes a value-binding expression for a component property of a backing bean
bottomControlClassAssigns one or more space-separated CSS class names to the 'Bottom' button
bottomControlLabelDefines a label for a bottom control
bottomTitleHTML: alt for the last button
columnClasses JSF: Assigns one or more space-separated CSS class names to the columns. If the CSS class names are comma-separated, each class will be assigned to a particular column in the order they follow in the attribute. If you have less class names than columns, the class will be applied to every n-fold column where n is the order in which the class is listed in the attribute. If there are more class names than columns, the overflow ones are ignored.
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. Default value is "middle"
converter JSF: Id of Converter to be used or reference to a Converter
converterMessageA ValueExpression enabled attribute that, if present, will be used as the text of the converter message, replacing any message that comes from the converter
copyAllControlClassAssigns one or more space-separated CSS class names to the 'Copy all' button
copyAllControlLabelDefines a label for a "Copy all" control
copyAllTitleHTML: alt for "Copy all" button
copyControlClassAssigns one or more space-separated CSS class names to the 'Copy' button
copyControlLabelDefines a label for a "Copy" control
copyTitleHTML: alt for a "Copy" button
disabledControlClassAssigns one or more space-separated CSS class names to the component disabled controls
downControlClassAssigns one or more space-separated CSS class names to the 'Down' button
downControlLabelDefines a label for a down control
downTitleHTML: alt for bottom button
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".
id JSF: Every 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
labelA localized user presentable name for this component.
listClassAssigns one or more space-separated CSS class names to the component lists
listsHeightDefines height of the list. Default value is "140".
moveControlsVisibleIf "false", 'Copy' and 'Remove' controls aren't displayed. Default value is "true".
onblur DHTML: The client-side script method to be called when the component loses the focus
onbottomclickThe client-side script method to be called when the 'Bottom' button is clicked
onclick DHTML: The client-side script method to be called when the component is clicked
oncopyallclickThe client-side script method to be called when the 'Copy All' button is clicked
oncopyclickThe client-side script method to be called when the 'Copy' button is clicked
ondblclick DHTML: The client-side script method to be called when the component is double-clicked
ondownclickThe client-side script method to be called when the 'Down' button is clicked
onfocus DHTML: The client-side script method to be called when the component gets the focus
onlistchangeThe client-side script method to be called before the list is changed
onlistchangedThe client-side script method to be called when the list is changed
onmousemove DHTML: The client-side script method to be called when a pointer is moved within the component
onmouseout DHTML: The client-side script method to be called when a pointer is moved away from the component
onmouseover DHTML: The client-side script method to be called when a pointer is moved onto the component
onorderchangeThe client-side script method to be called before the list order is changed
onorderchangedThe client-side script method to be called when the list order is changed
onremoveallclickThe client-side script method to be called when the 'Remove All' button is clicked
onremoveclickThe client-side script method to be called when the 'Remove' button is clicked
ontopclickThe client-side script method to be called when the 'Top' button is clicked
onupclickThe client-side script method to be called when the 'Up' button is clicked
orderControlsVisibleIf "false", 'Up' and 'Down' controls aren't displayed. Default value is "true".
removeAllControlClassAssigns one or more space-separated CSS class names to the 'Remove all' button
removeAllControlLabelDefines a label for a "Remove all" control
removeAllTitleHTML: alt for "Remove all" button
removeControlClassAssigns one or more space-separated CSS class names to the 'Remove' button
removeControlLabelDefines a label for a "Remove" control
removeTitleHTML: alt for a "Remove" button
rendered JSF: If "false", this component is not rendered
requiredMessageA ValueExpression enabled attribute which defines text of validation message to show, if a required field is missing
rowClasses JSF: Assigns one or more space-separated CSS class names to the rows. If the CSS class names are comma-separated, each class will be assigned to a particular row in the order they follow in the attribute. If you have less class names than rows, the class will be applied to every n-fold row where n is the order in which the class is listed in the attribute. If there are more class names than rows, the overflow ones are ignored.
rowKeyConverterConverter for a row key object
rowKeyVarThe attribute provides access to a row key in a Request scope
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
styleHTML: CSS style rules to be applied to the component
styleClass JSF: Assigns one or more CSS class names to the component. Corresponds to the HTML "class" attribute.
switchByClickIf "true", dragging between lists realized by click
switchByDblClickIf "true", items can be moved between the lists by double-clicking on them. Default value is "true".
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
topControlClassAssigns one or more space-separated CSS class names to the 'Top' button
topControlLabelDefines a label for a "Top" control
topTitleHTML: alt for the first button
upControlClassAssigns one or more space-separated CSS class names to the 'Up' button
upControlLabelDefines a label for an "Up" control
upTitleHTML: alt for top button
validator JSF: 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
validatorMessageA ValueExpression enabled attribute that, if present, will be used as the text of the validator message, replacing any message that comes from the validator
valueChangeListener JSF: Listener for value changes
varDefines a list on the page

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.

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.
















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.

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