ZK 5: Upgrade Notes"

From Documentation
m (correct highlight (via JWB))
 
(One intermediate revision by one other user not shown)
Line 13: Line 13:
  
 
== Attributes and Namespace ==
 
== Attributes and Namespace ==
=== The return type of <tt>setAttribute</tt> and <tt>removeAttribute</tt> of session/execution/application changed (from <tt>void</tt> to <tt>Object</tt>) ===
+
=== The return type of <code>setAttribute</code> and <code>removeAttribute</code> of session/execution/application changed (from <code>void</code> to <code>Object</code>) ===
First of all, you have to re-compile your application, if any of your Java program ever accessed the <tt>setAttribute</tt> or <tt>removeAttribute</tt> method of session, execution, or application (<tt>WebApp</tt>). It is because we change the return type of them, such that session/execution/application can have the same concept called scope (<tt>org.zkoss.zk.ui.ext.Scope</tt>) as component/space/page/desktop does. Since the change is only the return type, you don't need to modify the source codes.
+
First of all, you have to re-compile your application, if any of your Java program ever accessed the <code>setAttribute</code> or <code>removeAttribute</code> method of session, execution, or application (<code>WebApp</code>). It is because we change the return type of them, such that session/execution/application can have the same concept called scope (<code>org.zkoss.zk.ui.ext.Scope</code>) 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:
 
The new signature:
Line 24: Line 24:
 
=== Namespace deprecated ===
 
=== Namespace deprecated ===
  
Namespace (<tt>org.zkoss.zk.scripting.Namespace</tt>) is deprecated and replaced with the attribute scope of the space owner. In other words, with ZK 5, the following are the same.
+
Namespace (<code>org.zkoss.zk.scripting.Namespace</code>) 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">
 
<syntax lang="xml">
Line 31: Line 31:
 
</syntax>
 
</syntax>
  
Furthermore, ZK 5 will search the attribute scopes for any variable specified in EL or <tt>zscript</tt>.
+
Furthermore, ZK 5 will search the attribute scopes for any variable specified in EL or <code>zscript</code>.
  
 
<syntax lang="xml">
 
<syntax lang="xml">
Line 52: Line 52:
 
=== The attribute scope of the ID space is the same of the space owner's attribute scope ===
 
=== 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 <tt>window</tt>) has two attribute scopes. For example,
+
In the previous version, the space owner (such as <code>window</code>) has two attribute scopes. For example,
  
 
<syntax lang="xml">
 
<syntax lang="xml">
Line 68: Line 68:
 
</syntax>
 
</syntax>
  
It is too subtle and easy to get confused. After all, <tt>window</tt> 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 <tt>custom-attributes</tt> actually refer to the same scope -- the attribute scope of the space owner (<tt>window</tt>). Thus, both <tt>self.getAttribute("foo")</tt> and <tt>self.getAttribute("foo", self.SPACE_OWNER)</tt> return <tt>b</tt>.
+
It is too subtle and easy to get confused. After all, <code>window</code> 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 <code>custom-attributes</code> actually refer to the same scope -- the attribute scope of the space owner (<code>window</code>). Thus, both <code>self.getAttribute("foo")</code> and <code>self.getAttribute("foo", self.SPACE_OWNER)</code> return <code>b</code>.
  
 
== System Level Control ==
 
== System Level Control ==
Line 74: Line 74:
 
=== Event processing thread disabled by default ===
 
=== Event processing thread disabled by default ===
  
To be complaint with Servlet spec<ref>Some sophisticated framework highly depends on it. However, it can be resolved by implementing <tt>ExecutionInit</tt>, <tt>ExecutionCleanup</tt> and so on, if you prefer to use the event processing thread.</ref>, 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 <tt>if</tt> clause in the following example is never true.
+
To be complaint with Servlet spec<ref>Some sophisticated framework highly depends on it. However, it can be resolved by implementing <code>ExecutionInit</code>, <code>ExecutionCleanup</code> and so on, if you prefer to use the event processing thread.</ref>, 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 <code>if</code> clause in the following example is never true.
  
 
<source lang="java" >
 
<source lang="java" >
Line 83: Line 83:
 
</source>
 
</source>
  
If you prefer to keep using the event processing thread, specify the following in <tt>zk.xml</tt> to enable the use of the event processing thread.
+
If you prefer to keep using the event processing thread, specify the following in <code>zk.xml</code> to enable the use of the event processing thread.
  
 
<source lang="xml">
 
<source lang="xml">
Line 95: Line 95:
 
</blockquote>
 
</blockquote>
  
=== The method of <tt>ComponentCloneListener</tt> changed ===
+
=== The method of <code>ComponentCloneListener</code> changed ===
  
The <tt>clone</tt> method of the <tt>org.zkoss.zk.ui.util.ComponentCloneListener</tt> interface is renamed to <tt>willClone</tt> (to avoid unexpected overriding). The use and meaning is the same.
+
The <code>clone</code> method of the <code>org.zkoss.zk.ui.util.ComponentCloneListener</code> interface is renamed to <code>willClone</code> (to avoid unexpected overriding). The use and meaning is the same.
  
 
<source lang="java">
 
<source lang="java">
Line 103: Line 103:
 
</source>
 
</source>
  
=== The <tt>AuPocessor</tt> interface deprecated (replaced with <tt>AuExtension</tt>) ===
+
=== The <code>AuPocessor</code> interface deprecated (replaced with <code>AuExtension</code>) ===
  
The plug-in of ZK Update Engine is changed from <tt>org.zkoss.zk.au.http.AuProcessor</tt> to <tt>org.zkoss.zk.au.http.AuExtension</tt>. The <tt>init</tt> and <tt>destroy</tt> methods are introduced such that a plug-in can manage the lifecycle easily. In additon, the <tt>service</tt> method is simplified.
+
The plug-in of ZK Update Engine is changed from <code>org.zkoss.zk.au.http.AuProcessor</code> to <code>org.zkoss.zk.au.http.AuExtension</code>. The <code>init</code> and <code>destroy</code> methods are introduced such that a plug-in can manage the lifecycle easily. In additon, the <code>service</code> method is simplified.
  
=== The <tt>addRoot</tt>, <tt>removeRoot</tt>, <tt>moveRoot</tt>, <tt>addFellow</tt> and <tt>removeFellow</tt> methods of <tt>PageCtrl</tt> removed ===
+
=== The <code>addRoot</code>, <code>removeRoot</code>, <code>moveRoot</code>, <code>addFellow</code> and <code>removeFellow</code> methods of <code>PageCtrl</code> removed ===
  
To encapsulate better, the <tt>addRoot</tt>, <tt>removeRoot</tt>, <tt>moveRoot</tt>, <tt>addFellow</tt> and <tt>removeFellow</tt> methods are removed from <tt>org.zkoss.zk.ui.sys.PageCtrl</tt>.
+
To encapsulate better, the <code>addRoot</code>, <code>removeRoot</code>, <code>moveRoot</code>, <code>addFellow</code> and <code>removeFellow</code> methods are removed from <code>org.zkoss.zk.ui.sys.PageCtrl</code>.
  
=== The <tt>disable-behind-modal</tt> configuration disabled (always false) ===
+
=== The <code>disable-behind-modal</code> 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.
 
With ZK 5, there is no need to disable widgets that don't belong to the modal window, so this configuration is meaningless.
Line 117: Line 117:
 
== Component Use ==
 
== Component Use ==
  
=== The <tt>include</tt> component's mode default to <tt>auto</tt> ===
+
=== The <code>include</code> component's mode default to <code>auto</code> ===
  
The default mode of the <tt>include</tt> component become <tt>auto</tt> (while ZK 3.6 is <tt>defer</tt>). 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 <tt>include</tt> component rather than creating an independent page. It is more convenient to access the components inside the <tt>include</tt> component. However, if you prefer the <tt>defer</tt> mode as it used to be. You can either specify the mode in a ZUL page, such as
+
The default mode of the <code>include</code> component become <code>auto</code> (while ZK 3.6 is <code>defer</code>). 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 <code>include</code> component rather than creating an independent page. It is more convenient to access the components inside the <code>include</code> component. However, if you prefer the <code>defer</code> mode as it used to be. You can either specify the mode in a ZUL page, such as
  
 
<source lang="javascript">
 
<source lang="javascript">
Line 134: Line 134:
 
</source>
 
</source>
  
=== The <tt>a</tt> component introduced for HTML A ===
+
=== The <code>a</code> component introduced for HTML A ===
  
A new component called <tt>a</tt> is introduced for generating HTML A tag .Meanwhile, <tt>toolbarbutton</tt> is revised to have better look when used within a toolbar. Thus, use <tt>a</tt> if HTML A is what you really want. For example,
+
A new component called <code>a</code> is introduced for generating HTML A tag .Meanwhile, <code>toolbarbutton</code> is revised to have better look when used within a toolbar. Thus, use <code>a</code> if HTML A is what you really want. For example,
  
 
<source lang="xml">
 
<source lang="xml">
Line 143: Line 143:
 
</source>
 
</source>
  
=== CSS <tt>fixed-layout</tt> property default for <tt>grid</tt> and <tt>listbox</tt> ===
+
=== CSS <code>fixed-layout</code> property default for <code>grid</code> and <code>listbox</code> ===
  
With ZK 3, the <tt>grid</tt>, <tt>listbox</tt> and <tt>tree</tt> don't use the CSS <tt>fixed-layout</tt> property unless the <tt>fixedLayout</tt> property is specified. However, without <code>fixed-layout</code>, the user cannot adjust the column width precisely, and sometimes encounter the misalignment between header and body.
+
With ZK 3, the <code>grid</code>, <code>listbox</code> and <code>tree</code> don't use the CSS <code>fixed-layout</code> property unless the <code>fixedLayout</code> property is specified. However, without <code>fixed-layout</code>, the user cannot adjust the column width precisely, and sometimes encounter the misalignment between header and body.
  
Thus, since ZK 5, the use of <tt>fixed-layout</tt> 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 <tt>hflex</tt> (refer to [http://books.zkoss.org/wiki/Small_Talks/2009/September/ZK_5:_More_Flexible_Layout#Proportional_Flexibility]). The use of percentage in the <tt>width</tt> property of <tt>column</tt> is not recommended (since the browser will engage and the result might be unexpected ).
+
Thus, since ZK 5, the use of <code>fixed-layout</code> 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 <code>hflex</code> (refer to [[Small_Talks/2009/September/ZK_5:_More_Flexible_Layout#Proportional_Flexibility|ZK 5: More Flexible Layout]]). The use of percentage in the <code>width</code> property of <code>column</code> is not recommended (since the browser will engage and the result might be unexpected ).
  
 
<source lang="xml">
 
<source lang="xml">
Line 163: Line 163:
 
</source>
 
</source>
  
If you like the grid to be handled in the previous way (without <tt>fixed-layout</tt>), you can specify <tt>true</tt> to the <tt>sizedByContent</tt> property.
+
If you like the grid to be handled in the previous way (without <code>fixed-layout</code>), you can specify <code>true</code> to the <code>sizedByContent</code> property.
  
 
<source lang="xml">
 
<source lang="xml">
Line 169: Line 169:
 
</source>
 
</source>
  
=== The <tt>alphafix</tt> mold of <tt>image</tt> and <tt>imagemap</tt> deprecated ===
+
=== The <code>alphafix</code> mold of <code>image</code> and <code>imagemap</code> deprecated ===
  
ZK 5 handles the transparent issue of Internet Explorer 6 more generically. Instead of specifying the <tt>alphafix</tt> 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.
+
ZK 5 handles the transparent issue of Internet Explorer 6 more generically. Instead of specifying the <code>alphafix</code> 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.
  
 
<source lang="javascript">
 
<source lang="javascript">
Line 177: Line 177:
 
</source>
 
</source>
  
In other words, just specify a regular expression to a JavaScript variable called <tt>jq.IE6_ALPHAFIX</tt>.
+
In other words, just specify a regular expression to a JavaScript variable called <code>jq.IE6_ALPHAFIX</code>.
  
=== The methods of <tt>ClientConstraint</tt> changed ===
+
=== The methods of <code>ClientConstraint</code> changed ===
  
With ZK 5, the specification of implementation of the client validation is changed. The methods of the <tt>org.zkoss.zul.ClientConstraint</tt> interface are changed accordingly.
+
With ZK 5, the specification of implementation of the client validation is changed. The methods of the <code>org.zkoss.zul.ClientConstraint</code> interface are changed accordingly.
  
 
The typical way to implement the custom client validation is as follows.
 
The typical way to implement the custom client validation is as follows.
Line 187: Line 187:
 
#Implementing a JavaString class, say, foo.MyValidator.
 
#Implementing a JavaString class, say, foo.MyValidator.
  
#Implementing <tt>org.zkoss.zul.ClientConstraint</tt> such that
+
#Implementing <code>org.zkoss.zul.ClientConstraint</code> such that
  
 
<source lang="java">
 
<source lang="java">
Line 199: Line 199:
 
</source>
 
</source>
  
=== <tt>SimpleConstraint</tt> performs all validations at client ===
+
=== <code>SimpleConstraint</code> performs all validations at client ===
  
The <tt>org.zkoss.zul.SimpleConstraint</tt> performs all validations at the client (so there are no Ajax traffic). If you prefer to have some extra validation at the server,  specify <tt>server</tt> in the constraint. For example,
+
The <code>org.zkoss.zul.SimpleConstraint</code> performs all validations at the client (so there are no Ajax traffic). If you prefer to have some extra validation at the server,  specify <code>server</code> in the constraint. For example,
  
 
<source lang="javascript">
 
<source lang="javascript">
Line 209: Line 209:
 
It is helpful if the regular expression you specified is not compatible at both client and server<ref>The regular expression of JavaScript is not 100% compatible with the server. You can specify <code>server</code> if the pattern you specified is not compatible.</ref>.
 
It is helpful if the regular expression you specified is not compatible at both client and server<ref>The regular expression of JavaScript is not 100% compatible with the server. You can specify <code>server</code> if the pattern you specified is not compatible.</ref>.
  
If you implement your own JavaScript class for client validation and you want the server to help the validation, you can specify the <tt>serverValidate</tt> member as follows.
+
If you implement your own JavaScript class for client validation and you want the server to help the validation, you can specify the <code>serverValidate</code> member as follows.
  
 
<source lang="javascript">
 
<source lang="javascript">
Line 225: Line 225:
 
=== Overlapped window within another overlapped window not cropped ===
 
=== 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 <tt>verflow:visible</tt> CSS property.
+
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 <code>verflow:visible</code> CSS property.
  
=== Meaning of hbox/vbox <tt>pack</tt> attribute follows XUL's specification ===
+
=== Meaning of hbox/vbox <code>pack</code> attribute follows XUL's specification ===
  
With ZK 5, the meaning of hbox/vbox <tt>pack</tt> 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 <tt>pack</tt> attribute to make it backward compatible. i.e. "stretch,start", "stretch,center", or "stretch,end".
+
With ZK 5, the meaning of hbox/vbox <code>pack</code> 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 <code>pack</code> attribute to make it backward compatible. i.e. "stretch,start", "stretch,center", or "stretch,end".
  
 
== Component Styling ==
 
== Component Styling ==
  
=== The <tt>dynamic</tt> attribute of the <tt>style</tt> component deprecated ===
+
=== The <code>dynamic</code> attribute of the <code>style</code> component deprecated ===
  
With ZK 5, the <tt>style</tt> component decides automatically whether to generate the CSS content directly or to load thru URL. Thus, the <tt>dynamic</tt> attribute is meaningless.
+
With ZK 5, the <code>style</code> component decides automatically whether to generate the CSS content directly or to load thru URL. Thus, the <code>dynamic</code> attribute is meaningless.
  
=== The default mold of the <tt>button</tt> component changed to <tt>os</tt> ===
+
=== The default mold of the <code>button</code> component changed to <code>os</code> ===
  
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 <tt>os</tt> in ZK 5. If you prefer to use the <tt>trendy</tt> mold in the whole application, you can specify the following in <tt>zk.xml</tt>.
+
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 <code>os</code> in ZK 5. If you prefer to use the <code>trendy</code> mold in the whole application, you can specify the following in <code>zk.xml</code>.
  
 
<source lang="xml">
 
<source lang="xml">
Line 248: Line 248:
 
</source>
 
</source>
  
=== The default value of the <tt>zclass</tt> attribute more consistent (<tt>z-</tt> + component-name) ===
+
=== The default value of the <code>zclass</code> attribute more consistent (<code>z-</code> + component-name) ===
  
Some of the <tt>zclass</tt> naming are inconsistly in ZK 3.5. ZK 5 has fixed it. Modify your CSS file if you ever customize them.
+
Some of the <code>zclass</code> 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.
 
The affected components are as follows.
Line 259: Line 259:
 
  treefooter, treerow, table-children, and table-layout
 
  treefooter, treerow, table-children, and table-layout
  
For example, <tt>z-combo-item</tt> is renamed to <tt>z-comboitem</tt>, and <tt>z-list-cell</tt> renamed to <tt>z-listcell</tt>.
+
For example, <code>z-combo-item</code> is renamed to <code>z-comboitem</code>, and <code>z-list-cell</code> renamed to <code>z-listcell</code>.
  
=== Both <tt>Applet</tt> and <tt>Iframe</tt> extends from <tt>HtmlBasedComponent</tt> (instead of <tt>XulElement</tt>) ===
+
=== Both <code>Applet</code> and <code>Iframe</code> extends from <code>HtmlBasedComponent</code> (instead of <code>XulElement</code>) ===
  
It is pointless for <tt>applet</tt> and <tt>iframe</tt> to support drag-and-drop and other XUL features, so their Java implementations are extend from <tt>org.zkoss.zk.ui.HtmlBasedComonent</tt> instead of <tt>org.zkoss.zul.impl.XulElement</tt>.
+
It is pointless for <code>applet</code> and <code>iframe</code> to support drag-and-drop and other XUL features, so their Java implementations are extend from <code>org.zkoss.zk.ui.HtmlBasedComonent</code> instead of <code>org.zkoss.zul.impl.XulElement</code>.
  
=== The <tt>ZKPrefix</tt> library property deprecated ===
+
=== The <code>ZKPrefix</code> library property deprecated ===
  
The <tt>org.zkoss.zul.theme.enableZKPrefix</tt> library property is deprecated. To change the font family and/or size of ZK components, please use the library properties called <tt>org.zkoss.zul.theme.fontSizeM</tt> and others.
+
The <code>org.zkoss.zul.theme.enableZKPrefix</code> library property is deprecated. To change the font family and/or size of ZK components, please use the library properties called <code>org.zkoss.zul.theme.fontSizeM</code> and others.
  
 
== Component Development ==
 
== Component Development ==
Line 299: Line 299:
 
== Animation API deprecated ==
 
== Animation API deprecated ==
  
The animation API (<tt>anima</tt>) is deprecated. With ZK 5, the application can leverage the power of [http://www.jquery.com jQuery] for better animation. For example,
+
The animation API (<code>anima</code>) is deprecated. With ZK 5, the application can leverage the power of [http://www.jquery.com jQuery] for better animation. For example,
  
 
<source lang="xml">
 
<source lang="xml">

Latest revision as of 04:17, 20 January 2022

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[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>

  1. 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.

  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[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
});

  1. 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





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