10.10. <rich:orderingList>

⁠10.10.1. Basic usage

To use the <rich:orderingList> bind the value attribute to the list to be ordered. The var attribute specifies a variable to use when iterating through the list values. The var attribute is used within the itemLabel to assign the object value to be displayed. Similarly, the var attribute is used within the itemValue attribute to specify the object value mapped by the display value. If the itemValue is not of type String, a converter must be specified for this itemValue using either the converter attribute, or a nested <f:converter> tag.

⁠

Example 10.10. ItemLabel/ItemValue use

Using the itemLabel and itemValue attributes

<rich:orderingList value="#{listSelectBean.capitals}" var="capital" itemValue="#{capital}" itemLabel="#{capital.name}">
    <f:converter converterId="CapitalsConverter" />
</rich:orderingList>

The arrow keys on a keyboard can be used to highlight different items in the list. Pressing the ctrl modifier with the arrow keys will move the selected item up or down within the list.

⁠10.10.2. Column Layout

In addition to the above simple itemLabel display, the <rich:orderingList> supports a columnar layout of the itemValues to be sorted. This is achieved by nesting <rich:column> tags within the orderingList, and referencing the var attribute from within the <rich:column> EL.

⁠

Example 10.11. Nested <rich:column> tags

Using <rich:column> tags nested within the <rich:orderingList>

<rich:orderingList value="#{listSelectBean.capitals}" var="capital"  listWidth="300px">
    <f:converter converterId="CapitalsConverter" />
    <rich:column>
        <f:facet name="header">Flag</f:facet>
        <h:graphicImage value="#{capital.stateFlag}" alt="flag"  width="33"/>
    </rich:column>
    <rich:column>
        <f:facet name="header">Name</f:facet>
        #{capital.name}
    </rich:column>
    <rich:column>
        <f:facet name="header">State</f:facet>
        #{capital.state}
    </rich:column>
</rich:orderingList>

When using <rich:column> tags to layout the <rich:orderingList> items, the itemLabel attribute is irrelevant, and may be left out.

⁠10.10.3. JavaScript API

The <rich:orderingList> component can be controlled through the JavaScript API. The JavaScript API provides the following functions:

getList(): Returns the javascript list object backing the <rich:orderingList>. This list can be used to select/unselect item(s).
up(): Move the currently selected item(s) up one step.
down(): Move the currently selected item(s) down one step.
upTop(): Move the currently selected item(s) to the top of the list.
downBottom(): Move the currently selected item(s) to the bottom of the list.
toggleButtons(): Activate/de-activate the orderingList buttons based on the current component item state.

⁠10.10.4. Reference data

component-type: org.richfaces.OrderingList
component-class: org.richfaces.component.UIOrderingList
component-family: org.richfaces.SelectMany
renderer-type: org.richfaces.OrderingListRenderer

⁠10.10.5. Style classes and skin parameters

⁠

Table 10.10. Style classes (selectors) and corresponding skin parameters

Class (selector)	Skin Parameters	Mapped CSS properties
`.rf-ord` This class defines styles for the orderingList control itself.	No skin parameters.
`.rf-ord-cntr` This class defines styles for the container of the orderingList control.	No skin parameters.
`.rf-ord-cptn` This class defines styles for the caption of the orderingList control.	`headerTextColor`	color
	`headerSizeFont`	font-size
	`headerFamilyFont`	font-family
	`headerWeightFont`	font-weight
`.rf-ord-lst` This class defines styles for the items list of the orderingList control.	No skin parameters.
`.rf-ord-hdr` This class defines styles for the header of the items list.	`headerBackgroundColor`	background-color
	`headerTextColor`	color
	`headerSizeFont`	font-size
	`headerFamilyFont`	font-family
	`headerWeightFont`	font-weight
`.rf-ord-opt` This class defines styles for an option in the orderingList control.	`generalTextColor`	color
	`generalSizeFont`	font-size
	`generalFamilyFont`	font-family
`.rf-ord-sel` This class defines styles for the selected option of the orderingList control.	`generalTextColor`	border-color
`.rf-ord-dflt-lbl` This class defines styles for the default label of the orderingList control.	No skin parameters.
`.rf-ord-btn` This class defines styles for the button of the orderingList control.	`headerBackgroundColor`	background-color
	`panelBorderColor`	border-left-color
`.rf-ord-btn-dis` This class defines styles for the button of the orderingList control when it is disabled.	No skin parameters.
`.rf-ord-lst-scrl` This class defines styles for the list scrollbar.	No skin parameters.