6.63.  < rich:orderingList >

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

<rich:orderingList> component

Figure 6.158.  <rich:orderingList> component


6.63.2. Key Features

  • Highly customizable look and feel

  • Reordering possibility for list items

  • Multiple selection of list items

  • Keyboard support

Table 6.300. rich : orderingList attributes

Attribute NameDescription
activeItemStores active item
ajaxKeysDefines row keys that are updated after an Ajax request
bindingThe attribute takes a value-binding expression for a component property of a backing bean
bottomControlLabelDefines a label for a 'Bottom' control
captionLabelDefines caption representation text
columnClassesCSS class for a column
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(Default)- controls should be rendered to the right side of a list.
controlsTypeDefines type of a control: button or none.
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 (default) - controls should be rendered centered relatively to a list.
converterId of Converter to be used or reference to a Converter
downControlLabelDefines a label for a 'Down' control
fastOrderControlsVisibleIf "false", 'Top' and 'Bottom' controls aren't displayed.
idEvery 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
listHeightDefines height of a list
listWidthDefines width of a list
onbottomclickA JavaScript event handler; a button "Bottom" is clicked
onclickHTML: a script expression; a pointer button is clicked
ondblclickHTML: a script expression; a pointer button is double-clicked
ondownclickA JavaScript event handler; a button "Down" is clicked
onheaderclickA JavaScript event handler; a header is clicked
onmousemoveHTML: a script expression; a pointer is moved within
onmouseoutHTML: a script expression; a pointer is moved away
onmouseoverHTML: a script expression; a pointer is moved onto
onorderchangedA JavaScript event handler called on an order operation
ontopclickA JavaScript event handler; a button "Top" is clicked
onupclickHTML: a script expression; a button "Up" is clicked
orderControlsVisibleIf "false", 'Up' and 'Down' controls aren't displayed.
renderedIf "false", this component is not rendered
requiredIf "true", this component is checked for non-empty input
rowClassesCSS class for a row
rowKeyRowKey is a representation of an identifier for a specific data row
rowKeyConverterConverter for a row key object
rowKeyVarThe attribute provides access to a row key in a Request scope
rowsA 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
styleCSS style(s) is/are to be applied when this component is rendered
styleClassCorresponds to the HTML class attribute
topControlLabelDefines a label for a 'Top' control
upControlLabelDefines a label for a 'Up' control
validatorMethodBinding pointing at a method that is called during Process Validations phase of the request processing lifecycle, to validate the current value of this component
valueDefines a List or Array of items to be shown in a list
valueChangeListenerListener for value changes
varDefines a list on the page

Table 6.301. Component identification parameters

NameValue
component-typeorg.richfaces.OrderingList
component-classorg.richfaces.component.html.HtmlOrderingList
component-familyorg.richfaces.OrderingList
renderer-typeorg.richfaces.OrderingListRenderer

6.63.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.63.4. Creating the Component Dynamically Using Java

Example:


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

6.63.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.302. Keyboard usage for elements selection

Keys and combinations Description
CTRL+clickInverts selection for an item
SHIFT+clickSelects all rows from active one to a clicked row if they differ, else select the active row. All other selections are cleared
CTRL+ASelects all elements inside the list if some active element is already present in a list
Up, Down arrowsChanges the active and selected elements to the next or previous in a list

Table 6.303. Keyboard usage for elements reordering

Keys and combinations Description
Page UpMoves selected set to the top of a list
Page DownMoves selected set to the bottomof a list
CTRL+Up arrowMoves selected item to one position upper
CTRL+Down arrowMoves selected item to one position lower

6.63.6. JavaScript API

Table 6.304. JavaScript API

FunctionDescription
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

6.63.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.63.8. Skin Parameters Redefinition

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

Skin parametersCSS properties
tableBackgroundColorbackground-color
tableBorderColorborder-color

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

Skin parametersCSS properties
trimColorbackground-color
generalTextColorcolor
headerFamilyFontfont-family
headerSizeFontfont-size
tableBorderWidthborder-right-width
tableBorderWidthborder-bottom-width
tableBorderColorborder-right-color
tableBorderColorborder-bottom-color

Table 6.307. Skin parameters redefinition for caption element

Skin parametersCSS properties
headerFamilyFontfont-family
headerSizeFontfont-size
headerWeightFontfont-weight

Table 6.308. Skin parameters redefinition for row element

Skin parametersCSS properties
headerGradientColorbackground-color

Table 6.309. Skin parameters redefinition for selected row element

Skin parametersCSS properties
additionalBackgroundColorbackground-color

Table 6.310. Skin parameters redefinition for cell element

Skin parametersCSS properties
generalTextColorcolor
generalFamilyFontfont-family
generalSizeFontfont-size

Table 6.311. Skin parameters redefinition for selected cell element

Skin parametersCSS properties
generalTextColorcolor
generalFamilyFontfont-family
generalSizeFontfont-size

Table 6.312. Skin parameters redefinition for active cell element

Skin parametersCSS properties
generalFamilyFontfont-family
generalSizeFontfont-size

Table 6.313. Skin parameters redefinition for a button

Skin parametersCSS properties
trimColorbackground-color
generalTextColorcolor
headerFamilyFontfont-family
headerSizeFontfont-size

Table 6.314. Skin parameters redefinition for a disabled button

Skin parametersCSS properties
trimColorbackground-color
tabDisabledTextColorcolor
headerFamilyFontfont-family
headerSizeFontfont-size

Table 6.315. Skin parameters redefinition for a button highlight

Skin parametersCSS properties
trimColorbackground-color
selectControlColorborder-color
tableBorderWidthborder-width
headerFamilyFontfont-family
headerSizeFontfont-size
generalTextColorcolor

Table 6.316. Skin parameters redefinition for a pressed button

Skin parametersCSS properties
additionalBackgroundColorbackground-color
tableBorderColorborder-color
tableBorderWidthborder-width
headerFamilyFontfont-family
headerSizeFontfont-size
generalTextColorcolor

Table 6.317. Skin parameters redefinition for a button content

Skin parametersCSS properties
headerFamilyFontfont-family
headerSizeFontfont-size

Table 6.318. Skin parameters redefinition for a button selection

Skin parametersCSS properties
generalTextColorcolor

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

Skin parametersCSS properties
panelBorderColorborder-color

6.63.9. Definition of Custom Style Classes

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

Classes names

Figure 6.159. Classes names


Table 6.320. Classes names that define a list representation

Class nameDescription
rich-ordering-list-bodyDefines styles for a wrapper table element of an orderingList
rich-ordering-list-outputDefines styles for a wrapper <div> element of a list
rich-ordering-list-itemsDefines styles for a wrapper table element of items in the list
rich-ordering-list-contentDefines styles for a list content
rich-ordering-list-headerDefines styles for a wrapper <div> element for a list header
rich-ordering-list-table-headerDefines styles for a wrapper <tr> element for a list header
rich-ordering-list-table-header-cellDefines styles for a header cell

Table 6.321. Classes names that define a caption representation

Class nameDescription
rich-ordering-list-captionDefines styles for a caption
rich-ordering-list-caption-disabledDefines styles for a caption in disabled state
rich-ordering-list-caption-activeDefines styles for a caption in active state

Table 6.322. Classes names that define rows representation

Class nameDescription
rich-ordering-list-rowDefines styles for a row
rich-ordering-list-row-selectedDefines styles for a selected row
rich-ordering-list-row-activeDefines styles for an active row
rich-ordering-list-row-disabledDefines styles for a disabled row

Table 6.323. Classes names that define cells representation

Class nameDescription
rich-ordering-list-cellDefines styles for a cell
rich-ordering-list-cell-selectedDefines styles for a selected cell
rich-ordering-list-cell-activeDefines styles for an active cell
rich-ordering-list-cell-disabledDefines styles for a disabled cell

Table 6.324. Classes names that define a button representation

Class nameDescription
rich-ordering-list-buttonDefines styles for a button
rich-ordering-list-button-disabledDefines styles for a disabled button
rich-ordering-list-button-lightDefines styles for a button highlight
rich-ordering-list-button-pressDefines styles for a pressed button
rich-ordering-list-button-contentDefines styles for a button content
rich-ordering-list-button-selectionDefines styles for a button selection
rich-ordering-list-button-valignDefines styles for a wrapper <td> element for buttons vertical align
rich-ordering-list-button-layoutDefines styles for a wrapper <div> element of buttons layout

Table 6.325. Classes names that define controls representation

Class nameDescription
rich-ordering-controlsDefines styles for a controls group
rich-ordering-control-topDefines styles for a "top" control
rich-ordering-control-bottomDefines styles for a "bottom" control
rich-ordering-control-upDefines styles for a "up" control
rich-ordering-control-downDefines styles for a "down" control
rich-ordering-control-disabledDefines 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

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

Figure 6.161. 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.63.10. Relevant Resources Links

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