Live Data, Paging, setModel and Implement your own renderer"

From Documentation
m (correct highlight (via JWB))
 
(6 intermediate revisions by 3 users not shown)
Line 1: Line 1:
 +
{{Template:Smalltalk_Author|
 +
|author= Peter Kuo, Engineer, Potix Corporation
 +
|date=December 21, 2008
 +
|version= ZK 3, ZK 5
 +
}}
 +
 +
 
==Overview==
 
==Overview==
In a real world web application, it's common to collect data from database, and show it in <tt>listbox</tt> or <tt>grid</tt> or <tt>tree</tt>. The underlying data may be hundreds of thousands records. It's impractical to load them all to the client. Therefore ZK introduces concepts of <tt>Live Data</tt>, <tt>Paging</tt>. To separate view from data, ZK also introduces the concept of <tt>model</tt>. It is easier to use different views to show the same set of data. To show data in the view any way you like, a developer may implement his own renderer; ZK has provided a default renderer.
+
In a real world web application, it's common to collect data from database, and show it in <code>listbox</code> or <code>grid</code> or <code>tree</code>. The underlying data may be hundreds of thousands records. It's impractical to load them all to the client. Therefore ZK introduces concepts of <code>Live Data</code>, <code>Paging</code>. To separate view from data, ZK also introduces the concept of <code>model</code>. It is easier to use different views to show the same set of data. To show data in the view any way you like, a developer may implement his own renderer; ZK has provided a default renderer.
  
 
==What's Live Data==
 
==What's Live Data==
Line 16: Line 23:
 
</source>
 
</source>
 
   
 
   
Then, when a user clicks on the hyperlinks, the <tt>onPaging</tt> event is sent with an instance of <tt>org.zkoss.zul.event.PagingEvent</tt> to the paging component. To decide which portion of your 100 items are visible, you shall add a listener to the paging component.
+
Then, when a user clicks on the hyperlinks, the <code>onPaging</code> event is sent with an instance of <code>org.zkoss.zul.event.PagingEvent</code> to the paging component. To decide which portion of your 100 items are visible, you shall add a listener to the paging component.
  
 
<source lang="xml" >
 
<source lang="xml" >
Line 36: Line 43:
  
 
==What's Model==
 
==What's Model==
To assign data to a component (e.g. <tt>grid</tt> or <tt>listbox</tt>), you have to prepare the data in certain data model. For example, <tt>listbox</tt> and <tt>grid</tt> accept interfaces <tt>ListModel</tt> and <tt>GroupsModel</tt>, while <tt>tree</tt> only accepts <tt>TreeModel</tt>. See the <tt>setModel</tt> method of each component for the kind of model it accepts. Using the wrong type of data model will throw a cast error and is a common beginner mistake.
+
To assign data to a component (e.g. <code>grid</code> or <code>listbox</code>), you have to prepare the data in certain data model. For example, <code>listbox</code> and <code>grid</code> accept interfaces <code>ListModel</code> and <code>GroupsModel</code>, while <code>tree</code> only accepts <code>TreeModel</code>. See the <code>setModel</code> method of each component for the kind of model it accepts. Using the wrong type of data model will throw a cast error and is a common beginner mistake.
  
 
ZK has implemented following Models:
 
ZK has implemented following Models:
Line 50: Line 57:
 
==What's Renderer==
 
==What's Renderer==
 
A renderer is responsible for rendering the layout of certain model.
 
A renderer is responsible for rendering the layout of certain model.
For example, <tt>RowRenderer</tt> is responsible for rendering data stored in the <tt>ListModel</tt> to the specified <tt>row</tt> in the <tt>Grid</tt>.
+
For example, <code>RowRenderer</code> is responsible for rendering data stored in the <code>ListModel</code> to the specified <code>row</code> in the <code>Grid</code>.
  
 
ZK has provided default renders:
 
ZK has provided default renders:
  
 
==Three Steps to Use Live Data==
 
==Three Steps to Use Live Data==
*Prepare the data in the form of <tt>ListModel</tt>. ZK has a concrete implementation called <tt>org.zkoss.zul.SimpleListModel</tt>  for representing an array of objects.
+
*Prepare the data in the form of <code>ListModel</code>. ZK has a concrete implementation called <code>org.zkoss.zul.SimpleListModel</code>  for representing an array of objects.
*Implement the <tt>org.zkoss.zul.RowRenderer</tt> interface for rendering a row of data into the Grid.
+
*Implement the <code>org.zkoss.zul.RowRenderer</code> interface for rendering a row of data into the Grid.
** This is optional. If it is not specified, the default <tt>rowrender</tt> is used to render the data into the first column.
+
** This is optional. If it is not specified, the default <code>rowrender</code> is used to render the data into the first column.
 
** You could implement different renderers for represent the same data in different views.
 
** You could implement different renderers for represent the same data in different views.
*Specify the data in the <tt>model</tt> property, and, optionally, the <tt>rowrender</tt> in the <tt>rowRenderer</tt> property.
+
*Specify the data in the <code>model</code> property, and, optionally, the <code>rowrender</code> in the <code>rowRenderer</code> property.
  
 
==Examples==
 
==Examples==
Line 158: Line 165:
  
 
== If extreme large data set, say 1,000,000? ==
 
== If extreme large data set, say 1,000,000? ==
[http://docs.zkoss.org/wiki/ZK/How-Tos/Concepts-and-Tricks ZK/How-Tos/Concepts-and-Tricks]
+
Check implement paging for listboxes with many items under:
 +
[[http://en.wikibooks.org/wiki/ZK/How-Tos/Concepts_and_Tricks#Concepts]]
 +
 
  
Check
 
Implement paging for listboxes with many items
 
  
 
== Data Binding ==
 
== Data Binding ==
 
Not only showing the data by model, you can also modify underlying model by UI in real time.  
 
Not only showing the data by model, you can also modify underlying model by UI in real time.  
  
[[Example Code for Data binding with live data| Example code]]
+
[[ZK_Essentials/Displaying_Information_in_a_Grid_Using_Data_Binding/The_Concept_of_Data_Binding]]
  
 
== See Also ==
 
== See Also ==
[http://www.zkoss.org/smalltalks/livedata/livedataforgrid.dsp How to realize the idea of live data in a Grid]: A smalltalk
 
  
[http://www.zkoss.org/smalltalks/zkTreeModel/ ZK Tree Model]: A smalltalk.
+
[[Small_Talks/2007/March/How_to_realize_the_idea_of_live_data_in_a_Grid ]]
  
[http://zk1.svn.sourceforge.net/viewvc/zk1/branches/5.0/zul/src/org/zkoss/zul/Grid.java?revision=14211&view=markup Grid.java]: The source code of Grid.java. By tracing it, you'll know how renderer and setModel works, how <tt>render()</tt> is called, how the <tt>model</tt> is iterated through visible region. Keyword: render. You may also trace Tree.java and Listbox.java.
+
[[Small_Talks/2007/August/ZK_Tree_Model]]
  
[[Grids%2C_Trees_and_Listbox#Live_Data | Live Data]] section in chapter Grids, Trees and Listbox.
+
[http://zk1.svn.sourceforge.net/viewvc/zk1/branches/5.0/zul/src/org/zkoss/zul/Grid.java?revision=14211&view=markup Grid.java]: The source code of Grid.java. By tracing it, you'll know how renderer and setModel works, how <code>render()</code> is called, how the <code>model</code> is iterated through visible region. Keyword: render. You may also trace Tree.java and Listbox.java.
  
 
[http://www.zkoss.org/forum/index.zul#path%3DlistComment%3BdiscussionId%3D6320%3BcategoryId%3D14%3B Bug in Grid paging? handleError:1084]: A thread in forum.
 
[http://www.zkoss.org/forum/index.zul#path%3DlistComment%3BdiscussionId%3D6320%3BcategoryId%3D14%3B Bug in Grid paging? handleError:1084]: A thread in forum.
 +
 +
 +
{{Template:Smalltalk_Footer|
 +
|name=Potix Corporation
 +
}}

Latest revision as of 04:16, 20 January 2022

DocumentationSmall Talks2008DecemberLive Data, Paging, setModel and Implement your own renderer
Live Data, Paging, setModel and Implement your own renderer

Author
Peter Kuo, Engineer, Potix Corporation
Date
December 21, 2008
Version
ZK 3, ZK 5


Overview

In a real world web application, it's common to collect data from database, and show it in listbox or grid or tree. The underlying data may be hundreds of thousands records. It's impractical to load them all to the client. Therefore ZK introduces concepts of Live Data, Paging. To separate view from data, ZK also introduces the concept of model. It is easier to use different views to show the same set of data. To show data in the view any way you like, a developer may implement his own renderer; ZK has provided a default renderer.

What's Live Data

The main idea of "live data" is to separate data from the view. Developers only have to manipulate the data model, and the data of view (UI Component) will be updated accordingly. Secondly, it shortens the response time of user since only the required data will be downloaded the first time.

What's Paging

Paging separates long content into multiple pages.

A paging component is used for this purpose. For example, assume that you have 100 items and prefer to show 20 items at a time, then you can use the paging components as follows.

100000000000007A00000013F689AD21.png

<paging totalSize="100" pageSize="20"/>

Then, when a user clicks on the hyperlinks, the onPaging event is sent with an instance of org.zkoss.zul.event.PagingEvent to the paging component. To decide which portion of your 100 items are visible, you shall add a listener to the paging component.

<paging id="paging"/>
<zscript>
     List result = new SearchEngine().find("ZK");
     //assume SearchEngine.find() will return a list of items.
     paging.setTotalSize(result.size());
     paging.addEventListener("onPaging", new EventListener() {
             public void onEvent(Event event) {
             int pgno = event.getPaginal().getActivePage();
             int ofs = pgno * event.getPaginal().getPageSize();
             new Viewer().redraw(result, ofs, ofs + event.getPaginal().getPageSize() - 1);            //assume redraw(List result, int b, int e) will display
             //from the b-th item to the e-th item
         }
     });
</zscript>

What's Model

To assign data to a component (e.g. grid or listbox), you have to prepare the data in certain data model. For example, listbox and grid accept interfaces ListModel and GroupsModel, while tree only accepts TreeModel. See the setModel method of each component for the kind of model it accepts. Using the wrong type of data model will throw a cast error and is a common beginner mistake.

ZK has implemented following Models:

  • SimpleCategoryModel
  • SimpleGroupsModel
  • SimpleListModel
  • SimplePieModel
  • SimpleTreeModel
  • SimpleXYModel
  • SimpleXYZModel
  • SimpleHiLoModel

What's Renderer

A renderer is responsible for rendering the layout of certain model. For example, RowRenderer is responsible for rendering data stored in the ListModel to the specified row in the Grid.

ZK has provided default renders:

Three Steps to Use Live Data

  • Prepare the data in the form of ListModel. ZK has a concrete implementation called org.zkoss.zul.SimpleListModel for representing an array of objects.
  • Implement the org.zkoss.zul.RowRenderer interface for rendering a row of data into the Grid.
    • This is optional. If it is not specified, the default rowrender is used to render the data into the first column.
    • You could implement different renderers for represent the same data in different views.
  • Specify the data in the model property, and, optionally, the rowrender in the rowRenderer property.

Examples

Single-Column Example : Using only setModel

In the following example, an array of data("data") is prepared , it is passed as a parameter for the generation of a ListModel("strset"). Last, assign this ListModel into a Grid by setting the model of the Grid.

<window title="Live grid">
	<zscript>
	<![CDATA[  
		String[] data = new String[30];
		for(int j=0; j < data.length; ++j) {
			data[j] = "option "+j;
		}		  
		ListModel strset = new SimpleListModel(data);
	]]>
	</zscript>
	<grid model="${strset}">
		<columns>
			<column label="options" />
		</columns>
	</grid>
</window>

Two-Columns Example : User defined renderer

Since the default rowrender only satisfies the scenario of single-column, a customized rowrenderer must be implemented to commit the scenario of multi-column. In the following example, a two-columns live data for grid is demonstrated.

1.Prepare the Data Model

The first step is to prepare required data. A two-way array is adopted in this example and it is passed as a parameter for the generation of a ListModel which is implemented by SimpleListModel. In addition, ListModel now supports various data types,including Array, List, Map, and Set in the form of ListModelArray,ListModelList, ListModelMap,and ListModelSet.

//prepare the data model 
String[][] model = new String[100][2]; 
for(int j=0; j < model.length; ++j) { 
	model[j][0] = "key"+j;
	model[j][1] = "value"+j; 
} 
ListModel strset = new SimpleListModel(model);

2.Define the RowRenderer Class

Secondly, to define a class which implements the interface RowRenderer,its method render(Row row, java.lang.Object data) is required to be implemented.

   Method render(Row row, java.lang.Object data)
   row - The row to render the result.
   data - Returned from ListModel.getElementAt() 

In addition to pass required parameters into the method render(), the form of view (UI Component) for displaying data in the Grid also has to be defined, and any component which is supported by Grid could be adopted. In this example, Label is adopted, and the last step is to render Label into the specified row in the Grid by calling Label.setParent(Row row).


MyRowRenderer.java

import org.zkoss.zul.Label;
import org.zkoss.zul.Row;
import org.zkoss.zul.RowRenderer;

//define the RowRenderer class 
public class MyRowRenderer implements RowRenderer{ 
 
	public void render(Row row, java.lang.Object data) {
		String[] _data = (String[])data;
		new Label(_data[0]).setParent(row); 
		new Label(_data[1]).setParent(row);
	}
}

3.Specify model and rowRenderer Property

The properties of model and rowRenderer could be specified directly in the Grid. In this example,methods, Grid.setModel() and Grid.setRowRenderer() are adopted to specify required objects for realizing the idea of "live data".

<window title="Two-Column Live Data Demo" >
	<grid id="mygrid">
		<columns>
			<column label="key" />
			<column label="value" />
		</columns>
	</grid>
	<zscript><![CDATA[
		String[][] model = new String[100][2]; 
		
		for(int j=0; j < model.length; ++j) { 
			model[j][0] = "key"+j;
			model[j][1] = "value"+j; 
		} 
		ListModel strset = new SimpleListModel(model); 
		mygrid.setModel(strset); 
		mygrid.setRowRenderer(new MyRowRenderer());	 
	]]>
	</zscript>
</window>

If extreme large data set, say 1,000,000?

Check implement paging for listboxes with many items under: [[1]]


Data Binding

Not only showing the data by model, you can also modify underlying model by UI in real time.

ZK_Essentials/Displaying_Information_in_a_Grid_Using_Data_Binding/The_Concept_of_Data_Binding

See Also

Small_Talks/2007/March/How_to_realize_the_idea_of_live_data_in_a_Grid

Small_Talks/2007/August/ZK_Tree_Model

Grid.java: The source code of Grid.java. By tracing it, you'll know how renderer and setModel works, how render() is called, how the model is iterated through visible region. Keyword: render. You may also trace Tree.java and Listbox.java.

Bug in Grid paging? handleError:1084: A thread in forum.




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