New Features of ZK 3.6.1

From Documentation

DocumentationSmall Talks2009AprilNew Features of ZK 3.6.1
New Features of ZK 3.6.1

Robbie Cheng, Evangelist, Potix Corporation
April 28, 2009

The main focus of ZK 3.6.1 was bug-fixing, with over 47 bugs fixed. In addition to the host of bugs eradicated 20 new features have been added, including a debug mode for unit-testing and MVC enhancements!

In the following paragraphs, I'll introduce the most exciting new additions to ZK 3.6.1.

Ease of use

An intuitive way to access the Composer directly

Using ZK 3.6.1, the developer has easier access to the Composer by using a generic variable called ($composer) instead of the Java Class name (eg.$MyComposer).

For example,

<window id="win" apply="MyComposer">
    <grid model="${win$composer.model}"/>

instead of,

<grid model="${win$MyComposer.model}"/>

Developers can define required resources inside the Composer and access them easier.

An easy way to scroll to a specific UI component

ZK 3.6.1 provides an easier way to scroll to a specific UI component within a container. This is achieved by using the Clients.scrollIntoView() function.

In the following example, the vbox will scroll to the T1 label if the user clicks the button.

<div height="100px" width="50px" style="overflow:auto">
		<label value="A"/>
		<label value="B"/>
		<label value="C"/>
		<label value="D"/>
		<label value="E"/>
		<label value="F"/>
		<label value="G"/>
		<label value="H"/>
		<label id="T1" value="I"/>
<button label="scrollToT1" onClick="Clients.scrollIntoView(T1)"/>

Before, Beforescroll.png After, Afterscroll.png

Component reloaded

Datebox format enhancement

Since ZK 3.6.1, the format of datebox supports is enhanced, users can specify hour, and minute. Moreover, more Java format are supported, including yyyy/MM/dd-HH:mm,yyyy/MM/dd-kk:mm, yyyy/MM/dd-K:mm a, and etc.

<datebox format="yyyy/MM/dd HH:mm a" cols="25" />


A way to specify the position of the Popup component

ZK 3.6.1 provides the method, relative position) to specify the position of a popup component. The function's second argument takes a relative position, a list of 11 possible positions are provided below.


The following illustrates the simplicity of usage,

<popup id="pp">
	Here is popup
<button label="before_start" onClick=', "before_start");' />

Upon clicking the button the popup component will appear in the relative position specified. In this case the position is just above the button.


Native namespace support for zkhead

ZK 3.6.1 now provides support for zkhead which allows the user to specify the position of ZK’s default JS and CSS files. This is particularly useful if you want the JS and CSS files loaded in a specific order.

For example,

<html xmlns=""
<title>Native Complete Page</title>
<meta http-equiv="xxx" content="yyy"/>

Databinding enhancements

Using the "load-after" descriptive to delay loading behavior

The Databinding manager will load data from the Model and then supply the UI with the relevant information. This happens before event listener processes, using the load-when descriptive, are loaded. It would be more practical to load the processes defined within the event listener first as the Model is updated by said listeners. It is now possible to implement this by utilizing the descriptive load-after.

	<label id="lb1" value="@{tar.value, load-after=btn.onClick}"/>
        <label id="tar" value="john"/>
	<button id="btn" label="try" onClick='tar.setValue("mary")'/>

Once, user clicks the button, the order of processing is as follows,

  1. The process defined within event listener is executed. (tar.setValue("mary"))
  2. The loading behavior of Databinding is executed. (lbl.value = tar.value)

Using the "save-after" descriptive to delay saving behavior

The Databinding manager will access the UI’s data and pass it to the Model for storage or processing. This happens before event listener processes using the save-when descriptive are loaded. In most cases, this satisfies most developers' requirements as we usually want to retrieve users’ input data before processing it. However, if developers would like to delay the saving of data until after the invocation of the event listener they can utilize the save-after descriptive instead of save-when as follows.

Advanced features

Use the Component ID as a UUID for unit test

For client-side debugging, developers must generate a predictable component id allowing client-side unit testing libraries access to the UI components. This is made easier by ZK 3.6.1 as ZK can now automatically generate UUIDs (Universal Unique Identifiers) by using the component id rather than a randomly generated UUID.

Simply define the following configuration in zk.xml,


Then, the following component's UUID will be _zid_foo.

<textbox id="foo"/>

For more information, please refer to How to Test ZK Application with Selenium

A method of monitoring the generation of children components using the FullComposer

In previous versions methods defined in Composer and ComposerExt were only called when the associated component is generated. It would be more convenient if these methods were also called when their children were generated.

Using ZK 3.6.1 this is now possible by implementing FullComposer. If implemented alongside Composer and ComposerExt, the Composer methods will now be called not only by the top level component, but by its’ children as well.

For example, in the following listing, methods defined in Composer1 will be called while generating not only the div component, but the lb1 and lb2 components as well.

<window border="normal">
	info = "";
	import org.zkoss.zk.ui.metainfo.*;
	import org.zkoss.zk.ui.util.*;
	class Composer1 implements Composer, ComposerExt, FullComposer {
		public void doAfterCompose(Component comp) throws Exception {			
		public ComponentInfo doBeforeCompose(Page page, Component parent,
		ComponentInfo compInfo) throws Exception {			
		public void doBeforeComposeChildren(Component comp) throws Exception {
		public boolean doCatch(Throwable ex) throws Exception {
		public void doFinally() throws Exception {
	<div id="div" apply="Composer1">
		<label id="lb1" value="b_2_1"/>
		<label id="lb2" value="b_2_2"/>

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