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

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

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

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

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.

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

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

## JavaScript API

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

## Facets

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

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

Classes names

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 (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:

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:

Redefinition styles with own classes and styleClass attributes

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

## Relevant Resources Links

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