ZK 5: Upgrade Notes

Author
The ZK Team

Date
December, 2009

Version
ZK 3 to ZK 5

Overview

ZK 5 is major release aiming to be more powerful an controllable, yet easier to use. The upgrade effect depends on what features your application uses. Many of them can run without modification. Most of them can run after recompilaton. Some might have to adjust the configuration. Some might have to modify the codes. Note that all ZK add-ons (eg. ZK Calendar, ZK Spreadsheet, ZK JSP Tags, etc.) you used should be updated to their latest versions, which are made compatible with ZK 5. Here is a list of upgrade notes.

Server-side Upgrade Notes

Attributes and Namespace

The return type of setAttribute and removeAttribute of session/execution/application changed (from void to Object)

First of all, you have to re-compile your application, if any of your Java program ever accessed the setAttribute or removeAttribute method of session, execution, or application (WebApp). It is because we change the return type of them, such that session/execution/application can have the same concept called scope (org.zkoss.zk.ui.ext.Scope) as component/space/page/desktop does. Since the change is only the return type, you don't need to modify the source codes.

The new signature: <syntax lang="java"> Object setAttribute(String name, Object value); //returns the previous value if any Object removeAttribute(String name); //return the previous value if any </syntax>

Namespace deprecated

Namespace (org.zkoss.zk.scripting.Namespace) is deprecated and replaced with the attribute scope of the space owner. In other words, with ZK 5, the following are the same.

<syntax lang="xml"> <variabls foo="better"/> <custom-attribute foo="better" scope="space"/> </syntax>

Furthermore, ZK 5 will search the attribute scopes for any variable specified in EL or zscript.

<syntax lang="xml"> <window>

 <custom-attributes a="a" b="b"/> 

   <custom-attributes b="B"/> 
   ${a} and ${b} 
   <zscript>
   String s = a + b; //result: aB
   </zscript>

</window> </syntax>

Notice that the root component's parent scope is page, page's parent scope is desktop, desktop's parent scope is session, and session's parent scope is application.

If you use the namespace to store variables, it is better to check if the name is conflicts with variables stored in the attribute scope of the space owner.

The attribute scope of the ID space is the same of the space owner's attribute scope

In the previous version, the space owner (such as window) has two attribute scopes. For example,

<syntax lang="xml"> <window>

 <custom-attributes foo="a"/>

   <custom-attributes foo="b" scope="space"/>

 <zscript>
 self.getAttribute("foo"); //returns a in ZK 3
 self.getAttribute("foo", self.SPACE_SCOPE); //returns b
 </zscript>

</window> </syntax>

It is too subtle and easy to get confused. After all, window is the space owner. ZK 5 simplified it, such that a component has exactly one attribute scope (no matter it is a space owner or not). In the above example, both custom-attributes actually refer to the same scope -- the attribute scope of the space owner (window). Thus, both self.getAttribute("foo") and self.getAttribute("foo", self.SPACE_OWNER) return b.

System Level Control

Event processing thread disabled by default

To be complaint with Servlet spec, ZK 5 disables the event processing thread by default. Refer to ZK_Developer's_Reference/UI_Patterns/Event_Threads for how to adjust your application. For example, the if clause in the following example is never true.

 if (Messagebox.show("Delete?", "Prompt", Messagebox.YES|Messagebox.NO,
     Messagebox.QUESTION) == Messagebox.YES) {
     this_never_executes();
 }

If you prefer to keep using the event processing thread, specify the following in zk.xml to enable the use of the event processing thread.

<system-config>
	<disable-event-thread>false</disable-event-thread>
</system-config>

---

The method of ComponentCloneListener changed

The clone method of the org.zkoss.zk.ui.util.ComponentCloneListener interface is renamed to willClone (to avoid unexpected overriding). The use and meaning is the same.

Object willClone(Component comp);

The AuPocessor interface deprecated (replaced with AuExtension)

The plug-in of ZK Update Engine is changed from org.zkoss.zk.au.http.AuProcessor to org.zkoss.zk.au.http.AuExtension. The init and destroy methods are introduced such that a plug-in can manage the lifecycle easily. In additon, the service method is simplified.

The addRoot, removeRoot, moveRoot, addFellow and removeFellow methods of PageCtrl removed

To encapsulate better, the addRoot, removeRoot, moveRoot, addFellow and removeFellow methods are removed from org.zkoss.zk.ui.sys.PageCtrl.

The disable-behind-modal configuration disabled (always false)

With ZK 5, there is no need to disable widgets that don't belong to the modal window, so this configuration is meaningless.

Component Use

The include component's mode default to auto

The default mode of the include component become auto (while ZK 3.6 is defer). It means the page being included will be rendered immediately if it is a ZUL or ZHTML page. Furthermore, the components will become children of the include component rather than creating an independent page. It is more convenient to access the components inside the include component. However, if you prefer the defer mode as it used to be. You can either specify the mode in a ZUL page, such as

<include mode="defer" src="abc.zul"/>

Or, you can specify the following configuration in zk.xml to change the default mode for the whole application.

<library-property>
	<name>org.zkoss.zul.include.mode</name>
	<value>defer</value>
</library-property>

The a component introduced for HTML A

A new component called a is introduced for generating HTML A tag .Meanwhile, toolbarbutton is revised to have better look when used within a toolbar. Thus, use a if HTML A is what you really want. For example,

Refer <a href="http://www.zkoss.org" label="ZK"/> for details.
Or <a href="http://www.zkoss.org/zkdemo">ZK Demo</a>.

CSS fixed-layout property default for grid and listbox

With ZK 3, the grid, listbox and tree don't use the CSS fixed-layout property unless the fixedLayout property is specified. However, without fixed-layout, the user cannot adjust the column width precisely, and sometimes encounter the misalignment between header and body.

Thus, since ZK 5, the use of fixed-layout is default. The side effect is that the widths of columns are even distributed if you don't specify the column width. Notice that if you want to assign the width proportionally (depending the browser width), you can use the new introduced hflex (refer to ZK 5: More Flexible Layout). The use of percentage in the width property of column is not recommended (since the browser will engage and the result might be unexpected ).

<grid width="300px">
	<columns>
		<column label="Order" width="20px"/>
		<column label="Name" hflex="1"/>
		<column label="Value" hflex="2"/>
	</columns>
	<rows>
		<row><image src="foo.gif"/> username: <textbox/></row>
		<row><image src="foo.gif"/> password: <textbox/></row>
	</rows>
</grid>

If you like the grid to be handled in the previous way (without fixed-layout), you can specify true to the sizedByContent property.

<grid width="300px" sizedByContent="true">

The alphafix mold of image and imagemap deprecated

ZK 5 handles the transparent issue of Internet Explorer 6 more generically. Instead of specifying the alphafix mold on individual components, ZK 5 allows you specify the pattern of the image resources that require the so-called alphafix. For example, if you want to fix all PNG files in a given ZUL page, just specify the following in the ZUL page.

<?script content="jq.IE6_ALPHAFIX='.png';"?>

In other words, just specify a regular expression to a JavaScript variable called jq.IE6_ALPHAFIX.

The methods of ClientConstraint changed

With ZK 5, the specification of implementation of the client validation is changed. The methods of the org.zkoss.zul.ClientConstraint interface are changed accordingly.

The typical way to implement the custom client validation is as follows.

1. Implementing a JavaString class, say, foo.MyValidator.

1. Implementing org.zkoss.zul.ClientConstraint such that

//Java
String getClientConstraint() {
  return "new foo.MyValidator()";
}
String getClientPackages() {
  return "foo"; //the package name
}

SimpleConstraint performs all validations at client

The org.zkoss.zul.SimpleConstraint performs all validations at the client (so there are no Ajax traffic). If you prefer to have some extra validation at the server, specify server in the constraint. For example,

<textbox constraint="/.+@.+\.[a-z]+/,server"/>

It is helpful if the regular expression you specified is not compatible at both client and server.

If you implement your own JavaScript class for client validation and you want the server to help the validation, you can specify the serverValidate member as follows.

//JavaScript
ClientServerConstraint = zk.$extends(zul.inp.SimpleConstraint, {
	serverValidate: true
});

---

Overlapped window within another overlapped window not cropped

ZK 5 fully support the use of the overlapped and popup windows. The child overlapped window won't be cropped by the parent overlapped window, so you don't need to specify the verflow:visible CSS property.

Meaning of hbox/vbox pack attribute follows XUL's specification

With ZK 5, the meaning of hbox/vbox pack attribute is changed to follow XUL's specification. That is, start means extra space is placed on the right/bottom side of the hbox/vbox, center means extra space is split equally and placed on two sides(left and right/top and bottom of the hbox/vbox), end means extra space is placed on the left/top of the hbox/vbox. If you would like the hbox/vbox behaves just like in old version, you can add a stretch option on pack attribute to make it backward compatible. i.e. "stretch,start", "stretch,center", or "stretch,end".

Component Styling

The dynamic attribute of the style component deprecated

With ZK 5, the style component decides automatically whether to generate the CSS content directly or to load thru URL. Thus, the dynamic attribute is meaningless.

The default mold of the button component changed to os

The trendy look introduced in ZK 3.5 will slow down Internet Explorer if a page uses a lot of buttons. Thus, we change the default mold to os in ZK 5. If you prefer to use the trendy mold in the whole application, you can specify the following in zk.xml.

<library-property>
  <name>org.zkoss.zul.Button.mold</name>
  <value>trendy</value>
</library-property>

The default value of the zclass attribute more consistent (z- + component-name)

Some of the zclass naming are inconsistly in ZK 3.5. ZK 5 has fixed it. Modify your CSS file if you ever customize them.

The affected components are as follows.

comboitem, bandpopup, groupfoot, listcell, listfoot,
listfooter, listgroup, listgroupfoot, listhead, listheader,
listitem,  treecell, treechildren, treecol, treecols, treefoot,
treefooter, treerow, table-children, and table-layout

For example, z-combo-item is renamed to z-comboitem, and z-list-cell renamed to z-listcell.

Both Applet and Iframe extends from HtmlBasedComponent (instead of XulElement)

It is pointless for applet and iframe to support drag-and-drop and other XUL features, so their Java implementations are extend from org.zkoss.zk.ui.HtmlBasedComonent instead of org.zkoss.zul.impl.XulElement.

The ZKPrefix library property deprecated

The org.zkoss.zul.theme.enableZKPrefix library property is deprecated. To change the font family and/or size of ZK components, please use the library properties called org.zkoss.zul.theme.fontSizeM and others.

Component Development

The component development is changed. Refer to ZK_Component_Development_Essentials for details.

Client-side Upgrade Notes

The client is rewritten, so your customization have to rewrite, too.

Client-side Action deprecated

Client-side Actions are no longer supported. With ZK 5, the application have 100% controllability of widgets. A typical replacement is to use the client namespace (http://www.zkoss.org/2005/zk/client) to register the event listener directly. For example,

<!-- ZK 3.x: Client Side Action -->
<textbox
 action="onfocus: window.action.show(#{help1}); onblur: window.action.hide(#{help1})" />
<label id="help1" visible="false" value="This is help for text1." />

can be replaced with

<!-- ZK 5 -->
<textbox xmlns:w="http://www.zkoss.org/2005/zk/client"
 w:onFocus="jq(this.$f('help1')).fadeIn()" w:onBlur="jq(this.$f('help1')).fadeOut()"/>
<label id="help1" visible="false" value="This is help for text1." />

Animation API deprecated

The animation API (anima) is deprecated. With ZK 5, the application can leverage the power of jQuery for better animation. For example,

<!-- ZK 3.x: anima -->
<label sclass="ctl" value="SlideDown"
  action="onclick: zk.hide(#{t});anima.slideDown(#{t})"/>

<!- ZK 5: with jQury -->
<label sclass="ctl" value="SlideDown"
 w:onClick="jq(this.$f('t')).hide().slideDown()"
 xmlns:w="http://www.zkoss.org/2005/zk/client"/>

Please refer to JavaScript API for the complete description of JavaScript API at the client.

See Also

• Upgrading to ZK 5
• A forum thread : Upgrade to ZK5

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