The pickList
dual list is an input component that is used to transfer data between two different collections with drag-and-drop-based reordering, transition effects, POJO support, client-server callbacks, and more.
The pickList
component uses a custom data model, which is an instance of org.primefaces.model
DualListModel
that contains two lists—one for the source and one for the target. For a pickList
implementation that would be used to select countries, the data model could be as follows:
private List<String> countriesSource = new ArrayList<String>(); private List<String> countriesTarget = new ArrayList<String>(); countriesSource.add("England"); countriesSource.add("Germany"); countriesSource.add("Switzerland"); countriesSource.add("Turkey"); private DualListModel<String> countries = new DualListModel<String>(countriesSource, countriesTarget);
The definition of the component could be as follows:
<p:pickList id="simple" value="#{pickListBean.countries}" var="country" itemLabel="#{country}" itemValue="#{country}" />
The visual output (of the previous two code snippets) of the component will be two containers—one for the source list and one for the target list—and will be as follows:
The itemDisabled
attribute specifies whether an item can be picked or not. When it is set to true
, the source and target list will be rendered as disabled so as to prevent the selection.
It's possible to add captions at the top of the source list and the target list. The captions should be defined with the sourceCaption
and targetCaption
facets, as shown here:
<p:pickList id="withCaption" value="#{pickListBean.countries}" var="country" itemLabel="#{country}" itemValue="#{country}"> <f:facet name="sourceCaption">Available</f:facet> <f:facet name="targetCaption">Selected</f:facet> </p:pickList>
The showSourceControls
and showTargetControls
attributes specify the visibility of the reorder buttons of the source list and the target list.
The labels for the control buttons can also be customized with the addLabel
, addAllLabel
, removeLabel
, removeAllLabel
, moveUpLabel
, moveTopLabel
, moveDownLabel
, and moveBottomLabel
attributes.
The pickList
component supports dealing with complex POJOs as well. The data model should be based on org.primefaces.model.DualListModel
as it's defined with the example of strings. A converter for the Car
class should also be implemented and used as defined next. The following is a definition of a data model that contains a source list and target list for the Car
class:
DualListModel<Car> cars = new DualListModel<Car>(carsSource, carsTarget);
The <p:column>
element could be used while visualizing the instances of Car
within pickList
to clearly identify the attributes of the Car
class:
<p:pickList id="pojoSupport" value="#{pickListBean.cars}" var="car" itemLabel="#{car.name}" itemValue="#{car}"> <f:converter converterId="org.primefaces.cookbook.converter.CarConverter" /> <p:column> <p:graphicImage value="/resources/images/autocomplete/#{car.name}.png" width="100" height="70" /> </p:column> <p:column> #{car.name} </p:column> </p:pickList>
Effects can be applied with the effect
attribute for content transition when a selection is moved from the source list to the target list or vice versa. The default value of the effect
attribute is fade
. The other possible values for the attribute are given here:
blind
bounce
clip
drop
explode
fold
highlight
puff
pulsate
scale
shake
size
slide
To customize the animation speed, effectSpeed
can be used. Its default value is fast
; the other possible values are slow
and normal
.
The pickList
component supports the execution of a client-side callback when an item is transferred from one list to another. This could be achieved by providing a JavaScript method definition for the onTransfer
attribute, as shown here:
<p:pickList id="withCustomJS" onTransfer="handleTransfer(e)"
value="#{pickListBean.countries}" var="country"
itemLabel="#{country}" itemValue="#{country}" />
The definition of the script method to list the values of the item that is transferred, the definition of from- and to-lists, and so on, is given here:
<script type="text/javascript"> function handleTransfer(e) { alert(e.item); alert(e.from); alert(e.to); alert(e.type); } </script>
The variable e
provides access to the item transferred, the source and target unordered lists (named from
and to
, as an instance of HTMLUListElement
), and the type of action taken, such as command
, dblclick
, or dragdrop
.
The pickList
component provides the transfer
AJAX behavior event that will be fired when an item is moved from the source list to the target list or vice versa:
<p:pickList id="withAJAX" value="#{pickListBean.countries}" var="country" itemLabel="#{country}" itemValue="#{country}"> <p:ajax event="transfer" update="growl" listener="#{pickListBean.handleTransfer}" /> </p:pickList>
The handleTransfer
method will be invoked with org.primefaces.event.TransferEvent
. The items selected and the action taken can be identified through the instance of this event. A sample definition for the handleTransfer
method is given here:
public void handleTransfer(TransferEvent event) { MessageUtil.addInfoMessage("items.transferred", event.getItems()); MessageUtil.addInfoMessage("is.added", event.isAdd()); MessageUtil.addInfoMessage("is.removed", event.isRemove()); }
Be aware that if large datasets (approximately 1,000 items) are added to the source list of pickList
on IE or Chrome browsers, performance drawbacks might arise and affect the user experience of your application.
As it's not a UIData
component, pickList
doesn't do server-side processing for action and input handling. So, for example, using checkboxes inside pickList
will not work.
This recipe is available in the demo web application on GitHub (https://github.com/ova2/primefaces-cookbook/tree/second-edition). Clone the project if you have not done it yet, explore the project structure, and build and deploy the WAR file on application servers compatible with Servlet 3.x, such as JBoss WildFly and Apache TomEE.
The showcase for the recipe is available at http://localhost:8080/pf-cookbook/views/chapter5/pickList.jsf
.
For details about the MessageUtil
class, see the Internationalization (i18n) and Localization (L10n) recipe in Chapter 1, Getting Started with PrimeFaces.