Small Talks/2008/June/New Features of ZK 3.0.6

{{Template:Smalltalk_Author|
|author=Robbie Cheng, Engineer, Potix Corporation
|date=June 24, 2008
|version=
}}


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 <tt>forward</tt> 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,

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


==<tt>forEach</tt> supports dynamic declaration of <tt>Array</tt>==

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

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


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

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


==<tt>variables</tt> and <tt>custom-attributes</tt> support <tt>List</tt> and <tt>Map</tt>==

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

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

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.

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

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.

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

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,

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


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

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


=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,

<source lang="xml" >
<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> 
</source>


===Keyevent supports <tt>getReference()</tt>===

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,

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


=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,

[[Image:Processerror.jpg]]

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.

<source lang="xml" >
  <system-property>
	<name>org.zkoss.zul.theme.enableZKPrefix</name>
	<value>true</value>
  </system-property>
</source>

* 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,

<source lang="java" >
  body, html {height:auto}
</source>

* 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)

<source lang="xml" >
   <system-property>
	<name>org.zkoss.zul.theme.browserDefault</name>
	<value>true</value>
   </system-property>
 </source>  
   

<comment>/smalltalks/zk3.0.6/index.dsp</comment>


[[Category:ZK]]
{{Template:Smalltalk_Footer|
|name=Potix Corporation
}}