Groups Model"

From Documentation
m
Line 45: Line 45:
  
 
=Sorting and Regrouping=
 
=Sorting and Regrouping=
 +
 +
If your groups model allows the end user to sort and/or to re-group (i.e., grouping data based on different criteria), you have to implement <javadoc type="interface">org.zkoss.zul.GroupsModelExt</javadoc> too. Then, <javadoc method="group(java.util.Comparator, boolean, int)" type="interface">org.zkoss.zul.GroupsModelExt</javadoc> will be called if the user requests to sort the data based on particular column. And, <javadoc method="sort(java.util.Comparator, boolean, int)" type="interface">org.zkoss.zul.GroupsModelExt</javadoc> will be called if the user requests to re-group the data based on particular column.
 +
 +
<javadoc>org.zkoss.zul.GroupsModelArray</javadoc> support both sorting and re-grouping as described below:
 +
 +
* Sorting: <javadoc>org.zkoss.zul.GroupsModelArray</javadoc> sorts each group separately by using the specified comparator (java.util.Comparator).
 +
* Re-grouping: <javadoc>org.zkoss.zul.GroupsModelArray</javadoc> re-groups by assuming two data belong to the same group if the compared result is the same (i.e., the given java.util.Comparator returns 0).
 +
** For better control, you could implement <javadoc type="interface">org.zkoss.zul.GroupComparator</javadoc>, and pass an instance to, say, <javadoc method="setSortAscending(java.util.Comparator)">org.zkoss.zul.Column</javadoc> and <javadoc method="setSortDescending(java.util.Comparator)">org.zkoss.zul.Column</javadoc>.
  
 
[[Image:Grouping_model_explain.png]]
 
[[Image:Grouping_model_explain.png]]
 +
 +
If it is not the behavior you want, you could override <javadoc method="sortGroupData(java.lang.Object, java.lang.Object[], java.util.Comparator, boolean, int)">org.zkoss.zul.GroupsModelArray</javadoc>. Of course, you could extend from <javadoc>org.zkoss.zul.AbstractGroupsModel</javadoc> to have total control.
  
 
=Group Footer =
 
=Group Footer =

Revision as of 08:40, 30 December 2010

Here we describe how to implement a groups model (GroupsModel). For the concept about component, model and render, please refer to the Model-driven Display section.

A groups model is used to drive components that support groups of data. The groups of data is a two dimensional data: a list of grouped data and each grouped data is a list of data to display. Here is an example. Currently, Listbox and Grid both support a list of grouped data.

Instead of implementing GroupsModel, it is suggested to extend from AbstractGroupsModel, or to use one of the default implementations: GroupsModelArray and SimpleGroupsModel. GroupsModelArray supports regrouping, while SimpleGroupsModel is simpler but no regrouping is allowed (i.e., immutable).

For example, suppose you have a two-dimensional array, then you could

<zk>
	<zscript>
		String[][] datas = new String[][] {
			new String[] {
				// Today
				"RE: Bandbox Autocomplete Problem",
				"RE: It's not possible to navigate a listbox' ite",
				"RE: FileUpload"
			},
			new String[] {
				// Yesterday
				"RE: Opening more than one new browser window",
				"RE: SelectedItemConverter Question"
			},
			new String[] {
				"RE: Times_Series Chart help",
				"RE: SelectedItemConverter Question"
			}			
		};
		GroupsModel model = new SimpleGroupsModel(datas,
			new String[]{"Date: Today", "Date: Yesterday", "Date: Last Week"});
	</zscript>
	<grid model="${model}">
	 	<columns sizable="true">
	       <column label="Subject"/>
	     </columns>
	</grid>
</zk>

Then, the result

DrGroupsModel.png

Sorting and Regrouping

If your groups model allows the end user to sort and/or to re-group (i.e., grouping data based on different criteria), you have to implement GroupsModelExt too. Then, GroupsModelExt.group(Comparator, boolean, int) will be called if the user requests to sort the data based on particular column. And, GroupsModelExt.sort(Comparator, boolean, int) will be called if the user requests to re-group the data based on particular column.

GroupsModelArray support both sorting and re-grouping as described below:

Grouping model explain.png

If it is not the behavior you want, you could override GroupsModelArray.sortGroupData(Object, Object[], Comparator, boolean, int). Of course, you could extend from AbstractGroupsModel to have total control.

Group Footer

Version History

Last Update : 2010/12/30


Version Date Content
     



Last Update : 2010/12/30

Copyright © Potix Corporation. This article is licensed under GNU Free Documentation License.