[Myfaces Wiki] Update of "Working with auto sortable tables" by CatalinKormos

[Apache Wiki <wi...@apache.org>]

Dear Wiki user,

You have subscribed to a wiki page or wiki category on "Myfaces Wiki" for change notification.

The following page has been changed by CatalinKormos:
http://wiki.apache.org/myfaces/Working_with_auto_sortable_tables

------------------------------------------------------------------------------
  }
  }}}
  
+ === Enable auto sort on all columns ===
+ 
- The MyFaces extended data table provides a more painless solution for this kind of cases. You only need to specify sortable="true" on the data table, and you'll get the same effect without any other custom code. Please note the use of <t:column> component instead of <h:column> which allows to specify the default sorted column, and the sort(String column) method is not needed any more in your backing bean:
+ The MyFaces extended data table provides a more straightforward solution for this kind of cases. You only need to specify sortable="true" on the data table, and you'll get the same effect without any other custom code. Please note the use of <t:column> component instead of <h:column> which allows to specify the default sorted column, and the sort(String column) method is not needed any more in your backing bean:
  
  {{{
  <t:dataTable var="car"
@@ -83, +85 @@

  </t:dataTable>
  }}}
  
+ === Enable auto sort by columns ===
+ 
+ Automatic sorting can be enabled by each column by setting sortable="true" on each <t:column> component, like in the following example:
+ 
+ {{{
+ <t:dataTable var="car"
+              value="#{list.cars}"
+              sortColumn="#{list.sortColumn}"
+              sortAscending="#{list.ascending}"
+              preserveDataModel="true"
+              preserveSort="true">
+         <t:column defaultSorted="true" sortable="true">
+             <f:facet name="header">
+                 <h:outputText value="Type"/>                    
+             </f:facet>
+             <h:outputText value="#{car.type}" />            
+         </t:column>
+         <t:column>
+             <f:facet name="header">
+                 <h:outputText value="Color" />
+             </f:facet>
+             <h:outputText value="#{car.color}" />                    
+         </t:column>
+ </t:dataTable>
+ }}}
+ 
+ Note that in this case, the sorting is not enabled on the entire data table, only on the first column; the second column won't be sortable.
+ 
  === How does automatic sorting work ===
  
  If sortable="true" the data table will do the following:
-  1. wrapp the current model with a sortable one and make it the current model (this wrapper model is provided by MyFaces)
+  1. wrapp the current model with a sortable one and make it the current model (this wrapper model is provided by MyFaces, and the model gets wrapped only if it's not already sortable)
-  2. iterate over each column and wrapp the current content of the header facet with a command sort header component
+  2. determine which columns are sortable and wrapp the current content of the header facet with a command sort header component
-  3. while iterating over each column, get the first output component child of the column and find the property of the row object that is used to display the cell content, from its value attribute
+  3. while iterating over the sortable columns, get the first output component child of the column and find the property of the row object that is used to display the cell content, from its value attribute
   
  This would get the table into the same state as if you had specified the sort header in each column's header facet yourself. Then the sorting is handled in the sortable model. 
  
  === How are the sort properties determined ===
  
- As previously mentioned, when sortable="true" the data table will iterate over the columns and get the sort property from the value attribute of the first output component found in the column's children list. This is done by parsing the expression string of the value binding. For example, this a column:
+ When sorting is enabled on the data table, or on each column separately, the sort property will be determined from the value attribute of the first output component found in the column's children list. This is done by parsing the expression string of the value binding. For example, this a column:
  {{{
  <t:column>
     <f:facet name="header">
@@ -128, +158 @@

  #{car.price + car.taxes} => the property taken is "price" and this will be used when sorting
  }}}
  
- === Current limitations ===
- 
-  1. for sorting, only properties available on a row object can be used, and these must be comparable, i.e, implement the Comparable interface, or else they will be compared as strings
-  2. using sortable="true" makes all the columns sortable, it's not possible yet to have only some of the columns sortable.
- 
  === Customizing the sort property ===
  
- If you need to customize the sort property that is used to sort the values for a column, you can use the propertyName attribute of the command sort header component like in the following example, cause the sort headers are added only if not already present, usefull when the sorting should be performed by a different property than the displayed one:
+ If you need to customize the sort property that is used to sort the values for a column, you can use the propertyName attribute of the <t:commandSortHeader> component, or the sortPropertyName attribute of the <t:column> component, cause the sort headers are added only if not already present, usefull when the sorting should be performed by a different property than the displayed one:
  
  {{{
+ <t:column defaultSorted="true" sortable="true">
- <t:dataTable var="car"
-              value="#{list.cars}"
-              sortColumn="#{list.sortColumn}"
-              sortAscending="#{list.ascending}"
-              preserveDataModel="true"
-              preserveSort="true"
-              sortable="true">
-         <t:column defaultSorted="true">
-             <f:facet name="header">
+     <f:facet name="header">
-                 <t:commandSortHeader columnName="type" arrow="true" propertyName="id">  
+         <t:commandSortHeader columnName="type" arrow="true" propertyName="type">  
-                     <h:outputText value="Type"/>   
+             <h:outputText value="Type"/>   
-                 </t:commandSortHeader>
+         </t:commandSortHeader>
-             </f:facet>
+     </f:facet>
-             <h:outputText value="#{car.type}" />            
+     <h:outputText value="#{car.type}" />            
+ </t:column>        
-         </t:column>
-         <t:column>
-             <f:facet name="header">
-                 <h:outputText value="Color" />
-             </f:facet>
-             <h:outputText value="#{car.color}" />                    
-         </t:column>
- </t:dataTable>
  }}}
  
+ {{{
+ <t:column defaultSorted="true" sortable="true" sortPropertyName="type">
+     <f:facet name="header">
+         <h:outputText value="Type"/>   
+     </f:facet>
+     <h:outputText value="#{car.type}" />            
+ </t:column>        
+ }}}
+ 
+ === Note ===
+ 
+ Automatic sorting works only using properties available on a row object, and these must be comparable, i.e, implement the Comparable interface, or else they will be compared as strings
+