JBoss.org Community Documentation

- Prev
- Next

## 6.68. < rich:orderingList >

### 6.68.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.190. <rich:orderingList> component

### 6.68.2. Key Features

- Highly customizable look and feel

- Reordering possibility for list items

- Multiple selection of list items

- Keyboard support

Table 6.322. rich : orderingList attributes

Attribute Name | Description
--- | ---
activeItem | Stores active item
ajaxKeys | Defines row keys that are updated after an Ajax request
binding | The attribute takes a value-binding expression for a component property of a backing bean
bottomControlLabel | Defines a label for a 'Bottom' control
captionLabel | Defines caption representation text
columnClasses | CSS class for a column
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" (default) - controls should be rendered centered relatively to a list.
converter | Id of Converter to be used or reference to a Converter
downControlLabel | Defines a label for a 'Down' control
fastOrderControlsVisible | If "false", 'Top' and 'Bottom' controls aren't displayed. Default value is "true".
id | 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
listHeight | Defines height of a list. Default value is "140".
listWidth | Defines width of a list. Default value is "140".
onbottomclick | A JavaScript event handler; a button "Bottom" is clicked
onclick | HTML: a script expression; a pointer button is clicked
ondblclick | HTML: a script expression; a pointer button is double-clicked
ondownclick | A JavaScript event handler; a button "Down" is clicked
onheaderclick | A JavaScript event handler; a header is clicked
onmousemove | HTML: a script expression; a pointer is moved within
onmouseout | HTML: a script expression; a pointer is moved away
onmouseover | HTML: a script expression; a pointer is moved onto
onorderchanged | A JavaScript event handler called on an order operation
ontopclick | A JavaScript event handler; a button "Top" is clicked
onupclick | HTML: a script expression; a button "Up" is clicked
orderControlsVisible | If "false", 'Up' and 'Down' controls aren't displayed. Default value is "true".
rendered | If "false", this component is not rendered
required | If "true", this component is checked for non-empty input
rowClasses | CSS class for a row
rowKeyConverter | Converter for a row key object
rowKeyVar | The attribute provides access to a row key in a Request scope
rows | 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
style | CSS style(s) is/are to be applied when this component is rendered
styleClass | Corresponds to the HTML class attribute
topControlLabel | Defines a label for a 'Top' control
upControlLabel | Defines a label for a 'Up' control
validator | 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
value | Defines a List or Array of items to be shown in a list
valueChangeListener | Listener for value changes
var | Defines a list on the page

Table 6.323. 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.68.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.68.4. Creating the Component Dynamically Using Java

Example:

    import org.richfaces.component.html.HtmlOrderingList;

    ...

    HtmlOrderingList myOrderingList = new HtmlOrderingList();

    ...

### 6.68.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 "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.324. 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.325. 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 bottomof a list
CTRL+Up arrow | Moves selected item to one position upper
CTRL+Down arrow | Moves selected item to one position lower

### 6.68.6. JavaScript API

Table 6.326. 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.68.7. 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.68.8. Skin Parameters Redefinition

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

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

Table 6.328. 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.329. Skin parameters redefinition for caption element

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

Table 6.330. Skin parameters redefinition for row element

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

Table 6.331. Skin parameters redefinition for selected row element

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

Table 6.332. Skin parameters redefinition for cell element

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

Table 6.333. Skin parameters redefinition for selected cell element

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

Table 6.334. Skin parameters redefinition for active cell element

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

Table 6.335. Skin parameters redefinition for a button

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

Table 6.336. Skin parameters redefinition for a disabled button

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

Table 6.337. 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.338. 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.339. Skin parameters redefinition for a button content

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

Table 6.340. Skin parameters redefinition for a button selection

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

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

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

### 6.68.9. Definition of Custom Style Classes

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

Figure 6.191. Classes names

Table 6.342. 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.343. 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.344. 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.345. 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.346. 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.347. 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.192. 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.193. 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.68.10. Relevant Resources Links

Here you can see an example of <rich:orderingList> usage and sources for the given example.

- Prev6.67. < rich:modalPanel >
- Top of page
- Front page
- Next6.69. < rich:paint2D >