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:
blindbounceclipdropexplodefoldhighlightpuffpulsatescaleshakesizeslide
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());
}Tip
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.