ZK 5: Upgrade Notes
The ZK Team
December, 2009
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[1], 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>
- ↑ Some sophisticated framework highly depends on it. However, it can be resolved by implementing
ExecutionInit
,ExecutionCleanup
and so on, if you prefer to use the event processing thread.
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.
- Implementing a JavaString class, say, foo.MyValidator.
- 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[1].
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
});
- ↑ The regular expression of JavaScript is not 100% compatible with the server. You can specify
server
if the pattern you specified is not compatible.
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. |