Paging"

From Documentation
(25 intermediate revisions by 6 users not shown)
Line 3: Line 3:
 
= Paging =
 
= Paging =
  
*Demonstration: [http://www.zkoss.org/zkdemo/userguide/#g6 Paging (with Grid)], [http://www.zkoss.org/zkdemo/userguide/#g10 Paging (with Listbox)], [http://www.zkoss.org/zkdemo/userguide/#g15 Paging (with Tree)]
+
*Demonstration: [http://www.zkoss.org/zkdemo/grid/paging Paging (with Grid)], [http://www.zkoss.org/zkdemo/listbox/paging Paging (with Listbox)], [http://www.zkoss.org/zkdemo/tree/paging Paging (with Tree)]
 
*Java API: <javadoc>org.zkoss.zul.Paging</javadoc>
 
*Java API: <javadoc>org.zkoss.zul.Paging</javadoc>
 
*JavaScript API: <javadoc directory="jsdoc">zul.mesh.Paging</javadoc>
 
*JavaScript API: <javadoc directory="jsdoc">zul.mesh.Paging</javadoc>
 +
*Style Guide: [[ZK_Style_Guide/XUL_Component_Specification/Paging| Paging]]
  
 
= Employment/Purpose =
 
= Employment/Purpose =
  
A <tt>paging</tt> component is used to separate long content into multiple pages. 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.
+
A <tt>paging</tt> component is used with another component to separate long content into multiple pages. If a component has long content to display, you could separate them into pages, and then use a paging component as a controller to allow the user decide which page to display.
  
The <tt>listbox </tt>and <tt>grid </tt>component support the paging intrinsically, so you don't need to specify a paging component explicitly as above, unless you want to have different visual layout or to control multiple listbox and grid with one paging component.
+
The [[ZK Component Reference/Data/Listbox|listbox]], [[ZK Component Reference/Data/Grid|grid]] and [[ZK Component Reference/Data/Tree|tree]] components support the paging intrinsically, so you don't need to specify a paging component explicitly. In other words, they will instantiate and manage a paging component automatically if the paging mold is specified. Of course, you could specify an external paging component, if you want to have different visual layout, or to control multiple listboxes, grids and/or trees with one single paging component.
  
 
= Example =
 
= Example =
  
[[Image:ZKComRef_Paging.PNG]]
+
For example, suppose you have 100 items and prefer to show 20 items at a time, then you can use the paging components as follows.
  
 
<source lang="xml" >
 
<source lang="xml" >
Line 23: Line 24:
 
</source>
 
</source>
  
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.
+
[[Image:paging_mold_default.png ]]
 +
 
 +
When a user clicks on the hyperlinks, the <tt>onPaging</tt> event is sent with an instance of <javadoc>org.zkoss.zul.event.PagingEvent</javadoc> to the paging component. To decide which portion of your 100 items are visible, you should add a listener to the paging component. Please note that the code below is pseudo code. For real examples, please refer to [[#Use_Cases|User Cases]] below.
 +
 
 
<source lang="xml" >
 
<source lang="xml" >
 
<zk>
 
<zk>
 +
<div id="content"/> <!-- the long content is displayed here -->
 
<paging id="paging" />
 
<paging id="paging" />
 
 
Line 37: Line 42:
 
int pgno = event.getPaginal().getActivePage();
 
int pgno = event.getPaginal().getActivePage();
 
int ofs = pgno * event.getPaginal().getPageSize();
 
int ofs = pgno * event.getPaginal().getPageSize();
+
 
+
new Viewer().redraw(content,
new Viewer().redraw(result, ofs, ofs + event.getPaginal().
+
result, ofs, ofs + event.getPaginal().getPageSize() - 1);
getPageSize() - 1);
+
//assume redraw(Div content, List result, int b, int e) will display
//assume redraw(List result, int b, int e) will display
+
//the result to the content component from the b-th item to the e-th item
//from the b-th item to the e-th item
 
 
}
 
}
 
}
 
}
Line 48: Line 52:
 
</zscript>
 
</zscript>
 
</zk>
 
</zk>
</source>    
+
</source>
=Supported events=
+
 
 +
=Properties=
 +
== Disabled ==
 +
[Since 8.0.3]
 +
<javadoc method="setDisabled(boolean)">org.zkoss.zul.Paging</javadoc> is used to disable the paging component. It can block the user from navigating through the pagination. For example,
 +
 
 +
<source lang="xml">
 +
<paging pageSize="2" disabled="true"/>
 +
</source>
 +
 
 +
=Limitation=
 +
Paging can not apply [[ZK Developer's Reference/Performance Tips/Specify Stubonly for Client-only Components | stubonly]] at the same time. For example,
 +
<source lang="xml" >
 +
<listbox mold="paging" pageSize="1" >
 +
<listitem >
 +
<listcell stubonly="true"/>
 +
</listitem>
 +
<listitem>
 +
<listcell />
 +
</listitem>
 +
</listbox>
 +
</source>
 +
Although paging will [[ZK_Developer's_Reference/UI_Composing/Component-based_UI#Invalidate_a_Component|invalidate]] <tt>listbox</tt> and its children, <tt>stubonly</tt> needs the referred widget in client side which is detached during paging and throws mounting error.
 +
 
 +
=Supported Events=
  
 
{| border="1" | width="100%"
 
{| border="1" | width="100%"
Line 56: Line 84:
 
|-
 
|-
 
| <center><tt>onPaging</tt></center>
 
| <center><tt>onPaging</tt></center>
| <javadoc>org.zkoss.zk.ui.event.PagingEvent</javadoc>
+
| '''Event:''' <javadoc>org.zkoss.zul.event.PagingEvent</javadoc>
  
<tt>'''Description:''' Notifies one of the pages of a multi-page component is selected by the user.</tt>
+
Notifies one of the pages of a multi-page component is selected by the user.
  
 
|}
 
|}
  
=Supported molds=
+
*Inherited Supported Events: [[ZK_Component_Reference/Base_Components/XulElement#Supported_Events | XulElement]]
 +
 
 +
=Supported Molds=
 
Available molds of a component are defined in lang.xml embedded in zul.jar.
 
Available molds of a component are defined in lang.xml embedded in zul.jar.
 
{| border="1" | width="100%"
 
{| border="1" | width="100%"
Line 79: Line 109:
 
  *NONE
 
  *NONE
  
=Use cases=
+
=Use Cases=
  
 
{| border='1px' | width="100%"
 
{| border='1px' | width="100%"
Line 85: Line 115:
 
|-
 
|-
 
| 3.6
 
| 3.6
| Smalltalk: Paging Sorting with a filter object
+
| Small talks
| [http://docs.zkoss.org/wiki/Paging_Sorting_with_a_filter_object http://docs.zkoss.org/wiki/Paging_Sorting_with_a_filter_object]
+
|
|-
+
* [[Small Talks/2009/July/Handling huge data using ZK|Handling huge data using ZK]]
| 3.6
+
* [[Small_Talks/2009/May/Paging_Sorting_with_a_filter_object |Paging Sorting with a filter object]]
| Live Data
+
* [[Small_Talks/2008/June/Use_Load-On-Demand_to_Handle_Huge_Data|Use Load-On-Demand to Handle Huge Data]]
| [http://docs.zkoss.org/wiki/Live_Data,_Paging,_setModel_and_Implement_your_own_renderer http://docs.zkoss.org/wiki/Live_Data,_Paging,_setModel_and_Implement_your_own_renderer]
 
 
|}
 
|}
  
 
=Version History=
 
=Version History=
 +
{{LastUpdated}}
  
 
{| border='1px' | width="100%"
 
{| border='1px' | width="100%"

Revision as of 07:06, 27 July 2016

Paging

Employment/Purpose

A paging component is used with another component to separate long content into multiple pages. If a component has long content to display, you could separate them into pages, and then use a paging component as a controller to allow the user decide which page to display.

The listbox, grid and tree components support the paging intrinsically, so you don't need to specify a paging component explicitly. In other words, they will instantiate and manage a paging component automatically if the paging mold is specified. Of course, you could specify an external paging component, if you want to have different visual layout, or to control multiple listboxes, grids and/or trees with one single paging component.

Example

For example, suppose you have 100 items and prefer to show 20 items at a time, then you can use the paging components as follows.

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

Paging mold default.png

When a user clicks on the hyperlinks, the onPaging event is sent with an instance of PagingEvent to the paging component. To decide which portion of your 100 items are visible, you should add a listener to the paging component. Please note that the code below is pseudo code. For real examples, please refer to User Cases below.

<zk>
	<div id="content"/> <!-- the long content is displayed here -->
	<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 org.zkoss.zk.ui.event.EventListener() {
		public void onEvent(Event event) {
			int pgno = event.getPaginal().getActivePage();
			int ofs = pgno * event.getPaginal().getPageSize();

			new Viewer().redraw(content,
				result, ofs, ofs + event.getPaginal().getPageSize() - 1);
			//assume redraw(Div content, List result, int b, int e) will display
			//the result to the content component from the b-th item to the e-th item
			}
		}
	);
	</zscript>
</zk>

Properties

Disabled

[Since 8.0.3]

Paging.setDisabled(boolean) is used to disable the paging component. It can block the user from navigating through the pagination. For example,

<paging pageSize="2" disabled="true"/>

Limitation

Paging can not apply stubonly at the same time. For example,

<listbox mold="paging" pageSize="1" >
	<listitem >
		<listcell stubonly="true"/>
	</listitem>
	<listitem>
		<listcell />
	</listitem>
</listbox>

Although paging will invalidate listbox and its children, stubonly needs the referred widget in client side which is detached during paging and throws mounting error.

Supported Events

Name
Event Type
onPaging
Event: PagingEvent

Notifies one of the pages of a multi-page component is selected by the user.

Supported Molds

Available molds of a component are defined in lang.xml embedded in zul.jar.

Name
Snapshot
default
Paging mold default.png
os
Paging mold os.png

Supported Children

*NONE

Use Cases

Version Description Example Location
3.6 Small talks

Version History

Last Update : 2016/07/27


Version Date Content
     



Last Update : 2016/07/27

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