ZK Developer's Guide

In this phase, the page is initialized. To control this phase, it is possible to define a class or zscript for that phase.

Following is an example of defining a class for the init sequence:

<?init class="sample.InitSample" ?>

In the above example, the InitSample class from sample package is used. This class has to implement the org.zkoss.zk.util.util.Initiator interface.

The second way is to define a zscript for the init sequence:

<?init zscript="/init/init-sample.zs" ?>

<?init class="sample.InitSample" ?>

<zscript><![
CDATA[
import sample.InitSample;
]]>
</zscript>

<zscript><![
CDATA[
import sample.InitSample;
System.out.println(InitSample.class);
]]>
</zscript>

package sample;
import org.zkoss.zk.ui.Page;
import org.zkoss.zk.ui.util.Initiator;
public class InitSample implements Initiator
{
public void doAfterCompose(Page page) throws Exception
{
System.out.println("doAfterCompose");
}
public void doInit(Page page, Object[] args) throws Exception
{
System.out.println("doInit");
}
public void doCatch(Throwable throwable)
{
}
public void doFinally()
{
}
}

In this phase, the ZK loader is responsible for the interpretation of the pages. The components of each page are created and initialized.

The following steps are performed in this phase:

Composing Phase

Step 1: Before the creation and initialization is started, the optional values of if and unless attributes are evaluated (<window if="expression" /> or<window unless="expression" />). With these attributes it's possible to control the layout depending on some conditions.

Step 2: The component is created. In the case of specification of the use attribute (<window use="MyClass" />) the specified class is used to create the component. Otherwise the component is created based on the name. After that the members are initialized.

Step 3: The nested elements are interpreted.

After the Composing Phase

Step 4: If the component implements the org.zkoss.zk.ui.ext.AfterCompose interface, afterCompose() is called.

Step 5: After the creation of all children the event onCreate is send to the created component.

<zscript><![
CDATA[
elements = new String[] {"ZK", "AJAX", "FRAMEWORK"};
]]>
</zscript>
<listbox width="200px">
<listitem label="${each}" forEach="${elements}"/>
</listbox>

For each event that is queued, the event listeners are called in a thread. The processing of other events is not affected by the processing of code of a single event listener.

The last stage is to compose from all components one single HTML page. For the rendering of a component redraw() is called.

The lifecycle of updating a ZK page consists of three phases. These phases are illustrated in the diagram below:

The ZK Asynchronous Update Engine updates the appropriate components.

This is the same as the event processing on creation of a page.

ZK renders the affected components. The Client Engine updates the DOM tree on the browser on the basis of the ZK responses.

An interesting point in the processing of events is the sequence in which the events are processed. For the explanation, we assume that the onSelect event is sent and received.

First Step: All event listeners for the onSelect event for the targeting component are invoked that implement the marker interface org.zkoss.zk.ui.event.Express.

Second Step: Now the script for the onSelect attribute for the target component is executed. It's notable that if we don't have an event listener that implements org.zkoss.zk.ui.event.Express then the event listener in the first attribute is executed.

Third Step: Now all event listeners of the targeting component that do not implement the mentioned org.zkoss.ui.event.Express interface are executed.

Fourth Step: If the targeting component has an onSelect method it will be executed.

Fifth Step: All event listeners for the onSelect event that are registered to the parent page of the target component are executed.

We mentioned before that requests to one desktop are done in a sequence. Therefore, if one event listener is processing its instructions then all other event listeners for that desktop are blocked. There is no problem if we only have short instructions, but in the case of long instructions we come across the problem that it's not acceptable to wait.

For better illustration, we will provide a small example. First we have to implement a thread, which will do the work asynchronously. This thread is an implementation of the java.lang.Thread.

package sample.thread;
public class SampleWorkingThread extends Thread
{
private static int counter;
private Desktop desktop;
private Label label;
//Mutex variable for synchronization
private final Object mutex = new Integer(0);
/** Called by thread.zul to create a label asynchronously.
* To create a label, it starts a thread, and waits for its
completion.
*/
public static final Label asyncCreate(final Desktop desktop) throws
InterruptedException
{
//Create a new instance of the working thread
final SampleWorkingThread worker = new
SampleWorkingThread(desktop);
synchronized (worker.mutex)
{
worker.start();
//Suspend the thread
Executions.wait(worker.mutex);
return worker.label;
}
}
/**
* Implementation of the standard run method from java.lang.Thread.
*/
public void run()
{
++this.counter;
this.label = new Label("Execute, counter : " + counter);
synchronized (this.mutex)
{
//Proceed working of threads which are suspend with mutex
Executions.notify(this.desktop, this.mutex);
}
}
/**
* Constructor.
*
* @param desktop The reference to the acutal desktop instance.
*/
public WorkingThread(final Desktop desktop)
{
this.desktop = desktop;
}
}

Now we have to provide a ZUL page that starts the thread.

<window id="main" title="A Sample for a working Thread">
<button label="Start the thread">
<attribute name="onClick">
timer.start();
Label label = sample.thread.SampleWorkingThread
.asyncCreate(desktop);
main.appendChild(label);
timer.stop()
</attribute>
</button>
<timer id="timer" running="false" delay="1000" repeats="true"/>
</window>

When the user clicks on the button Start the thread, the thread starts doing the work asynchronously.

One important thread in a ZK application is the event processing thread. In this thread an event listener is processed.

Sometimes there is a demand to initialize or clean up the thread. For this we have the org.zkoss.zk.ui.event.EventThreadInit-interface. This interface has the method init(Component, Event) which must be implemented (and the prepare method). To register the listener it's necessary to make an entry in WEB-INF/zk.xml.

<zk>
<listener>
<listener-class>sample.SampleEventThreadInit</listener-class>
</listener>
</zk>

For cleanup there is the org.zkoss.zk.ui.event.EventThreadCleanup interface. Here, we have to implement the cleanup(Component, Event, List)method; additionally we also have to implement the complete method. The last parameter for the method cleanup is a list of exceptions that occur before the method is executed. To register the listener it's necessary to make an entry in WEB-INF/zk.xml.

<zk>
<listener>
<listener-class>sample.SampleEventThreadCleanup</listener-class>
</listener>
</zk>

An example implementation of such a listener is shown in Appendix A.

Until now we have used ZUML, but we haven't really explained what ZUML is and how to use it. The next section should you give some idea about working with ZUML. Before we start, it's important to note that the next section is not a reference for ZUML, it's just a guide to help in the development of a ZUML page.

The following event types exist in ZK:

It depends on the component whether an event is supported or not. It's noteworthy to say that an event is sent after the content of the component is updated.

A mold is an attribute that is used to customize pages in ZK. The org.zkoss.zk.ui.Component interface has the setMold method. If there isn't a mold defined; the mold with the name default is used.

Some components come with more than the default mold. For example, groupbox (represented by the class org.zkoss.zul.Groupbox) has the default and 3d molds.

To use the default mold nothing special is necessary.

<groupbox open="true" width="250px">
<caption label="Title of the group box"></caption>
</groupbox>

To use the 3d mold we have to specify the mold attribute.

<groupbox mold="3d" open="true" width="250px">
<caption label="Title of the group box"></caption>
</groupbox>

Beyond the normal attributes of elements (for example: width) there are some special attributes, which are called ZK Attributes.

<window use="sample.SampleWindow" />

<textbox if="${b==1}" />

<textbox unless="${c==1}" />

<listitem label="${each}" forEach="${elements}" />

<listitem label="${each}" forEach="${elements}"
forEachBegin="1" />

<listitem label="${each}" forEach="${elements}"
forEachEnd="1" />

There are special elements that aren't responsible for creating components, the so called ZK Elements. The task of these elements is to control a ZUML page.

The following is a list of ZK Elements:

The zk element is an element for grouping other components. Important at this juncture is that the zk element gets no member in the component tree.

Sample:

<window>
<zk>
<button id="buttonToSayHello" label="Say Hello" />
<button id="buttonToSayHelloAgain" label="Say Hello Again" />
</zk>
</window>

For layout and component tree, it's same as having no zk element.

A good question could be why to use the zk element. One important reason is that in a XML document there can be only one root element. And therefore, if we want to have more root elements (for example, more than one window) then we can use a zk element as root.

Another area of application is the possibility of iterating over components, or conditional evaluation. For that zk elements supports the following attributes:

A small example of usage is as follows:

<window>
<zk forEach="${element}">
<label value="${element.name}" />
<button id="buttonToSayHello" label="Say Hello"
if="${element.showSayHello}" />
<button id="buttonNotToSayHello" label="Say not Hello"
unless="${element.showSayHello}" />
</zk>
</window>

The zscript element is used for embedding Java code into ZUML pages. At the time of page evaluation the code will be interpreted by the BeanShell (http://www.beanshell.org). It's possible to embed Java code directly between the opening and closing zscript tags. Another way is to use the src attribute of the zscript element. In this attribute, you could specify a URI to a file, which contains the Java code. The zscript element supports conditional evaluation with the help of the if and unless attributes.

The attribute element defines an attribute of the enclosing element. We have used this ZK Element in the "Hello World" example.

<textbox width="60%" id="username">
<attribute name="onChanging">
...
</attribute>
</textbox>

One area of application is event listeners. The attribute element supports conditional evaluation with if and unless, too.

The custom-attributes element is used to define an object in a special scope (for example, page scope).

An example for defining a custom-attributes element is as follows:

<window>
<custom-attributes test="simple" />
</window>

This is the same as:

<window>
<zscript>
self.setAttribute("test", "simple");
</zscript>
</window>

It's possible to use the scope attribute:

<window>
<custom-attributes test="simple" scope="desktop" />
</window>

This is the same as:

<window>
<zscript>
desktop.setAttribute("test", "simple");
</zscript>
</window>

The custom-attributes element supports conditional evaluation with if and unless, too.

If we talk about UI, we have to talk about the layout of the pages. There are some elements that help you in the layout of a ZK page.

Some important elements are:

An example for using div and vbox elements is as follows:

<div align="center" style="vertical-align:center">
<vbox>
<groupbox mold="3d" open="true" width="250px">
<caption label="testbox"></caption>
<radiogroup id="master">
<radio label="Apple"/>
<radio label="Orange"/>
<radio label="Banana"/>
</radiogroup>
</groupbox>
<groupbox mold="3d" open="true" width="250px">
<caption label="another testbox"></caption>
<radiogroup id="client">
<radio label="Apple"/>
<radio label="Orange"/>
<radio label="Banana"/>
</radiogroup>
</groupbox>
</vbox>
</div>

The following screenshot shows the layout.

Instead of using the layout control it's possible to do the layout with a XHTML, and using Cascading Stylesheets (see Chapter 6: Creating Custom Components).

One important paradigm in object-oriented programming is Separation of Concerns (SoC). This paradigm says that an application should be broken into distinct features that overlap in functionality as little as possible (see http://en.wikipedia.org/wiki/Separation_of_concerns).

For large applications, it's not advisable to do the layout, and the logic together in one page. For such applications, you should follow the programming principle of separation of concerns. This separation is not only for architecture, but also for better maintenance of your application. This is because if you have your logic directly in Java classes, you can leverage the full power of your IDE, e.g. you can have a good debugger, and you can easily write unit tests.

If you like to work with Maven (http://maven.apache.org) it takes a little bit more effort. This is because of the rapid rate of releases in ZK; sometimes the Maven repositories have a bit of a delay in publishing. The most famous Maven repositories include the ZK framework, i.e. http://repo1.maven.org/maven2. The structure of the ZK framework in a Maven repository looks like:

As the illustration shows the ZK framework within the Maven repository has three different groupIDs:

The artifacts zcommon and zweb are common. The second group contains the artifacts of the ZK framework itself, and the last contains the additional tools like FCKEZ. See the complete part of the POM.XML for the deployment of ZK in a Maven project:

<dependency>
<groupId>org.zkoss.common</groupId>
<artifactId>zcommon</artifactId>
<version>2.3.0</version>
</dependency>
<dependency>
<groupId>org.zkoss.common</groupId>
<artifactId>zweb</artifactId>
<version>2.3.0</version>
</dependency>
<dependency>
<groupId>org.zkoss.zk</groupId>
<artifactId>zk</artifactId>
<version>2.3.0</version>
</dependency>
<dependency>
<groupId>org.zkoss.zk</groupId>
<artifactId>zul</artifactId>
<version>2.3.0</version>
</dependency>
<dependency>
<groupId>org.zkoss.zk</groupId>
<artifactId>zhtml</artifactId>
<version>2.3.0</version>
</dependency>
<dependency>
<groupId>org.zkoss.zk</groupId>
<artifactId>zkplus</artifactId>
<version>2.3.0</version>
</dependency>
<dependency>
<groupId>org.zkoss.zkforge</groupId>
<artifactId>gmapsz</artifactId>
<version>2.0-2</version>
</dependency>
<dependency>
<groupId>org.zkoss.zkforge</groupId>
<artifactId>fckez</artifactId>
<version>2.3-2</version>
</dependency>
<dependency>
<groupId>org.zkoss.zkforge</groupId>
<artifactId>dojoz</artifactId>
<version>0.2.2-2</version>
</dependency>