JBoss.orgCommunity Documentation
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.379. 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 |
bottomTitle | HTML: alt for last button |
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"- controls should be rendered to the right side of a list. Default value is "right". |
controlsType | Defines type of a control: button or none. Default value is "button". |
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" - controls should be rendered centered relatively to a list. Default value is "middle" |
converter | Id of Converter to be used or reference to a Converter |
converterMessage | A ValueExpression enabled attribute that, if present, will be used as the text of the converter message, replacing any message that comes from the converter |
downControlLabel | Defines a label for a 'Down' control |
downTitle | HTML: alt for bottom button |
fastOrderControlsVisible | If "false", 'Top' and 'Bottom' controls aren't displayed. Default value is "true". |
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 |
label | A localized user presentable name for this component. |
listHeight | Defines height of a list. Default value is "140". |
listWidth | Defines width of a list. Default value is "140". |
onbottomclick | HTML: script expression; 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 | HTML: script expression; a button "Down" is clicked |
onheaderclick | HTML: script expression; 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 |
onorderchange | HTML: script expression; before a order list is changed |
onorderchanged | HTML: script expression; a order list is changed |
ontopclick | HTML: script expression; 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. Default value is "true". |
rendered | If "false", this component is not rendered |
required | If "true", this component is checked for non-empty input |
requiredMessage | A ValueExpression enabled attribute that, if present, will be used as the text of the validation message for the "required" facility, if the "required" facility is used |
rowClasses | CSS class for a 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. Default value is "true" |
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 |
topTitle | HTML: alt for first button |
upControlLabel | Defines a label for a 'Up' control |
upTitle | HTML: alt for top button |
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 |
validatorMessage | A ValueExpression enabled attribute that, if present, will be used as the text of the validator message, replacing any message that comes from the validator |
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.380. 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 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.
Table 6.381. 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.382. 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 |
Table 6.383. 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 |
Table 6.384. 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 |
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.385. Skin parameters redefinition for a wrapper <div> element of a list
Skin parameters | CSS properties |
---|---|
tableBackgroundColor | background-color |
tableBorderColor | border-color |
Table 6.386. 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.387. Skin parameters redefinition for caption element
Skin parameters | CSS properties |
---|---|
headerFamilyFont | font-family |
headerSizeFont | font-size |
headerWeightFont | font-weight |
Table 6.388. Skin parameters redefinition for row element
Skin parameters | CSS properties |
---|---|
headerGradientColor | background-color |
Table 6.389. Skin parameters redefinition for selected row element
Skin parameters | CSS properties |
---|---|
additionalBackgroundColor | background-color |
Table 6.390. Skin parameters redefinition for cell element
Skin parameters | CSS properties |
---|---|
generalTextColor | color |
generalFamilyFont | font-family |
generalSizeFont | font-size |
Table 6.391. Skin parameters redefinition for selected cell element
Skin parameters | CSS properties |
---|---|
generalTextColor | color |
generalFamilyFont | font-family |
generalSizeFont | font-size |
Table 6.392. Skin parameters redefinition for active cell element
Skin parameters | CSS properties |
---|---|
generalFamilyFont | font-family |
generalSizeFont | font-size |
Table 6.393. Skin parameters redefinition for a button
Skin parameters | CSS properties |
---|---|
trimColor | background-color |
generalTextColor | color |
headerFamilyFont | font-family |
headerSizeFont | font-size |
Table 6.394. Skin parameters redefinition for a disabled button
Skin parameters | CSS properties |
---|---|
trimColor | background-color |
tabDisabledTextColor | color |
headerFamilyFont | font-family |
headerSizeFont | font-size |
Table 6.395. 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.396. 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.397. Skin parameters redefinition for a button content
Skin parameters | CSS properties |
---|---|
headerFamilyFont | font-family |
headerSizeFont | font-size |
Table 6.398. Skin parameters redefinition for a button selection
Skin parameters | CSS properties |
---|---|
generalTextColor | color |
Table 6.399. 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.400. 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.401. 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.402. 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.403. 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.404. 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.405. 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.
On RichFaces LiveDemo page you can see an example of <rich:orderingList> usage and sources for the given example.