⁠12.11. Table sorting

Tables entries can be sorted by defining external sorting algorithms. Refer to Section 12.3, “<rich:column>” for details on using the <rich:column> component in tables.

Note

To sort a table whose contents are not in English, add the org.richfaces.datatableUsesViewLocale context parameter to the project's web.xml settings file. Set the value of the context parameter to true.

⁠12.11.1. Comparator Definition

Use the comparator attribute of the <rich:column> to specify the comparator to use when sorting. If no comparator is specified, the sorting algorithm will invoke the entries compareTo method of the sortBy values if they implement the java.lang.Comparable interface. As a final fall back, the algorithm implements a null sort, sorting elements based on whether or not they are null.

⁠12.11.2. Built-in sort controls

The built-in sorting controls of the <rich:column> component allow a user to click the sort icons of a column to sort it in ascending or descending order.
Set the sortBy attribute to indicate which value to use when sorting the column. Expressions in the sortBy attribute must refer to the variable declared in the table's var attribute, which is used to fill the contents of the table.
⁠

Example 12.18. Basic sorting

​<rich:dataTable value="#{capitalsBean.capitals}" var="cap" width="300px">
​   <rich:column sortBy="#{cap.state}">
​      <f:facet name="header">
​         <h:outputText value="State Name"/>
​      </f:facet>
​      <h:outputText value="#{cap.state}"/>
​   </rich:column> 
​   <rich:column sortBy="#{cap.name}">
​      <f:facet name="header">
​         <h:outputText value="State Capital"/>
​      </f:facet>
​      <h:outputText value="#{cap.name}"/> 
​   </rich:column>
​</rich:dataTable>
The example uses the basic sorting method on both columns in the table.
Use the sortOrder attribute to set how the table's contents are sorted when it is first loaded. By default, the value of the sortOrder attribute is unsorted, so that table entries appear in the order the are contained in the data model. Use sortOrder="ascending" to sort the entries in ascending alphabetical or numerical order. Use sortOrder="descending" to sort the entries in descending alphabetical or numerical order. The sortOrder attribute can also be used to externally set the sort order of a table when using the external sorting method; refer to Section 12.11.3, “External sort controls” for details.

⁠12.11.3. External sort controls

Set the sortBy attribute to indicate which iteration object property to use when sorting the column. If using custom-defined rules for sorting, use the comparator attribute instead. Set the comparator attribute to point to your comparator method, which will be used when sorting the data model.

Note

The built-in sort controls can be disabled on a column-by-column basis by setting the column attribute sortType="custom". Alternatively one can disable sort controls for the whole application via the following context-param in the web.xml: 
​<context-param>
​    <param-name>org.richfaces.builtin.sort.enabled</param-name>
​    <param-value>false</param-value>
​</context-param>
Bind the sortOrder attribute to bean properties to manage the sorting order. The bean must handle all the sorting algorithms. Example 12.19, “Sorting” demonstrates table sorting using an external control.
⁠

Example 12.19. Sorting

​<rich:dataTable value="#{capitalsBean.capitals}" var="cap" id="table">
​    <rich:column>
​        <f:facet name="header">
​            State Flag
​        </f:facet>
​        <h:graphicImage value="#{cap.stateFlag}" alt="flag" />
​    </rich:column>
​    <rich:column sortBy="#{cap.name}" id="name" sortOrder="#{capitalsSortingBean.capitalsOrder}">
​        <f:facet name="header">
​            <a4j:commandLink value="Sort by Capital Name" render="table" action="#{capitalsSortingBean.sortByCapitals}" />
​        </f:facet>
​        <h:outputText value="#{cap.name}" />
​    </rich:column>
​    <rich:column sortBy="#{cap.state}" id="state" sortOrder="#{capitalsSortingBean.statesOrder}">
​        <f:facet name="header">
​            <a4j:commandLink value="Sort by State Name" render="table" action="#{capitalsSortingBean.sortByStates}" />
​        </f:facet>
​        <h:outputText value="#{cap.state}" />
​    </rich:column>
​    <rich:column sortBy="#{cap.timeZone}" id="timeZone" comparator="#{capitalsSortingBean.timeZoneComparator}"
​        sortOrder="#{capitalsSortingBean.timeZonesOrder}">
​        <f:facet name="header">
​            <a4j:commandLink value="Sort by Time Zone" render="table" action="#{capitalsSortingBean.sortByTimeZones}" />
​        </f:facet>
​        <h:outputText value="#{cap.timeZone}" />
​    </rich:column>
​</rich:dataTable>
The example uses an external control to manage the table's sorting.
When multiple columns are capable of being sorted at the same time, set the priority by which the columns are sorted with the sortPriorities attribute. The attribute must contain a list of column identifiers in the order of the sorting sequence.