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.2.  < rich:orderingList > available since 3.1.3

Table 6.503. rich : orderingList 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
bottomControlLabelDefines a label for a 'Bottom' control
bottomTitleHTML: alt for last button
captionLabelDefines caption representation text
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
controlsHorizontalAlignControls horizontal rendering. Possible values: "left" - controls should be rendered to the left side of a list. "right"- controls should be rendered to the right side of a list. Default value is "right".
controlsTypeDefines type of a control: button or none. Default value is "button".
controlsVerticalAlignControls vertical rendering. Possible values: "top" - controls should be rendered aligned to top side of a list. "bottom" - controls should be rendered aligned to bottom side of a list. "middle" - controls should be rendered centered relatively to a list. 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
downControlLabelDefines a label for a 'Down' control
downTitleHTML: alt for bottom button
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.
listHeightDefines height of a list. Default value is "140".
listWidthDefines width of a list. Default value is "140".
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
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
onheaderclickThe client-side script method to be called when the list header is clicked
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
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".
rendered JSF: If "false", this component is not rendered
required JSF: If "true", this component is checked for non-empty input
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
rowsHTML: A number of rows to display, or zero for all remaining rows in the list
selectionCollection which stores a set of selected items
showButtonLabelsIf "true", shows a label for a button. Default value is "true"
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.
topControlLabelDefines a label for a 'Top' control
topTitleHTML: alt for first button
upControlLabelDefines a label for a '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
value JSF: Defines a List or Array of items to be shown in a list
valueChangeListener JSF: Listener for value changes
varDefines a list on the page


The <rich:orderingList> component consists of

The "value" and "var" attributes are used to access the values of a list.

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

The information about the "converter" attribute is here.

The "selection" attribute stores the collection of items selected by you. In the example below after submitting the form the current collection is placed in the object's property and then <rich:dataTable> with selected items is shown.

Example:


...
<h:form>
        <rich:orderingList value="#{bean.simpleItems}" var="item" selection="#{bean.selection}" controlsType="button">
                <rich:column>
                    <f:facet name="header">
                            <h:outputText value="Cars" />
                    </f:facet>
                    <h:outputText value="#{item}" />
                </rich:column>
        </rich:orderingList>
        <rich:dataTable id="infoPanelID" value="#{bean.info}" var="info" rendered="true">
                <rich:column>
                            <h:outputText value="#{info}" />
                </rich:column>
        </rich:dataTable>
        <a4j:commandButton value="reRender" reRender="infoPanelID" />
</h:form>
...

The <rich:orderingList> component allows to use "caption" facet. A caption could be also defined with "captionLabel" attribute.

Simple example is placed below.

Example:


...
<rich:orderingList value="#{bean.simpleItems}" var="item" controlsType="button" selection="#{bean.selection}">
        <f:facet name="caption">
                <h:outputText value="Caption Facet" />
        </f:facet>
        <rich:column>
                <f:facet name="header">
                <h:outputText value="Cars" />
                </f:facet>
                <h:outputText value="#{item.name}" />
        </rich:column>
        <rich:column>
                <f:facet name="header">
                <h:outputText value="Price" />
                </f:facet>
                <h:outputText value="#{item.price}" />
        </rich:column>
</rich:orderingList>
...

The <rich:orderingList> component provides the possibility to use ordering controls set, which performs reordering. 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:orderingList value="#{bean.simpleItems}" var="item" controlsType="button" selection="#{bean.selection}">
        <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:orderingList>
...

The position of the controls relatively to a list could be customized with:

  • "controlsHorizontalAlign" attribute. Possible values:

    • "left" - controls render to the left side of a list

    • "right" (default) - controls render to the right side of a list

    • "center" - controls is centered

  • "controlsVerticalAlign" attribute. Possible values:

    • "top" - controls render aligned to the top side of a list

    • "bottom" - controls render aligned to the bottom side of a list

    • "center" (default) - controls is centered relatively to a list

The <rich:orderingList> component has a possibility to hide any of the controls by pairs using following attributes:

  • "orderControlsVisible" attribute has two values: "true" or "false". If false Up and Down controls are not displayed.

  • "fastOrderControlsVisible" attribute has two values: "true" or "false". If false Top and Bottom controls are not displayed.

The <rich:orderingList> 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 there.

You could also pack org.richfaces.renderkit.orderingList 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:orderingList> 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-ordering-list-table-header-cell{
        
font-weight:bold;
}
...

This is a result:


In the example the font weight for header text was changed.

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

Example:


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

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

Example:


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

This is a result:


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

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