|
|
| Line 1: |
Line 1: |
| − | = Overview =
| + | #REDIRECT [[Small Talks/2009/December/ZK 5: Upgrade Notes]] |
| − | | |
| − | 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 <tt>setAttribute</tt> and <tt>removeAttribute</tt> of session/execution/application changed (from <tt>void</tt> to <tt>Object</tt>) ===
| |
| − | 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.
| |
| − | | |
| − | 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 (<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.
| |
| − | | |
| − | <syntax lang="xml">
| |
| − | <variabls foo="better"/> <!-- deprecated -->
| |
| − | <custom-attribute foo="better" scope="space"/>
| |
| − | </syntax>
| |
| − | | |
| − | Furthermore, ZK 5 will search the attribute scopes for any variable specified in EL or <tt>zscript</tt>.
| |
| − | | |
| − | <syntax lang="xml">
| |
| − | <window>
| |
| − | <custom-attributes a="a" b="b"/> <!-- belongs to window's attribute scope -->
| |
| − | <div>
| |
| − | <custom-attributes b="B"/> <!-- belongs to div's attribute scope -->
| |
| − | ${a} and ${b} <!-- result: a and B -->
| |
| − | <zscript>
| |
| − | String s = a + b; //result: aB
| |
| − | </zscript>
| |
| − | </div>
| |
| − | </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 <tt>window</tt>) has two attribute scopes. For example,
| |
| − | | |
| − | <syntax lang="xml">
| |
| − | <window>
| |
| − | <custom-attributes foo="a"/>
| |
| − | <div>
| |
| − | <custom-attributes foo="b" scope="space"/>
| |
| − | </div>
| |
| − | | |
| − | <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, <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>.
| |
| − | | |
| − | == System Level Control ==
| |
| − | | |
| − | === 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. Please 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.
| |
| − | | |
| − | <source lang="java" >
| |
| − | if (Messagebox.show("Delete?", "Prompt", Messagebox.YES|Messagebox.NO,
| |
| − | Messagebox.QUESTION) == Messagebox.YES) {
| |
| − | this_never_executes();
| |
| − | }
| |
| − | </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.
| |
| − | | |
| − | <source lang="xml">
| |
| − | <system-config>
| |
| − | <disable-event-thread>false</disable-event-thread>
| |
| − | </system-config>
| |
| − | </source>
| |
| − | <blockquote>
| |
| − | ----
| |
| − | <references/>
| |
| − | </blockquote>
| |
| − | | |
| − | === The method of <tt>ComponentCloneListener</tt> 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.
| |
| − | | |
| − | <source lang="java">
| |
| − | Object willClone(Component comp);
| |
| − | </source>
| |
| − | | |
| − | === The <tt>AuPocessor</tt> interface deprecated (replaced with <tt>AuExtension</tt>) ===
| |
| − | | |
| − | 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 <tt>addRoot</tt>, <tt>removeRoot</tt>, <tt>moveRoot</tt>, <tt>addFellow</tt> and <tt>removeFellow</tt> methods of <tt>PageCtrl</tt> 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>.
| |
| − | | |
| − | === The <tt>disable-behind-modal</tt> 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 <tt>include</tt> component's mode default to <tt>auto</tt> ===
| |
| − | | |
| − | 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
| |
| − | | |
| − | <source lang="javascript">
| |
| − | <include mode="defer" src="abc.zul"/>
| |
| − | </source>
| |
| − | | |
| − | Or, you can specify the following configuration in zk.xml to change the default mode for the whole application.
| |
| − | | |
| − | <source lang="javascript">
| |
| − | <library-property>
| |
| − | <name>org.zkoss.zul.include.mode</name>
| |
| − | <value>defer</value>
| |
| − | </library-property>
| |
| − | </source>
| |
| − | | |
| − | === The <tt>a</tt> 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,
| |
| − | | |
| − | <source lang="xml">
| |
| − | Refer <a href="http://www.zkoss.org" label="ZK"/> for details.
| |
| − | Or <a href="http://www.zkoss.org/zkdemo">ZK Demo</a>.
| |
| − | </source>
| |
| − | | |
| − | === CSS <tt>fixed-layout</tt> property default for <tt>grid</tt> and <tt>listbox</tt> ===
| |
| − | | |
| − | 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.
| |
| − | | |
| − | 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 [[ZK Developer's Reference/UI Patterns/Grid's Columns and Hflex|ZK Developer's Reference: Grid's Columns and Hflex]]). 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 ).
| |
| − | | |
| − | <source lang="xml">
| |
| − | <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>
| |
| − | </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.
| |
| − | | |
| − | <source lang="xml">
| |
| − | <grid width="300px" sizedByContent="true">
| |
| − | </source>
| |
| − | | |
| − | === The <tt>alphafix</tt> mold of <tt>image</tt> and <tt>imagemap</tt> 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.
| |
| − | | |
| − | <source lang="javascript">
| |
| − | <?script content="jq.IE6_ALPHAFIX='.png';"?>
| |
| − | </source>
| |
| − | | |
| − | In other words, just specify a regular expression to a JavaScript variable called <tt>jq.IE6_ALPHAFIX</tt>.
| |
| − | | |
| − | === The methods of <tt>ClientConstraint</tt> 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.
| |
| − | | |
| − | The typical way to implement the custom client validation is as follows.
| |
| − | | |
| − | #Implementing a JavaString class, say, foo.MyValidator.
| |
| − | | |
| − | #Implementing <tt>org.zkoss.zul.ClientConstraint</tt> such that
| |
| − | | |
| − | <source lang="java">
| |
| − | //Java
| |
| − | String getClientConstraint() {
| |
| − | return "new foo.MyValidator()";
| |
| − | }
| |
| − | String getClientPackages() {
| |
| − | return "foo"; //the package name
| |
| − | }
| |
| − | </source>
| |
| − | | |
| − | === <tt>SimpleConstraint</tt> 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,
| |
| − | | |
| − | <source lang="javascript">
| |
| − | <textbox constraint="/.+@.+\.[a-z]+/,server"/>
| |
| − | </source>
| |
| − | | |
| − | 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.
| |
| − | | |
| − | <source lang="javascript">
| |
| − | //JavaScript
| |
| − | ClientServerConstraint = zk.$extends(zul.inp.SimpleConstraint, {
| |
| − | serverValidate: true
| |
| − | });
| |
| − | </source>
| |
| − | | |
| − | <blockquote>
| |
| − | ----
| |
| − | <references/>
| |
| − | </blockquote>
| |
| − | | |
| − | === 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.
| |
| − | | |
| − | === Meaning of hbox/vbox <tt>pack</tt> 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".
| |
| − | | |
| − | == Component Styling ==
| |
| − | | |
| − | === The <tt>dynamic</tt> attribute of the <tt>style</tt> 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.
| |
| − | | |
| − | === The default mold of the <tt>button</tt> component changed to <tt>os</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 <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>.
| |
| − | | |
| − | <source lang="xml">
| |
| − | <library-property>
| |
| − | <name>org.zkoss.zul.Button.mold</name>
| |
| − | <value>trendy</value>
| |
| − | </library-property>
| |
| − | </source>
| |
| − | | |
| − | === The default value of the <tt>zclass</tt> attribute more consistent (<tt>z-</tt> + 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.
| |
| − | | |
| − | 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, <tt>z-combo-item</tt> is renamed to <tt>z-comboitem</tt>, and <tt>z-list-cell</tt> renamed to <tt>z-listcell</tt>.
| |
| − | | |
| − | === Both <tt>Applet</tt> and <tt>Iframe</tt> extends from <tt>HtmlBasedComponent</tt> (instead of <tt>XulElement</tt>) ===
| |
| − | | |
| − | 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>.
| |
| − | | |
| − | === The <tt>ZKPrefix</tt> 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.
| |
| − | | |
| − | == Component Development ==
| |
| − | | |
| − | The component development is changed. Refer to [[ZK Component Development Essentials]] and [[ZK Client-side Reference]] 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,
| |
| − | | |
| − | <source lang="xml">
| |
| − | <!-- 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." />
| |
| − | </source>
| |
| − | | |
| − | can be replaced with
| |
| − | | |
| − | <source lang="xml">
| |
| − | <!-- 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." />
| |
| − | </source>
| |
| − | | |
| − | == 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,
| |
| − | | |
| − | <source lang="xml">
| |
| − | <!-- ZK 3.x: anima -->
| |
| − | <label sclass="ctl" value="SlideDown"
| |
| − | action="onclick: zk.hide(#{t});anima.slideDown(#{t})"/>
| |
| − | </source>
| |
| − | | |
| − | <source lang="xml">
| |
| − | <!- 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"/>
| |
| − | </source>
| |
| − | | |
| − | Please refer to [[http://zkoss.org/javadoc/latest/jsdoc/ JavaScript API]] for the complete description of JavaScript API at the client.
| |
| − | | |
| − | = See Also =
| |
| − | *[[Small Talks/2010/April/Upgrading to ZK 5|Small Talks: Upgrading to ZK 5]]
| |
| − | | |
| − | <comment>http://docs.zkoss.org/wiki/ZK_5:_Upgrade_Notes</comment>
| |