⁠12.10. Table filtering

Tables entries can be filtered by the user through either the basic built-in filter inputs, or by defining external filter controls. Refer to Section 12.3, “<rich:column>” for details on using the <rich:column> component in tables.

⁠12.10.1. Filter Definition

To define a filter for a column use either the filter or filterExpression attributes, then use the filterValue attribute to point to an object which holds the current filtering value for the column. The attribute can be used to store filtering conditions in a session.
Use the filterExpression attribute to define an expression that can be evaluated as a boolean value. The expression checks if each table entry satisfies the filtering condition when the table is rendered. For example, the expression might be a JSTL (JavaServer Pages Standard Tag Library) function such as contains or equals.
Use the filter attribute to define a filter interface. The attribute must use EL (Expression Language) to point to an object which implements the org.richfaces.model.Filter<T> interface. The object must provide a single accept(T t) method. The method takes each iteration object as a parameter and returns a boolean value, which determines whether the object satisfies the filter. By defining a custom filter, you can implement complex business logic to filter a table.

⁠12.10.2. Built-in filter controls

The built-in filter controls of the <rich:column> component allow the user to enter text to use as the filtering value. The value of the built-in filter control is bound to the filterValue attribute, which can either be an initial filtering value on the page, or a value binding on the server. The filterValue is then applied to the filter defined either by the filterExpression or filter column attributes.
The filterValue is of type String. Conversion is either done implicitly via EL in the filterExpression, or explicitly within the filter function. The filter is processed and the table is rendered when the onblur event occurs for the column.
⁠

Example 12.16. Basic filtering

​<rich:extendedDataTable value="#{carsBean.allInventoryItems}" var="car" filterVar="filterValue">
​    <f:facet name="header">
​        <h:outputText value="Cars marketplace"/>
​    </f:facet>
​    <rich:column filterExpression="#{empty filterValue or fn:startsWith(car.model, filterValue)}"
​                 filterValue="#{carsFilteringBean.modelFilter}">
​        <f:facet name="header">Model</f:facet>
​        <h:outputText value="#{car.model}"/>
​    </rich:column>
​    <rich:column filterExpression="#{empty filterValue or car.price ge filterValue}"
​                 filterValue="#{carsFilteringBean.priceFilter}"
​                 filterConverterMessage="Error converting the 'Price' filter value">
​        <f:facet name="header">Price</f:facet>
​        <h:outputText value="#{car.price}"/>
​    </rich:column>
​</rich:extendedDataTable>
The example uses the basic filtering method on both columns in the table.

⁠12.10.3. External filter controls

If you require more advanced filter controls use the external filtering properties of the <rich:column> component. With custom filter controls you can tailor the filter control, allowing for advanced use cases like select menus, checkboxes, etc. To use a custom filter control with the extendedDataTable component, one must first disable the built-in filter control.

Note

The built-in filter controls can be disabled on a column-by-column basis by setting the column attribute filterType="custom". Alternatively one can disable filter controls for the whole application via the following context-param in the web.xml: 
​<context-param>
​    <param-name>org.richfaces.builtin.filter.enabled</param-name>
​    <param-value>false</param-value>
​</context-param>
⁠

Example 12.17. Filtering example

​<rich:dataTable value="#{capitalsBean.capitals}" var="cap" id="table">
​
​    <f:facet name="header">
​        <rich:columnGroup>
​            <rich:column>
​                <h:outputText value="State Name" />
​            </rich:column>
​            <rich:column>
​                <h:outputText value="State Time Zone" />
​            </rich:column>
​        </rich:columnGroup>
​    </f:facet>
​    <rich:column filter="#{filteringBean.stateFilter}">
​        <f:facet name="header">
​            <h:inputText value="#{filteringBean.stateFilterValue}" id="input">
​                <a4j:ajax event="keyup" render="table@body">
​                    <a4j:attachQueue  requestDelay="700"
​                        ignoreDupResponses="true" />
​                </a4j:ajax>
​            </h:inputText>
​        </f:facet>
​        <h:outputText value="#{cap.state}" />
​    </rich:column>
​    <rich:column filterExpression="#{fn:containsIgnoreCase(cap.timeZone, filteringBean.zoneFilterValue)}">
​        <f:facet name="header">
​            <h:selectOneMenu value="#{filteringBean.zoneFilterValue}">
​                <f:selectItems value="#{filteringBean.zoneList}" />
​                <a4j:ajax event="change" render="table@body" />
​            </h:selectOneMenu>
​        </f:facet>
​        <h:outputText value="#{cap.timeZone}" />
​    </rich:column>
​</rich:dataTable>
The example uses a filter expression on the first column and a filter method on the second column.