rich:orderingList orderingList

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
tag-class | org.richfaces.taglib.OrderingListTagHandler

## Creating the Component with a Page Tag

Here is a simple example as it could be used on a page:

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>
    ...

## Creating the Component Dynamically Using Java

Example:

    import org.richfaces.component.html.HtmlOrderingList;
    ...
    HtmlOrderingList myOrderingList = new HtmlOrderingList();
    ...

## 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.

The "selection" attribute stores the collection of items selected by user. 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 will be 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 "header" facets.

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.

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 actve 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

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

## JavaScript API

JavaScript API

Function | Description
--- | ---
Hide() | Hides ordering control
Show() | Shows ordering control
isShown() | Checks if current control is shown
Enable() | Enables ordering control
Disable() | Disables ordering control
isEnabled() | Checksif current control is enabled
moveUp() | Moves up selected item in the list
moveDown() | Moves down selected item in the list
moveTop() | Moves top selected item in the list
moveBottom() | Moves bottom selected item in the list
getSelection() | Returns currently selected item
getItems() | Returns the collection of all items

## 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

## Skin Parameters Redefinition

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

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

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

Skin parameters redefinition for caption element

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

Skin parameters redefinition for row element

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

Skin parameters redefinition for selected row element

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

Skin parameters redefinition for cell element

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

Skin parameters redefinition for selected cell element

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

Skin parameters redefinition for active cell element

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

Skin parameters redefinition for a button

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

Skin parameters redefinition for a disabled button

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

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

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

Skin parameters redefinition for a button content

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

Skin parameters redefinition for a button selection

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

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

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

## Definition of Custom Style Classes

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

Style classes

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

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

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

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

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

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 and define necessary properties in them.

To change styles of particular <rich:orderingList> components, define your own style classes in the corresponding <rich:orderingList> component attributes.

## Relevant Resources Links

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