JBoss.orgCommunity Documentation
The <rich:pickList> component is used for moving selected item(s) from one list into another.
Multiple selection of list items
Keyboard support
Supports standard JSF internationalization
Highly customizable look and feel
The <rich:pickList> component consists of
2 item lists. Every item has three different representations: common, selected, active. Combination of these states is possible.
Move controls set is a set of controls, which performs moving items between lists.
The "value" attribute is the initial value of this component.
The <f:selectItem /> or <f:selectItems /> facets are used to define the values of a source list.
Example:
...
<rich:pickList value="#{pickBean.listValues}">
<f:selectItem itemValue="Bentley" itemLabel="Bentley"/>
<f:selectItem itemValue="Audi" itemLabel="Audi"/>
<f:selectItems value="#{pickBean.sourceList}"/>
</rich:pickList>
...
The "switchByClick" attribute provides an option to copy and remove items between lists by one click. Default value of this attribute is "false", so you need a double click to copy, remove items from one list to another.
Lables of the move controls can be defined with "copyAllControlLabel" , "copyControlLabel" , "removeControlLabel" , "removeAllControlLabel" attributes.
Example:
...
<rich:pickList copyAllControlLabel = "#{pickBean.copyAllLabel}" copyControlLabel = "#{pickBean.copyLabel}"
removeControlLabel = "#{pickBean.removeLabel}" removeAllControlLabel ="#{pickBean.removeAllLabel}" value="#{pickBean.listValues}">
<f:selectItem itemValue="Bentley" itemLabel="Bentley"/>
<f:selectItem itemValue="Audi" itemLabel="Audi"/>
<f:selectItems value="#{pickBean.sourceList}"/>
</rich:pickList>
...
If you don't want to display labels on the buttons you need to set "showButtonsLabel" to "false".
Alternative to the given attributes are the following facets: "copyAllControl" , "removeAllControl" , "copyControl" , "removeControl" , "copyAllControlDisabled" , "removeAllControlDisabled" , "copyControlDisabled" , "removeControlDisabled" , "caption" .
It is an example of usage of the facets and it is identical to the previous example.
...
<rich:pickList value="#{pickBean.listValues}">
<f:facet name="copyAllControl">
<h:commandButton value="#{pickBean.copyAllLabel}" />
</f:facet>
<f:facet name="copyControl">
<h:commandButton value="#{pickBean.copyLabel}" />
</f:facet>
<f:facet name="removeControl">
<h:commandButton value="#{pickBean.removeLabel}" />
</f:facet>
<f:facet name="removeAllControl">
<h:commandButton value="#{pickBean.removeAllLabel}" />
</f:facet>
<f:selectItem itemValue="Bentley" itemLabel="Bentley"/>
<f:selectItem itemValue="Audi" itemLabel="Audi"/>
<f:selectItems value="#{pickBean.sourceList}"/>
</rich:pickList>
...
With the help of "moveControlsVerticalAlign" attribute you can align move controls vertically.
The possible value for "moveControlsVerticalAlign" are "top", "bottom" and "center" (default value).
The <rich:pickList> component provides resizing of lists by using such attributes as:
"listsHeight" defines height of the lists.
"sourceListWidth" defines width of a source list.
"targetListWidth" defines width of a target list.
Example:
...
<rich:pickList listsHeight="#{pickBean.listsHeight}" sourceListWidth="#{pickBean.sourceListWidth}" targetListWidth="#{pickBean.targetListWidth}" value="#{pickBean.listValues}">
<f:selectItem itemValue="Bentley" itemLabel="Bentley"/>
<f:selectItem itemValue="Audi" itemLabel="Audi"/>
<f:selectItems value="#{pickBean.sourceList}"/>
</rich:pickList>
...
The
<rich:pickList>
component allows to use internationalization method
to redefine and localize the labels. You could use application resource bundle and define
RICH_PICK_LIST_COPY_ALL_LABEL
,
RICH_PICK_LIST_COPY_LABEL
,
RICH_PICK_LIST_REMOVE_ALL_LABEL
,
RICH_PICK_LIST_REMOVE_LABEL
there.
Table 6.230. 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 of <rich:pickList> attributes.
Table 6.231. Component Identification Parameters
Name | Value |
---|---|
component-type | org.richfaces.PickList |
component-class | org.richfaces.component.html.HtmlPickList |
component-family | org.richfaces.PickList |
renderer-type | org.richfaces.PickListRenderer |
tag-class | org.richfaces.taglib.PickListTag |
Table 6.232. Facets
Facet | Description |
---|---|
copyAllControl | Redefines the "copyAll" label with the control set. Related attribute is "copyAllControlLabel" |
removeAllControl | Redefines the "removeAll" label with the control set. Related attribute is "removeAllControlLabel" |
copyControl | Redefines the "copy" label with the control set. Related attribute is "copyControlLabel" |
removeControl | Redefines the "remove" label with the control set. Related attribute is "removeControlLabel" |
copyAllControlDisabled | Redefines the disabled "copyAll" label with the control set. |
removeAllControlDisabled | Redefines the disabled "removeAll" label with the control set. |
copyControlDisabled | Redefines the disabled "copy" label with the control set. |
removeControlDisabled | Redefines the disabled "remove" label with the control set. |
caption | Defines the "caption" label with the control set. |
Table 6.233. Classes names that define a list representation
Class name | Description |
---|---|
rich-list-picklist | Defines styles for a wrapper <table> element of a pickList |
Table 6.234. Classes names that define a source and target items representation
Class name | Description |
---|---|
rich-picklist-source-items | Defines styles for a wrapper <div> element of a source list |
rich-picklist-target-items | Defines styles for a wrapper <div> element of a target list |
rich-picklist-body | Defines styles for a wrapper <table> element of a list body (source and target) |
rich-picklist-list | Defines styles for a (source and target) list |
rich-picklist-list-content | Defines styles for a (source and target) list content |
rich-picklist-internal-tab | Defines styles for a wrapper <table> element of list items (source and target) |
Table 6.235. Classes names that define rows representation
Class name | Description |
---|---|
rich-picklist-source-row | Defines styles for a source list row |
rich-picklist-source-row-selected | Defines styles for a selected row in a source list |
rich-picklist-target-row-selected | Defines styles for a selected row in a target list |
Table 6.236. Classes names that define a source cell representation
Class name | Description |
---|---|
rich-picklist-source-cell | Defines styles for a cell in a source list |
rich-picklist-source-cell-selected | Defines styles for a selected cell in a source list |
rich-picklist-source-cell-active | Defines styles for an active cell in a source list |
Table 6.237. Classes names that define a target cell representation
Class name | Description |
---|---|
rich-picklist-target-cell | Defines styles for a target list cell |
rich-picklist-target-cell-selected | Defines styles for a selected cell in a target list |
rich-picklist-target-cell-active | Defines styles for an active cell in a target list |
Table 6.238. Classes names that define a control representation
Class name | Description |
---|---|
rich-picklist-controls | Defines styles for wrapper <div> element of a pickList controls |
rich-picklist-control-disabled | Defines styles for a control in a disabled state |
rich-picklist-control-copyall | Defines styles for a "copyAll" control |
rich-picklist-control-copy | Defines styles for a "Copy" control |
rich-picklist-control-remove | Defines styles for a "Remove" control |
rich-picklist-control-removeall | Defines styles for a "removeAll" control |
rich-picklist-control-img | Defines styles for a control image |
Table 6.239. Classes names that define a button representation
Class name | Description |
---|---|
rich-list-picklist-button | Defines styles for a button |
rich-list-picklist-button-disabled | Defines styles for a disabled button |
rich-list-picklist-button-press | Defines styles for a pressed button |
rich-list-picklist-button-light | Defines styles for a button highlight |
rich-list-picklist-button-selection | Defines styles for a button selection |
rich-list-picklist-button-content | Defines styles for a button content |
On RichFaces LiveDemo page you can see an example of <rich:pickList> usage and sources for the given example.