The Developer's Guide

Version 3.0.4


Table of Contents

1. Introduction
Traditional Web Applications
Ad-hoc AJAX Applications
ZK: What It Is
ZK: What It Is Not
ZK: Limitations
2. Getting Started
Hello World!
Interactivity
The zscript Element
The Scripting Language
The Scripting Codes in a Separate File
The attribute Element
The EL Expressions
The id Attribute
The if and unless Attributes
The forEach Attribute
The use and apply Attribute
The use Attribute
The apply Attribute
Used with the forward Attribute
Implement Java Classes in zscript
Create Components Manually
Developing ZK Applications without ZUML
Define New Components for a Particular Page
3. The Basics
Architecture Overview
The Execution Flow
Components, Pages and Desktops
Components
Pages
Desktops
Forest of Trees of Components
Component: a Visual Presentation and a Java Object
Identifiers
UUID
The ID Space
Namespace and ID Space
Variable and Functions Defined in zscript
Events
Desktops and Event Processing
Desktops and the Creation of Components
ZUML and XML Namespaces
4. The Component Lifecycle
The Lifecycle of Loading Pages
The Page Initial Phase
The Component Creation Phase
The Event Processing Phase
The Rendering Phase
The Lifecycle of Updating Pages
The Request Processing Phase
The Event Processing Phase
The Rendering Phase
The Molds
Component Garbage Collection
5. Event Listening and Processing
Add Event Listeners by Markup Languages
Add and Remove Event Listeners by Program
Declare a Member
Add and Remove Event Listeners Dynamically
Deferrable Event Listeners
Add and Remove Event Listeners to Pages Dynamically
The Invocation Sequence
Abort the Invocation Sequence
Send, Post and Echo Events from an Event Listener
Post Events
Send Events
Echo Events
Thread Model
Suspend and Resume
Long Operations
Initialization and Cleanup of Event Processing Thread
Initialization Before Processing Each Event
Cleanup After Processed Each Event
6. The ZK User Interface Markup Language
XML
Elements Must Be Well-formed
Special Character Must Be Replaced
Attribute Values Must Be Specified and Quoted
Comments
Character Encoding
Namespace
Conditional Evaluation
Iterative Evaluation
The each Variable
The forEachStatus Variable
How to Use each and forEachStatus Variables in Event Listeners
Load on Demand
Load-on-Demand with the fulfill Attribute
Load-on-Demand with an Event Listener
Implicit Objects
List of Implicit Objects
Information about Request and Execution
Processing Instructions
The page Directive
The component Directive
The init Directive
The variable-resolver Directive
The import Directive
ZK Attributes
The apply Attribute
The use Attribute
The if Attribute
The unless Attribute
The forEach Attribute
The forEachBegin Attribute
The forEachEnd Attribute
The fulfill Attribute
The forward Attribute
ZK Elements
The zk Element
The zscript Element
The attribute Element
The variables element
The custom-attributes element
Component Sets and XML Namespaces
Standard Namespaces
7. ZUML with the XUL Component Set
Basic Components
Label
Buttons
Radio and Radio Group
Image
Imagemap
Audio
Input Controls
Calendar
Progressmeter
Slider
Timer
Paging
Windows
Titles and Captions
The closable Property
The sizable Property
The Style Class (sclass)
The contentStyle Property
Borders
Overlapped, Popup, Modal, Highlighted and Embedded
The position Property
Common Dialogs
The Layout Components
A Nested borderlayout Component
The size and border Properties
The splittable and collapsible Properties
The flex property
The open Property
The onOpen Event
The Box Model
The spacing Property
The widths and heights Properties
Splitters
Tab Boxes
Nested Tab Boxes
The Accordion Tab Boxes
The orient Property
The align Property of Tabs
The closable Property
The disabled Property
Load-on-Demand for Tab Panels
Grids
Scrollable Grid
Sizable Columns
Grids with Paging
Sorting
Live Data
Auxiliary Headers
Special Properties
More Layout Components
Separators and Spaces
Group boxes
Toolbars
Menu bars
Execute a Menu Command
Use Menu Items as Check Boxes
The autodrop Property
The onOpen Event
More Menu Features
Context Menus
Customizable Tooltip and Popup Menus
The onOpen Event
List Boxes
Multi-Column List Boxes
Column Headers
Column Footers
Drop-Down List
Multiple Selection
Scrollable List Boxes
Sizable List Headers
List Boxes with Paging
Sorting
Special Properties
Live Data
List Boxes Contain Buttons
Tree Controls
The open Property and the onOpen Event
Multiple Selection
Paging
Special Properties
Create-on-Open for Tree Controls
Comboboxes
The autodrop Property
The description Property
The onOpen Event
The onChanging Event
Bandboxes
The closeDropdown Method
The autodrop Property
The onOpen Event
The onChanging Event
Chart
Live Data
Drill Down (The onClick Event)
Manipulate Areas
Drag and Drop
The draggable and droppable Properties
The onDrop Event
Dragging with Multiple Selections
Multiple Types of Draggable Components
Work with HTML Tags
The html Component
The Native Namespace, http://www.zkoss.org/2005/zk/native
The XHTML Namespace, http://www.w3.org/1999/xhtml
The include Component
The style Component
The script Component
The iframe Component
Work with HTML FORM and Java Servlets
The name Property
Components that Support the name Property
Rich User Interfaces
Client Side Actions
Reference to a Component
The onshow and onhide Actions
CSA JavaScript Utilities
Events
Mouse Events
Keystroke Events
Input Events
List and Tree Events
Slider and Scroll Events
Other Events
8. ZUML with the XHTML Component Set
The Goal
A XHTML Page Is A Valid ZUML Page
Server-Centric Interactivity
Servlets Work As Usual
The Differences
A Component Created for Each Tag
UUID Is ID
All Tags Are Valid
Case Insensitive
No Mold Support
The DOM Tree at the Browser
The TABLE and TBODY Tags
Events
Integrate with JSF, JSP and Others
Work with Existent Servlets
Enrich by Inclusion
Enrich Static HTML Pages
Use of ZK JSP Tags
Use of ZK JSF Components
Enrich a Dynamically Generated Page with ZK Filter
9. Macro Components
Three Steps to Use Macro Components
Step 1. The Implementation
Step 2. The Declaration
Step 3. The Use
Inline Macros
An Example
Regular Macros
Macro Components and The ID Space
Provide Additional Methods
10. Advanced Features
Identify Pages
Identify Components
The Component Path
Sorting
Browser's Information and Controls
The onClientInfo Event
The org.zkoss.ui.util.Clients Class
Prevent User From Closing a Window
Browser's History Management
Add the Appropriate States to Browser's History
Listen to the onBookmarkChanged Event and Manipulate the Desktop Accordingly
A Simple Example
Component Cloning
Component Serialization
Serializable Sessions
Serialization Listeners
Inter-Page Communication
Post and Send Events
Attributes
Inter-Web-Application Communication
Web Resources from Classpath
Annotations
Annotate ZUML Pages
Annotate Components Created Manually
Retrieve Annotations
Richlets
Implement the org.zkoss.zk.ui.Richlet interface
Configure web.xml and zk.xml
Session Timeout Management
Error Handling
Error Handling When Loading Pages
Error Handing When Updating Pages
Miscellaneous
Configure the ZK Loader Not to Compress the Output
11. Performance Tips
Use Compiled Java Codes
Use the deferred Attribute
The deferred Attribute and the onCreate Event
Use the forward Attribute
Use the Servlet Thread to Process Events
Modal Windows
Message Boxes
File Upload
Use the Native Namespace instead of the XHTML Namespace
Prolong the Period to Check Whether a File Is Modified
Defer the Creation of Child Components
Use Live Data and Paging for Large List Boxes
Use ZK JSP Tags or ZK JSF Components instead of ZK Filter
12. Other Devices and Output Formats
ZK Mobile
The Mobile Component Set, http://www.zkoss.org/2007/mil
XML Output
Three Steps to Generate XML Output with a ZUML Page
The XML Component Set
13. Internationalization
Locale
The px_preferred_locale Session Attribute
The Request Interceptor
Time Zone
The px_preferred_time_zone Session Attribute
The Request Interceptor
Labels
Locale-Dependent Files
Browser and Locale-Dependent URI
Locating Browser and Locale Dependent Resources in Java
Messages
Themes
Use the Theme with Smaller Fonts
Use the Theme with Larger Fonts
Use the Theme that Depends on Locale
Use Your Own Theme
The Theme Provider
14. Database Connectivity
ZK Is Presentation-Tier Only
Simplest Way to Use JDBC (but not recommended)
Use with Connection Pooling
Connect and Close a Connection
Configure Connection Pooling
ZK Features Applicable to Database Access
The org.zkoss.zk.ui.event.EventThreadCleanup Interface
Access Database in EL Expressions
Transaction and org.zkoss.zk.util.Initiator
15. Portal Integration
Configuration
WEB-INF/portlet.xml
WEB-INF/web.xml
The Usage
The zk_page and zk_richlet Parameter and Attribute
Examples
16. Beyond ZK
Logger
How to Configure Log Levels with ZK
Content of i3-log.conf
Location of i3-log.conf
Disable All Logs
DSP
iDOM

SIMPLY RICH

ZKTM

March 2008

Potix Corporation

Revision 209

Copyright © Potix Corporation. All rights reserved.

The material in this document is for information only and is subject to change without notice. While reasonable efforts have been made to assure its accuracy, Potix Corporation assumes no liability resulting from errors or omissions in this document, or from the use of the information contained herein.

Potix Corporation may have patents, patent applications, copyright or other intellectual property rights covering the subject matter of this document. The furnishing of this document does not give you any license to these patents, copyrights or other intellectual property.

Potix Corporation reserves the right to make changes in the product design without reservation and without notification to its users.

The Potix logo and ZK are trademarks of Potix Corporation.

All other product names are trademarks, registered trademarks, or trade names of their respective owners.