New Features of ZK 3.0.6

Robbie Cheng, Engineer, Potix Corporation
June 24, 2008

ZK 3.0.6 focuses mainly on fixing bugs and improving performance. In addition to over 33 bug fixes, there are 24 new features.

In this release, more features introduced and enhanced. All ZUL components support keyevents, and developers are allowed to forward event and pass object at the same time with ease. Moreover, for better system reliability, users will be prompted for a retry if process error and system out-of-service occurs, and both of them are customizable.

Last but not least, Firefox 3 is suppoted!

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

• Ease of Use
  • A way to pass object in forward attribute
  • forEach supports dynamic declaration of Array
  • variables and custom-attributes support List and Map
  • Assign a variable with a Reserved Name
  • A way to define the layout of included ZK page
• ZK Components Reloaded
  • New Features
    • ZUL components support onOK, onCancel, and onCtrlKey events
    • Keyevent supports getReference()
• Reliability Improvement
  • A way to customize the confirm dialog if process error
  • A way to customize the confirm dialog if server out-of-service
• Integration with Other Technologies
  • Integration with JSP without CSS in-compatibility

Ease of Use

A way to pass object in forward attribute

Forward attribute is a convenient way to forward event to other components, and it will be better if we can pass a object at the same time. Since ZK 3.0.6, it allows you to pass a object in the forward attribute directly as follows,

<window title="My First Window" onOK='alert("" + event.data)'>
    <button id="btn" forward="onOK(${self})" label="pass object"/>
</window>

forEach supports dynamic declaration of Array

To iterate a list of data, we usually construct it using zscript as follows,

<zscript>
  array = new String[] {"a", b, "c"}
</zscript>
<textbox forEach=""/>

But, it will more convenient for developers to declare the array inside forEach statement as follows,

<textbox forEach="'a', ${b}, 'c'"/>

variables and custom-attributes support List and Map

If you want to specify a list of values, you can specify the composite attribute with list as follows.

<variables simple="apple, orange" composite="list"/>

Then, it is converted to a list with two elements. The first element is "apple" and the second "orange". If you want to specify a map of values, you can specify the composite attribute with map as follows.

<variables simple="juice=apple, flavor=orange" composite="map"/>

Then, it is converted to a map with two entries. The first entry is ("juice", "apple") and the second ("flavor", "orange").

Assign a variable with Reserved Name

To assign a variable with a reserved name, say, forEach , you have to specify a namespace (which can be anything but ZK namespace) as follows.

<variables m:forEach="a value" xmlns:m="http://whatever.com"/>

Then, forEach will be considered as a variable rather than the iterative condition.

A way to define the layout of included ZK page

If a ZK page was included in another page, it might break the layout of the inlcuder page since the default height of ZK page is 100%. There are two ways to fix the issue, the straightforward one is to configure the layout in the include component, as follows,

<include src="another.zul" width="200px" height="100px"/>

An alternative way is to set the layout in the included ZK page directly as follows,

<?page style="width: 200px; height: 100px"?>
<label value="layout test"/>

Component Reloaded

New Components

ZUL components support onOK, onCancel, and onCtrlKey events.

Since ZK 3.0.6, for east of use, all ZUL components support key events, onOK, onCancel, and onCtrlKey. It allows developers to handle key event on components other than Window as follows,

<listbox width="450px">
  <listhead sizable="true">
    <listheader label="name" sort="auto"/>
    <listheader label="gender" sort="auto"/>
  </listhead>
  <listitem onOK='alert("This is an onOK event");'>
    <listcell label="SelectMe"/>
    <listcell label="Press Enter to show onOK event"/>
  </listitem>
</listbox> 

Keyevent supports getReference()

Before ZK 3.0.6, only Window supports keyevent, and it is not convenient to satisfy more complex circumstances, depend on which component triggers the keyevent. From now on, developers can handle this job well by invoking the getReference() method to know which child component of window triggers the keyevent,

<window  border="normal" width="200px" onOK='alert(event.reference.id)'>
  <textbox id="t1"/>
  <textbox id="t2"/>
</window>

Reliability Improvement

A way to customize the confirm dialog if process error

If the client fails to process command from server, it will prompt the user to reload the page as follows,
If you want to customize the dialog, simply provide your Javascript file to override the onProcessError() function.

A way to customize the confirm dialog if server out-of-service

Currently, when the server is out-of-service, a confirm dialog is shown to ask user whether to retry. If you want to customize the dialog, simply provide your Javascrip file to override the confirmRetry() function.

Integration with Other Technologies

Integration with JSP without CSS in-compatibility

There are three guidelines to handle CSS in-compatibility while integrating legacy JSP pages.

• While intergrating ZK pages and other legacy web pages, developers are advised to enable zk prefix to those common used CSS definitions to void CSS polutions by specifying the following system property in zk.xml.

  
  <system-property>
    <name>org.zkoss.zul.theme.enableZKPrefix</name>
    <value>true</value>
  </system-property>
  
  

• The default height of body and html is set to 100%. This assumption might break the layout of pages under some kinds of circumstances,ex. being included by another page. If you prefer a more precise layout, please define a style as follows,

  
  body, html {height:auto}
  
  

• To avoid to change the margin or padding of body, you can specify a system property in zk.xml as follows, (If it was OK to lose backward compatibility)

  
   <system-property>
    <name>org.zkoss.zul.theme.browserDefault</name>
    <value>true</value>
   </system-property>