This documentation is for an older version of ZK. For the latest documentationplease click here.
Home   Single Page

The Developer's Guide

Version 3.6.3

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!
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
Implement Java Classes in zscript
The forward Attribute
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
Forest of Trees of Components
Component: a Visual Part and a Java Object
The ID Space
Namespace and ID Space
Variable and Functions Defined in zscript
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
Elements Must Be Well-formed
Special Character Must Be Replaced
Attribute Values Must Be Specified and Quoted
Character Encoding
Conditional Evaluation
If and Unless
Switch and Case
Choose and When
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
The link, meta and script Directives
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
Radio and Radio Group
Input Controls
Titles and Captions
The closable Property
The sizable Property
The Style Class (sclass)
The contentStyle Property
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
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
Scrollable Grid
Sizable Columns
Grids with Paging
Live Data
Auxiliary Headers
Special Properties
More Layout Components
Separators and Spaces
Group boxes
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
Special Properties
Live Data
List Boxes Contain Buttons
Tree Controls
The open Property and the onOpen Event
Multiple Selection
Special Properties
Create-on-Open for Tree Controls
The autodrop Property
The description Property
The onOpen Event
The onChanging Event
The closeDropdown Method
The autodrop Property
The onOpen Event
The onChanging Event
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,
The XHTML Namespace,
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
Mouse Events
Keystroke Events
Input Events
List and Tree Events
Slider and Scroll Events
Other Events
8. Data Binding
Basic Concept
Adding a Data Source
Activates Data Binding Manager
Associate UI Components with Data Source
When to Load Data from Data Source to UI
When to Save Data from UI Components to the Data Source
Associate the Same Data Source with Multiple UI Components
Associate UI Components with a Collection
Customization of Conversion between the Data Source and UI Components
Define the Access Privilege of Data Binding Manager
9. 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
All Tags Are Valid
Case Insensitive
No Mold Support
The DOM Tree at the Browser
The TABLE and TBODY Tags
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
10. 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
11. Advanced Features
Identify Pages
Identify Components
The Component Path
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 onBookmarkChange Event and Manipulate the Desktop Accordingly
A Simple Example
Bookmarking with iframe
Component Cloning
Component Serialization
Serializable Sessions
Serialization Listeners
Inter-Page Communication
Post and Send Events
Inter-Web-Application Communication
Web Resources from Classpath
Annotate ZUML Pages
Annotate Components Created Manually
Retrieve Annotations
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
Configure the ZK Loader Not to Compress the Output
12. 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
13. Other Devices and Output Formats
ZK Mobile
The Mobile Component Set,
XML Output
Three Steps to Generate XML Output with a ZUML Page
The XML Component Set
14. Internationalization
The px_preferred_locale Session Attribute
The Request Interceptor
Time Zone
The px_preferred_time_zone Session Attribute
The Request Interceptor
Locale-Dependent Files
Browser and Locale-Dependent URI
Locating Browser and Locale Dependent Resources in Java
Change Font Size and/or Family
Use Your Own Theme
The Theme Provider
15. 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
16. Hibernate Integration
What is Hibernate
Installing Hibernate
Configuring the ZK Configuration File
Creating the Java Objects
Mapping the Java Objects
Using the Mapping Files
Using Java Annotation
Creating the Hibernate Configuration File
Creating DAO Objects
Accessing Persistence Objects in ZUML Page
17. Spring Integration
What is Spring
Prerequisites of Using Spring
Copy spring.jar into your Web library
Configure web.xml
Create Spring Configuration File
Creating Spring Bean Class
Accessing Spring Bean in the ZUML page
Using variable-Resolver
Using SpringUtil
Spring Security
Running a sample application
Prerequisites of using Spring Security
Configure the /WEB-INF/web.xml file
Create /WEB-INF/applicationContext-security.xml
Def ine which service to be secured
Def ine which ZK event to be secured
The ZUML Page
18. Portal Integration
The Usage
The zk_page and zk_richlet Parameter and Attribute
19. Beyond ZK
How to Configure Log Levels with ZK
Content of i3-log.conf
Location of i3-log.conf
Disable All Logs



June 2009

Potix Corporation

Revision 228

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.