The Developer's Guide

Aimed at simply and effectively exchanging documents Web technologies such as, HTTP and HTML are originated from the page-based stateless-communication model. In this model a page is self-contained and is a minimal unit that communicates between clients and servers.

Since the Web has emerged as the default platform for application development this model faces a substantial challenge: the inability to visually represent the complexities in today's applications. For example, to give a customer a quotation, you might have to open another page to search his trading records, another page for the recent prices, and another page for current stocking. Users are forced to leave the page they are working in, and navigate among several pages. It is easy to get lost and confused resulting in unhappy customers, lost sales and low productivities.

The challenge to develop a modern application upon this page-based model is also substantial. In this model, applications running at the server have to take care of everything: from parsing the request, rendering the response, routing processes that link users from one page to another, and handling versatile errors made by users. Many different frameworks such as: Struts, Tapestry and JSF have emerged to simplify this development process. Due to the huge gap between the page-based model and modern applications learning and using these frameworks is never a pleasant process, not to mention intuitive or simplistic.

Over a decade of evolution, Web applications have evolved from static HTML pages to Dynamic HTML pages, from applets to Flash, and finally to AJAX^[1] technologies (Asynchronous JavaScript and XML). Illustrated by Google Maps and Suggest, AJAX breaths new life into Web applications by delivering the same level of interactivity and responsiveness as desktop applications do. Unlike applets or Flash, AJAX is based on the standard browser and JavaScript with no proprietary plugins required.

AJAX is a kind of new generation DHTML. Like DHTML, it heavily relies on JavaScript to listen to events triggered by user's activity, and then manipulate visual presentation of a page (aka. DOM) in the browser dynamically. Moreover, it takes a step further by enabling communication with the server asynchronously without leaving or rendering the whole page again. It breaks the page-based model by introducing light-weight communication between clients and servers. With proper design AJAX could bring rich components, common to desktop applications, to life in Web applications allowing dynamic updates and more control over the application.

When providing the interactivity that users demand, AJAX adds more complexities and skill prerequisites to the already costly development of Web applications. Developers have to manipulate DOM in the browser and communicate with the server via incompatible and even buggy JavaScript APIs. For better interactivity developers have to replicate application data and business logic in the browser, increasing maintenance costs and the challenge of synchronizing data between the server and the client.

The bottom line is that ad hoc AJAX applications are no different from traditional Web applications in regards to the way processes are requested. Developers still have to fill the gap caused by the page-based and stateless model.

ZK is an event-driven, component-based framework to enable rich user interfaces for Web applications. ZK includes an AJAX-based event-driven engine, a rich set of XUL and XHTML components and a markup language called ZUML (ZK User Interface Markup Language).

With ZK, you represent your application in feature-rich XUL and XHTML components and manipulate them upon events triggered by user's activity, similar to what is done in desktop applications. Unlike most of other AJAX frameworks, as far as ZK is concerned, AJAX is a behind-the-scene technology. The synchronization of component content and the pipelining of events are done automatically by the ZK engine.

Your users get the same engaging interactivity and responsiveness of the desktop application, while your development retains the simplicity of developing desktop applications.

In addition to a simple model and rich components ZK also supports a markup language called ZUML. ZUML, like XHTML, enables developers to design user interfaces without programming. With XML namespaces, ZUML seamlessly integrates different set of tags^[2] into the same page. Currently ZUML supports two set of tags, XUL and HTML.

For fast prototyping and customization ZUML allows developers to embed EL expressions, and scripting codes in your favorite languages including but not limited to: Java^[3], JavaScript^[4], Ruby^[5] and Groovy^[6]. Developers could choose not to embed any scripting codes at all if they prefer a more rigid discipline. Unlike JavaScript embedded in HTML, ZK executes all embedded scripting code on the server.

It is interesting to note that everything running at the server is from the viewpoint of the application developers. Component developers have to balance the interactivity and simplicity by deciding what tasks will done at the browser and what tasks will be done at the server.

ZK assumes nothing about persistence or inter-server communication. ZK is designed to be as thin as possible. It is only aimed at the presentation tier. It does not require or suggest any other back-end technologies. All of your favorite middleware technologies such as: JDBC, Hibernate, Java Mail, EJB or JMS work as they used to.

ZK doesn't provide a tunnel, RMI or other API for developers to communicate between clients and servers. This is because all code runs at the server within the same JVM.

ZK doesn't enforce developers to use MVC or other design patterns. Whether to use them is the developer's choice.

ZK is not a framework aiming to bring XUL to Web applications. It is aimed to bring the desktop programming model to Web applications. Currently, it supports XUL and XHTML, in future it might support XAML, XQuery and others.

ZK embeds AJAX in the current implementation but it doesn't end in where AJAX does. With ZK API for Mobile devices, your applications could reach any devices that support J2ME such as: PDA, mobiles and game consoles. Moreover, you don't need to modify your application at all^[7].

ZK is not for applications that run most of tasks at the clients, such as 3D action games.

Unless you write a special component, ZK is not for applications that want to leverage the computing power at the clients.

After ZK is installed into your favorite Web server^[8], writing applications is straight forward. Just create a file, say hello.zul, as follows^[9] under a proper directory.

<window title="Hello" border="normal">
    Hello World!    
</window>

Then, browse to the right URL, say http://localhost/myapp/hello.zul, and you got it.

In a ZUML page, a XML element describes what component to create. In this example, it is a window (org.zkoss.zul.Window). The XML attributes are used to assign values to properties of the window component. In this example, it creates a window with a title and border, which is done by setting the title and border properties to "Hello" and "normal", respectively.

The text enclosed in the XML elements is also interpreted as a special component called label (org.zkoss.zul.Label). Thus, the above example is equivalent to the following.

<window title="Hello" border="normal">
    <label value="Hello World!"/>    
</window>

Also, it is equivalent to

<window title="Hello" border="normal">
    <label>Hello World!"</label>    
</window>

Let us put some interactivity into it.

<window title="Hello" border="normal">
    <button label="Say Hello" onClick="alert(&quot;Hello World!&quot;)"/>    
</window>

Then, when you click the button, you see as follows.

The onClick attribute is a special attribute used to add an event listener to the component. The attribute value could be any legal Java codes. Notice that we use " to denote the double quot (") to make it a legal XML document. If you are not familiar with XML, you might take a look at the XML section in the ZK User Interface Markup Language chapter.

The alert function is a global function to display a message dialog box. It is a shortcut to one of the show methods of the org.zkoss.zul.Messagebox class.

<button label="Say Hello" onClick="Messagebox.show(&quot;Hello World!&quot;)"/>

Notes:

The zscript element is a special element to define the scripting codes that will be evaluated when a ZUML page is rendered. Typical use includes initialization and declaring global variables and methods.

Note: You cannot use EL expressions in zscript codes.

For example, the following example displays a different message each time the button is pressed.

<window title="Hello" border="normal">
    <button label="Say Hello" onClick="sayHello()"/>    
    <zscript>    
    int count = 0;    
    void sayHello() { //declare a global function    
        alert("Hello World! "+ ++count);        
    }    
    </zscript>    
</window>

Note: zscript is evaluated only once when the page is loaded. It is usually used to define methods and initial variables.

<zscript language="javascript">
    alert('Say Hi in JavaScript');    
    new Label("Hi, JavaScript!").setParent(win);    
</zscript>

<button onClick="javascript: do_something_in_js();"/>

<window title="Hello" border="normal">
    <button label="Say Hello" onClick="sayHello()"/>    
    <zscript src="sayHello.zs"/>    
</window>

int count = 0;
void sayHello() { //declare a global function
    alert("Hello World! "+ ++count);    
}

The attribute element is a special element to define a XML attribute of the enclosing element. With proper use, it makes the page more readable. The following is equivalent to hello.zul described above.

<button label="Say Hello">
     <attribute name="onClick">alert("Hello World!");</attribute>    
</button>

You can control whether to omit the leading and trailing whitespaces of the attribute value by use of the trim attribute as follows. By default, no trim at all.

<button>
    <attribute name="label" trim="true">    
        The leading and trailing whitespaces will be omitted.        
    </attribute>    
</button>

Like JSP, you could use EL expressions in any part of ZUML pages, except the names of attributes, elements and processing instructions.

EL expressions use the syntax ${expr}. For example,

<element attr1=”${bean.property}”.../>
${map[entry]}
<another-element>${3+counter} is ${empty map}</another-element>

Tip: empty is an operator used to test whether a map, a collection, an array or a string is null or empty.

Tip: map[entry] is a way to access an element of a map. In other words, it is the same as map.get(entry) in Java.

When an EL expression is used as an attribute value, it could return any kind of objects as long as the component accepts it. For example, the following expression will be evaluated to a Boolean object.

<window if="${some > 10}">

Tip: The + operator in EL is arithmetic. It doesn't handle string catenations. If you want to catenate strings, simple use "${expr1} is added with ${expr2}".

Standard implicit objects, such as param and requestScope, and ZK implicit objects, such as self and page, are supported to simplify the use.

<textbox value="${param.who} does ${param.what}"/>

To import a method, you can use a processing instruction called the xel-method as follows.

<?xel-method prefix="c" name="forName"
    class="java.lang.Class"    
    signature="java.lang.Class forName(java.lang.String)"?>    
<textbox value="${c:forName('java.util.List')}"/>

To import EL functions from TLD files, you could use a processing instruction called taglib as follows.

<?taglib uri="http://www.zkoss.org/dsp/web/core" prefix="c" ?>

The Developer's Reference provides more details on EL expressions. Or, you might refer to JSP 2.0 tutorials or guides for more information about EL expressions.

To access a component in Java codes and EL expressions, you could assign an identifier to it by use of the id attribute. In the following example, we set an identifier to a label such that we could manipulate its value when one of the buttons is pressed.

<window title="Vote" border="normal">
    Do you like ZK? <label id="label"/>    
    <separator/>    
    <button label="Yes" onClick="label.value = self.label"/>    
    <button label="No" onClick="label.value = self.label"/>    
</window>

After pressing the Yes button, you will see the following.

The following is any example for referencing a component in an EL expression.

<textbox id="source" value="ABC"/>
<label value="${source.value}"/>

The if and unless attributes are used to control whether to create a component. In the following examples, both labels are created only if the request has a parameter called vote.

<label value="Vote 1" if="${param.vote}"/>
<label value="Vote 2" unless="${!param.vote}"/>

If both attributes are specified, the component won't be created unless they are both evaluated to true.

The forEach attribute is used to control how many components shall be created. If you specify a collection of objects to this attribute, ZK Loader will create a component for each item of the specified collection. For example, in the following ZUML page, the listitem element will evaluated three times (for "Monday", "Tuesday" and "Wednesday") and then generate three list items.

<zscript>contacts = new String[] {"Monday", "Tuesday", "Wednesday"};</zscript>
<listbox>
<listitem label="${each}" forEach="${contacts}"/>
</listbox>

When evaluating the element with the forEach attribute, the each variable is assigned one-by-one with objects from the collection, i.e., contacts in the previous example. Thus, the above ZUML page is the same as follows.

<listbox>
<listitem label="Monday"/>
<listitem label="Tuesday"/>
<listitem label="Wednesday"/>
</listbox>

Alternatively, you can specify a list of items in the forEach attribute by separating them with comma.

<listbox>
<listitem label="${each}" forEach="Monday, Tuesday, Wednesday"/>
</listbox>

In additions to forEach, you can control the iteration with forEachBegin and forEachEnd. Refer to the ZK Attributes section in the ZK User Interface Markup Language chapter for details.

Embedding codes improperly in pages might cause maintenance headache. There are several ways to separate codes from views.

First, you could listen to events you care, and then invoke the proper methods accordingly. For example, you could invoke your methods to initialize, process and cancel upon the onCreate^[10], onOK^[11] and onCancel^[12] events.

<window onCreate="MyManager.init(main)"onOK="MyManager.process(main)" onCancel="MyManager.cancel(main)"/>

In addition, you must have a Java class called MyManager shown as follows.

import org.zkoss.zul.Window;

public class MyManager {
    public static void init(Window main) { //does initialization    
    }    
    public static void save(Window main) { //saves the result    
    }    
    public static void cancel(Window main) { //cancel any changes    
    }    
}

However, the above approach requires you to embed some codes in the ZUML pages. The advantage of embedding codes in UI is easy to change the behavior dynamically (particularly in the prototype phase), but it still reveals some maintenance codes and the performance is bit slower^[13].

import org.zkoss.zul.Window;

public class MyWindow extends Window {
    public void onCreate() { //does initialization    
    }    
    public void onOK() { //save the result    
    }    
    public void onCancel() { //cancel any changes    
    }    
}

<window use="MyWindow">
    ...    
</window>

import org.zkoss.zk.ui.util.Composer;
import org.zkoss.zul.Window;
public class MyComposer implements Composer {
    public void doAfterCompose(Component comp) {    
        ((Window)comp).setTitle("My Title"); //do whatever initialization you want        
            //comp is Window since we will specify it to a window later            
    }    
}

<window apply="MyComposer">
...
</window>

<window apply="MyComposer, AnotherComposer">
    <textbox apply="${c:mycomposer()}"/>    
</window>

<window use="MyWindow">
    ...    
    <button label="OK"/>    
    <button label="Cancel"/>    
</window>

<window use="MyWindow">
    ...    
    <button label="OK" forward="onOK"/>    
    <button label="Cancel" forward="onCancel"/>    
</window>

public class MyWindow extends Window {
    public void onOK() {    
        //called when the OK button is clicked (or the ENTER button is pressed)        
    }    
    public void onCancel() {    
        //called when the Cancel button is clicked (or the ESC button is pressed)        
    }    
}

<zscript>
    public class MyWindow extends Window {    
    }    
</zscript>
<window use="MyWindow"/>

<zscript src="/zs/mywnd.zs"/>
<window use="MyWindow"/>

In addition to describe what components to create in ZUML pages, developers could create them manually. All component classes are concrete. You create them directly^[15] with their constructors.

<window id="main">
    <button label="Add Item">    
        <attribute name="onClick">        
    new Label("Added at "+new Date()).setParent(main);    
    new Separator().setParent(main);    
        </attribute>        
    </button>    
    <separator bar="true"/>    
</window>

When a component is created manually, it won't be added to any page automatically. In other words, it doesn't appear at user's browser. To add it to a page, you could invoke the setParent, appendChild or insertBefore method to assign a parent to it, and it becomes a part of a page if the parent is a part of a page.

There is no destroy or close method for components^[16]. A component is removed from the browser as soon as it is detached from the page. It is shown as soon as it is attached to the page.

<window id="main">
    <zscript>Component detached = null;</zscript>    
    <button id="btn" label="Detach">    
        <attribute name="onClick">        
    if(detached != null) {    
        detached.setParent(main);        
        detached = null;        
        btn.label = "Detach";        
    } else {    
        (detached = target).setParent(null);        
        btn.label = "Attach";        
    }    
        </attribute>        
    </button>    
    <separator bar="true"/>    
    <label id="target" value="You see this if it is attached."/>    
</window>

In the above example, you could use the setVisible method to have a similar effect. However, setVisible(false) doesn't remove the component from the browser. It just makes a component (and all its children) invisible.

After a component is detached from a page, the memory it occupies is release by JVM's garbage collector if the application has no reference to it.

import org.zkoss.zul.*;
public class TestRichlet extends org.zkoss.zk.ui.GenericRichlet {
    public void service(Page page) {    
        page.setTitle("Richlet Test");        

        final Window w = new Window("Richlet Test", "normal", false);        
        new Label("Hello World!").setParent(w);        
        final Label l = new Label();        
        l.setParent(w);        
        //...        
        w.setPage(page);        
    }    
}

As illustrated, it is simple to assign properties to a component by use of XML attributes.

<button label="OK" style="border:1px solid blue"/>

ZK provides a powerful yet simple way to let developers define new components for a particular pages. It is useful if most components of the same type share a set of properties.

First, you use the component directive to define a new component.

<?component name="bluebutton" extends="button" style="border:1px solid blue" label="OK"?>

<bluebutton/>
<bluebutton label="Cancel"/>

is equivalent to

<bluebutton style="border:1px solid blue" label="OK"/>
<bluebutton style="border:1px solid blue" label="Cancel"/>

Moreover, you can override the definition of button altogether as follows. Of course, it won't affect any other pages.

<?component name="button" extends="button" style="border:1px solid blue" label="OK"?>

<button/>
<button label="Cancel"/>

For more information, refer to the component Directive section in the ZK User Interface Markup Language chapter.

ZK includes an AJAX-based mechanism to automate interactivity, a rich set of XUL-based components to enrich usability, and a markup language to simplify development.

The AJAX-based mechanism consists of three parts as depicted below: ZK loader, ZK AU Engine^[17] and ZK Client Engine.

Based on the user's request, the ZK Loader loads a ZK page, interprets it, and renders the result into HTML pages in response to URL requests. A ZK page is written in a markup language called ZUML. ZUML, like HTML, is used to describe what components to create and how to represent them visually. These components, once created, remain available until the session is timeout.

The ZK AU^[18] Engine and the ZK Client Engine then work together as pitcher and catcher. They deliver events happening in the browser to the application running at the server, and update the DOM tree at the browser based on how components are manipulated by the application. This is so-called event-driven programming model.

It is common to decompose a visual presentation into several ZUML pages. For example, a page for displaying a purchase order, and a modal dialog for entering the payment term. If all components are uniquely identifiable in the same desktop, developers have to maintain the uniqueness of all identifiers for all pages that might created to the same desktop.

The concept of ID spaces is then introduced to resolved this issue. An ID space is a subset of components of a desktop. The uniqueness is guaranteed only in the scope of an ID space.

The simplest form of an ID space is a window (org.zkoss.zul.Window). All descendant components of a window (including the window itself) forms an independent ID space. Thus, you could use a window as the topmost component of each page, such that developers need to maintain the uniqueness of each page separately.

More generally, any component could form an ID space as long as it implements the org.zkoss.zk.ui.IdSpace interface. Page also implements the IdSpace interface, so it is also a space owner.

The topmost component of an ID space is called the owner of the ID space, which could be retrieved by the getSpaceOwner method in the Component interface.

If an ID space, say X, is a descendant of another ID space, say Y, then space X's owner is part of space Y but descendants of X is not part of space Y.

As depicted in the figure, there are three spaces: P, A and C. Space P includes P, A, F and G. Space A includes A, B, C and D. Space C includes C and E.

Components in the same ID spaces are called fellows. For example, A, B, C and D are fellows of the same ID space.

To retrieve another fellow, you could use the getFellow method in the IdSpace interface or the Component interface.

Notice that the getFellow method can be invoked against any components in the same ID space, not just the space owner. Similarly, the getSpaceOwner method returns the same object for any components in the same ID space, no matter it is the space owner or not.

The org.zkoss.zk.ui.Path class provides utilities to simplify the location of a component among ID spaces. Its use is similar to java.io.File.

Path.getComponent("/A/C/E");

new Path("A/C", "E").getComponent();

Namespace and ID Space

To let the interpreter able to access the components directly, the namespace concept (org.zkoss.scripting.Namespace) is introduced. First, each ID space has exactly one namespace. Second, variables defined in a namespace are visible to the scripting codes and EL expressions that belong to the same namespace.

<window border="normal">
    <label id="l" value="hi"/>    
    <zscript>    
        l.value = "Hi, namespace";        
    </zscript>    
    ${l.value}    
</window>

In the following example, there are two namspaces. One belongs to window w1 and the other to window w2^[24]. Thus, the b1 button's onClick script refers to the label defined in window w1, while the b2 button's onClick script refers to the checkbox defined in window w2.

<window id="w1">
    <window id="w2">    
        <label id="c"/>        
        <button id="b1" onClick="c.value = &quot;OK&quot;"/>        
    </window>    
    <checkbox id="c"/>    
    <button id="b2" onClick="c.label = &quot;OK&quot;"/>    
</window>

Notice the namespace is hierarchical. In other words, zscript in window w2 can see components in window w1, unless it is overridden in window w2. Thus, clicking button b1 will change label c in the following example.

<window id="w1">
    <window id="w2">    
        <button id="b1" onClick="c.value = &quot;OK&quot;"/>        
    </window>    
    <label id="c"/>    
</window>

In addition to ZK's assigning components to the namespace, you can assign your variables to them by use of the setVariable method, such that zscript can reference them directly.

<window id="A>
    <zscript>    
        Object myvar = new LinkedList();        
        void myfunc() {        
            ...            
        }        
    </zscript>    
    ...    
    <button label="add" onClick="myvar.add(some)"/>    
    <button label="some" onClick="myfunc()"/>    
</window>

<window>
    <zscript>    
    String var = "abc";    
    self.setVariable("var2", "xyz", true);    
    </zscript>    
    ${var} ${var2}    
</window>

<window>
abc xyz
</window>

<window>
    <zscript>    
    String var = "abc";    
    self.setVariable("var", "xyz", true);    
    </zscript>    
    ${var}    
</window>

<window>
abc
</window>

<window>
    <zscript>    
    String var = "abc";    
    </zscript>    
    <label id="var" value="A label"/>    
    ${var.value} <!-- Wrong! var is "abc", not the label -->    
</window>

<zscript>
Date now = new Date();
</zscript>

<zscript>
{ //create a new logic scope
    String var = "abc"; //visible only inside of the enclosing curly brace    
}
</zscript>

<window id="A">
    <zscript>var1 = "abc";</zscript>    
    <window id="B">    
        <zscript>var2 = "def";</zscript>        
    </window>    
</window>

<window id="A">
    <window id="B">    
        <zscript>        
    String b = "local to window B";    
        </zscript>        
    </window>    
</window>

<window id="A">
    <zscript>    
    var1 = var2 = "abc";    
    </zscript>    
    <window id="B">    
        <zscript>        
    Object var1 = "123";    
    var2 = "def";    
    var3 = "xyz";    
        </zscript>        
    </window>    
    ${var1} ${var2} ${var3}    
</window>

<zscript language="Java">
    var1 = 123;    
</zscript>
<zscript language="JavaScript">
    var2 = 234;    
</zscript>

<zscript>
    var1 = 123; //var1 belongs to the interpreter, not any namespace    
    page.getVariable("var1"); //returns null    
</zscript>

page.getInterpreter("JavaScript").getVariable("some"); //interpreter for JavaScript
page.getInterpreter(null).getVariable("some"); //interpreter for default language

An event (org.zkoss.zk.ui.event.Event) is used to notify application what happens. Each type of event is represented by a distinct class. For example, org.zkoss.zk.ui.event.MouseEvent denotes a mouse activity, such as clicking.

To response to an event, an application must register one or more event listeners to it. There are two ways to register an event listener. One is by specifying the onXxx attribute in the markup language. The other is by calling the addEventListener method for the component or the page you want to listen.

In addition to event triggered by user's activity at the browser, an application could fire events by use of the sendEvent, postEvent and echoEvent methods from the org.zkoss.zk.ui.event.Events class.

As mentioned above, a desktop is a collection of pages for serving the same URL request. A desktop is also the scope that an event listener could access.

When an event is fired, it is associate with a desktop. ZK separates events based on the associated desktops, and pipelines events into separated queues. Therefore, events for the same desktop are processed sequentially. On the other hand, events for different desktops are processed in parallel.

An event listener is allowed to access any components of any pages of the desktop associated with the event. It is also allowed to moving components from one page to another as long as they are in the same desktop. On the other hand, it cannot access components belonging to other desktops.

Note: Developers can detach a component from one desktop in one event listener, and then attach it to another desktop in other event listener.

The ZK User Interface Markup Language (ZUML) is a XML-based language used by developers to describe the visual presentation. ZUML is aimed to separate the dependency of the set of components to use. In other words, different set of components^[28], such as XUL and XHTML, could be used simultaneously in the same ZUML page. Different markup languages could be added transparently. If two or more set of components are used in the same page, developers have to use the XML namespaces to distinguish them. Refer to the Component Sets and XML Namespaces section in the ZK User Interface Markup Language chapter if you want to mix multiple component sets, say XUL and XHTML, in the same page.

Tip: Using XML namespaces in ZUML is optional. You need it only if you want to mix two or more.

It takes four phases for ZK loaders to load and interpret a ZUML page: the Page Initial Phase, the Component Creation Phase, the Event Processing Phase, and the Rendering Phase.

<?init class="MyInit"?>

<?init zscript="/my/init.zs"?>

It takes three phases for ZK AU Engine to process the ZK requests sent from the clients: the Request Processing Phase, the Event Processing Phase, and the Rendering Phase.

ZK AU Engine pipelines ZK requests into queues on a basis of one queue per desktop. Therefore, requests for the same desktop are processed sequentially. Requests for different desktops are processed in parallel.

A component could have different appearance even at the same page. The concept is called mold (aka., template). Developers could dynamically change the mold by use of the setMold method in the Component interface. All components support a mold called default, which is the default value. Some components might have support two or more molds For example, tabbox supports both default and accordion molds.

<tabbox><!-- if not specified, the default mold is assumed. -->
    <tabs>    
        <tab label="Default"/>        
    </tabs>    
    <tabpanels>    
        <tabpanel>        
        <tabbox mold="accordion">        
            <tabs>            
                <tab label="First Accordion"/>                
                <tab label="Second Accordion"/>                
            </tabs>            
            <tabpanels>            
                <tabpanel>The first panel.</tabpanel>                
                <tabpanel>The second panel.</tabpanel>                
            </tabpanels>            
        </tabbox>        
        </tabpanel>        
    </tabpanels>    
</tabbox>

Unlike many component-based GUI, ZK has no destroy or close method for components. Like W3C DOM, a component is removed from the browser as soon as it is detached from the page. It is shown as soon as it is attached to the page.

More precisely, once a component is detached from a page, it is no longer managed by ZK. If the application doesn't have any reference to it. The memory occupied by the component will be released by JVM's Garbage Collector.

The simplest way to add an event listener is to declare an attribute in a ZUML page. The value of the attribute for listening an event is any Java codes that could be interpreted by BeanShell.

<window title="Hello" border="normal">
    <button label="Say Hello" onClick="alert(&quot;Hello World!&quot;)"/>    
</window>

There are two ways to add event listeners by program.

<window use="MyWindow">
...
</window>

public class MyWindow extends org.zkoss.zul.Window {
    public void onOK() { //add an event listener    
        ...//handles the onOK event (sent when ENTER is pressed)        
    }    
}

public void onOK(org.zkoss.zk.ui.event.KeyEvent event) {...}

public void onOK(org.zkoss.zk.ui.event.Event event) {...}

void init(Component comp) {
    ...    
    comp.addEventListener("onClick", new MyListener());    
    ...    
}
class MyListener implements org.zkoss.zk.ui.event.EventListener {
    public void onEvent(Event event) throws UiException {    
        ...//processing the event        
    }    
}

public class DeferrableListener implements EventListener, Deferrable {
    private boolean _modified;    
    public void onEvent(Event event) {    
        _modified = true;        
    }    
    public boolean isDeferrable() {    
        return true;        
    }    
}

public class ModificationListener implements EventListener, Deferrable {
    private final Window _owner;    
    private final Page _page;    
    private boolean _modified;    

    public ModificationListener(Window owner) {    
        //Note: we have to remember the page because unregister might        
        //be called after the owner is detached        
        _owner = owner;        
        _page = owner.getPage();        
        _page.addEventListener("onChange", this);        
        _page.addEventListener("onSelect", this);        
        _page.addEventListener("onCheck", this);        
    }    
    /** Called to unregister the event listener.    
     */    
    public void unregister() {    
        _page.removeEventListener("onChange", this);        
        _page.removeEventListener("onSelect", this);        
        _page.removeEventListener("onCheck", this);        
    }    
    /** Returns whether the modified flag is set.    
     */    
    public boolean isModified() {    
        return _modified;        
    }    
    //-- EventListener --//    
    public void onEvent(Event event) throws UiException {    
        _modified = true;        
    }    
    //-- Deferrable --//    
    public boolean isDeferrable() {    
        return true;        
    }    
}

In addition to receiving events, an application could communicate among event listeners by posting or sending events to them.

<window id="w" title="Test echoEvent">
    <attribute name="onLater">    
    Thread.sleep(2000);    
    Clients.showBusy(null, false);    
    new Label("Done.").setParent(w);    
    </attribute>    

    <button label="echo">    
    <attribute name="onClick">    
    Clients.showBusy("Execute...", true);    
    Events.echoEvent("onLater", w, null);    
    </attribute>    
    </button>    
</window>

For each desktop, events are processed sequentially, so thread model is simple. Like developing desktop applications, you don't need to worry about racing and multi-threading. All you need to do is to register an event listener and process the event when invoked.

Tip: Each event listener executes in an independent thread called event processing thread, while the ZUML page is evaluated in the servlet thread.

Tip: The use of the event processing thread can be disabled such that all events are processed in the Servlet threads. It has a little bit better performance and less integration issues. However, you can not suspend the execution. Refer to the Use the Servlet Thread to Process Events section in the Advanced Features chapter.

public void doModal() throws InterruptedException {
    ...Executions.wait(_mutex); //suspend this thread, an event processing thread}    
public void endModal() {
...
    Executions.notify(_mutex); //resume the suspended event processing thread    
}

//Thread 1
public void request() {
    ...    
    synchronized (mutex) {    
        ...//start another thread        
        Executions.wait(mutex); //wait for its completion        
    }    
}

//Thread 2
public void process() {
    ... //process it asynchronously    
    synchronized