### Create new RichFaces Documentation Jira issue

Summary
255 characters left
Description
Environment
This will launch the RichFaces Jira page - to complete your feedback please login if needed, and submit the Jira.

JBoss.org Community Documentation

- Prev
- Next

### 6.12.2. < rich:orderingList > available since 3.1.3

expand all

#### 6.12.2.1. Description

The <rich:orderingList> is a component for ordering items in a list. This component provides possibilities to reorder a list and sort it on the client side.

Figure 6.275. <rich:orderingList> component

#### 6.12.2.2. Key Features

- Highly customizable look and feel

- Reordering possibility for list items

- Multiple selection of list items

- Keyboard support

Table 6.451. rich : orderingList attributes

Attribute Name | Description
--- | ---
activeItem | Stores active item
ajaxKeys | Defines 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
bottomControlLabel | Defines a label for a 'Bottom' control
bottomTitle | HTML: alt for last button
captionLabel | Defines 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.
componentState | It defines EL-binding for a component state for saving or redefinition
controlsHorizontalAlign | Controls 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".
controlsType | Defines type of a control: button or none. Default value is "button".
controlsVerticalAlign | Controls 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
converterMessage | A ValueExpression enabled attribute that, if present, will be used as the text of the converter message, replacing any message that comes from the converter
downControlLabel | Defines a label for a 'Down' control
downTitle | HTML: alt for bottom button
fastOrderControlsVisible | If "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
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
label | A localized user presentable name for this component.
listHeight | Defines height of a list. Default value is "140".
listWidth | Defines width of a list. Default value is "140".
onbottomclick | The 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
ondownclick | The client-side script method to be called when the 'Down' button is clicked
onheaderclick | The 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
onorderchange | The client-side script method to be called before the list order is changed
onorderchanged | The client-side script method to be called when the list order is changed
ontopclick | The client-side script method to be called when the 'Top' button is clicked
onupclick | The client-side script method to be called when the 'Up' button is clicked
orderControlsVisible | If "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
requiredMessage | A 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.
rowKeyConverter | Converter for a row key object
rowKeyVar | The attribute provides access to a row key in a Request scope
rows | HTML: A number of rows to display, or zero for all remaining rows in the list
selection | Collection which stores a set of selected items
showButtonLabels | If "true", shows a label for a button. Default value is "true"
style | HTML: 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.
topControlLabel | Defines a label for a 'Top' control
topTitle | HTML: alt for first button
upControlLabel | Defines a label for a 'Up' control
upTitle | HTML: 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
validatorMessage | A 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
var | Defines a list on the page

Table 6.452. Component identification parameters

Name | Value
--- | ---
component-type | org.richfaces.OrderingList
component-class | org.richfaces.component.html.HtmlOrderingList
component-family | org.richfaces.OrderingList
renderer-type | org.richfaces.OrderingListRenderer

#### 6.12.2.3. Creating the Component with a Page Tag

To create the simplest variant on a page use the following syntax:

Example:

    ...

    <rich:orderingList value="#{bean.list}" var="list">

            <rich:column>

                    <f:facet name="header">

                            <h:outputText value="Name" />

                    </f:facet>

                    <h:inputText value="#{list.name}" />

            </rich:column>

    <rich:orderingList>

    ...

#### 6.12.2.4. Creating the Component Dynamically Using Java

Example:

    import org.richfaces.component.html.HtmlOrderingList;

    ...

    HtmlOrderingList myOrderingList = new HtmlOrderingList();

    ...

#### 6.12.2.5. Details of Usage

The <rich:orderingList> component consists of

- Item list element that displays a list of items. It has three different representations for a single element: common, selected, active. Combination of these states is possible.

- Ordering controls set

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.

## Note

Currently the button controls type is based on <div> element.

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.

Table 6.453. 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 active 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 and selected elements to the next or previous in a list

Table 6.454. Keyboard usage for elements reordering

Keys and combinations | Description
--- | ---
Page Up | Moves selected set to the top of a list
Page Down | Moves selected set to the bottom of a list
CTRL+Up arrow | Moves selected item to one position upper
CTRL+Down arrow | Moves selected item to one position lower

#### 6.12.2.6. JavaScript API

Table 6.455. JavaScript API

Function | Description
--- | ---
hide() | Hides ordering control (to be implemented)
show() | Shows ordering control (to be implemented)
isShown() | Checks if current control is shown (to be implemented)
enable() | Enables ordering control (to be implemented)
disable() | Disables ordering control (to be implemented)
isEnabled() | Checks if current control is enabled (to be implemented)
Up() | Moves up selected item in the list
Down() | Moves down selected item in the list
Top() | Moves top selected item in the list
Bottom() | Moves bottom selected item in the list
getSelection() | Returns currently selected item
getItems() | Returns the collection of all items

#### 6.12.2.7. Facets

Table 6.456. Facets

Facet | Description
--- | ---
caption | Redefines the caption content. Related attribute is "captionLabel"
topControl | Redefines the label for the "Top" control. Related attribute is "topControlLabel"
bottomControl | Redefines the label for the "Bottom" control. Related attribute is "bottomControlLabel"
upControl | Redefines the label for the "Up" control. Related attribute is "upControlLabel"
downControl | Redefines the label for the "Down" control. Related attribute is "downControlLabel"
topControlDisabled | Redefines the disabled label for the "Top" control
bottomControlDisabled | Redefines the disabled label for the "Bottom" control
upControlDisabled | Redefines the disabled label for the "Up" control
downControlDisabled | Redefines the disabled label for the "Down" control

#### 6.12.2.8. Look-and-Feel Customization

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:orderingList> components at once:

- Redefine the corresponding skin parameters

- Add to your style sheets style classes used by a <rich:orderingList> component

#### 6.12.2.9. Skin Parameters Redefinition

Table 6.457. Skin parameters redefinition for a wrapper <div> element of a list

Skin parameters | CSS properties
--- | ---
tableBackgroundColor | background-color
tableBorderColor | border-color

Table 6.458. Skin parameters redefinition for a header cell of a list

Skin parameters | CSS properties
--- | ---
trimColor | background-color
generalTextColor | color
headerFamilyFont | font-family
headerSizeFont | font-size
tableBorderWidth | border-right-width
tableBorderWidth | border-bottom-width
tableBorderColor | border-right-color
tableBorderColor | border-bottom-color

Table 6.459. Skin parameters redefinition for caption element

Skin parameters | CSS properties
--- | ---
headerFamilyFont | font-family
headerSizeFont | font-size
headerWeightFont | font-weight

Table 6.460. Skin parameters redefinition for row element

Skin parameters | CSS properties
--- | ---
headerGradientColor | background-color

Table 6.461. Skin parameters redefinition for selected row element

Skin parameters | CSS properties
--- | ---
additionalBackgroundColor | background-color

Table 6.462. Skin parameters redefinition for cell element

Skin parameters | CSS properties
--- | ---
generalTextColor | color
generalFamilyFont | font-family
generalSizeFont | font-size

Table 6.463. Skin parameters redefinition for selected cell element

Skin parameters | CSS properties
--- | ---
generalTextColor | color
generalFamilyFont | font-family
generalSizeFont | font-size

Table 6.464. Skin parameters redefinition for active cell element

Skin parameters | CSS properties
--- | ---
generalFamilyFont | font-family
generalSizeFont | font-size

Table 6.465. Skin parameters redefinition for a button

Skin parameters | CSS properties
--- | ---
trimColor | background-color
generalTextColor | color
headerFamilyFont | font-family
headerSizeFont | font-size

Table 6.466. Skin parameters redefinition for a disabled button

Skin parameters | CSS properties
--- | ---
trimColor | background-color
tabDisabledTextColor | color
headerFamilyFont | font-family
headerSizeFont | font-size

Table 6.467. 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.468. 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.469. Skin parameters redefinition for a button content

Skin parameters | CSS properties
--- | ---
headerFamilyFont | font-family
headerSizeFont | font-size

Table 6.470. Skin parameters redefinition for a button selection

Skin parameters | CSS properties
--- | ---
generalTextColor | color

Table 6.471. Skin parameters redefinition for top, bottom, up, down controls and for controls in disabled state

Skin parameters | CSS properties
--- | ---
panelBorderColor | border-color

#### 6.12.2.10. Definition of Custom Style Classes

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

Figure 6.276. Classes names

Table 6.472. Classes names that define a list representation

Class name | Description
--- | ---
rich-ordering-list-body | Defines styles for a wrapper table element of an orderingList
rich-ordering-list-output | Defines styles for a wrapper <div> element of a list
rich-ordering-list-items | Defines styles for a wrapper table element of items in the list
rich-ordering-list-content | Defines styles for a list content
rich-ordering-list-header | Defines styles for a wrapper <div> element for a list header
rich-ordering-list-table-header | Defines styles for a wrapper <tr> element for a list header
rich-ordering-list-table-header-cell | Defines styles for a header cell

Table 6.473. Classes names that define a caption representation

Class name | Description
--- | ---
rich-ordering-list-caption | Defines styles for a caption
rich-ordering-list-caption-disabled | Defines styles for a caption in disabled state
rich-ordering-list-caption-active | Defines styles for a caption in active state

Table 6.474. Classes names that define rows representation

Class name | Description
--- | ---
rich-ordering-list-row | Defines styles for a row
rich-ordering-list-row-selected | Defines styles for a selected row
rich-ordering-list-row-active | Defines styles for an active row
rich-ordering-list-row-disabled | Defines styles for a disabled row

Table 6.475. Classes names that define cells representation

Class name | Description
--- | ---
rich-ordering-list-cell | Defines styles for a cell
rich-ordering-list-cell-selected | Defines styles for a selected cell
rich-ordering-list-cell-active | Defines styles for an active cell
rich-ordering-list-cell-disabled | Defines styles for a disabled cell

Table 6.476. Classes names that define a button representation

Class name | Description
--- | ---
rich-ordering-list-button | Defines styles for a button
rich-ordering-list-button-disabled | Defines styles for a disabled button
rich-ordering-list-button-light | Defines styles for a button highlight
rich-ordering-list-button-press | Defines styles for a pressed button
rich-ordering-list-button-content | Defines styles for a button content
rich-ordering-list-button-selection | Defines styles for a button selection
rich-ordering-list-button-valign | Defines styles for a wrapper <td> element for buttons vertical align
rich-ordering-list-button-layout | Defines styles for a wrapper <div> element of buttons layout

Table 6.477. Classes names that define controls representation

Class name | Description
--- | ---
rich-ordering-controls | Defines styles for a controls group
rich-ordering-control-top | Defines styles for a "top" control
rich-ordering-control-bottom | Defines styles for a "bottom" control
rich-ordering-control-up | Defines styles for a "up" control
rich-ordering-control-down | Defines styles for a "down" control
rich-ordering-control-disabled | Defines styles for controls in disabled state

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:

Figure 6.277. Redefinition styles with predefined classes

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:

Figure 6.278. Redefinition styles with own classes and styleClass attributes

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

#### 6.12.2.11. Relevant Resources Links

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

- Prev6.12.1. < rich:listShuttle > ...
- Top of page
- Front page
- Next6.12.3. < rich:pickList > ...