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.
Highly customizable look and feel
Reordering possibility for list items
Multiple selection of list items
Keyboard support
Table 6.300. 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(Default)- controls should be rendered to the right side of a list. |
controlsType | Defines type of a control: button or none. |
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. |
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 |
listWidth | Defines width of a list |
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. |
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 |
rowKey | RowKey is a representation of an identifier for a specific data 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.301. 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 |
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>
...
Example:
import org.richfaces.component.html.HtmlOrderingList;
...
HtmlOrderingList myOrderingList = new HtmlOrderingList();
...
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 "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+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.303. 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 |
Table 6.304. 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 |
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
Table 6.305. Skin parameters redefinition for a wrapper <div> element of a list
Skin parameters | CSS properties |
---|---|
tableBackgroundColor | background-color |
tableBorderColor | border-color |
Table 6.306. 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.307. Skin parameters redefinition for caption element
Skin parameters | CSS properties |
---|---|
headerFamilyFont | font-family |
headerSizeFont | font-size |
headerWeightFont | font-weight |
Table 6.308. Skin parameters redefinition for row element
Skin parameters | CSS properties |
---|---|
headerGradientColor | background-color |
Table 6.309. Skin parameters redefinition for selected row element
Skin parameters | CSS properties |
---|---|
additionalBackgroundColor | background-color |
Table 6.310. Skin parameters redefinition for cell element
Skin parameters | CSS properties |
---|---|
generalTextColor | color |
generalFamilyFont | font-family |
generalSizeFont | font-size |
Table 6.311. Skin parameters redefinition for selected cell element
Skin parameters | CSS properties |
---|---|
generalTextColor | color |
generalFamilyFont | font-family |
generalSizeFont | font-size |
Table 6.312. Skin parameters redefinition for active cell element
Skin parameters | CSS properties |
---|---|
generalFamilyFont | font-family |
generalSizeFont | font-size |
Table 6.313. Skin parameters redefinition for a button
Skin parameters | CSS properties |
---|---|
trimColor | background-color |
generalTextColor | color |
headerFamilyFont | font-family |
headerSizeFont | font-size |
Table 6.314. Skin parameters redefinition for a disabled button
Skin parameters | CSS properties |
---|---|
trimColor | background-color |
tabDisabledTextColor | color |
headerFamilyFont | font-family |
headerSizeFont | font-size |
Table 6.315. 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.316. 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.317. Skin parameters redefinition for a button content
Skin parameters | CSS properties |
---|---|
headerFamilyFont | font-family |
headerSizeFont | font-size |
Table 6.318. Skin parameters redefinition for a button selection
Skin parameters | CSS properties |
---|---|
generalTextColor | color |
Table 6.319. Skin parameters redefinition for top, bottom, up, down controls and for controls in disabled state
Skin parameters | CSS properties |
---|---|
panelBorderColor | border-color |
On the screenshot there are classes names that define styles for component elements.
Table 6.320. 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.321. 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.322. 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.323. 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.324. 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.325. 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:
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:
As it could be seen on the picture above, the font style for rows was changed.
Here you can see an example of <rich:orderingList> usage and sources for the given example.