A multiselect input component, SelectCheckboxMenu is based on checkboxes in an overlay menu. Although it is an input component, it is presented to users as a menu so that it makes sense to handle selectCheckboxMenu in this chapter.
In this recipe, we will implement a selectCheckboxMenu component in both simple and advanced forms. In the advanced case, we will learn about the built-in filtering feature. After submitting the selected items, they will be shown in a dialog.
The usage of p:selectCheckboxMenu is the same as the usage of p:selectManyCheckbox. Checkbox items can be attached via several f:selectItem tags or one f:selectItems tag. In the following simple example, we will use f:selectItems to display colors:
<p:selectCheckboxMenu label="Colors"
value="#{checkboxMenuBean.selectedColors}">
<f:selectItems value="#{checkboxMenuBean.colors}"/>
</p:selectCheckboxMenu>The label attribute defines text shown to the user. The advanced p:selectCheckboxMenu component comes with a filtering feature. The feature is activated by setting filter to true. The following code shows this:
<p:selectCheckboxMenu label="Languages" filter="true"
value="#{checkboxMenuBean.selectedLanguages}">
<f:selectItems value="#{checkboxMenuBean.languages}"/>
<f:converter
converterId="org.primefaces.cookbook.converter.LocaleConverter"/>
</p:selectCheckboxMenu>
<p:commandButton value="Submit" update="display"
oncomplete="PF('dlg').show()"
style="margin-top:20px; display:block;"/>
<p:dialog header="Selected colors and languages" widgetVar="dlg">
<h:panelGroup id="display">
<p:dataList value="#{checkboxMenuBean.selectedColors}"
var="color">
#{color}
</p:dataList>
<p:dataList value="#{checkboxMenuBean.selectedLanguages}"
var="lang">
#{lang}
</p:dataList>
</h:panelGroup>
</p:dialog>The following screenshot shows the simple and advanced cases as well as a dialog with the selected values:
The available checkbox items are created in the CheckboxMenuBean CDI bean. Items for colors are stored in a HashMap class, and items for languages are stored in a list of SelectItem objects. The following code shows this:
@Named
@ViewScoped
public class CheckboxMenu implements Serializable {
private List<SelectItem> languages;
private Map<String, String> color;
private List<Locale> selectedLanguages;
private List<String> selectedColors;
public List<SelectItem> getLanguages() {
if (languages == null) {
languages = new ArrayList<SelectItem>();
languages.add(
new SelectItem(new Locale("de"), "German"));
...
}
return languages;
}
public Map<String, String> getColors() {
if (color == null) {
color = new HashMap<String, String>();
color.put("Red", "Red");
...
}
return color;
}
// getters / setters
...
}After submitting the form, the selected items get set in the selectedColors and selectedLanguages variables, respectively. Their values are displayed as lists in the dialog.
There are various configuration settings for the filter functionality in SelectCheckboxMenu. They are tag attributes described in the following table:
|
Selector |
Applies |
|---|---|
|
|
This is the match mode for filtering. The valid values are |
|
|
This is the client-side function to use in custom filtering. |
|
|
This defines whether filtering would be case sensitive. The default value is |
An example of filterMatchMode="custom" is a custom JavaScript function that leverages fuzzy matching (http://dustindiaz.com/autocomplete-fuzzy-matching). The following code shows this:
function customFilter(itemLabel, filterValue) {
var reg = new RegExp(filterValue.split('').join('\w*'), 'i'),
if (itemLabel.match(reg)) {
// return true to accept
return true;
}
// return false to reject
return false;
}This function can be used by setting filterFunction="customFilter".
In the advanced example, we used LocaleConverter—a JSF converter—to convert java.util.Locale to String and vice versa. The LocaleConverter class can be found on GitHub (https://github.com/ova2/primefaces-cookbook/tree/second-edition) in the org.primefaces.cookbook.converter package.
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/chapter6/checkboxMenu.jsf.