A table might be sorted by a single column (the primary sort column) or multiple columns. If a table is sorted by multiple columns, then the column by which the items are first sorted is the primary sort column.
You can enable users to change the primary sort column of a table by adding clickable column headings that redisplay the page, set the clicked column as the primary sort column, and set the column’s sortDirection to a direction type you specify.
When you specify a column’s sortDirection, you can specify either a literal value (ascending, descending, or none) or a semantic value, such as toggle. The following table describes the sort direction types you can use to specify a column’s sort direction.
Note: When you specify a semantic value, TableInfo examines the column’s current sort direction and computes a new literal value based on the sort direction type you specify.
sortDirection setting | Description |
|---|---|
| Sorts the column by ascending values. |
| Sorts the column by descending values. |
| The column is not sorted. |
| Toggles the column’s sort direction between ascending and descending. |
| If the column is the primary sort column for the table, toggles the column’s sort direction between ascending and descending. Otherwise, makes the column the primary sort column and sets its sort direction to ascending. |
| Cycles the column’s sort direction from none to ascending to descending and back to none again. |
| If the column is the primary sort column for the table, cycles the column’s sort direction from none to ascending to descending and back to none again. Otherwise, makes the column the primary sort column and sets its sort direction to ascending. |
| Cycles the column’s sort direction from none to descending to ascending and back to none again. |
| If the column is the primary sort column for the table, cycles the column’s sort direction from none to descending to ascending and back to none again. Otherwise, makes the column the primary sort column and sets its sort direction to descending. |
The earlier example uses TableInfo to render a simple table. You can modify this code, so users can click on any column heading and sort the table by the property associated with that column, thereby setting the primary sort column. The following sections show how to implement these changes in two steps:
Modify the outputStart oparam
Modify the outputStart oparam so each column heading links back to the current page and passes back to the page its column index as the value of a parameter named sortColumn.
<dsp:oparam name="outputStart"> <TABLE border=1 cellspacing=2 cellpadding=2> <TR> <dsp:droplet name="ForEach"> <dsp:param bean="TableInfo.tableColumns" name="array"/> <dsp:param name="sortProperties" value=""/> <dsp:oparam name="output"> <dsp:setvalue paramvalue="element.heading" param="columnHeading"/> <TD align="center"> <dsp:a href="table.jsp"> <dsp:param name="sortColumn" param="index"/> <dsp:valueof param="columnHeading"/> </dsp:a> </TD> </dsp:oparam> </dsp:droplet> </TR> </dsp:oparam>
When a user clicks on a column heading, the column’s index is passed back to the page in the sortColumn parameter. The code you add in step 2 checks for a value for this parameter.
Get the sortColumn parameter value
Add code to the beginning of the page that receives the sortColumn parameter, checks the parameter for a value, and sets the primary sort column accordingly if a value exists.
The code should set the sortDirection for the column whose index is passed in to the page, to a direction type that makes the column the primary sort column (if it is not already). Direction types that set a column as the primary sort column are toggle_if_primary, cycle_up_if_primary, and cycle_down_if_primary. If you specify a direction type other than one of these, the sort direction of the clicked column changes accordingly, but the column does not become the primary column on which table items are sorted. (Refer to the table previously provided in this section for more information on direction types.)
<dsp:droplet name="IsNull">
<dsp:param name="value" param="sortColumn"/>
<dsp:oparam name="false">
<dsp:setvalue
bean="TableInfo.tableColumns[param:sortColumn].sortDirection"
value="toggle_if_primary"/>
</dsp:oparam>
<dsp:oparam name="true">
<dsp:setvalue bean="TableInfo.reset" value="${null}">
</oparam/>
</dsp:droplet>
When the page is called, the application checks for a value for sortColumn. One of two processes occurs, depending on whether sortColumn has a value:
sortColumn has no value: The sorting instructions in TableInfo are reset. The sortDirection property for each column is set to none, and both TableInfo.sortString and TableInfo.primarySortString are cleared, which causes the table to be rendered unsorted. Consequently, the items in the table are then rendered in the order they are listed in the object that maintains them.
sortColumn has a value: The value is the index of the column by which to sort the items in the table, and the sort direction for the respective column is set to the specified direction type. In this example, the specified direction type is toggle_if_primary, which either toggles the column’s sort direction if the column is already the primary sort column, or makes the column the primary sort column (if it is not already) and sets the sort direction to the default sort direction (normally ascending) for the TableInfo component. The table is then rendered according to the current sorting instructions.
For example, a table displaying the model, price, and color of a list of automobiles in that order. The user clicks on the column heading of the first column, and the page sets the value of TableInfo.tableColumns[0].sortDirection to toggle_if_primary. The TableInfo component automatically sets both sortString and primarySortString to +model, indicating that the table should be sorted on ascending values of model.
Note: primarySortString is always equal to the first term in sortString.
Later, the user clicks on the column heading of the second column, and the page sets the value of TableInfo.tableColumns[1].sortDirection to cycle_down_if_primary. The TableInfo component automatically prepends the second column’s sort property to sortString, and sets it as the new value of primarySortString. Now, sortString isprice, +model, and primarySortString is price.
Note that if the page sets the value of TableInfo.tableColumns[1].sortDirection to descending, the sort direction of the column changes in place. That is, the column does not become the primary sort column. sortString is +model, price, and primarySortString remains +model.
By using setvalue and hidden input fields to change the sortDirection property of a column, you can manipulate both when the column is sorted against the other columns in the table and the sort direction of the column.
