https://www.zkoss.org/_w/api.php?action=feedcontributions&user=Char&feedformat=atomDocumentation - User contributions [en]2024-03-28T18:54:35ZUser contributionsMediaWiki 1.35.1https://www.zkoss.org/_w/index.php?title=Small_Talks/2010/April/Client_Side_Programming&diff=15277Small Talks/2010/April/Client Side Programming2010-12-21T04:59:05Z<p>Char: /* Override a Widget Method */</p>
<hr />
<div>{{Template:Smalltalk_Author|<br />
|author=Peter Kuo, Engineer, Potix Corporation<br />
|date=April 20, 2010<br />
|version=ZK 5.0 and above<br />
}}<br />
<br />
== Introduction ==<br />
<br />
In ZK 5 we continue to focus on our strong Server-side approach which boosts your productivity but now provides developers the option to control the client side programming. We have dubbed this blending of technology, Server+client Fusion.<br />
<br />
In order to execute application-specific code at the client, ZK introduces the concept of the Client Namespace <ref>For ZK 3.6 and prior, please use [http://books.zkoss.org/wiki/ZK_Client-side_References Client Side Actions] instead.</ref>. With the Client Namespace, developers are able to listen to any client-side event, override ZK methods and execute any custom client-side code.<br />
<br />
----<br />
<references/><br />
<br />
== Before writing JavaScript in a ZUL file ==<br />
<br />
<br />
=== Define ZK Client Namespace ===<br />
In order to write client-side code, you are required to specify the XML namespace which is named http://www.zkoss.org/2005/zk/client. In the following example, you can see the <mp>onClick</mp> event is handled by client side JavaScript.<br />
<source lang="xml"><br />
<button label="client" xmlns:w="http://www.zkoss.org/2005/zk/client" w:onClick="alert('clicked')"/><br />
</source><br />
<br />
=== How to Get Widget Reference in JavaScript ===<br />
<br />
When the client event is invoked, you can reference the widget using <mp>this</mp>. In the below example this refers to the label.<br />
<br />
<source lang="xml"><br />
<window xmlns:w="http://www.zkoss.org/2005/zk/client"><br />
<label value="change me by click" w:onClick="this.setValue('clicked');"/> <br />
</window><br />
</source><br />
<br />
<javadoc directory="jsdoc">zk.widget</javadoc> can retrieve other widgets using the function <mp>$f</mp>. This works in a similar manner as <mp>getFellow</mp>. <br />
<br />
In additions, you can use jQuery to select a DOM element of a widget<ref>Since ZK 5.0.2</ref>. For example <code>jq("@window")</code> will select DOM elements of all window widget. And, <code>jq("$win1")</code> will select DOM elements of all widgets whose ID is <code>win1</code>. (see <javadoc directory="jsdoc">_global_.jq</javadoc>). <br />
<br />
<source lang="xml"><br />
<window xmlns:w="http://www.zkoss.org/2005/zk/client"><br />
<vbox><br />
<label id="labelone" value="click to change"<br />
w:onClick="this.setValue('changed by click label');" /><br />
<br />
<button label="button"<br />
w:onClick="this.$f('labelone').setValue('changed by button');" /><br />
<br />
<html><![CDATA[<br />
<a href="javascript:;" onclick="zk.Widget.$(jq('$labelone')[0]).setValue('changed with jq');">not widget</a><br />
]]></html> <br />
<br />
</vbox><br />
</window><br />
</source><br />
<br />
<code>zk.Widget.$</code> is a utility to return particular zk widget by given id of dom element. (see <javadoc directory="jsdoc">zk.Widget</javadoc>). <br />
<br />
----<br />
<references/><br />
<br />
=== Execute JavaScript After All Widgets Are Loaded ===<br />
Set <code>defer</code> attribute of <code>script</code> to "true", if you want to access widgets. It means deferring the execution of the script codes until the widget is instantiated and mounted. Note that <code>script</code> here is a zk component, not an HTML tag. Similarly, <code>defer</code> here is not in the same context as HTML . More detail at <javadoc>org.zkoss.zul.api.Script</javadoc>.<br />
<source lang="xml"><br />
<script defer="true"><br />
..........<br />
</script><br />
</source><br />
<br />
== Things you can do ==<br />
===Define a Client-side Listener of ZK Widget event===<br />
For example, handle <code>onClick</code> event of a <code>label</code> component's corresponding widget at the client side.<br />
<br />
<source lang="xml"><br />
<window xmlns:w="http://www.zkoss.org/2005/zk/client"><br />
<label value="change me by click" w:onClick="this.setValue('clicked');"/> <br />
</window><br />
</source><br />
<br />
In an event listener, you can access the widget by using <code>this</code> as shown above. In addition, you can access the event (an instance of <javadoc directory="jsdoc">zk.Event</javadoc>) by using <code>event</code>.<br />
<br />
You can find more detail at [[ZK Client-side Reference]] and [http://books.zkoss.org/wiki/ZK_Configuration_Reference/zk.xml/The_client-config_Element ZK5: Client Computing with ZUML].<br />
<br />
===Override a Widget Method===<br />
For example, override the <code>setValue</code> implementation of a <code>label</code> widget.<br />
<br />
<source lang="xml"><br />
<window xmlns:w="http://www.zkoss.org/2005/zk/client"><br />
<label><br />
<attribute w:name="setValue"><br />
function (value) {<br />
this.$setValue(value); //call the original method<br />
if (this.desktop) {<br />
this._flag = !this._flag;<br />
this.setStyle('background:'+(this._flag ? 'red':'green'));<br />
}<br />
}<br />
</attribute><br />
</label><br />
</window><br />
</source><br />
<br />
You can find more detail at [[ZK Client-side Reference]] and [http://books.zkoss.org/wiki/ZK_Client-side_Reference/General_Control ZK5: Client Computing with ZUML].<br />
<br />
EL expressions is allowed <ref>EL expressions are allowed since ZK 5.0.2</ref><ref> EL is evaluated when rendering a page. In other words, it is evaluated before sending the JavaScript code to the client for execution later.</ref> to simplify the passing of data from server to client. For example, you could pass a Java bean's property to the client as shown below.<br />
<br />
<source lang="javascript"><br />
w:setValue='function (value) { this.$setValue(value + "${foo.description}")}';<br />
</source><br />
<br />
<references/><br />
<br />
=== Override a Default Widget Method ===<br />
In previous section, we showed how to override method of a particular widget we declared. But how to override the default widget method for all such widgets? We can modify it by overwriting the widget's <code>prototype</code> implementation. The following is a sample to modify the default <code>setValue</code> of <code>label</code><br />
<source lang="xml"><br />
<window xmlns:w="http://www.zkoss.org/2005/zk/client"><br />
<label id="labelone" value="label one"/><br />
<label id="labeltwo" value="label two"/><br />
<script defer="true"><br />
old = zul.wgt.Label.prototype.setValue; <br />
zul.wgt.Label.prototype.setValue = function (){<br />
arguments[0]="modified prototype"+arguments[0];<br />
old.apply(this,arguments);<br />
} <br />
</script><br />
<button label="change" onClick='labelone.setValue((new Date()).toString());labeltwo.setValue((new Date()).toString());'/> <br />
</window><br />
</source><br />
<br />
=== Override a Default Widget Method for Whole Application ===<br />
In additions to specifying the JavaScript code or file in each page, you can configure ZK to load one or more particular JavaScript files.<br />
<br />
First, you have to modify <code>zk.xml</code> to specify a so-called <i>lang-addon</i> XML file. For example,<br />
<br />
<source lang="xml"><br />
<zk><br />
......<br />
<language-config><br />
<addon-uri>/WEB-INF/mylabel-lang-addon.xml</addon-uri><br />
</language-config> <br />
......<br />
</zk><br />
</source><br />
<br />
Then, you can specify the JavaScript files to load with each ZK page in this XML file as follows.<br />
<br />
<source lang="xml"><br />
<?xml version="1.0" encoding="UTF-8"?><br />
<language-addon><br />
<language-name>xul/html</language-name><br />
<javascript src="/mylabel.js" charset="UTF-8"/> <br />
</language-addon><br />
</source><br />
<br />
The content of the JavaScript file, of course, could be anything you want. For example, if you want to customize the behavior of <javadoc directory="jsdoc">zul.wgt.Label</javadoc>, the JavaScript file could be as follows:<br />
<br />
<source lang="javascript"><br />
zk.afterLoad("zul.wgt",function(){<br />
old = zul.wgt.Label.prototype.setValue; <br />
zul.wgt.Label.prototype.setValue = function (){<br />
arguments[0]="lang-addon "+arguments[0];<br />
old.apply(this,arguments);<br />
} <br />
});<br />
</source><br />
<br />
Notice that it is important to use <javadoc method="afterLoad(_global_.String, _global_.Function)" directory="jsdoc">_global_.zk</javadoc> to specify the customization code, since ZK JavaScript packages are loaded only when required. In other words, the customization code has to wait until the package is loaded. In this example, we have to wait for the zul.wgt package being loaded to execute the customization code.<br />
<br />
===Define a New Widget Method===<br />
For example, in [[Small_Talks/2009/July/ZK_5.0_and_Server%2BClient_Fusion|ZK 5.0 and Server+Client Fusion]], we defined an <code>update</code> function for <code>listbox</code><br />
<br />
<source lang="xml"><br />
<zk xmlns:w="http://www.zkoss.org/2005/zk/client"><br />
....<br />
<listbox id="list" rows="10" width="300px"><br />
<attribute w:name="update"><![CDATA[<br />
....<br />
]]></attribute><br />
</listbox><br />
</source><br />
<br />
===Define a DOM Attribute===<br />
<br />
[Since 5.0.3]<br />
<br />
Sometimes we need to specify a DOM attribute that is not generated by a ZK widget. It can be done by use the client-attribute namespace: <cdoe>http://www.zkoss.org/2005/zk/client/attribute"</code>. For example, if you want to generate the onload attribute for the iframe component, then you can do as follows:<br />
<br />
<source lang="xml"><br />
<iframe src="http://www.google.com" width="100%" height="300px"<br />
xmlns:wa="http://www.zkoss.org/2005/zk/client/attribute"<br />
wa:onload="alert(window.location.href)"/><br />
</source><br />
<br />
The generate DOM element will then have an attribute called <code>onload</code>.<br />
<br />
===Specify a Different Widget Class===<br />
<br />
You could specify your own implementation instead of the default widget class (at the client) as follows.<br />
<br />
<source lang="xml"><br />
<zk xmlns:w="http://www.zkoss.org/2005/zk/client"><br />
...<br />
<button w:use="foo.MyButton"/><br />
</zk><br />
</source><br />
<br />
where <code>foo.MyButton</code> is a widget you implement. For example,<br />
<br />
<source lang="javascript"><br />
zk.$package("foo").MyButton = zk.$extends(zul.wgt.Button, {<br />
setLabel: function (label) {<br />
this.$supers("setLabel", arguments);<br />
//do whatever you want<br />
}<br />
});<br />
</source><br />
<br />
=== ''Watch''': ZK Client Engine Event ===<br />
To implement a ZK widget, traditional DOM events are not enough. Therefore, ZK defines extra widget related events like <code>onHide</code>,<code>onFloatUp</code> and system-level events such as '''watch'''. ZK provide its mechanism to fire and listen to '''watch'''.<br />
<source lang="xml"><br />
<window xmlns:w="http://www.zkoss.org/2005/zk/client"><br />
<button label="show" onClick="b1.setVisible(true);" /><br />
<button label="hide" onClick="b1.setVisible(false);" /><br />
<!--<br />
onShow is not called when first time rendering.<br />
It is called while setVisible="false", and then setVisible="true" <br />
--><br />
<button label="if onShow" id="b1"<br />
style="position:relative;zoom:1"><br />
<attribute w:name="onShow"><br />
alert("listened to onShow");<br />
</attribute><br />
<attribute w:name="bind_"><br />
function () { this.$bind_(); zWatch.listen({onShow: this});}<br />
</attribute><br />
</button><br />
</window><br />
</source><br />
<references/><br />
<br />
=== Use Third Party JavaScript Library ===<br />
[[Small_Talks/2009/July/ZK_5.0_and_jQuery_part_2|ZK 5.0 and jQuery part 2]] demonstrates how to utilize [http://jqueryui.com jQuery UI Tools] for low-level interaction, animation and more.<br />
<br />
=== Listen to DOM event ===<br />
For more sophisticated control, you can listen to DOM events. The following example demonstrates two different ways to handle the <code>onblur</code> event. <br />
<source lang="xml"><br />
<window title="listen dom event" border="normal"<br />
xmlns:w="http://www.zkoss.org/2005/zk/client"><br />
<textbox value="onBlur to alert" w:onBlur="alert('onBlur by zk')" /><br />
<textbox value="onblur to alert"><br />
<attribute w:name="bind_"><br />
function () { <br />
this.$bind_(); <br />
jq(this).bind('blur',function(event){alert('blurred by jquery')});<br />
}<br />
</attribute><br />
</textbox><br />
</window><br />
</source><br />
<br />
=== Animation ===<br />
Please visit [http://www.zkoss.org/zkdemo/userguide/ ZK Live Demo] and search for "animations". The following is a simplified example.<br />
<source lang="xml"><br />
<zk xmlns:w="http://www.zkoss.org/2005/zk/client"><br />
<button label="slideDown"<br />
w:onClick="jq(this.$f('t')).hide().slideDown()" /><br />
<div id="t"><br />
<button label="target" /><br />
</div><br />
</zk><br />
</source><br />
<br />
* Since 5.0.2, there is an alternative way to look for a fellow:<br />
<br />
<source lang="javascript"><br />
this.$f().fellowId<br />
</source><br />
<br />
=== Communicate to Server ===<br />
<javadoc directory="jsdoc">_global_.zAu</javadoc> is an utility to communicate with the server. In other words, it handles AU requests and responses. The following example sends a customized <code>onUser</code> event to the server.<br />
<br />
<source lang="xml" ><br />
<window><br />
<html onUser='l.value ="onUser "+org.zkoss.lang.Objects.toString(event.data)'><![CDATA[<br />
<a href="javascript:;" onclick="zAu.send(new zk.Event(zk.Widget.$(this), 'onUser',[1,2]));">onUser with [1, 2]</a><br />
]]></html> <br />
<label id="l"/> <br />
</window><br />
</source><br />
<br />
== Summary ==<br />
The ability to do client side programming allows developers to easily access and control ZK widgets. ZK retains its server-centric philosophy for productivity but enhances the controllability at client side with this capability; making it just as customizable as any client centric framework. The possibilities are limiteless.<br />
<br />
== Download ==<br />
I've created a project named [http://code.google.com/p/zk-sample/ zk-sample] host on google code. The related sample code can be found on its repository.<br />
<br />
== See Also ==<br />
*[[ZK Client-side Reference/General Control|ZK Client-side Reference]]<br />
#[[Small_Talks/2009/July/ZK_5.0_and_Server%2BClient_Fusion|ZK 5.0 and Server+Client Fusion]]<br />
#[[Small_Talks/2009/July/ZK_5.0_and_jQuery|ZK 5.0 and jQuery]]<br />
#[[Small_Talks/2009/July/ZK_5.0_and_jQuery_part_2|ZK 5.0 and jQuery part 2]]<br />
#[http://books.zkoss.org/wiki/ZK_Client-side_Reference/General_Control ZK5: Client Computing with ZUML]<br />
#<javadoc directory="jsdoc">_global_.jq</javadoc> -- jQuery selector for ZK widget.<br />
#<javadoc directory="jsdoc">zk.Widget</javadoc> -- See the usage of $f(), $n(), bind_(), $()<br />
#[[ZK Client-side Reference/Notifications/Client Activity Watches|Client Activity Watches]] -- onShow, onHide in ZK5<br />
#[http://www.zkoss.org/javadoc/latest/jsdoc/ JavaScript API] -- Documentation for ZK JavaScript API.<br />
#[http://www.zkoss.org/forum/listComment/12420 Customizing Error Box] -- from Forum<br />
#[http://www.zkoss.org/forum/listComment/12445 How to position image after label text on each tab of tabbox?] -- from Forum, modify domContent_ is a good way to customize a little bit.<br />
<br />
[[Category:Small Talk]]<br />
{{Template:CommentedSmalltalk_Footer|<br />
|name=Potix Corporation <br />
}}</div>Charhttps://www.zkoss.org/_w/index.php?title=ZK_Component_Reference/Essential_Components/Applet&diff=15274ZK Component Reference/Essential Components/Applet2010-12-21T04:52:43Z<p>Char: /* Employment/Purpose */</p>
<hr />
<div>{{ZKComponentReferencePageHeader}}<br />
<br />
= Applet =<br />
<br />
*Demonstration: N/A<br />
*Java API: <javadoc>org.zkoss.zul.Applet</javadoc><br />
*JavaScript API: <javadoc directory="jsdoc">zul.med.Applet</javadoc><br />
*Style Guide: N/A<br />
<br />
= Employment/Purpose =<br />
<br />
A generic applet component.<br />
<br />
If the properties are not enough, you can use [http://books.zkoss.org/wiki/ZK_Configuration_Reference/zk.xml/The_client-config_Element the Client-Attribute namespace] to specify them.<br />
<br />
<source lang="xml"><br />
<applet xmlns:ca="http://www.zkoss.org/2005/zk/client/attribute"<br />
ca:whatever_name="whatever_value"/><br />
</source><br />
<br />
<br />
=== Archive and Codebase ===<br />
<br />
Since 5.0.3, both <code>archive</code> and <code>codebase</code> properties are encoded with the application's context path and URL rewriting, so you don't and shall not encode it again.<br />
<br />
= Example =<br />
<br />
[[Image:ZKComRef_Applet_Examples.PNG]] <br />
<br />
<source lang="xml" ><br />
<applet codebase="img/" code="ticker.class" msg="ZK is Simple and Rich!" width="580px" /><br />
</source><br />
<br />
=Supported Events=<br />
<br />
{| border="1" | width="100%"<br />
! <center>Name</center><br />
! <center>Event Type</center><br />
|-<br />
| None<br />
| None<br />
|}<br />
*Inherited Supported Events: [[ZK_Component_Reference/Base_Components/HtmlBasedComponent#Supported_Events | HtmlBasedComponent]]<br />
<br />
=Supported Children=<br />
<br />
*NONE<br />
<br />
=Use Cases=<br />
<br />
{| border='1px' | width="100%"<br />
! Version !! Description !! Example Location<br />
|-<br />
| &nbsp;<br />
| &nbsp;<br />
| &nbsp;<br />
|}<br />
<br />
=Version History=<br />
{{LastUpdated}}<br />
{| border='1px' | width="100%"<br />
! Version !! Date !! Content<br />
|-<br />
| 5.0.3<br />
| June 2010<br />
| The archive, myscript, align, hspace, and vspace properties are supported<br />
|}<br />
<br />
{{ZKComponentReferencePageFooter}}</div>Charhttps://www.zkoss.org/_w/index.php?title=Small_Talks/2010/April/Client_Side_Programming&diff=15273Small Talks/2010/April/Client Side Programming2010-12-21T04:50:50Z<p>Char: /* Define a Client-side Listener of ZK Widget event */</p>
<hr />
<div>{{Template:Smalltalk_Author|<br />
|author=Peter Kuo, Engineer, Potix Corporation<br />
|date=April 20, 2010<br />
|version=ZK 5.0 and above<br />
}}<br />
<br />
== Introduction ==<br />
<br />
In ZK 5 we continue to focus on our strong Server-side approach which boosts your productivity but now provides developers the option to control the client side programming. We have dubbed this blending of technology, Server+client Fusion.<br />
<br />
In order to execute application-specific code at the client, ZK introduces the concept of the Client Namespace <ref>For ZK 3.6 and prior, please use [http://books.zkoss.org/wiki/ZK_Client-side_References Client Side Actions] instead.</ref>. With the Client Namespace, developers are able to listen to any client-side event, override ZK methods and execute any custom client-side code.<br />
<br />
----<br />
<references/><br />
<br />
== Before writing JavaScript in a ZUL file ==<br />
<br />
<br />
=== Define ZK Client Namespace ===<br />
In order to write client-side code, you are required to specify the XML namespace which is named http://www.zkoss.org/2005/zk/client. In the following example, you can see the <mp>onClick</mp> event is handled by client side JavaScript.<br />
<source lang="xml"><br />
<button label="client" xmlns:w="http://www.zkoss.org/2005/zk/client" w:onClick="alert('clicked')"/><br />
</source><br />
<br />
=== How to Get Widget Reference in JavaScript ===<br />
<br />
When the client event is invoked, you can reference the widget using <mp>this</mp>. In the below example this refers to the label.<br />
<br />
<source lang="xml"><br />
<window xmlns:w="http://www.zkoss.org/2005/zk/client"><br />
<label value="change me by click" w:onClick="this.setValue('clicked');"/> <br />
</window><br />
</source><br />
<br />
<javadoc directory="jsdoc">zk.widget</javadoc> can retrieve other widgets using the function <mp>$f</mp>. This works in a similar manner as <mp>getFellow</mp>. <br />
<br />
In additions, you can use jQuery to select a DOM element of a widget<ref>Since ZK 5.0.2</ref>. For example <code>jq("@window")</code> will select DOM elements of all window widget. And, <code>jq("$win1")</code> will select DOM elements of all widgets whose ID is <code>win1</code>. (see <javadoc directory="jsdoc">_global_.jq</javadoc>). <br />
<br />
<source lang="xml"><br />
<window xmlns:w="http://www.zkoss.org/2005/zk/client"><br />
<vbox><br />
<label id="labelone" value="click to change"<br />
w:onClick="this.setValue('changed by click label');" /><br />
<br />
<button label="button"<br />
w:onClick="this.$f('labelone').setValue('changed by button');" /><br />
<br />
<html><![CDATA[<br />
<a href="javascript:;" onclick="zk.Widget.$(jq('$labelone')[0]).setValue('changed with jq');">not widget</a><br />
]]></html> <br />
<br />
</vbox><br />
</window><br />
</source><br />
<br />
<code>zk.Widget.$</code> is a utility to return particular zk widget by given id of dom element. (see <javadoc directory="jsdoc">zk.Widget</javadoc>). <br />
<br />
----<br />
<references/><br />
<br />
=== Execute JavaScript After All Widgets Are Loaded ===<br />
Set <code>defer</code> attribute of <code>script</code> to "true", if you want to access widgets. It means deferring the execution of the script codes until the widget is instantiated and mounted. Note that <code>script</code> here is a zk component, not an HTML tag. Similarly, <code>defer</code> here is not in the same context as HTML . More detail at <javadoc>org.zkoss.zul.api.Script</javadoc>.<br />
<source lang="xml"><br />
<script defer="true"><br />
..........<br />
</script><br />
</source><br />
<br />
== Things you can do ==<br />
===Define a Client-side Listener of ZK Widget event===<br />
For example, handle <code>onClick</code> event of a <code>label</code> component's corresponding widget at the client side.<br />
<br />
<source lang="xml"><br />
<window xmlns:w="http://www.zkoss.org/2005/zk/client"><br />
<label value="change me by click" w:onClick="this.setValue('clicked');"/> <br />
</window><br />
</source><br />
<br />
In an event listener, you can access the widget by using <code>this</code> as shown above. In addition, you can access the event (an instance of <javadoc directory="jsdoc">zk.Event</javadoc>) by using <code>event</code>.<br />
<br />
You can find more detail at [[ZK Client-side Reference]] and [http://books.zkoss.org/wiki/ZK_Configuration_Reference/zk.xml/The_client-config_Element ZK5: Client Computing with ZUML].<br />
<br />
===Override a Widget Method===<br />
For example, override the <code>setValue</code> implementation of a <code>label</code> widget.<br />
<br />
<source lang="xml"><br />
<window xmlns:w="http://www.zkoss.org/2005/zk/client"><br />
<label><br />
<attribute w:name="setValue"><br />
function (value) {<br />
this.$setValue(value); //call the original method<br />
if (this.desktop) {<br />
this._flag = !this._flag;<br />
this.setStyle('background:'+(this._flag ? 'red':'green'));<br />
}<br />
}<br />
</attribute><br />
</label><br />
</window><br />
</source><br />
<br />
You can find more detail at [[ZK Client-side Reference]] and [http://docs.zkoss.org/wiki/ZK5:_Client_Computing_with_ZUML ZK5: Client Computing with ZUML].<br />
<br />
EL expressions is allowed <ref>EL expressions are allowed since ZK 5.0.2</ref><ref> EL is evaluated when rendering a page. In other words, it is evaluated before sending the JavaScript code to the client for execution later.</ref> to simplify the passing of data from server to client. For example, you could pass a Java bean's property to the client as shown below.<br />
<br />
<source lang="javascript"><br />
w:setValue='function (value) { this.$setValue(value + "${foo.description}")}';<br />
</source><br />
<br />
<references/><br />
<br />
=== Override a Default Widget Method ===<br />
In previous section, we showed how to override method of a particular widget we declared. But how to override the default widget method for all such widgets? We can modify it by overwriting the widget's <code>prototype</code> implementation. The following is a sample to modify the default <code>setValue</code> of <code>label</code><br />
<source lang="xml"><br />
<window xmlns:w="http://www.zkoss.org/2005/zk/client"><br />
<label id="labelone" value="label one"/><br />
<label id="labeltwo" value="label two"/><br />
<script defer="true"><br />
old = zul.wgt.Label.prototype.setValue; <br />
zul.wgt.Label.prototype.setValue = function (){<br />
arguments[0]="modified prototype"+arguments[0];<br />
old.apply(this,arguments);<br />
} <br />
</script><br />
<button label="change" onClick='labelone.setValue((new Date()).toString());labeltwo.setValue((new Date()).toString());'/> <br />
</window><br />
</source><br />
<br />
=== Override a Default Widget Method for Whole Application ===<br />
In additions to specifying the JavaScript code or file in each page, you can configure ZK to load one or more particular JavaScript files.<br />
<br />
First, you have to modify <code>zk.xml</code> to specify a so-called <i>lang-addon</i> XML file. For example,<br />
<br />
<source lang="xml"><br />
<zk><br />
......<br />
<language-config><br />
<addon-uri>/WEB-INF/mylabel-lang-addon.xml</addon-uri><br />
</language-config> <br />
......<br />
</zk><br />
</source><br />
<br />
Then, you can specify the JavaScript files to load with each ZK page in this XML file as follows.<br />
<br />
<source lang="xml"><br />
<?xml version="1.0" encoding="UTF-8"?><br />
<language-addon><br />
<language-name>xul/html</language-name><br />
<javascript src="/mylabel.js" charset="UTF-8"/> <br />
</language-addon><br />
</source><br />
<br />
The content of the JavaScript file, of course, could be anything you want. For example, if you want to customize the behavior of <javadoc directory="jsdoc">zul.wgt.Label</javadoc>, the JavaScript file could be as follows:<br />
<br />
<source lang="javascript"><br />
zk.afterLoad("zul.wgt",function(){<br />
old = zul.wgt.Label.prototype.setValue; <br />
zul.wgt.Label.prototype.setValue = function (){<br />
arguments[0]="lang-addon "+arguments[0];<br />
old.apply(this,arguments);<br />
} <br />
});<br />
</source><br />
<br />
Notice that it is important to use <javadoc method="afterLoad(_global_.String, _global_.Function)" directory="jsdoc">_global_.zk</javadoc> to specify the customization code, since ZK JavaScript packages are loaded only when required. In other words, the customization code has to wait until the package is loaded. In this example, we have to wait for the zul.wgt package being loaded to execute the customization code.<br />
<br />
===Define a New Widget Method===<br />
For example, in [[Small_Talks/2009/July/ZK_5.0_and_Server%2BClient_Fusion|ZK 5.0 and Server+Client Fusion]], we defined an <code>update</code> function for <code>listbox</code><br />
<br />
<source lang="xml"><br />
<zk xmlns:w="http://www.zkoss.org/2005/zk/client"><br />
....<br />
<listbox id="list" rows="10" width="300px"><br />
<attribute w:name="update"><![CDATA[<br />
....<br />
]]></attribute><br />
</listbox><br />
</source><br />
<br />
===Define a DOM Attribute===<br />
<br />
[Since 5.0.3]<br />
<br />
Sometimes we need to specify a DOM attribute that is not generated by a ZK widget. It can be done by use the client-attribute namespace: <cdoe>http://www.zkoss.org/2005/zk/client/attribute"</code>. For example, if you want to generate the onload attribute for the iframe component, then you can do as follows:<br />
<br />
<source lang="xml"><br />
<iframe src="http://www.google.com" width="100%" height="300px"<br />
xmlns:wa="http://www.zkoss.org/2005/zk/client/attribute"<br />
wa:onload="alert(window.location.href)"/><br />
</source><br />
<br />
The generate DOM element will then have an attribute called <code>onload</code>.<br />
<br />
===Specify a Different Widget Class===<br />
<br />
You could specify your own implementation instead of the default widget class (at the client) as follows.<br />
<br />
<source lang="xml"><br />
<zk xmlns:w="http://www.zkoss.org/2005/zk/client"><br />
...<br />
<button w:use="foo.MyButton"/><br />
</zk><br />
</source><br />
<br />
where <code>foo.MyButton</code> is a widget you implement. For example,<br />
<br />
<source lang="javascript"><br />
zk.$package("foo").MyButton = zk.$extends(zul.wgt.Button, {<br />
setLabel: function (label) {<br />
this.$supers("setLabel", arguments);<br />
//do whatever you want<br />
}<br />
});<br />
</source><br />
<br />
=== ''Watch''': ZK Client Engine Event ===<br />
To implement a ZK widget, traditional DOM events are not enough. Therefore, ZK defines extra widget related events like <code>onHide</code>,<code>onFloatUp</code> and system-level events such as '''watch'''. ZK provide its mechanism to fire and listen to '''watch'''.<br />
<source lang="xml"><br />
<window xmlns:w="http://www.zkoss.org/2005/zk/client"><br />
<button label="show" onClick="b1.setVisible(true);" /><br />
<button label="hide" onClick="b1.setVisible(false);" /><br />
<!--<br />
onShow is not called when first time rendering.<br />
It is called while setVisible="false", and then setVisible="true" <br />
--><br />
<button label="if onShow" id="b1"<br />
style="position:relative;zoom:1"><br />
<attribute w:name="onShow"><br />
alert("listened to onShow");<br />
</attribute><br />
<attribute w:name="bind_"><br />
function () { this.$bind_(); zWatch.listen({onShow: this});}<br />
</attribute><br />
</button><br />
</window><br />
</source><br />
<references/><br />
<br />
=== Use Third Party JavaScript Library ===<br />
[[Small_Talks/2009/July/ZK_5.0_and_jQuery_part_2|ZK 5.0 and jQuery part 2]] demonstrates how to utilize [http://jqueryui.com jQuery UI Tools] for low-level interaction, animation and more.<br />
<br />
=== Listen to DOM event ===<br />
For more sophisticated control, you can listen to DOM events. The following example demonstrates two different ways to handle the <code>onblur</code> event. <br />
<source lang="xml"><br />
<window title="listen dom event" border="normal"<br />
xmlns:w="http://www.zkoss.org/2005/zk/client"><br />
<textbox value="onBlur to alert" w:onBlur="alert('onBlur by zk')" /><br />
<textbox value="onblur to alert"><br />
<attribute w:name="bind_"><br />
function () { <br />
this.$bind_(); <br />
jq(this).bind('blur',function(event){alert('blurred by jquery')});<br />
}<br />
</attribute><br />
</textbox><br />
</window><br />
</source><br />
<br />
=== Animation ===<br />
Please visit [http://www.zkoss.org/zkdemo/userguide/ ZK Live Demo] and search for "animations". The following is a simplified example.<br />
<source lang="xml"><br />
<zk xmlns:w="http://www.zkoss.org/2005/zk/client"><br />
<button label="slideDown"<br />
w:onClick="jq(this.$f('t')).hide().slideDown()" /><br />
<div id="t"><br />
<button label="target" /><br />
</div><br />
</zk><br />
</source><br />
<br />
* Since 5.0.2, there is an alternative way to look for a fellow:<br />
<br />
<source lang="javascript"><br />
this.$f().fellowId<br />
</source><br />
<br />
=== Communicate to Server ===<br />
<javadoc directory="jsdoc">_global_.zAu</javadoc> is an utility to communicate with the server. In other words, it handles AU requests and responses. The following example sends a customized <code>onUser</code> event to the server.<br />
<br />
<source lang="xml" ><br />
<window><br />
<html onUser='l.value ="onUser "+org.zkoss.lang.Objects.toString(event.data)'><![CDATA[<br />
<a href="javascript:;" onclick="zAu.send(new zk.Event(zk.Widget.$(this), 'onUser',[1,2]));">onUser with [1, 2]</a><br />
]]></html> <br />
<label id="l"/> <br />
</window><br />
</source><br />
<br />
== Summary ==<br />
The ability to do client side programming allows developers to easily access and control ZK widgets. ZK retains its server-centric philosophy for productivity but enhances the controllability at client side with this capability; making it just as customizable as any client centric framework. The possibilities are limiteless.<br />
<br />
== Download ==<br />
I've created a project named [http://code.google.com/p/zk-sample/ zk-sample] host on google code. The related sample code can be found on its repository.<br />
<br />
== See Also ==<br />
*[[ZK Client-side Reference/General Control|ZK Client-side Reference]]<br />
#[[Small_Talks/2009/July/ZK_5.0_and_Server%2BClient_Fusion|ZK 5.0 and Server+Client Fusion]]<br />
#[[Small_Talks/2009/July/ZK_5.0_and_jQuery|ZK 5.0 and jQuery]]<br />
#[[Small_Talks/2009/July/ZK_5.0_and_jQuery_part_2|ZK 5.0 and jQuery part 2]]<br />
#[http://books.zkoss.org/wiki/ZK_Client-side_Reference/General_Control ZK5: Client Computing with ZUML]<br />
#<javadoc directory="jsdoc">_global_.jq</javadoc> -- jQuery selector for ZK widget.<br />
#<javadoc directory="jsdoc">zk.Widget</javadoc> -- See the usage of $f(), $n(), bind_(), $()<br />
#[[ZK Client-side Reference/Notifications/Client Activity Watches|Client Activity Watches]] -- onShow, onHide in ZK5<br />
#[http://www.zkoss.org/javadoc/latest/jsdoc/ JavaScript API] -- Documentation for ZK JavaScript API.<br />
#[http://www.zkoss.org/forum/listComment/12420 Customizing Error Box] -- from Forum<br />
#[http://www.zkoss.org/forum/listComment/12445 How to position image after label text on each tab of tabbox?] -- from Forum, modify domContent_ is a good way to customize a little bit.<br />
<br />
[[Category:Small Talk]]<br />
{{Template:CommentedSmalltalk_Footer|<br />
|name=Potix Corporation <br />
}}</div>Charhttps://www.zkoss.org/_w/index.php?title=ZK_Developer%27s_Reference/Theming_and_Styling/Understanding_the_Theming_Subsystem/Providing_Theme_Resources&diff=15271ZK Developer's Reference/Theming and Styling/Understanding the Theming Subsystem/Providing Theme Resources2010-12-21T04:30:20Z<p>Char: </p>
<hr />
<div>{{ZKDevelopersReferencePageHeader}}<br />
<br />
__TOC__<br />
<br />
A theme provider (<javadoc type="interface">org.zkoss.zk.ui.util.ThemeProvider</javadoc>) allows you the full control of CSS styling, including but not limited to<br />
<br />
* Allow you to switch among multiple themes based on, say, the user's preference, cookie, locale or others<br />
* Replace the CSS styling of particular component(s) with your own customization<br />
* Add additional CSS files<br />
<br />
We illustrate the theme provider with two examples. One is straightforward: set the corresponding attributes based on the cookie. The other '''injects''' a fragment to the URI such that we can allow the browser to cache the CSS file.<br />
<br />
<blockquote><br />
----<br />
For information of 3.6 and earlier, please refer to [http://books.zkoss.org/wiki/Theme#ZK_3_Theme_Provider ZK 3 Theme Provider].<br />
</blockquote><br />
<br />
=Examples=<br />
== A Simple Example ==<br />
In the following example, we store the preferred font size and the skin (theme) in the cookie and retrieve them when required.<br />
<br />
<source lang="java"><br />
package my;<br />
public class MyThemeProvider implements ThemeProvder {<br />
public Collection getThemeURIs(Execution exec, List uris) {<br />
if ("silvergray".equals(getSkinCookie(exec))) {<br />
uris.add("~./silvergray/color.css.dsp");<br />
uris.add("~./silvergray/img.css.dsp");<br />
}<br />
return uris;<br />
}<br />
public int getWCSCacheControl(Execution exec, String uri) {<br />
return -1;<br />
}<br />
public String beforeWCS(Execution exec, String uri) {<br />
final String fsc = getFontSizeCookie(exec);<br />
if ("lg".equals(fsc)) {<br />
exec.setAttribute("fontSizeM", "15px");<br />
exec.setAttribute("fontSizeMS", "13px");<br />
exec.setAttribute("fontSizeS", "13px");<br />
exec.setAttribute("fontSizeXS", "12px");<br />
} else if ("sm".equals(fsc)) {<br />
exec.setAttribute("fontSizeM", "10px");<br />
exec.setAttribute("fontSizeMS", "9px");<br />
exec.setAttribute("fontSizeS", "9px");<br />
exec.setAttribute("fontSizeXS", "8px");<br />
}<br />
return uri;<br />
}<br />
public String beforeWidgetCSS(Execution exec, String uri) {<br />
return uri;<br />
}<br />
/** Returns the font size specified in cooke. */<br />
private static String getFontSizeCookie(Execution exec) {<br />
Cookie[] cookies = ((HttpServletRequest)exec.getNativeRequest()).getCookies();<br />
if (cookies!=null)<br />
for (int i=0; i<cookies.length; i++)<br />
if ("myfontsize".equals(cookies[i].getName()))<br />
return cookies[i].getValue();<br />
return "";<br />
}<br />
/** Returns the skin specified in cookie. */<br />
private static String getSkinCookie(Execution exec) {<br />
Cookie[] cookies = ((HttpServletRequest)exec.getNativeRequest()).getCookies();<br />
if (cookies!=null)<br />
for (int i=0; i<cookies.length; i++)<br />
if ("myskin".equals(cookies[i].getName()))<br />
return cookies[i].getValue();<br />
return "";<br />
}<br />
}<br />
</source><br />
<br />
Notice that we return -1 when <javadoc type="interface" method="getWCSCacheControl(org.zkoss.zk.ui.Execution, java.lang.String)">org.zkoss.zk.ui.util.ThemeProvider</javadoc> is called to disallow the browser to cache the CSS file. It is necessary since we manipulate the content of the CSS file by setting the attributes (based on the cookie). It means the content might be different with the same request URL. For a cacheable example, please refer to [[#A Cacheable Example|the next section]].<br />
<br />
Then, you configure <tt>WEB-INF/zk.xml</tt> by adding the following lines.<br />
<br />
<source lang="xml" ><br />
<desktop-config><br />
<theme-provider-class>my.MyThemeProvider</theme-provider-class><br />
</desktop-config><br />
</source><br />
<br />
== A Cacheable Example ==<br />
<br />
To improve the performance, it is better to allow the browser to cache the CSS file as long as possible. With the theme provider, it can be done by returning a positive number when <javadoc type="interface" method="getWCSCacheControl(org.zkoss.zk.ui.Execution, java.lang.String)">org.zkoss.zk.ui.util.ThemeProvider</javadoc> is called. However, because the browser will use the cached version, we have to ensure the browser gets a different URL for each different theme. Here is we illustrate a technique called '''fragment injection'''.<br />
<br />
The idea is simple: when <javadoc type="interface" method="getThemeURIs(org.zkoss.zk.ui.Execution, java.util.List)">org.zkoss.zk.ui.util.ThemeProvider</javadoc> is called, we '''inject''' a special fragment to denote the content, such that each different theme is represented with a different URL. The injection can be done easily with the inner class called <javadoc>org.zkoss.zk.ui.util.ThemeProvider.Aide</javadoc>. For example,<br />
<br />
<source lang="java"><br />
final String fsc = getFontSizeCookie(exec);<br />
if (fsc != null && fsc.length() > 0) {<br />
for (ListIterator it = uris.listIterator(); it.hasNext();) {<br />
final String uri = (String)it.next();<br />
if (uri.startsWith(DEFAULT_WCS)) {<br />
it.set(Aide.injectURI(uri, fsc));<br />
break;<br />
}<br />
}<br />
}<br />
</source><br />
<br />
Then, we can retrieve the fragment we encoded into the URI later when <javadoc type="interface" method="beforeWCS(org.zkoss.zk.ui.Execution, java.lang.String)">org.zkoss.zk.ui.util.ThemeProvider</javadoc> is called. It can be done easily by use of <javadoc method="decodeURI(java.lang.String)">org.zkoss.zk.ui.util.ThemeProvider.Aide</javadoc>. <javadoc method="decodeURI(java.lang.String)">org.zkoss.zk.ui.util.ThemeProvider.Aide</javadoc> returns a two-element array if the fragment is found. The first element is the URI without fragment, and the second element is the fragment. For example,<br />
<br />
<source lang="java"><br />
public String beforeWCS(Execution exec, String uri) {<br />
final String[] dec = Aide.decodeURI(uri);<br />
if (dec != null) {<br />
if ("lg".equals(dec[1])) {<br />
exec.setAttribute("fontSizeM", "15px");<br />
exec.setAttribute("fontSizeMS", "13px");<br />
exec.setAttribute("fontSizeS", "13px");<br />
exec.setAttribute("fontSizeXS", "12px");<br />
} else if ("sm".equals(dec[1])) {<br />
exec.setAttribute("fontSizeM", "10px");<br />
exec.setAttribute("fontSizeMS", "9px");<br />
exec.setAttribute("fontSizeS", "9px");<br />
exec.setAttribute("fontSizeXS", "8px");<br />
}<br />
return dec[0];<br />
}<br />
return uri;<br />
}<br />
</source><br />
<br />
Here is a complete example:<br />
<br />
<source lang="java"><br />
public class CacheableThemeProvider implements ThemeProvider{<br />
private static String DEFAULT_WCS = "~./zul/css/zk.wcs";<br />
<br />
public Collection getThemeURIs(Execution exec, List uris) {<br />
//font-size<br />
final String fsc = getFontSizeCookie(exec);<br />
if (fsc != null && fsc.length() > 0) {<br />
for (ListIterator it = uris.listIterator(); it.hasNext();) {<br />
final String uri = (String)it.next();<br />
if (uri.startsWith(DEFAULT_WCS)) {<br />
it.set(Aide.injectURI(uri, fsc));<br />
break;<br />
}<br />
}<br />
}<br />
<br />
//slivergray<br />
if ("silvergray".equals(getSkinCookie(exec))) {<br />
uris.add("~./silvergray/color.css.dsp");<br />
uris.add("~./silvergray/img.css.dsp");<br />
}<br />
return uris;<br />
}<br />
<br />
public int getWCSCacheControl(Execution exec, String uri) {<br />
return 8760; //safe to cache<br />
}<br />
public String beforeWCS(Execution exec, String uri) {<br />
final String[] dec = Aide.decodeURI(uri);<br />
if (dec != null) {<br />
if ("lg".equals(dec[1])) {<br />
exec.setAttribute("fontSizeM", "15px");<br />
exec.setAttribute("fontSizeMS", "13px");<br />
exec.setAttribute("fontSizeS", "13px");<br />
exec.setAttribute("fontSizeXS", "12px");<br />
} else if ("sm".equals(dec[1])) {<br />
exec.setAttribute("fontSizeM", "10px");<br />
exec.setAttribute("fontSizeMS", "9px");<br />
exec.setAttribute("fontSizeS", "9px");<br />
exec.setAttribute("fontSizeXS", "8px");<br />
}<br />
return dec[0];<br />
}<br />
return uri;<br />
}<br />
<br />
public String beforeWidgetCSS(Execution exec, String uri) {<br />
return uri;<br />
}<br />
<br />
/** Returns the font size specified in cooke. */<br />
private static String getFontSizeCookie(Execution exec) {<br />
Cookie[] cookies = ((HttpServletRequest)exec.getNativeRequest()).getCookies();<br />
if (cookies!=null)<br />
for (int i=0; i<cookies.length; i++)<br />
if ("myfontsize".equals(cookies[i].getName()))<br />
return cookies[i].getValue();<br />
return "";<br />
}<br />
/** Returns the skin specified in cookie. */<br />
private static String getSkinCookie(Execution exec) {<br />
Cookie[] cookies = ((HttpServletRequest)exec.getNativeRequest()).getCookies();<br />
if (cookies!=null)<br />
for (int i=0; i<cookies.length; i++)<br />
if ("myskin".equals(cookies[i].getName()))<br />
return cookies[i].getValue();<br />
return "";<br />
}<br />
}<br />
</source><br />
<br />
= How to Specify the Media Types =<br />
<br />
In additions to String instances, you can return instances of <javadoc>org.zkoss.web.servlet.StyleSheet</javadoc> in the returned collection of <javadoc method="getThemeURIs(org.zkoss.zk.ui.Execution,java.util.List)">org.zkoss.zk.ui.util.ThemeProvider</javadoc>, such that you can control more about the generated CSS link. For example, if you want to add a CSS link for [http://www.w3.org/TR/CSS2/media.html the media type], say, <code>print, handheld</code>, then you can do as follows.<br />
<br />
<source lang="java"><br />
public Collection getThemeURIs(Execution exec, List uris) {<br />
uris.add(new StyleSheet("/theme/foo.css", "text/css", "print, handheld", false));<br />
return uris;<br />
}<br />
</source><br />
<br />
=Version History=<br />
{{LastUpdated}}<br />
{| border='1px' | width="100%"<br />
! Version !! Date !! Content<br />
|-<br />
| 5.0.3<br />
| June 2010<br />
| The media type was allowed in <javadoc>org.zkoss.web.servlet.StyleSheet</javadoc>.<br />
|}<br />
<br />
{{ZKDevelopersReferencePageFooter}}</div>Charhttps://www.zkoss.org/_w/index.php?title=ZK_Developer%27s_Guide/ZK_in_Depth/Style_Customization/Theme&diff=15267ZK Developer's Guide/ZK in Depth/Style Customization/Theme2010-12-21T03:59:34Z<p>Char: </p>
<hr />
<div>{{ZKDevelopersGuidePageHeader}}<br />
<br />
A [http://en.wikipedia.org/wiki/Theme_(computing) theme] is a preset package containing graphical appearance details, used to customize the look and feel of ZUML components.<br />
<br />
You can configure it to change font size/family. You can also use your own theme, or decide the theme at the run time through <tt>Theme Provider</tt>. <br />
Learn more: [http://books.zkoss.org/wiki/ZK_Developer's_Reference/Theming_and_Styling Theme]<br />
<br />
{{ ZKDevelopersGuidePageFooter}}</div>Charhttps://www.zkoss.org/_w/index.php?title=Small_Talks/2009/December/ZK_5:_Upgrade_Notes&diff=15261Small Talks/2009/December/ZK 5: Upgrade Notes2010-12-21T03:41:21Z<p>Char: /* Animation API deprecated */</p>
<hr />
<div>{{Template:Smalltalk_Author|<br />
|author= The ZK Team<br />
|date=December, 2009<br />
|version= ZK 3 to ZK 5<br />
}}<br />
<br />
<br />
= Overview =<br />
<br />
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.<br />
<br />
= Server-side Upgrade Notes =<br />
<br />
== Attributes and Namespace ==<br />
=== The return type of <tt>setAttribute</tt> and <tt>removeAttribute</tt> of session/execution/application changed (from <tt>void</tt> to <tt>Object</tt>) ===<br />
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.<br />
<br />
The new signature:<br />
<syntax lang="java"><br />
Object setAttribute(String name, Object value); //returns the previous value if any<br />
Object removeAttribute(String name); //return the previous value if any<br />
</syntax><br />
<br />
=== Namespace deprecated ===<br />
<br />
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.<br />
<br />
<syntax lang="xml"><br />
<variabls foo="better"/> <!-- deprecated --><br />
<custom-attribute foo="better" scope="space"/><br />
</syntax><br />
<br />
Furthermore, ZK 5 will search the attribute scopes for any variable specified in EL or <tt>zscript</tt>.<br />
<br />
<syntax lang="xml"><br />
<window><br />
<custom-attributes a="a" b="b"/> <!-- belongs to window's attribute scope --><br />
<div><br />
<custom-attributes b="B"/> <!-- belongs to div's attribute scope --><br />
${a} and ${b} <!-- result: a and B --><br />
<zscript><br />
String s = a + b; //result: aB<br />
</zscript><br />
</div><br />
</window><br />
</syntax><br />
<br />
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.<br />
<br />
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.<br />
<br />
=== The attribute scope of the ID space is the same of the space owner's attribute scope ===<br />
<br />
In the previous version, the space owner (such as <tt>window</tt>) has two attribute scopes. For example,<br />
<br />
<syntax lang="xml"><br />
<window><br />
<custom-attributes foo="a"/><br />
<div><br />
<custom-attributes foo="b" scope="space"/><br />
</div><br />
<br />
<zscript><br />
self.getAttribute("foo"); //returns a in ZK 3<br />
self.getAttribute("foo", self.SPACE_SCOPE); //returns b<br />
</zscript><br />
</window><br />
</syntax><br />
<br />
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>.<br />
<br />
== System Level Control ==<br />
<br />
=== Event processing thread disabled by default ===<br />
<br />
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 [[Performance tip#Use_the_Servlet_Thread_to_Process_Events]] for how to adjust your application. For example, the <tt>if</tt> clause in the following example is never true.<br />
<br />
<source lang="java" ><br />
if (Messagebox.show("Delete?", "Prompt", Messagebox.YES|Messagebox.NO,<br />
Messagebox.QUESTION) == Messagebox.YES) {<br />
this_never_executes();<br />
}<br />
</source><br />
<br />
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.<br />
<br />
<source lang="xml"><br />
<system-config><br />
<disable-event-thread>false</disable-event-thread><br />
</system-config><br />
</source><br />
<blockquote><br />
----<br />
<references/><br />
</blockquote><br />
<br />
=== The method of <tt>ComponentCloneListener</tt> changed ===<br />
<br />
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.<br />
<br />
<source lang="java"><br />
Object willClone(Component comp);<br />
</source><br />
<br />
=== The <tt>AuPocessor</tt> interface deprecated (replaced with <tt>AuExtension</tt>) ===<br />
<br />
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.<br />
<br />
=== The <tt>addRoot</tt>, <tt>removeRoot</tt>, <tt>moveRoot</tt>, <tt>addFellow</tt> and <tt>removeFellow</tt> methods of <tt>PageCtrl</tt> removed ===<br />
<br />
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>.<br />
<br />
=== The <tt>disable-behind-modal</tt> configuration disabled (always false) ===<br />
<br />
With ZK 5, there is no need to disable widgets that don't belong to the modal window, so this configuration is meaningless.<br />
<br />
== Component Use ==<br />
<br />
=== The <tt>include</tt> component's mode default to <tt>auto</tt> ===<br />
<br />
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<br />
<br />
<source lang="javascript"><br />
<include mode="defer" src="abc.zul"/><br />
</source><br />
<br />
Or, you can specify the following configuration in zk.xml to change the default mode for the whole application.<br />
<br />
<source lang="javascript"><br />
<library-property><br />
<name>org.zkoss.zul.include.mode</name><br />
<value>defer</value><br />
</library-property><br />
</source><br />
<br />
=== The <tt>a</tt> component introduced for HTML A ===<br />
<br />
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,<br />
<br />
<source lang="xml"><br />
Refer <a href="http://www.zkoss.org" label="ZK"/> for details.<br />
Or <a href="http://www.zkoss.org/zkdemo">ZK Demo</a>.<br />
</source><br />
<br />
=== CSS <tt>fixed-layout</tt> property default for <tt>grid</tt> and <tt>listbox</tt> ===<br />
<br />
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.<br />
<br />
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 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 ).<br />
<br />
<source lang="xml"><br />
<grid width="300px"><br />
<columns><br />
<column label="Order" width="20px"/><br />
<column label="Name" hflex="1"/><br />
<column label="Value" hflex="2"/><br />
</columns><br />
<rows><br />
<row><image src="foo.gif"/> username: <textbox/></row><br />
<row><image src="foo.gif"/> password: <textbox/></row><br />
</rows><br />
</grid><br />
</source><br />
<br />
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.<br />
<br />
<source lang="xml"><br />
<grid width="300px" sizedByContent="true"><br />
</source><br />
<br />
=== The <tt>alphafix</tt> mold of <tt>image</tt> and <tt>imagemap</tt> deprecated ===<br />
<br />
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.<br />
<br />
<source lang="javascript"><br />
<?script content="jq.IE6_ALPHAFIX='.png';"?><br />
</source><br />
<br />
In other words, just specify a regular expression to a JavaScript variable called <tt>jq.IE6_ALPHAFIX</tt>.<br />
<br />
=== The methods of <tt>ClientConstraint</tt> changed ===<br />
<br />
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.<br />
<br />
The typical way to implement the custom client validation is as follows.<br />
<br />
#Implementing a JavaString class, say, foo.MyValidator.<br />
<br />
#Implementing <tt>org.zkoss.zul.ClientConstraint</tt> such that<br />
<br />
<source lang="java"><br />
//Java<br />
String getClientConstraint() {<br />
return "new foo.MyValidator()";<br />
}<br />
String getClientPackages() {<br />
return "foo"; //the package name<br />
}<br />
</source><br />
<br />
=== <tt>SimpleConstraint</tt> performs all validations at client ===<br />
<br />
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,<br />
<br />
<source lang="javascript"><br />
<textbox constraint="/.+@.+\.[a-z]+/,server"/><br />
</source><br />
<br />
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>.<br />
<br />
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.<br />
<br />
<source lang="javascript"><br />
//JavaScript<br />
ClientServerConstraint = zk.$extends(zul.inp.SimpleConstraint, {<br />
serverValidate: true<br />
});<br />
</source><br />
<br />
<blockquote><br />
----<br />
<references/><br />
</blockquote><br />
<br />
=== Overlapped window within another overlapped window not cropped ===<br />
<br />
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.<br />
<br />
=== Meaning of hbox/vbox <tt>pack</tt> attribute follows XUL's specification ===<br />
<br />
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".<br />
<br />
== Component Styling ==<br />
<br />
=== The <tt>dynamic</tt> attribute of the <tt>style</tt> component deprecated ===<br />
<br />
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.<br />
<br />
=== The default mold of the <tt>button</tt> component changed to <tt>os</tt> ===<br />
<br />
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>.<br />
<br />
<source lang="xml"><br />
<library-property><br />
<name>org.zkoss.zul.Button.mold</name><br />
<value>trendy</value><br />
</library-property><br />
</source><br />
<br />
=== The default value of the <tt>zclass</tt> attribute more consistent (<tt>z-</tt> + component-name) ===<br />
<br />
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.<br />
<br />
The affected components are as follows.<br />
<br />
comboitem, bandpopup, groupfoot, listcell, listfoot,<br />
listfooter, listgroup, listgroupfoot, listhead, listheader,<br />
listitem, treecell, treechildren, treecol, treecols, treefoot,<br />
treefooter, treerow, table-children, and table-layout<br />
<br />
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>.<br />
<br />
=== Both <tt>Applet</tt> and <tt>Iframe</tt> extends from <tt>HtmlBasedComponent</tt> (instead of <tt>XulElement</tt>) ===<br />
<br />
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>.<br />
<br />
=== The <tt>ZKPrefix</tt> library property deprecated ===<br />
<br />
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.<br />
<br />
== Component Development ==<br />
<br />
The component development is changed. Refer to [[ZK5: Component Development Guide]] for details.<br />
<br />
= Client-side Upgrade Notes =<br />
<br />
The client is rewritten, so your customization have to rewrite, too.<br />
<br />
== Client-side Action deprecated ==<br />
<br />
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,<br />
<br />
<source lang="xml"><br />
<!-- ZK 3.x: Client Side Action --><br />
<textbox<br />
action="onfocus: window.action.show(#{help1}); onblur: window.action.hide(#{help1})" /><br />
<label id="help1" visible="false" value="This is help for text1." /><br />
</source><br />
<br />
can be replaced with<br />
<br />
<source lang="xml"><br />
<!-- ZK 5 --><br />
<textbox xmlns:w="http://www.zkoss.org/2005/zk/client"<br />
w:onFocus="jq(this.$f('help1')).fadeIn()" w:onBlur="jq(this.$f('help1')).fadeOut()"/><br />
<label id="help1" visible="false" value="This is help for text1." /><br />
</source><br />
<br />
== Animation API deprecated ==<br />
<br />
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,<br />
<br />
<source lang="xml"><br />
<!-- ZK 3.x: anima --><br />
<label sclass="ctl" value="SlideDown"<br />
action="onclick: zk.hide(#{t});anima.slideDown(#{t})"/><br />
</source><br />
<br />
<source lang="xml"><br />
<!- ZK 5: with jQury --><br />
<label sclass="ctl" value="SlideDown"<br />
w:onClick="jq(this.$f('t')).hide().slideDown()"<br />
xmlns:w="http://www.zkoss.org/2005/zk/client"/><br />
</source><br />
<br />
Please refer to [[ZK5: JavaScript API]] for the complete description of JavaScript API at the client.<br />
<br />
= See Also =<br />
*[[Small_Talks/2010/April/Upgrading_to_ZK_5 | Upgrading to ZK 5]]<br />
*A forum thread : [http://www.zkoss.org/forum/listComment/11094 Upgrade to ZK5 ]<br />
<br />
<br />
<comment>http://docs.zkoss.org/wiki/ZK_5:_Upgrade_Notes</comment><br />
<br />
<br />
{{Template:Smalltalk_Footer|<br />
|name=Potix Corporation <br />
}}</div>Charhttps://www.zkoss.org/_w/index.php?title=Small_Talks/2009/December/ZK_5:_Upgrade_Notes&diff=15258Small Talks/2009/December/ZK 5: Upgrade Notes2010-12-21T03:37:27Z<p>Char: /* Component Development */</p>
<hr />
<div>{{Template:Smalltalk_Author|<br />
|author= The ZK Team<br />
|date=December, 2009<br />
|version= ZK 3 to ZK 5<br />
}}<br />
<br />
<br />
= Overview =<br />
<br />
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.<br />
<br />
= Server-side Upgrade Notes =<br />
<br />
== Attributes and Namespace ==<br />
=== The return type of <tt>setAttribute</tt> and <tt>removeAttribute</tt> of session/execution/application changed (from <tt>void</tt> to <tt>Object</tt>) ===<br />
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.<br />
<br />
The new signature:<br />
<syntax lang="java"><br />
Object setAttribute(String name, Object value); //returns the previous value if any<br />
Object removeAttribute(String name); //return the previous value if any<br />
</syntax><br />
<br />
=== Namespace deprecated ===<br />
<br />
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.<br />
<br />
<syntax lang="xml"><br />
<variabls foo="better"/> <!-- deprecated --><br />
<custom-attribute foo="better" scope="space"/><br />
</syntax><br />
<br />
Furthermore, ZK 5 will search the attribute scopes for any variable specified in EL or <tt>zscript</tt>.<br />
<br />
<syntax lang="xml"><br />
<window><br />
<custom-attributes a="a" b="b"/> <!-- belongs to window's attribute scope --><br />
<div><br />
<custom-attributes b="B"/> <!-- belongs to div's attribute scope --><br />
${a} and ${b} <!-- result: a and B --><br />
<zscript><br />
String s = a + b; //result: aB<br />
</zscript><br />
</div><br />
</window><br />
</syntax><br />
<br />
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.<br />
<br />
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.<br />
<br />
=== The attribute scope of the ID space is the same of the space owner's attribute scope ===<br />
<br />
In the previous version, the space owner (such as <tt>window</tt>) has two attribute scopes. For example,<br />
<br />
<syntax lang="xml"><br />
<window><br />
<custom-attributes foo="a"/><br />
<div><br />
<custom-attributes foo="b" scope="space"/><br />
</div><br />
<br />
<zscript><br />
self.getAttribute("foo"); //returns a in ZK 3<br />
self.getAttribute("foo", self.SPACE_SCOPE); //returns b<br />
</zscript><br />
</window><br />
</syntax><br />
<br />
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>.<br />
<br />
== System Level Control ==<br />
<br />
=== Event processing thread disabled by default ===<br />
<br />
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 [[Performance tip#Use_the_Servlet_Thread_to_Process_Events]] for how to adjust your application. For example, the <tt>if</tt> clause in the following example is never true.<br />
<br />
<source lang="java" ><br />
if (Messagebox.show("Delete?", "Prompt", Messagebox.YES|Messagebox.NO,<br />
Messagebox.QUESTION) == Messagebox.YES) {<br />
this_never_executes();<br />
}<br />
</source><br />
<br />
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.<br />
<br />
<source lang="xml"><br />
<system-config><br />
<disable-event-thread>false</disable-event-thread><br />
</system-config><br />
</source><br />
<blockquote><br />
----<br />
<references/><br />
</blockquote><br />
<br />
=== The method of <tt>ComponentCloneListener</tt> changed ===<br />
<br />
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.<br />
<br />
<source lang="java"><br />
Object willClone(Component comp);<br />
</source><br />
<br />
=== The <tt>AuPocessor</tt> interface deprecated (replaced with <tt>AuExtension</tt>) ===<br />
<br />
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.<br />
<br />
=== The <tt>addRoot</tt>, <tt>removeRoot</tt>, <tt>moveRoot</tt>, <tt>addFellow</tt> and <tt>removeFellow</tt> methods of <tt>PageCtrl</tt> removed ===<br />
<br />
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>.<br />
<br />
=== The <tt>disable-behind-modal</tt> configuration disabled (always false) ===<br />
<br />
With ZK 5, there is no need to disable widgets that don't belong to the modal window, so this configuration is meaningless.<br />
<br />
== Component Use ==<br />
<br />
=== The <tt>include</tt> component's mode default to <tt>auto</tt> ===<br />
<br />
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<br />
<br />
<source lang="javascript"><br />
<include mode="defer" src="abc.zul"/><br />
</source><br />
<br />
Or, you can specify the following configuration in zk.xml to change the default mode for the whole application.<br />
<br />
<source lang="javascript"><br />
<library-property><br />
<name>org.zkoss.zul.include.mode</name><br />
<value>defer</value><br />
</library-property><br />
</source><br />
<br />
=== The <tt>a</tt> component introduced for HTML A ===<br />
<br />
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,<br />
<br />
<source lang="xml"><br />
Refer <a href="http://www.zkoss.org" label="ZK"/> for details.<br />
Or <a href="http://www.zkoss.org/zkdemo">ZK Demo</a>.<br />
</source><br />
<br />
=== CSS <tt>fixed-layout</tt> property default for <tt>grid</tt> and <tt>listbox</tt> ===<br />
<br />
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.<br />
<br />
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 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 ).<br />
<br />
<source lang="xml"><br />
<grid width="300px"><br />
<columns><br />
<column label="Order" width="20px"/><br />
<column label="Name" hflex="1"/><br />
<column label="Value" hflex="2"/><br />
</columns><br />
<rows><br />
<row><image src="foo.gif"/> username: <textbox/></row><br />
<row><image src="foo.gif"/> password: <textbox/></row><br />
</rows><br />
</grid><br />
</source><br />
<br />
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.<br />
<br />
<source lang="xml"><br />
<grid width="300px" sizedByContent="true"><br />
</source><br />
<br />
=== The <tt>alphafix</tt> mold of <tt>image</tt> and <tt>imagemap</tt> deprecated ===<br />
<br />
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.<br />
<br />
<source lang="javascript"><br />
<?script content="jq.IE6_ALPHAFIX='.png';"?><br />
</source><br />
<br />
In other words, just specify a regular expression to a JavaScript variable called <tt>jq.IE6_ALPHAFIX</tt>.<br />
<br />
=== The methods of <tt>ClientConstraint</tt> changed ===<br />
<br />
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.<br />
<br />
The typical way to implement the custom client validation is as follows.<br />
<br />
#Implementing a JavaString class, say, foo.MyValidator.<br />
<br />
#Implementing <tt>org.zkoss.zul.ClientConstraint</tt> such that<br />
<br />
<source lang="java"><br />
//Java<br />
String getClientConstraint() {<br />
return "new foo.MyValidator()";<br />
}<br />
String getClientPackages() {<br />
return "foo"; //the package name<br />
}<br />
</source><br />
<br />
=== <tt>SimpleConstraint</tt> performs all validations at client ===<br />
<br />
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,<br />
<br />
<source lang="javascript"><br />
<textbox constraint="/.+@.+\.[a-z]+/,server"/><br />
</source><br />
<br />
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>.<br />
<br />
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.<br />
<br />
<source lang="javascript"><br />
//JavaScript<br />
ClientServerConstraint = zk.$extends(zul.inp.SimpleConstraint, {<br />
serverValidate: true<br />
});<br />
</source><br />
<br />
<blockquote><br />
----<br />
<references/><br />
</blockquote><br />
<br />
=== Overlapped window within another overlapped window not cropped ===<br />
<br />
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.<br />
<br />
=== Meaning of hbox/vbox <tt>pack</tt> attribute follows XUL's specification ===<br />
<br />
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".<br />
<br />
== Component Styling ==<br />
<br />
=== The <tt>dynamic</tt> attribute of the <tt>style</tt> component deprecated ===<br />
<br />
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.<br />
<br />
=== The default mold of the <tt>button</tt> component changed to <tt>os</tt> ===<br />
<br />
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>.<br />
<br />
<source lang="xml"><br />
<library-property><br />
<name>org.zkoss.zul.Button.mold</name><br />
<value>trendy</value><br />
</library-property><br />
</source><br />
<br />
=== The default value of the <tt>zclass</tt> attribute more consistent (<tt>z-</tt> + component-name) ===<br />
<br />
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.<br />
<br />
The affected components are as follows.<br />
<br />
comboitem, bandpopup, groupfoot, listcell, listfoot,<br />
listfooter, listgroup, listgroupfoot, listhead, listheader,<br />
listitem, treecell, treechildren, treecol, treecols, treefoot,<br />
treefooter, treerow, table-children, and table-layout<br />
<br />
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>.<br />
<br />
=== Both <tt>Applet</tt> and <tt>Iframe</tt> extends from <tt>HtmlBasedComponent</tt> (instead of <tt>XulElement</tt>) ===<br />
<br />
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>.<br />
<br />
=== The <tt>ZKPrefix</tt> library property deprecated ===<br />
<br />
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.<br />
<br />
== Component Development ==<br />
<br />
The component development is changed. Refer to [[ZK5: Component Development Guide]] for details.<br />
<br />
= Client-side Upgrade Notes =<br />
<br />
The client is rewritten, so your customization have to rewrite, too.<br />
<br />
== Client-side Action deprecated ==<br />
<br />
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,<br />
<br />
<source lang="xml"><br />
<!-- ZK 3.x: Client Side Action --><br />
<textbox<br />
action="onfocus: window.action.show(#{help1}); onblur: window.action.hide(#{help1})" /><br />
<label id="help1" visible="false" value="This is help for text1." /><br />
</source><br />
<br />
can be replaced with<br />
<br />
<source lang="xml"><br />
<!-- ZK 5 --><br />
<textbox xmlns:w="http://www.zkoss.org/2005/zk/client"<br />
w:onFocus="jq(this.$f('help1')).fadeIn()" w:onBlur="jq(this.$f('help1')).fadeOut()"/><br />
<label id="help1" visible="false" value="This is help for text1." /><br />
</source><br />
<br />
== Animation API deprecated ==<br />
<br />
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,<br />
<br />
<source lang="xml"><br />
<!-- ZK 3.x: anima --><br />
<label sclass="ctl" value="SlideDown"<br />
action="onclick: zk.hide(#{t});anima.slideDown(#{t})"/><br />
</source><br />
<br />
<source lang="xml"><br />
<!- ZK 5: with jQury --><br />
<label sclass="ctl" value="SlideDown"<br />
w:onClick="jq(this.$f('t')).hide().slideDown()"<br />
xmlns:w="http://www.zkoss.org/2005/zk/client"/><br />
</source><br />
<br />
Please refer to [http://docs.zkoss.org/wiki/ZK5:_JavaScript_API ZK5: JavaScript API] for the complete description of JavaScript API at the client.<br />
<br />
= See Also =<br />
*[[Small_Talks/2010/April/Upgrading_to_ZK_5 | Upgrading to ZK 5]]<br />
*A forum thread : [http://www.zkoss.org/forum/listComment/11094 Upgrade to ZK5 ]<br />
<br />
<br />
<comment>http://docs.zkoss.org/wiki/ZK_5:_Upgrade_Notes</comment><br />
<br />
<br />
{{Template:Smalltalk_Footer|<br />
|name=Potix Corporation <br />
}}</div>Charhttps://www.zkoss.org/_w/index.php?title=Small_Talks/2009/December/ZK_5:_Upgrade_Notes&diff=15257Small Talks/2009/December/ZK 5: Upgrade Notes2010-12-21T03:36:34Z<p>Char: /* CSS fixed-layout property default for grid and listbox */</p>
<hr />
<div>{{Template:Smalltalk_Author|<br />
|author= The ZK Team<br />
|date=December, 2009<br />
|version= ZK 3 to ZK 5<br />
}}<br />
<br />
<br />
= Overview =<br />
<br />
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.<br />
<br />
= Server-side Upgrade Notes =<br />
<br />
== Attributes and Namespace ==<br />
=== The return type of <tt>setAttribute</tt> and <tt>removeAttribute</tt> of session/execution/application changed (from <tt>void</tt> to <tt>Object</tt>) ===<br />
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.<br />
<br />
The new signature:<br />
<syntax lang="java"><br />
Object setAttribute(String name, Object value); //returns the previous value if any<br />
Object removeAttribute(String name); //return the previous value if any<br />
</syntax><br />
<br />
=== Namespace deprecated ===<br />
<br />
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.<br />
<br />
<syntax lang="xml"><br />
<variabls foo="better"/> <!-- deprecated --><br />
<custom-attribute foo="better" scope="space"/><br />
</syntax><br />
<br />
Furthermore, ZK 5 will search the attribute scopes for any variable specified in EL or <tt>zscript</tt>.<br />
<br />
<syntax lang="xml"><br />
<window><br />
<custom-attributes a="a" b="b"/> <!-- belongs to window's attribute scope --><br />
<div><br />
<custom-attributes b="B"/> <!-- belongs to div's attribute scope --><br />
${a} and ${b} <!-- result: a and B --><br />
<zscript><br />
String s = a + b; //result: aB<br />
</zscript><br />
</div><br />
</window><br />
</syntax><br />
<br />
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.<br />
<br />
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.<br />
<br />
=== The attribute scope of the ID space is the same of the space owner's attribute scope ===<br />
<br />
In the previous version, the space owner (such as <tt>window</tt>) has two attribute scopes. For example,<br />
<br />
<syntax lang="xml"><br />
<window><br />
<custom-attributes foo="a"/><br />
<div><br />
<custom-attributes foo="b" scope="space"/><br />
</div><br />
<br />
<zscript><br />
self.getAttribute("foo"); //returns a in ZK 3<br />
self.getAttribute("foo", self.SPACE_SCOPE); //returns b<br />
</zscript><br />
</window><br />
</syntax><br />
<br />
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>.<br />
<br />
== System Level Control ==<br />
<br />
=== Event processing thread disabled by default ===<br />
<br />
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 [[Performance tip#Use_the_Servlet_Thread_to_Process_Events]] for how to adjust your application. For example, the <tt>if</tt> clause in the following example is never true.<br />
<br />
<source lang="java" ><br />
if (Messagebox.show("Delete?", "Prompt", Messagebox.YES|Messagebox.NO,<br />
Messagebox.QUESTION) == Messagebox.YES) {<br />
this_never_executes();<br />
}<br />
</source><br />
<br />
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.<br />
<br />
<source lang="xml"><br />
<system-config><br />
<disable-event-thread>false</disable-event-thread><br />
</system-config><br />
</source><br />
<blockquote><br />
----<br />
<references/><br />
</blockquote><br />
<br />
=== The method of <tt>ComponentCloneListener</tt> changed ===<br />
<br />
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.<br />
<br />
<source lang="java"><br />
Object willClone(Component comp);<br />
</source><br />
<br />
=== The <tt>AuPocessor</tt> interface deprecated (replaced with <tt>AuExtension</tt>) ===<br />
<br />
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.<br />
<br />
=== The <tt>addRoot</tt>, <tt>removeRoot</tt>, <tt>moveRoot</tt>, <tt>addFellow</tt> and <tt>removeFellow</tt> methods of <tt>PageCtrl</tt> removed ===<br />
<br />
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>.<br />
<br />
=== The <tt>disable-behind-modal</tt> configuration disabled (always false) ===<br />
<br />
With ZK 5, there is no need to disable widgets that don't belong to the modal window, so this configuration is meaningless.<br />
<br />
== Component Use ==<br />
<br />
=== The <tt>include</tt> component's mode default to <tt>auto</tt> ===<br />
<br />
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<br />
<br />
<source lang="javascript"><br />
<include mode="defer" src="abc.zul"/><br />
</source><br />
<br />
Or, you can specify the following configuration in zk.xml to change the default mode for the whole application.<br />
<br />
<source lang="javascript"><br />
<library-property><br />
<name>org.zkoss.zul.include.mode</name><br />
<value>defer</value><br />
</library-property><br />
</source><br />
<br />
=== The <tt>a</tt> component introduced for HTML A ===<br />
<br />
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,<br />
<br />
<source lang="xml"><br />
Refer <a href="http://www.zkoss.org" label="ZK"/> for details.<br />
Or <a href="http://www.zkoss.org/zkdemo">ZK Demo</a>.<br />
</source><br />
<br />
=== CSS <tt>fixed-layout</tt> property default for <tt>grid</tt> and <tt>listbox</tt> ===<br />
<br />
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.<br />
<br />
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 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 ).<br />
<br />
<source lang="xml"><br />
<grid width="300px"><br />
<columns><br />
<column label="Order" width="20px"/><br />
<column label="Name" hflex="1"/><br />
<column label="Value" hflex="2"/><br />
</columns><br />
<rows><br />
<row><image src="foo.gif"/> username: <textbox/></row><br />
<row><image src="foo.gif"/> password: <textbox/></row><br />
</rows><br />
</grid><br />
</source><br />
<br />
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.<br />
<br />
<source lang="xml"><br />
<grid width="300px" sizedByContent="true"><br />
</source><br />
<br />
=== The <tt>alphafix</tt> mold of <tt>image</tt> and <tt>imagemap</tt> deprecated ===<br />
<br />
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.<br />
<br />
<source lang="javascript"><br />
<?script content="jq.IE6_ALPHAFIX='.png';"?><br />
</source><br />
<br />
In other words, just specify a regular expression to a JavaScript variable called <tt>jq.IE6_ALPHAFIX</tt>.<br />
<br />
=== The methods of <tt>ClientConstraint</tt> changed ===<br />
<br />
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.<br />
<br />
The typical way to implement the custom client validation is as follows.<br />
<br />
#Implementing a JavaString class, say, foo.MyValidator.<br />
<br />
#Implementing <tt>org.zkoss.zul.ClientConstraint</tt> such that<br />
<br />
<source lang="java"><br />
//Java<br />
String getClientConstraint() {<br />
return "new foo.MyValidator()";<br />
}<br />
String getClientPackages() {<br />
return "foo"; //the package name<br />
}<br />
</source><br />
<br />
=== <tt>SimpleConstraint</tt> performs all validations at client ===<br />
<br />
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,<br />
<br />
<source lang="javascript"><br />
<textbox constraint="/.+@.+\.[a-z]+/,server"/><br />
</source><br />
<br />
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>.<br />
<br />
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.<br />
<br />
<source lang="javascript"><br />
//JavaScript<br />
ClientServerConstraint = zk.$extends(zul.inp.SimpleConstraint, {<br />
serverValidate: true<br />
});<br />
</source><br />
<br />
<blockquote><br />
----<br />
<references/><br />
</blockquote><br />
<br />
=== Overlapped window within another overlapped window not cropped ===<br />
<br />
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.<br />
<br />
=== Meaning of hbox/vbox <tt>pack</tt> attribute follows XUL's specification ===<br />
<br />
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".<br />
<br />
== Component Styling ==<br />
<br />
=== The <tt>dynamic</tt> attribute of the <tt>style</tt> component deprecated ===<br />
<br />
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.<br />
<br />
=== The default mold of the <tt>button</tt> component changed to <tt>os</tt> ===<br />
<br />
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>.<br />
<br />
<source lang="xml"><br />
<library-property><br />
<name>org.zkoss.zul.Button.mold</name><br />
<value>trendy</value><br />
</library-property><br />
</source><br />
<br />
=== The default value of the <tt>zclass</tt> attribute more consistent (<tt>z-</tt> + component-name) ===<br />
<br />
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.<br />
<br />
The affected components are as follows.<br />
<br />
comboitem, bandpopup, groupfoot, listcell, listfoot,<br />
listfooter, listgroup, listgroupfoot, listhead, listheader,<br />
listitem, treecell, treechildren, treecol, treecols, treefoot,<br />
treefooter, treerow, table-children, and table-layout<br />
<br />
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>.<br />
<br />
=== Both <tt>Applet</tt> and <tt>Iframe</tt> extends from <tt>HtmlBasedComponent</tt> (instead of <tt>XulElement</tt>) ===<br />
<br />
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>.<br />
<br />
=== The <tt>ZKPrefix</tt> library property deprecated ===<br />
<br />
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.<br />
<br />
== Component Development ==<br />
<br />
The component development is changed. Refer to [http://docs.zkoss.org/wiki/ZK5:_Component_Development_Guide ZK5: Component Development Guide] for details.<br />
<br />
= Client-side Upgrade Notes =<br />
<br />
The client is rewritten, so your customization have to rewrite, too.<br />
<br />
== Client-side Action deprecated ==<br />
<br />
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,<br />
<br />
<source lang="xml"><br />
<!-- ZK 3.x: Client Side Action --><br />
<textbox<br />
action="onfocus: window.action.show(#{help1}); onblur: window.action.hide(#{help1})" /><br />
<label id="help1" visible="false" value="This is help for text1." /><br />
</source><br />
<br />
can be replaced with<br />
<br />
<source lang="xml"><br />
<!-- ZK 5 --><br />
<textbox xmlns:w="http://www.zkoss.org/2005/zk/client"<br />
w:onFocus="jq(this.$f('help1')).fadeIn()" w:onBlur="jq(this.$f('help1')).fadeOut()"/><br />
<label id="help1" visible="false" value="This is help for text1." /><br />
</source><br />
<br />
== Animation API deprecated ==<br />
<br />
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,<br />
<br />
<source lang="xml"><br />
<!-- ZK 3.x: anima --><br />
<label sclass="ctl" value="SlideDown"<br />
action="onclick: zk.hide(#{t});anima.slideDown(#{t})"/><br />
</source><br />
<br />
<source lang="xml"><br />
<!- ZK 5: with jQury --><br />
<label sclass="ctl" value="SlideDown"<br />
w:onClick="jq(this.$f('t')).hide().slideDown()"<br />
xmlns:w="http://www.zkoss.org/2005/zk/client"/><br />
</source><br />
<br />
Please refer to [http://docs.zkoss.org/wiki/ZK5:_JavaScript_API ZK5: JavaScript API] for the complete description of JavaScript API at the client.<br />
<br />
= See Also =<br />
*[[Small_Talks/2010/April/Upgrading_to_ZK_5 | Upgrading to ZK 5]]<br />
*A forum thread : [http://www.zkoss.org/forum/listComment/11094 Upgrade to ZK5 ]<br />
<br />
<br />
<comment>http://docs.zkoss.org/wiki/ZK_5:_Upgrade_Notes</comment><br />
<br />
<br />
{{Template:Smalltalk_Footer|<br />
|name=Potix Corporation <br />
}}</div>Charhttps://www.zkoss.org/_w/index.php?title=Small_Talks/2009/December/ZK_5:_Upgrade_Notes&diff=15256Small Talks/2009/December/ZK 5: Upgrade Notes2010-12-21T03:35:20Z<p>Char: /* Event processing thread disabled by default */</p>
<hr />
<div>{{Template:Smalltalk_Author|<br />
|author= The ZK Team<br />
|date=December, 2009<br />
|version= ZK 3 to ZK 5<br />
}}<br />
<br />
<br />
= Overview =<br />
<br />
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.<br />
<br />
= Server-side Upgrade Notes =<br />
<br />
== Attributes and Namespace ==<br />
=== The return type of <tt>setAttribute</tt> and <tt>removeAttribute</tt> of session/execution/application changed (from <tt>void</tt> to <tt>Object</tt>) ===<br />
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.<br />
<br />
The new signature:<br />
<syntax lang="java"><br />
Object setAttribute(String name, Object value); //returns the previous value if any<br />
Object removeAttribute(String name); //return the previous value if any<br />
</syntax><br />
<br />
=== Namespace deprecated ===<br />
<br />
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.<br />
<br />
<syntax lang="xml"><br />
<variabls foo="better"/> <!-- deprecated --><br />
<custom-attribute foo="better" scope="space"/><br />
</syntax><br />
<br />
Furthermore, ZK 5 will search the attribute scopes for any variable specified in EL or <tt>zscript</tt>.<br />
<br />
<syntax lang="xml"><br />
<window><br />
<custom-attributes a="a" b="b"/> <!-- belongs to window's attribute scope --><br />
<div><br />
<custom-attributes b="B"/> <!-- belongs to div's attribute scope --><br />
${a} and ${b} <!-- result: a and B --><br />
<zscript><br />
String s = a + b; //result: aB<br />
</zscript><br />
</div><br />
</window><br />
</syntax><br />
<br />
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.<br />
<br />
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.<br />
<br />
=== The attribute scope of the ID space is the same of the space owner's attribute scope ===<br />
<br />
In the previous version, the space owner (such as <tt>window</tt>) has two attribute scopes. For example,<br />
<br />
<syntax lang="xml"><br />
<window><br />
<custom-attributes foo="a"/><br />
<div><br />
<custom-attributes foo="b" scope="space"/><br />
</div><br />
<br />
<zscript><br />
self.getAttribute("foo"); //returns a in ZK 3<br />
self.getAttribute("foo", self.SPACE_SCOPE); //returns b<br />
</zscript><br />
</window><br />
</syntax><br />
<br />
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>.<br />
<br />
== System Level Control ==<br />
<br />
=== Event processing thread disabled by default ===<br />
<br />
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 [[Performance tip#Use_the_Servlet_Thread_to_Process_Events]] for how to adjust your application. For example, the <tt>if</tt> clause in the following example is never true.<br />
<br />
<source lang="java" ><br />
if (Messagebox.show("Delete?", "Prompt", Messagebox.YES|Messagebox.NO,<br />
Messagebox.QUESTION) == Messagebox.YES) {<br />
this_never_executes();<br />
}<br />
</source><br />
<br />
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.<br />
<br />
<source lang="xml"><br />
<system-config><br />
<disable-event-thread>false</disable-event-thread><br />
</system-config><br />
</source><br />
<blockquote><br />
----<br />
<references/><br />
</blockquote><br />
<br />
=== The method of <tt>ComponentCloneListener</tt> changed ===<br />
<br />
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.<br />
<br />
<source lang="java"><br />
Object willClone(Component comp);<br />
</source><br />
<br />
=== The <tt>AuPocessor</tt> interface deprecated (replaced with <tt>AuExtension</tt>) ===<br />
<br />
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.<br />
<br />
=== The <tt>addRoot</tt>, <tt>removeRoot</tt>, <tt>moveRoot</tt>, <tt>addFellow</tt> and <tt>removeFellow</tt> methods of <tt>PageCtrl</tt> removed ===<br />
<br />
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>.<br />
<br />
=== The <tt>disable-behind-modal</tt> configuration disabled (always false) ===<br />
<br />
With ZK 5, there is no need to disable widgets that don't belong to the modal window, so this configuration is meaningless.<br />
<br />
== Component Use ==<br />
<br />
=== The <tt>include</tt> component's mode default to <tt>auto</tt> ===<br />
<br />
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<br />
<br />
<source lang="javascript"><br />
<include mode="defer" src="abc.zul"/><br />
</source><br />
<br />
Or, you can specify the following configuration in zk.xml to change the default mode for the whole application.<br />
<br />
<source lang="javascript"><br />
<library-property><br />
<name>org.zkoss.zul.include.mode</name><br />
<value>defer</value><br />
</library-property><br />
</source><br />
<br />
=== The <tt>a</tt> component introduced for HTML A ===<br />
<br />
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,<br />
<br />
<source lang="xml"><br />
Refer <a href="http://www.zkoss.org" label="ZK"/> for details.<br />
Or <a href="http://www.zkoss.org/zkdemo">ZK Demo</a>.<br />
</source><br />
<br />
=== CSS <tt>fixed-layout</tt> property default for <tt>grid</tt> and <tt>listbox</tt> ===<br />
<br />
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.<br />
<br />
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://docs.zkoss.org/wiki/ZK_5:_More_Flexible_Layout#Proportional_Flexibility 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 ).<br />
<br />
<source lang="xml"><br />
<grid width="300px"><br />
<columns><br />
<column label="Order" width="20px"/><br />
<column label="Name" hflex="1"/><br />
<column label="Value" hflex="2"/><br />
</columns><br />
<rows><br />
<row><image src="foo.gif"/> username: <textbox/></row><br />
<row><image src="foo.gif"/> password: <textbox/></row><br />
</rows><br />
</grid><br />
</source><br />
<br />
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.<br />
<br />
<source lang="xml"><br />
<grid width="300px" sizedByContent="true"><br />
</source><br />
<br />
=== The <tt>alphafix</tt> mold of <tt>image</tt> and <tt>imagemap</tt> deprecated ===<br />
<br />
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.<br />
<br />
<source lang="javascript"><br />
<?script content="jq.IE6_ALPHAFIX='.png';"?><br />
</source><br />
<br />
In other words, just specify a regular expression to a JavaScript variable called <tt>jq.IE6_ALPHAFIX</tt>.<br />
<br />
=== The methods of <tt>ClientConstraint</tt> changed ===<br />
<br />
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.<br />
<br />
The typical way to implement the custom client validation is as follows.<br />
<br />
#Implementing a JavaString class, say, foo.MyValidator.<br />
<br />
#Implementing <tt>org.zkoss.zul.ClientConstraint</tt> such that<br />
<br />
<source lang="java"><br />
//Java<br />
String getClientConstraint() {<br />
return "new foo.MyValidator()";<br />
}<br />
String getClientPackages() {<br />
return "foo"; //the package name<br />
}<br />
</source><br />
<br />
=== <tt>SimpleConstraint</tt> performs all validations at client ===<br />
<br />
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,<br />
<br />
<source lang="javascript"><br />
<textbox constraint="/.+@.+\.[a-z]+/,server"/><br />
</source><br />
<br />
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>.<br />
<br />
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.<br />
<br />
<source lang="javascript"><br />
//JavaScript<br />
ClientServerConstraint = zk.$extends(zul.inp.SimpleConstraint, {<br />
serverValidate: true<br />
});<br />
</source><br />
<br />
<blockquote><br />
----<br />
<references/><br />
</blockquote><br />
<br />
=== Overlapped window within another overlapped window not cropped ===<br />
<br />
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.<br />
<br />
=== Meaning of hbox/vbox <tt>pack</tt> attribute follows XUL's specification ===<br />
<br />
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".<br />
<br />
== Component Styling ==<br />
<br />
=== The <tt>dynamic</tt> attribute of the <tt>style</tt> component deprecated ===<br />
<br />
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.<br />
<br />
=== The default mold of the <tt>button</tt> component changed to <tt>os</tt> ===<br />
<br />
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>.<br />
<br />
<source lang="xml"><br />
<library-property><br />
<name>org.zkoss.zul.Button.mold</name><br />
<value>trendy</value><br />
</library-property><br />
</source><br />
<br />
=== The default value of the <tt>zclass</tt> attribute more consistent (<tt>z-</tt> + component-name) ===<br />
<br />
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.<br />
<br />
The affected components are as follows.<br />
<br />
comboitem, bandpopup, groupfoot, listcell, listfoot,<br />
listfooter, listgroup, listgroupfoot, listhead, listheader,<br />
listitem, treecell, treechildren, treecol, treecols, treefoot,<br />
treefooter, treerow, table-children, and table-layout<br />
<br />
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>.<br />
<br />
=== Both <tt>Applet</tt> and <tt>Iframe</tt> extends from <tt>HtmlBasedComponent</tt> (instead of <tt>XulElement</tt>) ===<br />
<br />
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>.<br />
<br />
=== The <tt>ZKPrefix</tt> library property deprecated ===<br />
<br />
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.<br />
<br />
== Component Development ==<br />
<br />
The component development is changed. Refer to [http://docs.zkoss.org/wiki/ZK5:_Component_Development_Guide ZK5: Component Development Guide] for details.<br />
<br />
= Client-side Upgrade Notes =<br />
<br />
The client is rewritten, so your customization have to rewrite, too.<br />
<br />
== Client-side Action deprecated ==<br />
<br />
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,<br />
<br />
<source lang="xml"><br />
<!-- ZK 3.x: Client Side Action --><br />
<textbox<br />
action="onfocus: window.action.show(#{help1}); onblur: window.action.hide(#{help1})" /><br />
<label id="help1" visible="false" value="This is help for text1." /><br />
</source><br />
<br />
can be replaced with<br />
<br />
<source lang="xml"><br />
<!-- ZK 5 --><br />
<textbox xmlns:w="http://www.zkoss.org/2005/zk/client"<br />
w:onFocus="jq(this.$f('help1')).fadeIn()" w:onBlur="jq(this.$f('help1')).fadeOut()"/><br />
<label id="help1" visible="false" value="This is help for text1." /><br />
</source><br />
<br />
== Animation API deprecated ==<br />
<br />
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,<br />
<br />
<source lang="xml"><br />
<!-- ZK 3.x: anima --><br />
<label sclass="ctl" value="SlideDown"<br />
action="onclick: zk.hide(#{t});anima.slideDown(#{t})"/><br />
</source><br />
<br />
<source lang="xml"><br />
<!- ZK 5: with jQury --><br />
<label sclass="ctl" value="SlideDown"<br />
w:onClick="jq(this.$f('t')).hide().slideDown()"<br />
xmlns:w="http://www.zkoss.org/2005/zk/client"/><br />
</source><br />
<br />
Please refer to [http://docs.zkoss.org/wiki/ZK5:_JavaScript_API ZK5: JavaScript API] for the complete description of JavaScript API at the client.<br />
<br />
= See Also =<br />
*[[Small_Talks/2010/April/Upgrading_to_ZK_5 | Upgrading to ZK 5]]<br />
*A forum thread : [http://www.zkoss.org/forum/listComment/11094 Upgrade to ZK5 ]<br />
<br />
<br />
<comment>http://docs.zkoss.org/wiki/ZK_5:_Upgrade_Notes</comment><br />
<br />
<br />
{{Template:Smalltalk_Footer|<br />
|name=Potix Corporation <br />
}}</div>Charhttps://www.zkoss.org/_w/index.php?title=Small_Talks/2008/December/Live_Data,_Paging,_setModel_and_Implement_your_own_renderer&diff=15252Small Talks/2008/December/Live Data, Paging, setModel and Implement your own renderer2010-12-21T03:33:58Z<p>Char: /* See Also */</p>
<hr />
<div>{{Template:Smalltalk_Author|<br />
|author=<br />
|date=December <br />
|version= <br />
}}<br />
<br />
<br />
==Overview==<br />
In a real world web application, it's common to collect data from database, and show it in <tt>listbox</tt> or <tt>grid</tt> or <tt>tree</tt>. The underlying data may be hundreds of thousands records. It's impractical to load them all to the client. Therefore ZK introduces concepts of <tt>Live Data</tt>, <tt>Paging</tt>. To separate view from data, ZK also introduces the concept of <tt>model</tt>. It is easier to use different views to show the same set of data. To show data in the view any way you like, a developer may implement his own renderer; ZK has provided a default renderer.<br />
<br />
==What's Live Data==<br />
The main idea of "live data" is to separate data from the view. Developers only have to manipulate the data model, and the data of view (UI Component) will be updated accordingly. Secondly, it shortens the response time of user since only the required data will be downloaded the first time.<br />
<br />
==What's Paging==<br />
Paging separates long content into multiple pages.<br />
<br />
A paging component is used for this purpose. For example, assume that you have 100 items and prefer to show 20 items at a time, then you can use the paging components as follows.<br />
<br />
[[Image:100000000000007A00000013F689AD21.png]]<br />
<br />
<source lang="xml" ><br />
<paging totalSize="100" pageSize="20"/><br />
</source><br />
<br />
Then, when a user clicks on the hyperlinks, the <tt>onPaging</tt> event is sent with an instance of <tt>org.zkoss.zul.event.PagingEvent</tt> to the paging component. To decide which portion of your 100 items are visible, you shall add a listener to the paging component.<br />
<br />
<source lang="xml" ><br />
<paging id="paging"/><br />
<zscript><br />
List result = new SearchEngine().find("ZK");<br />
//assume SearchEngine.find() will return a list of items.<br />
paging.setTotalSize(result.size());<br />
paging.addEventListener("onPaging", new EventListener() {<br />
public void onEvent(Event event) {<br />
int pgno = event.getPaginal().getActivePage();<br />
int ofs = pgno * event.getPaginal().getPageSize();<br />
new Viewer().redraw(result, ofs, ofs + event.getPaginal().getPageSize() - 1); //assume redraw(List result, int b, int e) will display<br />
//from the b-th item to the e-th item<br />
}<br />
});<br />
</zscript><br />
</source><br />
<br />
==What's Model==<br />
To assign data to a component (e.g. <tt>grid</tt> or <tt>listbox</tt>), you have to prepare the data in certain data model. For example, <tt>listbox</tt> and <tt>grid</tt> accept interfaces <tt>ListModel</tt> and <tt>GroupsModel</tt>, while <tt>tree</tt> only accepts <tt>TreeModel</tt>. See the <tt>setModel</tt> method of each component for the kind of model it accepts. Using the wrong type of data model will throw a cast error and is a common beginner mistake.<br />
<br />
ZK has implemented following Models:<br />
*SimpleCategoryModel<br />
*SimpleGroupsModel<br />
*SimpleListModel<br />
*SimplePieModel<br />
*SimpleTreeModel<br />
*SimpleXYModel<br />
*SimpleXYZModel<br />
*SimpleHiLoModel<br />
<br />
==What's Renderer==<br />
A renderer is responsible for rendering the layout of certain model.<br />
For example, <tt>RowRenderer</tt> is responsible for rendering data stored in the <tt>ListModel</tt> to the specified <tt>row</tt> in the <tt>Grid</tt>.<br />
<br />
ZK has provided default renders:<br />
<br />
==Three Steps to Use Live Data==<br />
*Prepare the data in the form of <tt>ListModel</tt>. ZK has a concrete implementation called <tt>org.zkoss.zul.SimpleListModel</tt> for representing an array of objects.<br />
*Implement the <tt>org.zkoss.zul.RowRenderer</tt> interface for rendering a row of data into the Grid.<br />
** This is optional. If it is not specified, the default <tt>rowrender</tt> is used to render the data into the first column.<br />
** You could implement different renderers for represent the same data in different views.<br />
*Specify the data in the <tt>model</tt> property, and, optionally, the <tt>rowrender</tt> in the <tt>rowRenderer</tt> property.<br />
<br />
==Examples==<br />
=== Single-Column Example : Using only setModel ===<br />
In the following example, an array of data("data") is prepared , it is passed as a parameter for the generation of a ListModel("strset"). Last, assign this ListModel into a Grid by setting the model of the Grid.<br />
<br />
<source lang="xml" ><br />
<window title="Live grid"><br />
<zscript><br />
<![CDATA[ <br />
String[] data = new String[30];<br />
for(int j=0; j < data.length; ++j) {<br />
data[j] = "option "+j;<br />
} <br />
ListModel strset = new SimpleListModel(data);<br />
]]><br />
</zscript><br />
<grid model="${strset}"><br />
<columns><br />
<column label="options" /><br />
</columns><br />
</grid><br />
</window><br />
</source><br />
<br />
=== Two-Columns Example : User defined renderer ===<br />
Since the default rowrender only satisfies the scenario of single-column, a customized rowrenderer must be implemented to commit the scenario of multi-column. In the following example, a two-columns live data for grid is demonstrated.<br />
<br />
====1.Prepare the Data Model====<br />
<br />
The first step is to prepare required data. A two-way array is adopted in this example and it is passed as a parameter for the generation of a ListModel which is implemented by SimpleListModel. In addition, ListModel now supports various data types,including Array, List, Map, and Set in the form of ListModelArray,ListModelList, ListModelMap,and ListModelSet.<br />
<br />
<source lang="java" ><br />
//prepare the data model <br />
String[][] model = new String[100][2]; <br />
for(int j=0; j < model.length; ++j) { <br />
model[j][0] = "key"+j;<br />
model[j][1] = "value"+j; <br />
} <br />
ListModel strset = new SimpleListModel(model);<br />
</source><br />
<br />
====2.Define the RowRenderer Class====<br />
<br />
Secondly, to define a class which implements the interface RowRenderer,its method render(Row row, java.lang.Object data) is required to be implemented.<br />
<br />
Method render(Row row, java.lang.Object data)<br />
row - The row to render the result.<br />
data - Returned from ListModel.getElementAt() <br />
<br />
In addition to pass required parameters into the method render(), the form of view (UI Component) for displaying data in the Grid also has to be defined, and any component which is supported by Grid could be adopted. In this example, Label is adopted, and the last step is to render Label into the specified row in the Grid by calling Label.setParent(Row row).<br />
<br />
<br />
MyRowRenderer.java<br />
<br />
<source lang="java" ><br />
import org.zkoss.zul.Label;<br />
import org.zkoss.zul.Row;<br />
import org.zkoss.zul.RowRenderer;<br />
<br />
//define the RowRenderer class <br />
public class MyRowRenderer implements RowRenderer{ <br />
<br />
public void render(Row row, java.lang.Object data) {<br />
String[] _data = (String[])data;<br />
new Label(_data[0]).setParent(row); <br />
new Label(_data[1]).setParent(row);<br />
}<br />
}<br />
</source><br />
<br />
====3.Specify model and rowRenderer Property====<br />
<br />
The properties of model and rowRenderer could be specified directly in the Grid. In this example,methods, Grid.setModel() and Grid.setRowRenderer() are adopted to specify required objects for realizing the idea of "live data".<br />
<br />
<source lang="xml" ><br />
<window title="Two-Column Live Data Demo" ><br />
<grid id="mygrid"><br />
<columns><br />
<column label="key" /><br />
<column label="value" /><br />
</columns><br />
</grid><br />
<zscript><![CDATA[<br />
String[][] model = new String[100][2]; <br />
<br />
for(int j=0; j < model.length; ++j) { <br />
model[j][0] = "key"+j;<br />
model[j][1] = "value"+j; <br />
} <br />
ListModel strset = new SimpleListModel(model); <br />
mygrid.setModel(strset); <br />
mygrid.setRowRenderer(new MyRowRenderer()); <br />
]]><br />
</zscript><br />
</window><br />
</source><br />
<br />
== If extreme large data set, say 1,000,000? ==<br />
[[ZK/How-Tos/Concepts-and-Tricks]]<br />
<br />
Check <br />
Implement paging for listboxes with many items<br />
<br />
== Data Binding ==<br />
Not only showing the data by model, you can also modify underlying model by UI in real time. <br />
<br />
[[Example Code for Data binding with live data| Example code]]<br />
<br />
== See Also ==<br />
[http://www.zkoss.org/smalltalks/livedata/livedataforgrid.dsp How to realize the idea of live data in a Grid]: A smalltalk<br />
<br />
[http://www.zkoss.org/smalltalks/zkTreeModel/ ZK Tree Model]: A smalltalk.<br />
<br />
[http://zk1.svn.sourceforge.net/viewvc/zk1/branches/5.0/zul/src/org/zkoss/zul/Grid.java?revision=14211&view=markup Grid.java]: The source code of Grid.java. By tracing it, you'll know how renderer and setModel works, how <tt>render()</tt> is called, how the <tt>model</tt> is iterated through visible region. Keyword: render. You may also trace Tree.java and Listbox.java.<br />
<br />
[[Grids%2C_Trees_and_Listbox#Live_Data | Live Data]] section in chapter Grids, Trees and Listbox.<br />
<br />
[http://www.zkoss.org/forum/index.zul#path%3DlistComment%3BdiscussionId%3D6320%3BcategoryId%3D14%3B Bug in Grid paging? handleError:1084]: A thread in forum.<br />
<br />
<br />
{{Template:Smalltalk_Footer|<br />
|name=Potix Corporation <br />
}}</div>Charhttps://www.zkoss.org/_w/index.php?title=Small_Talks/2008/December/Live_Data,_Paging,_setModel_and_Implement_your_own_renderer&diff=15251Small Talks/2008/December/Live Data, Paging, setModel and Implement your own renderer2010-12-21T03:32:48Z<p>Char: /* If extreme large data set, say 1,000,000? */</p>
<hr />
<div>{{Template:Smalltalk_Author|<br />
|author=<br />
|date=December <br />
|version= <br />
}}<br />
<br />
<br />
==Overview==<br />
In a real world web application, it's common to collect data from database, and show it in <tt>listbox</tt> or <tt>grid</tt> or <tt>tree</tt>. The underlying data may be hundreds of thousands records. It's impractical to load them all to the client. Therefore ZK introduces concepts of <tt>Live Data</tt>, <tt>Paging</tt>. To separate view from data, ZK also introduces the concept of <tt>model</tt>. It is easier to use different views to show the same set of data. To show data in the view any way you like, a developer may implement his own renderer; ZK has provided a default renderer.<br />
<br />
==What's Live Data==<br />
The main idea of "live data" is to separate data from the view. Developers only have to manipulate the data model, and the data of view (UI Component) will be updated accordingly. Secondly, it shortens the response time of user since only the required data will be downloaded the first time.<br />
<br />
==What's Paging==<br />
Paging separates long content into multiple pages.<br />
<br />
A paging component is used for this purpose. For example, assume that you have 100 items and prefer to show 20 items at a time, then you can use the paging components as follows.<br />
<br />
[[Image:100000000000007A00000013F689AD21.png]]<br />
<br />
<source lang="xml" ><br />
<paging totalSize="100" pageSize="20"/><br />
</source><br />
<br />
Then, when a user clicks on the hyperlinks, the <tt>onPaging</tt> event is sent with an instance of <tt>org.zkoss.zul.event.PagingEvent</tt> to the paging component. To decide which portion of your 100 items are visible, you shall add a listener to the paging component.<br />
<br />
<source lang="xml" ><br />
<paging id="paging"/><br />
<zscript><br />
List result = new SearchEngine().find("ZK");<br />
//assume SearchEngine.find() will return a list of items.<br />
paging.setTotalSize(result.size());<br />
paging.addEventListener("onPaging", new EventListener() {<br />
public void onEvent(Event event) {<br />
int pgno = event.getPaginal().getActivePage();<br />
int ofs = pgno * event.getPaginal().getPageSize();<br />
new Viewer().redraw(result, ofs, ofs + event.getPaginal().getPageSize() - 1); //assume redraw(List result, int b, int e) will display<br />
//from the b-th item to the e-th item<br />
}<br />
});<br />
</zscript><br />
</source><br />
<br />
==What's Model==<br />
To assign data to a component (e.g. <tt>grid</tt> or <tt>listbox</tt>), you have to prepare the data in certain data model. For example, <tt>listbox</tt> and <tt>grid</tt> accept interfaces <tt>ListModel</tt> and <tt>GroupsModel</tt>, while <tt>tree</tt> only accepts <tt>TreeModel</tt>. See the <tt>setModel</tt> method of each component for the kind of model it accepts. Using the wrong type of data model will throw a cast error and is a common beginner mistake.<br />
<br />
ZK has implemented following Models:<br />
*SimpleCategoryModel<br />
*SimpleGroupsModel<br />
*SimpleListModel<br />
*SimplePieModel<br />
*SimpleTreeModel<br />
*SimpleXYModel<br />
*SimpleXYZModel<br />
*SimpleHiLoModel<br />
<br />
==What's Renderer==<br />
A renderer is responsible for rendering the layout of certain model.<br />
For example, <tt>RowRenderer</tt> is responsible for rendering data stored in the <tt>ListModel</tt> to the specified <tt>row</tt> in the <tt>Grid</tt>.<br />
<br />
ZK has provided default renders:<br />
<br />
==Three Steps to Use Live Data==<br />
*Prepare the data in the form of <tt>ListModel</tt>. ZK has a concrete implementation called <tt>org.zkoss.zul.SimpleListModel</tt> for representing an array of objects.<br />
*Implement the <tt>org.zkoss.zul.RowRenderer</tt> interface for rendering a row of data into the Grid.<br />
** This is optional. If it is not specified, the default <tt>rowrender</tt> is used to render the data into the first column.<br />
** You could implement different renderers for represent the same data in different views.<br />
*Specify the data in the <tt>model</tt> property, and, optionally, the <tt>rowrender</tt> in the <tt>rowRenderer</tt> property.<br />
<br />
==Examples==<br />
=== Single-Column Example : Using only setModel ===<br />
In the following example, an array of data("data") is prepared , it is passed as a parameter for the generation of a ListModel("strset"). Last, assign this ListModel into a Grid by setting the model of the Grid.<br />
<br />
<source lang="xml" ><br />
<window title="Live grid"><br />
<zscript><br />
<![CDATA[ <br />
String[] data = new String[30];<br />
for(int j=0; j < data.length; ++j) {<br />
data[j] = "option "+j;<br />
} <br />
ListModel strset = new SimpleListModel(data);<br />
]]><br />
</zscript><br />
<grid model="${strset}"><br />
<columns><br />
<column label="options" /><br />
</columns><br />
</grid><br />
</window><br />
</source><br />
<br />
=== Two-Columns Example : User defined renderer ===<br />
Since the default rowrender only satisfies the scenario of single-column, a customized rowrenderer must be implemented to commit the scenario of multi-column. In the following example, a two-columns live data for grid is demonstrated.<br />
<br />
====1.Prepare the Data Model====<br />
<br />
The first step is to prepare required data. A two-way array is adopted in this example and it is passed as a parameter for the generation of a ListModel which is implemented by SimpleListModel. In addition, ListModel now supports various data types,including Array, List, Map, and Set in the form of ListModelArray,ListModelList, ListModelMap,and ListModelSet.<br />
<br />
<source lang="java" ><br />
//prepare the data model <br />
String[][] model = new String[100][2]; <br />
for(int j=0; j < model.length; ++j) { <br />
model[j][0] = "key"+j;<br />
model[j][1] = "value"+j; <br />
} <br />
ListModel strset = new SimpleListModel(model);<br />
</source><br />
<br />
====2.Define the RowRenderer Class====<br />
<br />
Secondly, to define a class which implements the interface RowRenderer,its method render(Row row, java.lang.Object data) is required to be implemented.<br />
<br />
Method render(Row row, java.lang.Object data)<br />
row - The row to render the result.<br />
data - Returned from ListModel.getElementAt() <br />
<br />
In addition to pass required parameters into the method render(), the form of view (UI Component) for displaying data in the Grid also has to be defined, and any component which is supported by Grid could be adopted. In this example, Label is adopted, and the last step is to render Label into the specified row in the Grid by calling Label.setParent(Row row).<br />
<br />
<br />
MyRowRenderer.java<br />
<br />
<source lang="java" ><br />
import org.zkoss.zul.Label;<br />
import org.zkoss.zul.Row;<br />
import org.zkoss.zul.RowRenderer;<br />
<br />
//define the RowRenderer class <br />
public class MyRowRenderer implements RowRenderer{ <br />
<br />
public void render(Row row, java.lang.Object data) {<br />
String[] _data = (String[])data;<br />
new Label(_data[0]).setParent(row); <br />
new Label(_data[1]).setParent(row);<br />
}<br />
}<br />
</source><br />
<br />
====3.Specify model and rowRenderer Property====<br />
<br />
The properties of model and rowRenderer could be specified directly in the Grid. In this example,methods, Grid.setModel() and Grid.setRowRenderer() are adopted to specify required objects for realizing the idea of "live data".<br />
<br />
<source lang="xml" ><br />
<window title="Two-Column Live Data Demo" ><br />
<grid id="mygrid"><br />
<columns><br />
<column label="key" /><br />
<column label="value" /><br />
</columns><br />
</grid><br />
<zscript><![CDATA[<br />
String[][] model = new String[100][2]; <br />
<br />
for(int j=0; j < model.length; ++j) { <br />
model[j][0] = "key"+j;<br />
model[j][1] = "value"+j; <br />
} <br />
ListModel strset = new SimpleListModel(model); <br />
mygrid.setModel(strset); <br />
mygrid.setRowRenderer(new MyRowRenderer()); <br />
]]><br />
</zscript><br />
</window><br />
</source><br />
<br />
== If extreme large data set, say 1,000,000? ==<br />
[[ZK/How-Tos/Concepts-and-Tricks]]<br />
<br />
Check <br />
Implement paging for listboxes with many items<br />
<br />
== Data Binding ==<br />
Not only showing the data by model, you can also modify underlying model by UI in real time. <br />
<br />
[[Example Code for Data binding with live data| Example code]]<br />
<br />
== See Also ==<br />
[http://www.zkoss.org/smalltalks/livedata/livedataforgrid.dsp How to realize the idea of live data in a Grid]: A smalltalk<br />
<br />
[http://www.zkoss.org/smalltalks/zkTreeModel/ ZK Tree Model]: A smalltalk.<br />
<br />
[http://zk1.svn.sourceforge.net/viewvc/zk1/branches/5.0/zul/src/org/zkoss/zul/Grid.java?revision=14211&view=markup Grid.java]: The source code of Grid.java. By tracing it, you'll know how renderer and setModel works, how <tt>render()</tt> is called, how the <tt>model</tt> is iterated through visible region. Keyword: render. You may also trace Tree.java and Listbox.java.<br />
<br />
[http://docs.zkoss.org/wiki/Grids%2C_Trees_and_Listbox#Live_Data Live Data] section in chapter Grids, Trees and Listbox.<br />
<br />
[http://www.zkoss.org/forum/index.zul#path%3DlistComment%3BdiscussionId%3D6320%3BcategoryId%3D14%3B Bug in Grid paging? handleError:1084]: A thread in forum.<br />
<br />
<br />
{{Template:Smalltalk_Footer|<br />
|name=Potix Corporation <br />
}}</div>Charhttps://www.zkoss.org/_w/index.php?title=Small_Talks/2009/December/ZK_5:_Upgrade_Notes&diff=15244Small Talks/2009/December/ZK 5: Upgrade Notes2010-12-21T03:15:03Z<p>Char: /* See Also */</p>
<hr />
<div>{{Template:Smalltalk_Author|<br />
|author=<br />
|date=December <br />
|version= <br />
}}<br />
<br />
<br />
= Overview =<br />
<br />
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.<br />
<br />
= Server-side Upgrade Notes =<br />
<br />
== Attributes and Namespace ==<br />
=== The return type of <tt>setAttribute</tt> and <tt>removeAttribute</tt> of session/execution/application changed (from <tt>void</tt> to <tt>Object</tt>) ===<br />
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.<br />
<br />
The new signature:<br />
<syntax lang="java"><br />
Object setAttribute(String name, Object value); //returns the previous value if any<br />
Object removeAttribute(String name); //return the previous value if any<br />
</syntax><br />
<br />
=== Namespace deprecated ===<br />
<br />
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.<br />
<br />
<syntax lang="xml"><br />
<variabls foo="better"/> <!-- deprecated --><br />
<custom-attribute foo="better" scope="space"/><br />
</syntax><br />
<br />
Furthermore, ZK 5 will search the attribute scopes for any variable specified in EL or <tt>zscript</tt>.<br />
<br />
<syntax lang="xml"><br />
<window><br />
<custom-attributes a="a" b="b"/> <!-- belongs to window's attribute scope --><br />
<div><br />
<custom-attributes b="B"/> <!-- belongs to div's attribute scope --><br />
${a} and ${b} <!-- result: a and B --><br />
<zscript><br />
String s = a + b; //result: aB<br />
</zscript><br />
</div><br />
</window><br />
</syntax><br />
<br />
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.<br />
<br />
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.<br />
<br />
=== The attribute scope of the ID space is the same of the space owner's attribute scope ===<br />
<br />
In the previous version, the space owner (such as <tt>window</tt>) has two attribute scopes. For example,<br />
<br />
<syntax lang="xml"><br />
<window><br />
<custom-attributes foo="a"/><br />
<div><br />
<custom-attributes foo="b" scope="space"/><br />
</div><br />
<br />
<zscript><br />
self.getAttribute("foo"); //returns a in ZK 3<br />
self.getAttribute("foo", self.SPACE_SCOPE); //returns b<br />
</zscript><br />
</window><br />
</syntax><br />
<br />
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>.<br />
<br />
== System Level Control ==<br />
<br />
=== Event processing thread disabled by default ===<br />
<br />
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 [http://docs.zkoss.org/wiki/Performance_tip#Use_the_Servlet_Thread_to_Process_Events Performance tip#Use_the_Servlet_Thread_to_Process_Events] for how to adjust your application. For example, the <tt>if</tt> clause in the following example is never true.<br />
<br />
<source lang="java" ><br />
if (Messagebox.show("Delete?", "Prompt", Messagebox.YES|Messagebox.NO,<br />
Messagebox.QUESTION) == Messagebox.YES) {<br />
this_never_executes();<br />
}<br />
</source><br />
<br />
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.<br />
<br />
<source lang="xml"><br />
<system-config><br />
<disable-event-thread>false</disable-event-thread><br />
</system-config><br />
</source><br />
<blockquote><br />
----<br />
<references/><br />
</blockquote><br />
<br />
=== The method of <tt>ComponentCloneListener</tt> changed ===<br />
<br />
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.<br />
<br />
<source lang="java"><br />
Object willClone(Component comp);<br />
</source><br />
<br />
=== The <tt>AuPocessor</tt> interface deprecated (replaced with <tt>AuExtension</tt>) ===<br />
<br />
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.<br />
<br />
=== The <tt>addRoot</tt>, <tt>removeRoot</tt>, <tt>moveRoot</tt>, <tt>addFellow</tt> and <tt>removeFellow</tt> methods of <tt>PageCtrl</tt> removed ===<br />
<br />
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>.<br />
<br />
=== The <tt>disable-behind-modal</tt> configuration disabled (always false) ===<br />
<br />
With ZK 5, there is no need to disable widgets that don't belong to the modal window, so this configuration is meaningless.<br />
<br />
== Component Use ==<br />
<br />
=== The <tt>include</tt> component's mode default to <tt>auto</tt> ===<br />
<br />
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<br />
<br />
<source lang="javascript"><br />
<include mode="defer" src="abc.zul"/><br />
</source><br />
<br />
Or, you can specify the following configuration in zk.xml to change the default mode for the whole application.<br />
<br />
<source lang="javascript"><br />
<library-property><br />
<name>org.zkoss.zul.include.mode</name><br />
<value>defer</value><br />
</library-property><br />
</source><br />
<br />
=== The <tt>a</tt> component introduced for HTML A ===<br />
<br />
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,<br />
<br />
<source lang="xml"><br />
Refer <a href="http://www.zkoss.org" label="ZK"/> for details.<br />
Or <a href="http://www.zkoss.org/zkdemo">ZK Demo</a>.<br />
</source><br />
<br />
=== CSS <tt>fixed-layout</tt> property default for <tt>grid</tt> and <tt>listbox</tt> ===<br />
<br />
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.<br />
<br />
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://docs.zkoss.org/wiki/ZK_5:_More_Flexible_Layout#Proportional_Flexibility 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 ).<br />
<br />
<source lang="xml"><br />
<grid width="300px"><br />
<columns><br />
<column label="Order" width="20px"/><br />
<column label="Name" hflex="1"/><br />
<column label="Value" hflex="2"/><br />
</columns><br />
<rows><br />
<row><image src="foo.gif"/> username: <textbox/></row><br />
<row><image src="foo.gif"/> password: <textbox/></row><br />
</rows><br />
</grid><br />
</source><br />
<br />
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.<br />
<br />
<source lang="xml"><br />
<grid width="300px" sizedByContent="true"><br />
</source><br />
<br />
=== The <tt>alphafix</tt> mold of <tt>image</tt> and <tt>imagemap</tt> deprecated ===<br />
<br />
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.<br />
<br />
<source lang="javascript"><br />
<?script content="jq.IE6_ALPHAFIX='.png';"?><br />
</source><br />
<br />
In other words, just specify a regular expression to a JavaScript variable called <tt>jq.IE6_ALPHAFIX</tt>.<br />
<br />
=== The methods of <tt>ClientConstraint</tt> changed ===<br />
<br />
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.<br />
<br />
The typical way to implement the custom client validation is as follows.<br />
<br />
#Implementing a JavaString class, say, foo.MyValidator.<br />
<br />
#Implementing <tt>org.zkoss.zul.ClientConstraint</tt> such that<br />
<br />
<source lang="java"><br />
//Java<br />
String getClientConstraint() {<br />
return "new foo.MyValidator()";<br />
}<br />
String getClientPackages() {<br />
return "foo"; //the package name<br />
}<br />
</source><br />
<br />
=== <tt>SimpleConstraint</tt> performs all validations at client ===<br />
<br />
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,<br />
<br />
<source lang="javascript"><br />
<textbox constraint="/.+@.+\.[a-z]+/,server"/><br />
</source><br />
<br />
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>.<br />
<br />
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.<br />
<br />
<source lang="javascript"><br />
//JavaScript<br />
ClientServerConstraint = zk.$extends(zul.inp.SimpleConstraint, {<br />
serverValidate: true<br />
});<br />
</source><br />
<br />
<blockquote><br />
----<br />
<references/><br />
</blockquote><br />
<br />
=== Overlapped window within another overlapped window not cropped ===<br />
<br />
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.<br />
<br />
=== Meaning of hbox/vbox <tt>pack</tt> attribute follows XUL's specification ===<br />
<br />
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".<br />
<br />
== Component Styling ==<br />
<br />
=== The <tt>dynamic</tt> attribute of the <tt>style</tt> component deprecated ===<br />
<br />
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.<br />
<br />
=== The default mold of the <tt>button</tt> component changed to <tt>os</tt> ===<br />
<br />
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>.<br />
<br />
<source lang="xml"><br />
<library-property><br />
<name>org.zkoss.zul.Button.mold</name><br />
<value>trendy</value><br />
</library-property><br />
</source><br />
<br />
=== The default value of the <tt>zclass</tt> attribute more consistent (<tt>z-</tt> + component-name) ===<br />
<br />
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.<br />
<br />
The affected components are as follows.<br />
<br />
comboitem, bandpopup, groupfoot, listcell, listfoot,<br />
listfooter, listgroup, listgroupfoot, listhead, listheader,<br />
listitem, treecell, treechildren, treecol, treecols, treefoot,<br />
treefooter, treerow, table-children, and table-layout<br />
<br />
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>.<br />
<br />
=== Both <tt>Applet</tt> and <tt>Iframe</tt> extends from <tt>HtmlBasedComponent</tt> (instead of <tt>XulElement</tt>) ===<br />
<br />
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>.<br />
<br />
=== The <tt>ZKPrefix</tt> library property deprecated ===<br />
<br />
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.<br />
<br />
== Component Development ==<br />
<br />
The component development is changed. Refer to [http://docs.zkoss.org/wiki/ZK5:_Component_Development_Guide ZK5: Component Development Guide] for details.<br />
<br />
= Client-side Upgrade Notes =<br />
<br />
The client is rewritten, so your customization have to rewrite, too.<br />
<br />
== Client-side Action deprecated ==<br />
<br />
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,<br />
<br />
<source lang="xml"><br />
<!-- ZK 3.x: Client Side Action --><br />
<textbox<br />
action="onfocus: window.action.show(#{help1}); onblur: window.action.hide(#{help1})" /><br />
<label id="help1" visible="false" value="This is help for text1." /><br />
</source><br />
<br />
can be replaced with<br />
<br />
<source lang="xml"><br />
<!-- ZK 5 --><br />
<textbox xmlns:w="http://www.zkoss.org/2005/zk/client"<br />
w:onFocus="jq(this.$f('help1')).fadeIn()" w:onBlur="jq(this.$f('help1')).fadeOut()"/><br />
<label id="help1" visible="false" value="This is help for text1." /><br />
</source><br />
<br />
== Animation API deprecated ==<br />
<br />
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,<br />
<br />
<source lang="xml"><br />
<!-- ZK 3.x: anima --><br />
<label sclass="ctl" value="SlideDown"<br />
action="onclick: zk.hide(#{t});anima.slideDown(#{t})"/><br />
</source><br />
<br />
<source lang="xml"><br />
<!- ZK 5: with jQury --><br />
<label sclass="ctl" value="SlideDown"<br />
w:onClick="jq(this.$f('t')).hide().slideDown()"<br />
xmlns:w="http://www.zkoss.org/2005/zk/client"/><br />
</source><br />
<br />
Please refer to [http://docs.zkoss.org/wiki/ZK5:_JavaScript_API ZK5: JavaScript API] for the complete description of JavaScript API at the client.<br />
<br />
= See Also =<br />
*[http://docs.zkoss.org/wiki/ZK_5:_Upgrade_Notes ZK 5: Upgrade Notes]<br />
*A forum thread : [http://www.zkoss.org/forum/listComment/11094 Upgrade to ZK5 ]<br />
<br />
<br />
<comment>http://docs.zkoss.org/wiki/ZK_5:_Upgrade_Notes</comment><br />
<br />
<br />
{{Template:Smalltalk_Footer|<br />
|name=Potix Corporation <br />
}}</div>Charhttps://www.zkoss.org/_w/index.php?title=Small_Talks/2009/December/New_Features_of_ZK_5.0_RC2&diff=15242Small Talks/2009/December/New Features of ZK 5.0 RC22010-12-21T03:13:17Z<p>Char: /* Download & other resources */</p>
<hr />
<div>{{Template:Smalltalk_Author|<br />
|author=Timothy Clare, Technology Evangelist, Potix Corporation<br />
|date=December 8th, 2009<br />
|version=ZK 5 RC 2<br />
}}<br />
<br />
<br />
= Architectural Advancements =<br />
<br />
== Server+Client Fusion ==<br />
<br />
Since 2005 ZK has been renowned for its server-centric approach, providing the ultimate in productivity gains. We will continue to push the server-centric envelope to make ZK even more productive. In addition to the server-centric approach, developers can now optionally leverage the full controllability of client-side programming using jQuery and GWT<ref>Coming soon!</ref>! <br />
<br />
<br />
<b>ZK is <i>developer-centric</i></b><br />
<br />
<br />
It's the developer's choice whether to implement a function using either server-side or client-side development according to their requirements. In fact, now developers do not need to choose between productivity and controllability as you can use both server-centric and client-centric approaches in the same application, even in the same page! The amalgamation of these two development strategies is called Server+Client Fusion. <br />
<br />
<br />
It is not about server-centric or client-centric, it is about developer-centric!<br />
<br />
<br />
For more information, you can take a look at the following resources:<br />
<br />
<br />
*[[Small_Talks/2009/July/ZK_5.0_and_Server%2BClient_Fusion |The server-centric and the Server+Client Fusion approach]]<br />
*Client-centric approach [[Small_Talks/2009/July/ZK_5.0_and_jQuery |1]] [[Small_Talks/2009/July/ZK_5.0_and_jQuery_part_2 |2]]<br />
<br />
== Ajax-as-a-Service ==<br />
<br />
One of the main new architectural features is the ability to load client-side JavaScript packages from distributed servers. This means that a local copy of the library does not have to be kept, freeing authors from constantly updating their application to use the latest libraries. This architecture delivers [http://en.wikipedia.org/wiki/Enterprise_application_integration EAI] integration at the client-side, enabling the same close knit ease of integration of a backend system but at the client! <br />
<br />
<br />
For more information on this topic you can take a look at Tom's blog post [http://blog.zkoss.org/index.php/2009/08/16/experiment-on-eai-mashup-and-ajax-as-a-service here]<br />
<br />
= Change to LGPL License =<br />
<br />
To extend our reach beyond what a GPL-licensed framework can achieve, ZK 5 CE<ref>ZK 5 is released under three editions: CE (Community Edition), PE (Professional Edition) and EE (Enterprise Edition)</ref> is now moving to LGPL (Lesser General Public License) offering more freedom and allowing ZK to be integrated with more frameworks under different licensing models.<br />
<br />
Now, with the LGPL-licensed ZK 5 CE, you are free to use, develop and deploy your ZK powered application/framework, regardless of whether it is open source, proprietary, or commercial.<br />
<br />
ZK 3 and older versions were licensed under the GPL and will continue to be in the future. For more information, please visit the [http://www.zkoss.org/license license page].<br />
<br />
=New Components=<br />
<br />
== Flash Charts ==<br />
<br />
ZK 5 now provides a new charting component which uses flash to render the charts on screen. The flash chart provides advantages such as the ability to redraw charts in a more visually pleasing manner and customize the chart styling.<br />
<br />
Below is an example of a ZUL file and resulting chart.<br />
<br />
<source lang="java"><br />
private FlashChart chart;<br />
public void doAfterCompose(Component comp) throws Exception {<br />
super.doAfterCompose(comp);<br />
SimplePieModel model = new SimplePieModel();<br />
model.setValue("2009", "Java", new Integer(500));<br />
model.setValue("2008", "PHP", new Integer(600));<br />
model.setValue("2007", "ASP", new Integer(400));<br />
model.setValue("2006", "C++", new Integer(1200));<br />
chart.setModel(model);<br />
}<br />
</source><br />
<br />
<br /><br />
<br />
[[Image:FlashChart-PieChart.png]]<br />
<br />
For more information please refer to [[Small_Talks/2009/December/Introduction_of_FlashChart |FlashChart]].<br />
<br />
== Colorbox ==<br />
<br />
In ZK 5<ref>Available in ZK 5 PE and EE</ref> we introduce a new component, named Colorbox. The Colorbox provides an easy way for an end user to pick a color. In addition to it being a separate component, the Component Menu has also been extended to provide support for the colorbox.<br />
<br />
[[Image:colorbox.png]]<br />
<br />
For more information please refer to [[Small_Talks/2009/November/ZK_5.0_Component_Colorbox |ZK 5.0 Component Colorbox]].<br />
<br />
=Security & Performance improvements=<br />
<br />
<br />
==Ignoring client commands==<br />
<br />
When a component is invisible or disabled, under normal circumstances you would not want to accept commands sent from the server. With ZK 5 this is now possible, for more information on how to implement this functionality please take a look [[ZK_Developer's_Reference/Security_Tips | here!]]<br />
<br />
==More caching control of the ThemeProvider==<br />
<br />
With the advent of ZK 5 you are now able to configure if and/or how your CSS is cached by the browser. This provides performance enhancements meaning that unnecessary data is not sent to the browser.<br />
<br />
For more information and examples please take a look [[Theme#Implement_a_Theme_Provider | here!]]<br />
<br />
==Reusing the Desktop==<br />
<br />
In ZK 5 it is now possible to reuse a Desktop rather than creating a new one from scratch. This gives a performance benefit as the Desktop does not have to be recreated and disposed. For more information please take a look [[ZK_Developer's_Reference/Performance_Tips/Reuse_Desktops| here]].<br />
<br />
= Ease of use =<br />
<br />
<br />
== Freezing columns ==<br />
<br />
In ZK 5 you are now able to freeze columns within a ''Grid'' and ''Listbox''. This mirrors functionality seen within Excel and makes data in these components easier to read, interpret and handle. <br />
<br />
The following code demonstrates how to freeze a column within a ''Grid'':<br />
<br />
<source lang="xml"><br />
<grid><br />
<frozen style="background: #dfded8" columns="3"><br />
...<br />
</frozen><br />
</grid></source><br />
<br />
For more information and a demonstration please [[Small_Talks/2009/September/ZK_5:_Frozen_Column,_In-place_Editing_and_Rowspan#Live_Demo |here]]!<br />
<br />
==Auto fitting columns ==<br />
<br />
When you want to resize a column of a Grid or Listbox, all you now need to do is double click the column when the mouse is over where the columns meet and the column will automatically resize to fit its contents. To enable this functionality Grid's columns need the attribute '''''sizable="true''"'''. In other words, all sizable column provides the auto-fitting functionality. For example:<br />
<br />
<br />
<source lang="xml"><br />
<grid><br />
<columns sizable="true"><br />
<column label="column 1"/><br />
<column label="column 2"/><br />
<column label="column 3"/><br />
</columns><br />
<rows><br />
<row><br />
<label value="cell1"/><br />
<label value="cell2"/><br />
<label value="cell3"/><br />
</row><br />
</rows><br />
</grid><br />
</source><br />
<br />
== The Event Queue ==<br />
<br />
When server push was introduced in ZK 3, we minimized the server-push API to two methods: activate and deactivate. Once activated, a developer could access any component in any way he liked. However, it still requires some knowledge of thread programming. We have now encapsulated the use of server push in the form of event firing and listening, named the Event Queue (org.zkoss.zkmax.ui.eq.EventQueue)<ref>Available in ZK 5 EE</ref>.<br />
<br />
We extended the event queue to support the concept of scope. Currently, there are two scopes: desktop and application. Within the desktop scope, an event queue is visible only to the associated desktop. Within an application scope, an event queue is visible to the whole application and any thread (not just event listeners) can access it. The application-scope event queue is based on the server push but the developer doesn't need to know that and he doesn't need to do any thread programming, as it is handled automatically by the event queue.<br />
<br />
For more information on the Event Queue please take a look at the [[Small_Talks/2009/August/ZK_5:_Chat_with_Event_Queue |relevant Small Talk]].<br />
<br />
== Enhanced Datebox ==<br />
<br />
The ''Datebox'' has now been enhanced as you can see in the demo below.<br />
<br />
<gflash width="330" height="330">Zk5_datebox_demo.swf</gflash><br />
<br />
== Button supports Ctrl+Click when hyperlinked ==<br />
<br />
<br />
When a button is used to link to another page, see example below, you are able to hold Control and click on the button to follow the link in a new browser window. It makes the navigation more like a hyperlink.<br />
<br />
<source lang="xml"><br />
<button label="Goto hello" href="test.zul"/><br />
</source><br />
<br />
= Improved Layout Control =<br />
<br />
== vflex/hflex support ==<br />
<br />
You are now able to embed any component into the vflex/hflex containers, meaning the layout and size of each control can be controlled. You can find out more information regarding this in this [[Small_Talks/2009/September/ZK_5:_More_Flexible_Layout#Resizing_Flexibility |Small Talk]].<br />
<br />
== File upload ==<br />
<br />
Within ZK 5, the file upload has been redesigned so it can be integrated with any widget. For example, buttons and menu items can now be used to upload a file. In addition to this, the display of the upload status has been enhanced and can be customized easily. <br />
<br />
For more information and a live demo please [[Small_Talks/2009/July/ZK_5:_New_File_Upload |click here]]!<br />
<br />
== The vbox and hbox ==<br />
<br />
The vbox and hbox now have a XUL box model with align and pack attributes, the align attribute specifies how child elements of the box are aligned when the box size is greater than that of its' children combined. For vboxes the align attribute defines how they will be aligned horizontally and for hboxes how they will be aligned vertically. An example below shows a vbox with the align attribute set to <tt>stretch</tt> and the results of such.<br />
<br />
<source lang="xml"><br />
<window width="300px" height="200px" title="Datebox test" border="normal"><br />
<vbox width="300px" height="150px" align="stretch"><br />
<button height="30px" label="Goto 1" /><br />
<button height="30px" label="Goto 2" /><br />
<button height="30px" label="Goto 3" /><br />
</vbox><br />
</window></source><br />
<br />
[[Image:vBox_align_stretch.png]]<br />
<br />
<br />
In the above example the <tt>stretch</tt> option will stretch the button out to fit the container, using <tt>start</tt>, <tt>center</tt> and <tt>end</tt> will align you buttons on the left hand side, center and right hand side respectively.<br />
<br />
<br />
The pack attribute defines where the controls are placed within the box if the combined size of the controls is smaller than that of the size of the box. When the box is a hbox they describe the position horizontally and when the box is a vbox they describe the position vertically.<br />
<br />
An example below shows a hbox with it's pack attribute set to <tt>end</tt>.<br />
<br />
<br />
<source lang="xml"><br />
<window width="300px" height="200px" title="Datebox test" border="normal"><br />
<hbox width="300px" height="150px" pack="end"><br />
<button height="30px" label="Goto 1" /><br />
<button height="30px" label="Goto 2" /><br />
<button height="30px" label="Goto 3" /><br />
</hbox><br />
</window></source><br />
<br />
[[Image:hBox_pack_end.png]]<br />
<br />
In the above example the <tt>end</tt> option places the buttons on the right hand side of the window. The other options <tt>start</tt>, <tt>center</tt> and <tt>stretch</tt> will position your buttons on the left hand side, center and spread them out to fill the container.<br />
<br />
<br />
=== Special cases ===<br />
<br />
<br />
*If you specify "stretch,start", then the Extra proportionally and evenly allocated space for each child is placed on the right or bottom side of the child<br />
*If you specify "stretch,center", then the Extra proportionally and evenly allocated space for each child is split equally along each side of the child<br />
*If you specify "stretch,end", then the Extra proportionally and evenly allocated space for each child is placed on the left or top side of the child<br />
<br />
*If there are {@link Splitter} child inside Box component, then the box behaves like setting stretch pack attribute; no matter you specify "stretch" in pack attribute or not<br />
<br />
== New Cell component ==<br />
<br />
In ZK5, we have introduced a new component named Cell which can be embedded into a Grid or Box (Hbox and Vbox) to fully control the layout and the style. You can now use the rowspan or the colspan property to layout your Grid, for example a content cell can now cross over multiple rows. The code below demonstrates how to do this:<br />
<br />
<source lang="xml"><br />
<row><br />
<cell sclass="years" rowspan="12"><br />
...<br />
</cell><br />
</row><br />
</source><br />
<br />
More information and a live demo is available [[Small_Talks/2009/September/ZK_5:_Frozen_Column,_In-place_Editing_and_Rowspan#Live_Demo |here]]!<br />
<br />
= Functional Improvements =<br />
<br />
<br />
==Sizable Panel==<br />
<br />
The panel can now be resized so long as the attribute '''''sizable''''' is set to ''true''. The example ZUL below shows a panel which can be resized and the image displays a panel which is in the process of being resized.<br />
<br />
<source lang="xml"><br />
<panel sizable="true" id="panel" framable="true" width="500px" height="400px"<br />
title="Panel"<br />
maximizable="true" minimizable="true" border="normal"<br />
collapsible="true" closable="true"><br />
<panelchildren><br />
<textbox width="100%" height="100%" /><br />
</panelchildren><br />
</panel><br />
</source><br />
<br />
[[Image:resizable_panel.png]]<br />
<br />
== Input element supports inplace editing ==<br />
<br />
In ZK5, all input elements can have the in-place-editing functionality, like the combobox, textbox, datebox, and so on.<br />
<br />
For example,<br />
<source lang="xml"><br />
<textbox inplace="true"/><br />
<combobox inplace="true"/><br />
<datebox inplace="true"/><br />
</source><br />
<br />
The ''inplace'' property is used to enable or disable the in-place-editing function for the input element. More information and a live demo is available [[Small_Talks/2009/September/ZK_5:_Frozen_Column,_In-place_Editing_and_Rowspan#Live_Demo |here]]!<br />
<br />
== After clicking a button it can be disabled ==<br />
<br />
To prevent multiple clicks of a button upon clicking a button and a process executing the button is now disabled. The button is then re-enabled after the processing has finished, this is done using the autodisable feature.<br />
<br />
<source lang="xml"><br />
<button id="ok" label="OK" autodisable="self" /><br />
</source><br />
<br />
The above code demonstrates autodisable functionality, it is possible to re-enable buttons using the following method.<br />
<br />
<br />
<source lang="xml"><br />
<button label="enable all" onClick="ok.disabled = cancel.disabled =<br />
false"/></source><br />
<br />
== Timebox now supports new date format ==<br />
<br />
The ''timebox'' now supports new date formats, for example you can now use a to signify it is am or pm. The input string follows the formatting of the [http://java.sun.com/j2se/1.4.2/docs/api/java/text/SimpleDateFormat.html SimpleDateFormat].<br />
<br />
Below is an example of using a within the format.<br />
<br />
<source lang="xml"><br />
<zk><br />
<window title="Test"><br />
<timebox cols="20" format="a hh:mm:ss"/><br />
</window><br />
</zk></source><br />
<br />
== The Fisheye control supports dynamic images ==<br />
<br />
The Fisheye<ref>Available in ZK 5 PE and EE</ref> now supports dynamically created images, for example you can create an image using the Java2D libraries and then set the content of the fisheye to the create image, below is an example of how to do this.<br />
<br />
<source lang="xml"><br />
<?page title="Auto Generated index.zul"?><br />
<zk><br />
<window title="test of autodisable"><br />
<fisheyebar><fisheye id="fish1" /></fisheyebar><br />
<br />
<zscript><br />
import java.awt.*;<br />
import java.awt.image.*;<br />
import java.awt.geom.*;<br />
<br />
<br />
void draw() {<br />
BufferedImage bi = new BufferedImage(200, 200, BufferedImage.TYPE_INT_RGB);<br />
Graphics2D g2d = bi.createGraphics();<br />
Line2D line = new Line2D.Double(0, 0, bi.getWidth(), bi.getHeight());<br />
g2d.setColor(Color.blue);<br />
g2d.setStroke(new BasicStroke(100));<br />
g2d.draw(line);<br />
fish1.setImageContent(bi);<br />
}<br />
<br />
draw();<br />
</zscript> <br />
</window><br />
</zk></source><br />
<br />
== ToolbarButton enhanced ==<br />
<br />
A button supports the toolbar mold and the ''toolbarbutton'' derives from a button with the default mold set to "toolbarbutton".<br />
<br />
<source lang="xml"><br />
<window title="Test"><br />
<toolbar><toolbarbutton label="toolbarbutton" /></toolbar><br />
</window></source><br />
<br />
As a compatibility note, when using the ''toolbarbutton'' when it is not in a ''toolbar'' it will produce a hyperlink. Now within ZK 5 you are able to use a new control called the ''a'' which will produce a normal hyperlink!<br />
<br />
== Overlapping windows improved ==<br />
<br />
The overlapping windows have been improved to included better pop-up functionality and the ability to close the pop-up by clicking on the area surrounding it.<br />
<br />
[[Image:zk5_overlapping_windows.png]]<br />
<br />
== Wiring components in a nested ID space ==<br />
<br />
ZK 5 can now wire components to controllers when they are in a nested ID space. For example we have two ZUL files:<br />
<br />
<br />
'''Main file'''<br />
<br />
<source lang="xml"><br />
<window id="mywindow" apply="MyComposer"><br />
<include id="i" src="includeme.zul" /><br />
</window><br />
</source><br />
<br />
<br />
'''Included file - includeme.zul'''<br />
<br />
<source lang="xml"><br />
<textbox id="username" /><br />
</source><br />
<br />
<br />
Before ZK 5 you could not access the textbox "username" from "MyComposer", however now you can. To do this you need to specify:<br />
<br />
<source lang="java"><br />
public class MyComposer extends GenericAutowireComposer {<br />
Textbox id_of_include$control_id;<br />
<br />
...<br />
}<br />
</source><br />
<br />
In the case of our example this would be:<br />
<br />
<source lang="java"><br />
public class MyComposer extends GenericAutowireComposer {<br />
Textbox i$username;<br />
<br />
...<br />
}<br />
</source><br />
<br />
==Readonly combobox supports keystroke selection of items==<br />
<br />
The combobox now supports selection of items using keystrokes.<br />
<br />
<source lang="xml"><br />
<zk><br />
<zscript><br />
String[] data = new String[30];<br />
for(int j=0; j &lt; data.length; ++j) {<br />
data[j] = "option "+j;<br />
}<br />
ListModel strset = new SimpleListModel(data);<br />
</zscript><br />
<br />
<window id="window" width="100%" height="100%"><br />
<combobox model="${strset}" readonly="true" /><br />
</window><br />
</zk></source><br />
<br />
The above code outputs:<br />
<br />
[[Image:readonly_combobox.png]]<br />
<br />
==Custom attributes now support databinding ==<br />
<br />
Custom attributes now support databinding, for example in the following example an instance of the class foo is bound to a '''''btn''''' attribute of a Button.<br />
<br />
<source lang="xml"><br />
<listbox id="listbox" model="@{fooList}" height="200px" selectedItem="@{selectedFoo}"><br />
<listhead sizable="true"><br />
<listheader label="bar"/><br />
</listhead><br />
<listitem self="@{each=str}" value="@{str}"><br />
<listcell><br />
<button label="drilldown..." onClick='alert(self.getAttribute("btn").item)'><br />
<custom-attributes btn="@{str}"/><br />
</button><br />
</listcell><br />
</listitem><br />
</listbox><br />
</source><br />
<br />
==Client engine supports Canvas==<br />
<br />
The client engine now supports dynamic loading of the [http://en.wikipedia.org/wiki/Canvas_(HTML_element) Canvas]. To include a dependency on ZK canvas you can specify it using ZK 5's package dependencies. To do this please take a look [[Zk.canvas | here!]] For more details on dynamically loading and specifying packages in ZK 5 you can refer to [[ZK_Client-side_Reference/Widget_Package_Descriptor | this link.]]<br />
<br />
= Configuration =<br />
<br />
<br />
== Control whether to allow content to be indexed by search engines ==<br />
<br />
With ZK 5<ref>Available in ZK 5 EE</ref>, you can control whether the generate HTML page can be indexed by the search engines (aka., crawlable). By default, it is not crawlable<ref>On the other hand, ZK 3 and prior is always crawlable.</ref>. You can enable it by using the example below.<br />
<br />
<source lang="xml"><br />
<system-config><br />
<crawlable>true</crawlable><br />
</system-config></source><br />
<br />
== Specify javascript directory ==<br />
You are now able to specify one or multiple locations of your JavaScript files, since it is overkill to place some JavaScript widgets within a JAR file. You can specify a directory using the following markup.<br />
<br />
<source lang="xml"><br />
<library-property><br />
<name>org.zkoss.web.util.resource.dir</name><br />
<value>/WEB-INF/cwr</value><br />
</library-property></source><br />
<br />
== Use ZK.xml to store application specific information ==<br />
<br />
The zk.xml file can now store application specific information, meaning that this information can be used within your own application or plug-in. This is a lot more convenient and will save developers time and effort!<br />
<br />
=Download & other resources =<br />
<br />
*[http://www.zkoss.org/download/zk.dsp Download ZK 5 RC2 here]<br />
*[http://www.zkoss.org/release/rn-5.0.0-RC2.dsp Take a look at ZK 5 RC2's release notes here]<br />
*View the [[Small_Talks/2009/December/ZK_5:_Upgrade_Notes |ZK 5: Upgrade Notes]]<br />
<br />
=References=<br />
<br />
<references/><br />
<br />
<br />
[[Category:ZK]]<br />
[[Category:New Features]]<br />
[[Category:Server+Client fusion]]<br />
{{Template:CommentedSmalltalk_Footer|<br />
|name=Potix Corporation<br />
}}</div>Charhttps://www.zkoss.org/_w/index.php?title=Small_Talks/2009/September/New_Features_of_ZK_5.0_RC&diff=15241Small Talks/2009/September/New Features of ZK 5.0 RC2010-12-21T03:12:28Z<p>Char: /* Download & other resources */</p>
<hr />
<div><br />
{{Template:Smalltalk_Author|<br />
|author=Timothy Clare, Technology Evangelist, Potix Corporation<br />
|date=September 28th, 2009<br />
|version=ZK 5 RC<br />
}}<br />
<br />
<br />
= Architectural Advancements =<br />
<br />
== Server+Client Fusion ==<br />
<br />
Since 2005 ZK has been renowned for its' server-centric approach, providing the ultimate in productivity gains. We will continue to push the server-centric envelope to make ZK even more productive. In addition to the server-centric approach, developers can now optionally leverage the full controllability of client-side programming using jQuery and GWT<ref>Coming soon!</ref>! <br />
<br />
<br />
<b>ZK is <i>developer-centric</i></b><br />
<br />
<br />
It's the developer's choice whether to implement a function using either server-side or client-side development according to their requirements. In fact, now developers do not need to choose between productivity and controllability as you can use both server-centric and client-centric approaches in the same application, even in the same page! The amalgamation of these two development strategies is called Server+Client Fusion. <br />
<br />
<br />
It is not about server-centric or client-centric, it is about developer-centric!<br />
<br />
<br />
For more information, you can take a look at the following resources:<br />
<br />
<br />
* [[Small_Talks/2009/July/ZK_5.0_and_Server%2BClient_Fusion |The server-centric and the Server+Client Fusion approach]]<br />
* Client-centric approach [[Small_Talks/2009/July/ZK_5.0_and_jQuery |1]] [[Small_Talks/2009/July/ZK_5.0_and_jQuery_part_2 |2]]<br />
<br />
== Ajax-as-a-Service ==<br />
<br />
One of the main new architectural features is the ability to load client-side JavaScript packages from distributed servers. This means that a local copy of the library does not have to be kept, freeing authors from constantly updating their application to use the latest libraries. This architecture delivers [http://en.wikipedia.org/wiki/Enterprise_application_integration EAI] integration at the client-side, enabling the same close knit ease of integration of a backend system but at the client! <br />
<br />
<br />
For more information on this topic you can take a look at Tom Yeh』s blog post [http://blog.zkoss.org/index.php/2009/08/16/experiment-on-eai-mashup-and-ajax-as-a-service here]<br />
<br />
= Change to LGPL License =<br />
<br />
To extend our reach beyond what a GPL-licensed framework can achieve, ZK 5 is now moving to LGPL (Lesser General Public License) offering more freedom and allowing ZK to be integrated with more frameworks under different licensing models.<br />
<br />
Now, with the LGPL-licensed ZK 5, you are free to use, develop and deploy your ZK powered application/framework, regardless of whether it is open source, proprietary, or commercial.<br />
<br />
ZK 3 and older versions were licensed under the GPL and will continue to be in the future. <br />
<br />
<br />
= Ease of use =<br />
<br />
<br />
== Freezing columns ==<br />
<br />
In ZK 5 you are now able to freeze columns within a ''Grid'' and ''Listbox''. This mirrors functionality seen within Excel and makes data in these components easier to read, interpret and handle. <br />
<br />
The following code demonstrates how to freeze a column within a ''Grid'':<br />
<br />
<source lang="xml"><br />
<grid><br />
<frozen style="background: #dfded8" columns="3"><br />
...<br />
</frozen><br />
</grid></source><br />
<br />
For more information and a demonstration please [[Small_Talks/2009/September/ZK_5:_Frozen_Column,_In-place_Editing_and_Rowspan#Live_Demo |here]]!<br />
<br />
== The Event Queue ==<br />
<br />
When server push was introduced in ZK 3, we minimized the server-push API to two methods: activate and deactivate. Once activated, a developer could access any component in any way he liked. However, it still requires some knowledge of thread programming. We have now encapsulated the use of server push in the form of event firing and listening, named the Event Queue (org.zkoss.zkmax.ui.eq.EventQueue).<br />
<br />
We extended the event queue to support the concept of scope. Currently, there are two scopes: desktop and application. Within the desktop scope, an event queue is visible only to the associated desktop. Within an application scope, an event queue is visible to the whole application and any thread (not just event listeners) can access it. The application-scope event queue is based on the server push but the developer doesn't need to know that and he doesn't need to do any thread programming, as it is handled automatically by the event queue.<br />
<br />
For more information on the Event Queue please take a look at the [[Small_Talks/2009/August/ZK_5:_Chat_with_Event_Queue |Small Talk]].<br />
<br />
== Enhanced Datebox ==<br />
<br />
The ''Datebox'' has now been enhanced as you can see in the demo below.<br />
<br />
<gflash width="330" height="330">Zk5_datebox_demo.swf</gflash><br />
<br />
== Button supports Ctrl+Click when hyperlinked ==<br />
<br />
<br />
When a button is used to link to another page, see example below, you are able to hold Control and click on the button to follow the link in a new browser window.<br />
<br />
<source lang="xml"><br />
<button label="Goto hello" href="test.zul"/><br />
</source><br />
<br />
<br />
<br />
= Improved Layout Control =<br />
<br />
== vFlex/hFlex support ==<br />
<br />
You are now able to embed any component into the vFlex/hFlex containers, meaning the layout and size of each control can be controlled. You can find out more information regarding this in this [[Small_Talks/2009/September/ZK_5:_More_Flexible_Layout#Resizing_Flexibility |Small Talk]].<br />
<br />
== File upload ==<br />
<br />
Within ZK 5, the file upload has been redesigned so it can be integrated with any widget. For example, buttons and menu items can now be used to upload a file. In addition to this, the display of the upload status has been enhanced and can be customized easily. <br />
<br />
For more information and a live demo please [[Small_Talks/2009/July/ZK_5:_New_File_Upload |click here]]!<br />
<br />
== The vbox and hbox ==<br />
<br />
The vbox and hbox now have a XUL box model with align and pack attributes, the align attribute specifies how child elements of the box are aligned when the box size is greater than that of its' children combined. For vboxes the align attribute defines how they will be aligned horizontally and vice versa for the hbox. An example below shows a vbox with the align attribute set to stretch and the results of such.<br />
<br />
<source lang="xml"><br />
<window width="300px" height="200px" title="Datebox test" border="normal"><br />
<vbox width="300px" height="150px" align="stretch"><br />
<button height="30px" label="Goto 1" /><br />
<button height="30px" label="Goto 2" /><br />
<button height="30px" label="Goto 3" /><br />
</vbox><br />
</window></source><br />
<br />
[[Image:vBox_align_stretch.png]]<br />
<br />
<br />
In the above example the <tt>stretch</tt> option will stretch the button out to fit the container, using <tt>start</tt>, <tt>center</tt> and <tt>end</tt> will align you buttons on the left hand side, center and right hand side respectively.<br />
<br />
<br />
The pack attribute defines where the controls are placed within the box if the combined size of the controls is smaller than that of the size of the box. When the box is an hbox they describe the position horizontally and when the box is a vbox they describe the position vertically.<br />
<br />
An example below shows an hbox with it's pack attribute set to <tt>end</tt>.<br />
<br />
<br />
<source lang="xml"><br />
<window width="300px" height="200px" title="Datebox test" border="normal"><br />
<hbox width="300px" height="150px" pack="end"><br />
<button height="30px" label="Goto 1" /><br />
<button height="30px" label="Goto 2" /><br />
<button height="30px" label="Goto 3" /><br />
</hbox><br />
</window></source><br />
<br />
[[Image:hBox_pack_end.png]]<br />
<br />
In the above example the end option places the buttons on the right hand side of the window. The other options <tt>start</tt>, <tt>center</tt> and <tt>stretch</tt> will position your buttons on the left hand side, center and spread them out to fill the container.<br />
<br />
<br />
=== Special cases ===<br />
<br />
<br />
*If you specify "stretch,start", then the Extra proportionally and evenly allocated space for each child is placed on the right or bottom side of the child<br />
*If you specify "stretch,center", then the Extra proportionally and evenly allocated space for each child is split equally along each side of the child<br />
*If you specify "stretch,end", then the Extra proportionally and evenly allocated space for each child is placed on the left or top side of the child<br />
<br />
*If there are {@link Splitter} child inside Box component, then the box behaves like setting stretch pack attribute; no matter you specify "stretch" in pack attribute or not<br />
<br />
== New Cell component ==<br />
<br />
In ZK5, we have introduced a new component named Cell which can be embedded into a Grid or Box (Hbox and Vbox) to fully control the layout and the style. You can now use the rowspan or the colspan property to layout your Grid, for example a content cell can now cross over multiple rows. The code below demonstrates how to do this:<br />
<br />
<source lang="xml"><br />
<row><br />
<cell sclass="years" rowspan="12"><br />
...<br />
</cell><br />
</row><br />
</source><br />
<br />
More information and a live demo is available [[Small_Talks/2009/September/ZK_5:_Frozen_Column,_In-place_Editing_and_Rowspan#Live_Demo |here]]!<br />
<br />
= Functional Improvements =<br />
<br />
<br />
== Input element supports inplace editing ==<br />
<br />
In ZK5, all input elements can have the in-place-editing functionality, like the combobox, textbox, datebox, and so on.<br />
<br />
For example,<br />
<source lang="xml"><br />
<textbox inplace="true"/><br />
<combobox inplace="true"/><br />
<datebox inplace="true"/><br />
</source><br />
<br />
The ''inplace'' property is used to enable or disable the in-place-editing function for the input element. More information and a live demo is available [[Small_Talks/2009/September/ZK_5:_Frozen_Column,_In-place_Editing_and_Rowspan#Live_Demo |here]]!<br />
<br />
== After clicking a button it can be disabled ==<br />
<br />
To prevent multiple clicks of a button upon clicking a button and a process executing the button is now disabled. The button is then re-enabled after the processing has finished, this is done using the autodisable feature.<br />
<br />
<source lang="xml"><br />
<button id="ok" label="OK" autodisable="self" /><br />
</source><br />
<br />
The above code demonstrates autodisable functionality, it is possible to re-enable buttons using the following method.<br />
<br />
<br />
<source lang="xml"><br />
<button label="enable all" onClick="ok.disabled = cancel.disabled =<br />
false"/></source><br />
<br />
== Timebox now supports new date format ==<br />
<br />
The ''timebox'' now supports new date formats, for example you can now use a to signify it is am or pm. The input string follows the formatting of the [http://java.sun.com/j2se/1.4.2/docs/api/java/text/SimpleDateFormat.html SimpleDateFormat].<br />
<br />
Below is an example of using a within the format.<br />
<br />
<source lang="xml"><br />
<zk><br />
<window title="Test"><br />
<timebox cols="20" format="a hh:mm:ss"/><br />
</window><br />
</zk></source><br />
<br />
== The Fisheye control supports dynamic images ==<br />
<br />
The Fisheye now supports dynamically created images, for example you can create an image using the Java2D libraries and then set the content of the fisheye to the create image, below is an example of how to do this.<br />
<br />
<source lang="xml"><br />
<?page title="Auto Generated index.zul"?><br />
<zk><br />
<window title="test of autodisable"><br />
<fisheyebar><fisheye id="fish1" /></fisheyebar><br />
<br />
<zscript><br />
import java.awt.*;<br />
import java.awt.image.*;<br />
import java.awt.geom.*;<br />
<br />
<br />
void draw() {<br />
BufferedImage bi = new BufferedImage(200, 200, BufferedImage.TYPE_INT_RGB);<br />
Graphics2D g2d = bi.createGraphics();<br />
Line2D line = new Line2D.Double(0, 0, bi.getWidth(), bi.getHeight());<br />
g2d.setColor(Color.blue);<br />
g2d.setStroke(new BasicStroke(100));<br />
g2d.draw(line);<br />
fish1.setImageContent(bi);<br />
}<br />
<br />
draw();<br />
</zscript> <br />
</window><br />
</zk></source><br />
<br />
== ToolbarButton enhanced ==<br />
<br />
A button supports the toolbar mold and the ''toolbarbutton'' derives from a button with the default mold set to "toolbarbutton".<br />
<br />
<source lang="xml"><br />
<window title="Test"><br />
<toolbar><toolbarbutton label="toolbarbutton" /></toolbar><br />
</window></source><br />
<br />
As a compatibility note, when using the ''toolbarbutton'' when it is not in a ''toolbar'' it will produce a hyperlink. Now within ZK 5 you are able to use a new control called the ''a'' which will produce a normal hyperlink!<br />
<br />
== Overlapping windows improved ==<br />
<br />
The overlapping windows have been improved to included better pop-up functionality and the ability to close the pop-up by clicking on the area surrounding it.<br />
<br />
[[Image:zk5_overlapping_windows.png]]<br />
<br />
= Configuration =<br />
<br />
<br />
== Specifying crawlable content ==<br />
<br />
<br />
You are not able to specify whether content is crawlable, this works by generating tags within your content where content only exists in the form of Javascript. This allows your content to be crawled by Google and is similar to how the client-centric frameworks behave. However, there is a performance penalty so this option is disabled by default. You can enable it by using the example below.<br />
<br />
<source lang="xml"><br />
<system-config><br />
<crawlable>true</crawlable><br />
</system-config></source><br />
<br />
== Specify javascript directory ==<br />
You are now able to specify one or multiple locations of your JavaScript files, since it is overkill to place some JavaScript widgets within a JAR file. You can specify a directory using the following markup.<br />
<br />
<source lang="xml"><br />
<library-property><br />
<name>org.zkoss.web.util.resource.dir</name><br />
<value>/WEB-INF/cwr</value><br />
</library-property></source><br />
<br />
== Use ZK.xml to store application specific information ==<br />
<br />
The zk.xml file can now store application specific information, meaning that this information can be used within your own application or plug-in. This is a lot more convenient and will save developers time and effort!<br />
<br />
=Download & other resources =<br />
<br />
*[http://www.zkoss.org/download/zk.dsp Download ZK 5 RC here]<br />
*[http://www.zkoss.org/release/rn-5.0.0-RC.dsp Take a look at ZK 5's release notes here]<br />
*View the [[Small_Talks/2009/December/ZK_5:_Upgrade_Notes |ZK 5: Upgrade Notes]]<br />
<br />
=References=<br />
<br />
<references /><br />
<br />
<br />
<comment>http://docs.zkoss.org/wiki/New_Features_of_ZK_5.0_RC</comment><br />
<br />
<br />
[[Category:ZK]]<br />
[[Category:New Features]]<br />
[[Category:Server+Client fusion]]<br />
{{Template:Smalltalk_Footer|<br />
|name=Potix Corporation<br />
}}</div>Charhttps://www.zkoss.org/_w/index.php?title=Small_Talks/2010/June/New_Features_of_ZK_5.0.3&diff=15240Small Talks/2010/June/New Features of ZK 5.0.32010-12-21T03:11:30Z<p>Char: /* Download & other resources */</p>
<hr />
<div>{{Template:Smalltalk_Author|<br />
|author=Timothy Clare, Technology Evangelist, Potix Corporation<br />
|date=June 29th, 2010<br />
|version=ZK 5.0.3<br />
}}<br />
<br />
ZK 5.0.3 is a maintenance release focusing on fixing some issues and introducing requested features. Requested features included Calendar day rendering along with hflex and vflex improvements.<br />
<br />
=Calendar Day Renderer=<br />
<br />
It is now possible to customize the appearance of days on ZK's Calendar. This is achieved by overriding the default renderer at the client.<br />
<br />
==An example: Customizing Calendar's disabled days==<br />
<br />
Not in the image, days belonging to the previous and next month are not black, they are a light shade of grey as indicated by the function ''disabled'' in the ''zul.db.Renderer''.<br />
<br />
[[Image:calendar_with_renderer.png]]<br />
<br />
<br />
For more information please consult the <javadoc directory="jsdoc">zul.db.Renderer</javadoc> jsdoc.<br />
<br />
=Controlling whether a portallayout panel is draggable=<br />
<br />
ZK 5.0.3 now affords us the ability to specify whether a portallayout panel can be drag-able or not. The code below demonstrates this functionality.<br />
<br />
[[Image:portal_layout_draggable_option.png]]<br />
<br />
<source lang="xml"><br />
<portallayout><br />
<portalchildren style="padding: 5px" width="30%"><br />
<panel height="150px" title="Google Tools" border="normal"<br />
collapsible="true" closable="true" maximizable="true"<br />
style="margin-bottom:10px"><br />
<panelchildren><br />
<br />
</panelchildren><br />
</panel><br />
<panel height="300px" title="LabPixies Clock" border="normal"<br />
collapsible="true" closable="true" maximizable="true"<br />
style="margin-bottom:10px"<br />
draggable="false"><br />
<panelchildren><br />
This is not draggable. <br />
</panelchildren><br />
</panel><br />
</portalchildren><br />
</portallayout><br />
</source><br />
<br />
=Tabbox can auto grow=<br />
<br />
Assume we have two tabpanels, with one larger than the other. If the smaller is displayed first upon showing the new tabpanel the tabbox will now resize itself to accommodate the size of its contents. Below is the code and output.<br />
<br />
[[Image:tabbox_expand.png]]<br />
<br />
[[Image:tabbox_expand2.png]]<br />
<br />
<source lang="xml"><br />
<window id="tabView" title="Case 2" closable="true" hflex="min" width="500px"><br />
<borderlayout hflex="min" vflex="min"><br />
<north hflex="min" vflex="min"><br />
<br />
<tabbox hflex="min" vflex="min"><br />
<tabs><br />
<tab label="Tab One"/><br />
<tab label="Tab Two"/><br />
</tabs><br />
<br />
<tabpanels hflex="min" vflex="min"><br />
<!-- <br />
<custom-attributes org.zkoss.zul.client.rod="false"/><br />
--><br />
<tabpanel hflex="min" vflex="min"><br />
<grid hflex="min" vflex="min"><br />
<rows><br />
<row><br />
<label value="Top East"/><br />
<textbox /><br />
</row><br />
</rows><br />
</grid><br />
<br />
</tabpanel><br />
<tabpanel hflex="min" vflex="min"><br />
<borderlayout hflex="min" vflex="min"><br />
<west hflex="min" vflex="min"><br />
<grid hflex="min" vflex="min"><br />
<rows><br />
<row><br />
<label value="File:"/><br />
<textbox width="98%"/><br />
</row><br />
<row><br />
<label value="Type:"/><br />
<hbox><br />
<listbox rows="1" mold="select"><br />
<listitem label="Java Files,(*.java)"/><br />
<listitem label="All Files,(*.*)"/><br />
</listbox><br />
<button label="Browse..."/><br />
</hbox><br />
</row><br />
<row><br />
<label value="Options:"/><br />
<textbox rows="3" hflex="min" vflex="min"/><br />
</row><br />
</rows><br />
</grid><br />
</west><br />
<east hflex="min" vflex="min"><br />
<grid hflex="min" vflex="min"><br />
<rows><br />
<row><br />
<label value="Top East"/><br />
<textbox /><br />
</row><br />
</rows><br />
</grid><br />
<br />
</east><br />
</borderlayout><br />
<br />
</tabpanel> <br />
</tabpanels><br />
</tabbox><br />
</north><br />
<center hflex="min" vflex="min"><br />
<borderlayout hflex="min" vflex="min"><br />
<west hflex="min" vflex="min"><br />
<grid hflex="min" vflex="min"><br />
<rows><br />
<row><br />
<label value="Bottom West"/><br />
<textbox /><br />
</row><br />
</rows><br />
</grid><br />
</west><br />
<east hflex="min" vflex="min"><br />
<grid hflex="min" vflex="min"><br />
<rows><br />
<row><br />
<label value="Bottom East"/><br />
<textbox /><br />
</row><br />
</rows><br />
</grid><br />
</east><br />
</borderlayout> <br />
</center><br />
</borderlayout><br />
</window><br />
</source><br />
<br />
=Download & other resources =<br />
<br />
*[http://www.zkoss.org/download/zk.dsp Download ZK 5 here]<br />
*[http://www.zkoss.org/release/rn-5.0.3.dsp Take a look at ZK 5's release notes here]<br />
*View the [[Small_Talks/2009/December/ZK_5:_Upgrade_Notes |ZK 5: Upgrade Notes]] and a real case: [[Small Talks/2010/April/Upgrading to ZK 5|Upgrading to ZK 5]]<br />
<br />
[[Category:ZK]]<br />
[[Category:New Features]]<br />
[[Category:Server+Client fusion]]<br />
{{Template:CommentedSmalltalk_Footer|<br />
|name=Potix Corporation<br />
}}</div>Charhttps://www.zkoss.org/_w/index.php?title=Small_Talks/2009/December/ZK_5:_Upgrade_Notes&diff=15239Small Talks/2009/December/ZK 5: Upgrade Notes2010-12-21T03:09:41Z<p>Char: /* See Also */</p>
<hr />
<div>{{Template:Smalltalk_Author|<br />
|author=<br />
|date=December <br />
|version= <br />
}}<br />
<br />
<br />
= Overview =<br />
<br />
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.<br />
<br />
= Server-side Upgrade Notes =<br />
<br />
== Attributes and Namespace ==<br />
=== The return type of <tt>setAttribute</tt> and <tt>removeAttribute</tt> of session/execution/application changed (from <tt>void</tt> to <tt>Object</tt>) ===<br />
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.<br />
<br />
The new signature:<br />
<syntax lang="java"><br />
Object setAttribute(String name, Object value); //returns the previous value if any<br />
Object removeAttribute(String name); //return the previous value if any<br />
</syntax><br />
<br />
=== Namespace deprecated ===<br />
<br />
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.<br />
<br />
<syntax lang="xml"><br />
<variabls foo="better"/> <!-- deprecated --><br />
<custom-attribute foo="better" scope="space"/><br />
</syntax><br />
<br />
Furthermore, ZK 5 will search the attribute scopes for any variable specified in EL or <tt>zscript</tt>.<br />
<br />
<syntax lang="xml"><br />
<window><br />
<custom-attributes a="a" b="b"/> <!-- belongs to window's attribute scope --><br />
<div><br />
<custom-attributes b="B"/> <!-- belongs to div's attribute scope --><br />
${a} and ${b} <!-- result: a and B --><br />
<zscript><br />
String s = a + b; //result: aB<br />
</zscript><br />
</div><br />
</window><br />
</syntax><br />
<br />
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.<br />
<br />
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.<br />
<br />
=== The attribute scope of the ID space is the same of the space owner's attribute scope ===<br />
<br />
In the previous version, the space owner (such as <tt>window</tt>) has two attribute scopes. For example,<br />
<br />
<syntax lang="xml"><br />
<window><br />
<custom-attributes foo="a"/><br />
<div><br />
<custom-attributes foo="b" scope="space"/><br />
</div><br />
<br />
<zscript><br />
self.getAttribute("foo"); //returns a in ZK 3<br />
self.getAttribute("foo", self.SPACE_SCOPE); //returns b<br />
</zscript><br />
</window><br />
</syntax><br />
<br />
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>.<br />
<br />
== System Level Control ==<br />
<br />
=== Event processing thread disabled by default ===<br />
<br />
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 [http://docs.zkoss.org/wiki/Performance_tip#Use_the_Servlet_Thread_to_Process_Events Performance tip#Use_the_Servlet_Thread_to_Process_Events] for how to adjust your application. For example, the <tt>if</tt> clause in the following example is never true.<br />
<br />
<source lang="java" ><br />
if (Messagebox.show("Delete?", "Prompt", Messagebox.YES|Messagebox.NO,<br />
Messagebox.QUESTION) == Messagebox.YES) {<br />
this_never_executes();<br />
}<br />
</source><br />
<br />
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.<br />
<br />
<source lang="xml"><br />
<system-config><br />
<disable-event-thread>false</disable-event-thread><br />
</system-config><br />
</source><br />
<blockquote><br />
----<br />
<references/><br />
</blockquote><br />
<br />
=== The method of <tt>ComponentCloneListener</tt> changed ===<br />
<br />
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.<br />
<br />
<source lang="java"><br />
Object willClone(Component comp);<br />
</source><br />
<br />
=== The <tt>AuPocessor</tt> interface deprecated (replaced with <tt>AuExtension</tt>) ===<br />
<br />
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.<br />
<br />
=== The <tt>addRoot</tt>, <tt>removeRoot</tt>, <tt>moveRoot</tt>, <tt>addFellow</tt> and <tt>removeFellow</tt> methods of <tt>PageCtrl</tt> removed ===<br />
<br />
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>.<br />
<br />
=== The <tt>disable-behind-modal</tt> configuration disabled (always false) ===<br />
<br />
With ZK 5, there is no need to disable widgets that don't belong to the modal window, so this configuration is meaningless.<br />
<br />
== Component Use ==<br />
<br />
=== The <tt>include</tt> component's mode default to <tt>auto</tt> ===<br />
<br />
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<br />
<br />
<source lang="javascript"><br />
<include mode="defer" src="abc.zul"/><br />
</source><br />
<br />
Or, you can specify the following configuration in zk.xml to change the default mode for the whole application.<br />
<br />
<source lang="javascript"><br />
<library-property><br />
<name>org.zkoss.zul.include.mode</name><br />
<value>defer</value><br />
</library-property><br />
</source><br />
<br />
=== The <tt>a</tt> component introduced for HTML A ===<br />
<br />
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,<br />
<br />
<source lang="xml"><br />
Refer <a href="http://www.zkoss.org" label="ZK"/> for details.<br />
Or <a href="http://www.zkoss.org/zkdemo">ZK Demo</a>.<br />
</source><br />
<br />
=== CSS <tt>fixed-layout</tt> property default for <tt>grid</tt> and <tt>listbox</tt> ===<br />
<br />
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.<br />
<br />
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://docs.zkoss.org/wiki/ZK_5:_More_Flexible_Layout#Proportional_Flexibility 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 ).<br />
<br />
<source lang="xml"><br />
<grid width="300px"><br />
<columns><br />
<column label="Order" width="20px"/><br />
<column label="Name" hflex="1"/><br />
<column label="Value" hflex="2"/><br />
</columns><br />
<rows><br />
<row><image src="foo.gif"/> username: <textbox/></row><br />
<row><image src="foo.gif"/> password: <textbox/></row><br />
</rows><br />
</grid><br />
</source><br />
<br />
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.<br />
<br />
<source lang="xml"><br />
<grid width="300px" sizedByContent="true"><br />
</source><br />
<br />
=== The <tt>alphafix</tt> mold of <tt>image</tt> and <tt>imagemap</tt> deprecated ===<br />
<br />
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.<br />
<br />
<source lang="javascript"><br />
<?script content="jq.IE6_ALPHAFIX='.png';"?><br />
</source><br />
<br />
In other words, just specify a regular expression to a JavaScript variable called <tt>jq.IE6_ALPHAFIX</tt>.<br />
<br />
=== The methods of <tt>ClientConstraint</tt> changed ===<br />
<br />
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.<br />
<br />
The typical way to implement the custom client validation is as follows.<br />
<br />
#Implementing a JavaString class, say, foo.MyValidator.<br />
<br />
#Implementing <tt>org.zkoss.zul.ClientConstraint</tt> such that<br />
<br />
<source lang="java"><br />
//Java<br />
String getClientConstraint() {<br />
return "new foo.MyValidator()";<br />
}<br />
String getClientPackages() {<br />
return "foo"; //the package name<br />
}<br />
</source><br />
<br />
=== <tt>SimpleConstraint</tt> performs all validations at client ===<br />
<br />
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,<br />
<br />
<source lang="javascript"><br />
<textbox constraint="/.+@.+\.[a-z]+/,server"/><br />
</source><br />
<br />
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>.<br />
<br />
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.<br />
<br />
<source lang="javascript"><br />
//JavaScript<br />
ClientServerConstraint = zk.$extends(zul.inp.SimpleConstraint, {<br />
serverValidate: true<br />
});<br />
</source><br />
<br />
<blockquote><br />
----<br />
<references/><br />
</blockquote><br />
<br />
=== Overlapped window within another overlapped window not cropped ===<br />
<br />
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.<br />
<br />
=== Meaning of hbox/vbox <tt>pack</tt> attribute follows XUL's specification ===<br />
<br />
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".<br />
<br />
== Component Styling ==<br />
<br />
=== The <tt>dynamic</tt> attribute of the <tt>style</tt> component deprecated ===<br />
<br />
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.<br />
<br />
=== The default mold of the <tt>button</tt> component changed to <tt>os</tt> ===<br />
<br />
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>.<br />
<br />
<source lang="xml"><br />
<library-property><br />
<name>org.zkoss.zul.Button.mold</name><br />
<value>trendy</value><br />
</library-property><br />
</source><br />
<br />
=== The default value of the <tt>zclass</tt> attribute more consistent (<tt>z-</tt> + component-name) ===<br />
<br />
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.<br />
<br />
The affected components are as follows.<br />
<br />
comboitem, bandpopup, groupfoot, listcell, listfoot,<br />
listfooter, listgroup, listgroupfoot, listhead, listheader,<br />
listitem, treecell, treechildren, treecol, treecols, treefoot,<br />
treefooter, treerow, table-children, and table-layout<br />
<br />
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>.<br />
<br />
=== Both <tt>Applet</tt> and <tt>Iframe</tt> extends from <tt>HtmlBasedComponent</tt> (instead of <tt>XulElement</tt>) ===<br />
<br />
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>.<br />
<br />
=== The <tt>ZKPrefix</tt> library property deprecated ===<br />
<br />
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.<br />
<br />
== Component Development ==<br />
<br />
The component development is changed. Refer to [http://docs.zkoss.org/wiki/ZK5:_Component_Development_Guide ZK5: Component Development Guide] for details.<br />
<br />
= Client-side Upgrade Notes =<br />
<br />
The client is rewritten, so your customization have to rewrite, too.<br />
<br />
== Client-side Action deprecated ==<br />
<br />
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,<br />
<br />
<source lang="xml"><br />
<!-- ZK 3.x: Client Side Action --><br />
<textbox<br />
action="onfocus: window.action.show(#{help1}); onblur: window.action.hide(#{help1})" /><br />
<label id="help1" visible="false" value="This is help for text1." /><br />
</source><br />
<br />
can be replaced with<br />
<br />
<source lang="xml"><br />
<!-- ZK 5 --><br />
<textbox xmlns:w="http://www.zkoss.org/2005/zk/client"<br />
w:onFocus="jq(this.$f('help1')).fadeIn()" w:onBlur="jq(this.$f('help1')).fadeOut()"/><br />
<label id="help1" visible="false" value="This is help for text1." /><br />
</source><br />
<br />
== Animation API deprecated ==<br />
<br />
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,<br />
<br />
<source lang="xml"><br />
<!-- ZK 3.x: anima --><br />
<label sclass="ctl" value="SlideDown"<br />
action="onclick: zk.hide(#{t});anima.slideDown(#{t})"/><br />
</source><br />
<br />
<source lang="xml"><br />
<!- ZK 5: with jQury --><br />
<label sclass="ctl" value="SlideDown"<br />
w:onClick="jq(this.$f('t')).hide().slideDown()"<br />
xmlns:w="http://www.zkoss.org/2005/zk/client"/><br />
</source><br />
<br />
Please refer to [http://docs.zkoss.org/wiki/ZK5:_JavaScript_API ZK5: JavaScript API] for the complete description of JavaScript API at the client.<br />
<br />
= See Also =<br />
*[[Small_Talks/2009/December/ZK_5:_Upgrade_Notes |ZK 5: Upgrade Notes]]<br />
*A forum thread : [http://www.zkoss.org/forum/listComment/11094 Upgrade to ZK5 ]<br />
<br />
<br />
<comment>http://docs.zkoss.org/wiki/ZK_5:_Upgrade_Notes</comment><br />
<br />
<br />
{{Template:Smalltalk_Footer|<br />
|name=Potix Corporation <br />
}}</div>Charhttps://www.zkoss.org/_w/index.php?title=Small_Talks/2010/May/New_Features_of_ZK_5.0.2&diff=15238Small Talks/2010/May/New Features of ZK 5.0.22010-12-21T03:09:06Z<p>Char: /* Download & other resources */</p>
<hr />
<div>{{Template:Smalltalk_Author|<br />
|author=Timothy Clare, Technology Evangelist, Potix Corporation<br />
|date=May 12th, 2010<br />
|version=ZK 5.0.2<br />
}}<br />
<br />
<br />
ZK 5.0.2 is a maintenance release focusing on fixing some issues and introducing requested features. Requested features include, enhanced jQuery selectors to enable ZTL testing, auto setting of pageSize when using a paging mold and introduction of a method to track Ajax requests in Google Analytics.<br />
<br />
<br />
<br />
=Auto pageSize depending on the component's height=<br />
<br />
If a component such as Grid which used paging needed to stretch to fit its container then it would do so without any regard for the pageSize. This would have to be set manually by the developer.<br />
<br />
However, in ZK 5.0.2 this is no longer the case. This release introduces an auto PageSize concept which alters the pagesize depending on the size of the component making it much easier for developers to create feature rich application which require paging.<br />
<br />
The feature can be turned on by setting the <tt>autopaging</tt> property to true. The following is an example of this feature.<br />
<br />
[[Image:grid_autopageSize.png]]<br />
<br />
<br />
<source lang="xml"><br />
<grid id="listbox" autopaging="true" mold="paging" vflex="true"><br />
<columns><br />
<column label="column1"/><br />
</columns><br />
<rows><br />
<row forEach="&#36;{items}"><br />
${each}<br />
</row><br />
</rows><br />
</grid><br />
</source><br />
<br />
<br />
<br />
=Enhanced jQuery selectors=<br />
<br />
In ZK 5.0.2 jQuery’s selectors have been enhanced to handle ZK widget’s ID’s and types. The following is a ZUL snippet and then a list of appropriate selectors with their effects.<br />
<br />
<source lang="xml"><br />
<zk><br />
<window id="win1" class="abc" border="normal"><br />
<div id="abc" class="abc"/><br />
</window><br />
<window id="win2"><br />
<div id="abc" class="abc"/><br />
</window><br />
</zk><br />
</source><br />
<br />
#jq('@window > $abc') will return the two div(id=abc) elements<br />
#jq('@window[class~="abc"] @div') will only return the div where is inside the window with "abc" CSS class name<br />
#jq('div$win1 > $abc') will return the div element where is inside the win1 window<br />
#jq('$abc') will return all the elements that match from the given id<br />
#jq('@div') will return all the elements that match from the given tag name<br />
#jq('@window:first') will return id="win1"<br />
#jq('@window[border="normal]"') will return id="win1"<br />
<br />
<br />
For an interactive demo of the above feature please [http://www.zkoss.org/zkdemo/test/selector.zul click here].<br />
For a video of the above feature please [http://blog.zkoss.org/index.php/2010/05/12/zk-5-0-2-zks-jquery-selectors click here].<br />
<br />
=Tracking Ajax requests with Google Analytics=<br />
<br />
One of the problems with Ajax is the fact that it isn’t easy to track clicks in your application without building your own system to do so. ZK 5.0.2 changes this by allowing users to track their application by overriding our beforeSend JavaScript method. <br />
<br />
The following demonstrates some example code.<br />
<br />
<source lang="javascript"><br />
var auBfSend = zAu.beforeSend;<br />
zAu.beforeSend = function (uri, req) {<br />
try {<br />
var target = req.target;<br />
if (target.id) {<br />
var data = req.data||{},<br />
value = data.items && data.items[0]?data.items[0].id:data.value;<br />
pageTracker._trackPageview((target.desktop?target.desktop.requestPath:"") + "/" + target.id + "/" + req.name + (value?"/"+value:""));<br />
}<br />
} catch (e) {<br />
}<br />
return auBfSend(uri, req);<br />
};<br />
</source><br />
<br />
=A simple implementation of the FileuploadDialog=<br />
<br />
With 5.0.0 and 5.0.1, <javadoc method="get()">org.zkoss.zul.Fileupload</javadoc> worked only if the event thread is enabled. If the event thread is disabled, it is suggested to use <javadoc method="setUpload(java.lang.String)">org.zkoss.zul.Button</javadoc>.<br />
<br />
In 5.0.2, <javadoc method="get()">org.zkoss.zul.Fileupload</javadoc> can be used if the event thread is disabled. However, the handling is a bit different. Because the event thread is disabled, <javadoc method="get()">org.zkoss.zul.Fileupload</javadoc> won't return the uploaded files. Rather, you have to register a listener for the event called <tt>onUpload</tt>, and then retrieve the uploaded files in the listener.<br />
<br />
The following code demonstrates how to do this.<br />
<br />
<source lang="xml"><br />
<br />
<zk><br />
<zscript deferred="true"><![CDATA[<br />
import org.zkoss.util.media.Media;<br />
<br />
Executions.getCurrent().getDesktop().setAttribute(<br />
"org.zkoss.zul.Fileupload.target", uploadBtn);<br />
<br />
public void processMedia(Media[] media) {<br />
if (media != null) {<br />
for (int i = 0; i < media.length; i++) {<br />
if (media[i] instanceof org.zkoss.image.Image) {<br />
image.setContent(media[i]);<br />
} else {<br />
Messagebox.show("Not an image: " + media[i], "Error",<br />
Messagebox.OK, Messagebox.ERROR);<br />
break; //not to show too many errors<br />
}<br />
}<br />
}<br />
}<br />
]]></zscript><br />
<vbox><br />
<button id="uploadBtn" label="Upload"<br />
onUpload="processMedia(event.getMedias());"<br />
onClick="Fileupload.get(-1);" /><br />
<image id="image" /><br />
</vbox><br />
</zk><br />
<br />
</source><br />
<br />
It is very important to set the target that <tt>onUpload</tt> will be sent to.<br />
<br />
<source lang="java"><br />
Executions.getCurrent().getDesktop().setAttribute(<br />
"org.zkoss.zul.Fileupload.target", uploadBtn);<br />
</source><br />
<br />
If you do not then the top level component (in this case vbox) will be selected as the target and not the button.<br />
<br />
=Defer rendering of client widgets=<br />
<br />
In ZK 5.0.2 we can now defer the rendering of client widgets. This enables the large and complex pages to be displayed to the user quicker thus making the page feel more responsive.<br />
To implement this you set the property <tt>renderdefer</tt> to a integer value. An example is shown below.<br />
<br />
<source lang="xml"><br />
<window title="inner" width="300px" height="200px" border="normal" renderdefer="100"><br />
</source><br />
<br />
For more information please [[ZK_Developer's_Reference/Performance_Tips/Defer_the_Rendering_of_Client_Widgets| click here]].<br />
<br />
=Download & other resources =<br />
<br />
*[http://www.zkoss.org/download/zk.dsp Download ZK 5 here]<br />
*[http://www.zkoss.org/release/rn-5.0.2.dsp Take a look at ZK 5's release notes here]<br />
*View the [[Small_Talks/2009/December/ZK_5:_Upgrade_Notes |ZK 5: Upgrade Notes]] and a real case: [[Small Talks/2010/April/Upgrading to ZK 5|Upgrading to ZK 5]]<br />
<br />
=References=<br />
<br />
<references/><br />
<br />
<br />
[[Category:ZK]]<br />
[[Category:New Features]]<br />
[[Category:Server+Client fusion]]<br />
{{Template:CommentedSmalltalk_Footer|<br />
|name=Potix Corporation<br />
}}</div>Charhttps://www.zkoss.org/_w/index.php?title=Small_Talks/2010/January/New_Features_of_ZK_5.0&diff=15237Small Talks/2010/January/New Features of ZK 5.02010-12-21T03:08:29Z<p>Char: /* Download & other resources */</p>
<hr />
<div>{{Template:Smalltalk_Author|<br />
|author=Timothy Clare, Technology Evangelist, Potix Corporation<br />
|date=January 26th, 2010<br />
|version=ZK 5<br />
}}<br />
<br />
<br />
= Architectural Advancements =<br />
<br />
== Server+client Fusion ==<br />
<br />
Since 2005 ZK has been renowned for its server-centric approach, providing the ultimate in productivity gains. We will continue to push the server-centric envelope to make ZK even more productive. In addition to the server-centric approach, developers can now optionally leverage the full controllability of client-side programming using jQuery and GWT<ref>Coming soon!</ref>! <br />
<br />
<br />
<b>ZK is <i>developer-centric</i></b><br />
<br />
<br />
It's the developer's choice whether to implement a function using either server-side or client-side development according to their requirements. In fact, now developers do not need to choose between productivity and controllability as you can use both server-centric and client-centric approaches in the same application, even in the same page! The amalgamation of these two development strategies is called Server+Client Fusion. <br />
<br />
<br />
It is not about server-centric or client-centric, it is about developer-centric!<br />
<br />
<br />
For more information, you can take a look at the following resources:<br />
<br />
<br />
*[[Small_Talks/2009/July/ZK_5.0_and_Server%2BClient_Fusion |The server-centric and the Server+Client Fusion approach]]<br />
*Client-centric approach [[Small_Talks/2009/July/ZK_5.0_and_jQuery |1]] [[Small_Talks/2009/July/ZK_5.0_and_jQuery_part_2 |2]]<br />
<br />
== Ajax-as-a-Service ==<br />
<br />
One of the main new architectural features is the ability to load client-side JavaScript packages from distributed servers. This means that a local copy of the library does not have to be kept, freeing authors from constantly updating their application to use the latest libraries. This architecture delivers [http://en.wikipedia.org/wiki/Enterprise_application_integration EAI] integration at the client-side, enabling the same close knit ease of integration of a backend system but at the client! <br />
<br />
<br />
For more information on this topic you can take a look at Tom's blog post [http://blog.zkoss.org/index.php/2009/08/16/experiment-on-eai-mashup-and-ajax-as-a-service here]<br />
<br />
== The Event Queue ==<br />
<br />
When server push was introduced in ZK 3, we minimized the server-push API to two methods: activate and deactivate. Once activated, a developer could access any component in any way he liked. However, it still requires some knowledge of thread programming. We have now encapsulated the use of server push in the form of event firing and listening, named the Event Queue (org.zkoss.zkmax.ui.eq.EventQueue)<ref>Available in ZK 5 EE</ref>.<br />
<br />
We extended the event queue to support the concept of scope. Currently, there are two scopes: desktop and application. Within the desktop scope, an event queue is visible only to the associated desktop. Within an application scope, an event queue is visible to the whole application and any thread (not just event listeners) can access it. The application-scope event queue is based on the server push but the developer doesn't need to know that and he doesn't need to do any thread programming, as it is handled automatically by the event queue.<br />
<br />
For more information on the Event Queue please take a look at the [[Small_Talks/2009/August/ZK_5:_Chat_with_Event_Queue | relevant Small Talk]].<br />
<br />
<br />
===EventQueue supports asynchronous listener===<br />
<br />
With the EventQueue now supporting asynchronous listeners processing of listeners can be easily dealt with outside of the main thread. This means that if a listener takes a long time to execute then the user doesn』t need to wait for this operation to conclude before interacting with the system.<br />
<br />
= Change to LGPL License =<br />
<br />
To extend our reach beyond what a GPL-licensed framework can achieve, ZK 5 CE<ref>ZK 5 is released under three editions: CE (Community Edition), PE (Professional Edition) and EE (Enterprise Edition)</ref> is now moving to LGPL (Lesser General Public License) offering more freedom and allowing ZK to be integrated with more frameworks under different licensing models.<br />
<br />
Now, with the LGPL-licensed ZK 5 CE, you are free to use, develop and deploy your ZK powered application/framework, regardless of whether it is open source, proprietary, or commercial.<br />
<br />
ZK 3 and older versions were licensed under the GPL and will continue to be in the future. For more information, please visit the [http://www.zkoss.org/license license page].<br />
<br />
=ZK 5 CE Update=<br />
<br />
We are continuing our commitment to the Community and the Community Edition of ZK. To this end for the final release of ZK 5 we have added both the BorderLayout and Client-polling Server Push to the edition.<br />
<br />
The BorderLayout is a key layout component providing developers with the ability to place components in north, south, center, west and east areas. This affords developers greater control over the placement of components enabling the rapid creation of complex, enterprise-grade user interfaces.<br />
<br />
Client-polling is a famous method of implementing Server Push and is now included in ZK CE! Server Push is a communication technology which enables the server to send data to the client without a specific request client-side. This is extremely useful when building web applications such as web based instant messenger applications and stock monitoring systems.<br />
<br />
=New Components=<br />
<br />
== Flash Charts ==<br />
<br />
ZK 5 now provides a new charting component which uses flash to render the charts on screen. The flash chart provides advantages such as the ability to redraw charts in a more visually pleasing manner and customize the chart styling.<br />
<br />
Below is an example of a ZUL file and resulting chart.<br />
{|<br />
|width="450px" |<br />
<syntax lang="java"><br />
private FlashChart chart;<br />
public void doAfterCompose(Component comp) throws Exception {<br />
super.doAfterCompose(comp);<br />
SimplePieModel model = new SimplePieModel();<br />
model.setValue("2009", "Java", new Integer(500));<br />
model.setValue("2008", "PHP", new Integer(600));<br />
model.setValue("2007", "ASP", new Integer(400));<br />
model.setValue("2006", "C++", new Integer(1200));<br />
chart.setModel(model);<br />
}<br />
</syntax><br />
|<br />
[[Image:FlashChart-PieChart.png]]<br />
|}<br />
For more information please refer to [[Small_Talks/2009/December/Introduction_of_FlashChart |Introduction of FlashChart]].<br />
<br />
== Colorbox ==<br />
<br />
In ZK 5<ref>Available in ZK 5 PE and EE</ref> we introduce a new component, named Colorbox. The Colorbox provides an easy way for an end user to pick a color. In addition to it being a separate component, the Component Menu has also been extended to provide support for the colorbox.<br />
<br />
[[Image:colorbox.png]]<br />
<br />
For more information please refer to [[Small_Talks/2009/November/ZK_5.0_Component_Colorbox |ZK 5.0 Component Colorbox]].<br />
<br />
=Security & Performance improvements=<br />
<br />
<br />
==Ignoring foreign commands==<br />
<br />
When a component is invisible or disabled, under normal circumstances you would not want to accept commands sent from the server. With ZK 5 this is now possible, for more information on how to implement this functionality please take a look [[ZK_Developer's_Reference/Security_Tips/Block_Request_for_Inaccessible_Widgets | here!]]<br />
<br />
==More caching control of the ThemeProvider==<br />
<br />
With the advent of ZK 5 you are now able to configure if and/or how your CSS is cached by the browser. This provides performance enhancements meaning that unnecessary data is not sent to the browser.<br />
<br />
For more information and examples please take a look [[Theme#Implement_a_Theme_Provider | here!]]<br />
<br />
==Reusing the Desktop==<br />
<br />
In ZK 5 it is now possible to reuse a Desktop rather than creating a new one from scratch. This gives a performance benefit as the Desktop does not have to be recreated and disposed. For more information please take a look [[ZK Developer's Reference/Performance Tips/Reuse Desktops| here]].<br />
<br />
= Ease of use =<br />
<br />
<br />
== Freezing columns ==<br />
<br />
In ZK 5 you are now able to freeze columns within a ''Grid'' and ''Listbox''. This mirrors functionality seen within Excel and makes data in these components easier to read, interpret and handle. <br />
<br />
The following code demonstrates how to freeze a column within a ''Grid'':<br />
<br />
<source lang="xml"><br />
<grid><br />
<frozen style="background: #dfded8" columns="3"><br />
...<br />
</frozen><br />
</grid></source><br />
<br />
For more information and a demonstation please [[Small_Talks/2009/September/ZK_5:_Frozen_Column,_In-place_Editing_and_Rowspan#Live_Demo |click here]]!<br />
<br />
==Auto fitting columns ==<br />
<br />
When you want to resize a column of a Grid or Listbox, all you now need to do is double click the column when the mouse is over where the columns meet and the column will automatically resize to fit its contents. To enable this functionality Grid's columns need the attribute '''''sizable="true''"'''. In other words, all sizable column provides the auto-fitting functionality. For example:<br />
<br />
<br />
<source lang="xml"><br />
<grid><br />
<columns sizable="true"><br />
<column label="column 1"/><br />
<column label="column 2"/><br />
<column label="column 3"/><br />
</columns><br />
<rows><br />
<row><br />
<label value="cell1"/><br />
<label value="cell2"/><br />
<label value="cell3"/><br />
</row><br />
</rows><br />
</grid><br />
</source><br />
<br />
<br />
<br />
== Enhanced Datebox ==<br />
<br />
The ''Datebox'' has nowbeen enhanced as you can see in the demo below.<br />
<br />
<gflash width="330" height="330">Zk5_datebox_demo.swf</gflash><br />
<br />
== Button supports Ctrl+Click when hyperlinked ==<br />
<br />
<br />
When a button is used to link to another page, see example below, you are able to hold Control and click on the button to follow the link in a new browser window. It makes the navigation more like a hyperlink.<br />
<br />
<source lang="xml"><br />
<button label="Goto hello" href="test.zul"/><br />
</source><br />
<br />
= Improved Layout Controls & Molds =<br />
<br />
== vflex/hflex support ==<br />
<br />
You are now able to embed any component into the vflex/hflex containers, meaning the layout and size of each control can be controlled. You can find out more information regarding this in this [[Small_Talks/2009/September/ZK_5:_More_Flexible_Layout#Resizing_Flexibility |Small Talk]].<br />
<br />
== File upload ==<br />
<br />
Within ZK 5, the file upload has been redesigned so it can be integrated with any widget. For example, buttons and menu items can now be used to upload a file. In addition to this, the display of the upload status has been enhanced and can be customized easily. <br />
<br />
For more information and a live demo please [[Small_Talks/2009/July/ZK_5:_New_File_Upload |click here]]!<br />
<br />
== The vbox and hbox ==<br />
<br />
The vbox and hbox now have a XUL box model with align and pack attributes, the align attribute specifies how child elements of the box are aligned when the box size is greater than that of its' children combined. For vboxes the align attribute defines how they will be aligned horizontally and for hboxes how they will be aligned vertically. An example below shows a vbox with the align attribute set to <tt>stretch</tt> and the results of such.<br />
{|<br />
| width="500px"<br />
<syntax lang="xml"><br />
<window width="300px" height="200px" title="Datebox test" border="normal"><br />
<vbox width="300px" height="150px" align="stretch"><br />
<button height="30px" label="Goto 1" /><br />
<button height="30px" label="Goto 2" /><br />
<button height="30px" label="Goto 3" /><br />
</vbox><br />
</window></syntax><br />
|<br />
[[Image:vBox_align_stretch.png]]<br />
|}<br />
<br />
In the above example the <tt>stretch</tt> option will stretch the button out to fit the container, using <tt>start</tt>, <tt>center</tt> and <tt>end</tt> will align you buttons on the left hand side, center and right hand side respectively.<br />
<br />
<br />
The pack attribute defines where the controls are placed within the box if the combined size of the controls is smaller than that of the size of the box. When the box is a hbox they describe the position horizontally and when the box is a vbox they describe the position vertically.<br />
<br />
An example below shows a hbox with it's pack attribute set to <tt>end</tt>.<br />
<br />
{|<br />
| width="500px" |<br />
<syntax lang="xml"><br />
<window width="300px" height="200px" title="Datebox test" border="normal"><br />
<hbox width="300px" height="150px" pack="end"><br />
<button height="30px" label="Goto 1" /><br />
<button height="30px" label="Goto 2" /><br />
<button height="30px" label="Goto 3" /><br />
</hbox><br />
</window></syntax><br />
|<br />
[[Image:hBox_pack_end.png]]<br />
|}<br />
In the above example the <tt>end</tt> option places the buttons on the right hand side of the window. The other options <tt>start</tt>, <tt>center</tt> and <tt>stretch</tt> will position your buttons on the left hand side, center and spread them out to fill the container.<br />
<br />
<br />
=== Special cases ===<br />
<br />
<br />
*If you specify "stretch,start", then the Extra proportionally and evenly allocated space for each child is placed on the right or bottom side of the child<br />
*If you specify "stretch,center", then the Extra proportionally and evenly allocated space for each child is split equally along each side of the child<br />
*If you specify "stretch,end", then the Extra proportionally and evenly allocated space for each child is placed on the left or top side of the child<br />
<br />
*If there are {@link Splitter} child inside Box component, then the box behaves like setting stretch pack attribute; no matter you specify "stretch" in pack attribute or not<br />
<br />
== New Cell component ==<br />
<br />
In ZK5, we have introduced a new component named Cell which can be embedded into a Grid or Box (Hbox and Vbox) to fully control the layout and the style. You can now use the rowspan or the colspan property to layout your Grid, for example a content cell can now cross over multiple rows. The code below demonstrates how to do this:<br />
<br />
<source lang="xml"><br />
<row><br />
<cell sclass="years" rowspan="12"><br />
...<br />
</cell><br />
</row><br />
</source><br />
<br />
More information and a live demo is available [[Small_Talks/2009/September/ZK_5:_Frozen_Column,_In-place_Editing_and_Rowspan#Live_Demo |here]]!<br />
<br />
==New rounded mold==<br />
<br />
ZK 5 introduces a new mold for ZK 5 named 「rounded.」 The mold provides elegant and rounded controls as shown below. <br />
{|<br />
|width="400px"|<br />
<syntax lang="xml"><br />
<zk><br />
<combobox id="a1" mold="rounded"><br />
<comboitem label="Simply Rich" /><br />
</combobox> <br />
<br />
<datebox id="a2" mold="rounded"/> <br />
<timebox id="a3" mold="rounded"/><br />
<spinner id="a4" mold="rounded"/><br />
<bandbox id="a5" mold="rounded"><br />
<bandpopup>Search</bandpopup><br />
</bandbox><br />
</zk><br />
</syntax><br />
|<br />
[[Image:Rounded.png]]<br />
|}<br />
<br />
= Functional Improvements =<br />
<br />
==Introduced variable resolver for CDI (Java EE 6) managed beans==<br />
<br />
Having passed its final release stage on December 10th 2009, Weld offers dependency injection (CDI) as a standard part of the Java EE 6 platform. This is good news to developers everywhere! <br />
<br />
The ZK team has worked fast and has integrated CDI (Context and Dependency Injection) with ZK 5. For more information on the implementation please [http://blog.zkoss.org/index.php/2010/01/07/integrate-zk-and-jsr-299weld/ click here].<br />
<br />
<br />
<br />
==Sizeable Panel==<br />
<br />
The panel can now be resized so long as the attribute '''''sizable''''' is set to ''true''. The example ZUL below shows a panel which can be resized and the image displays a panel which is in the process of being resized.<br />
{|<br />
| width="400px" |<br />
<syntax lang="xml"><br />
<panel sizable="true" id="panel" framable="true" width="500px" height="400px"<br />
title="Panel"<br />
maximizable="true" minimizable="true" border="normal"<br />
collapsible="true" closable="true"><br />
<panelchildren><br />
<textbox width="100%" height="100%" /><br />
</panelchildren><br />
</panel><br />
</syntax><br />
|<br />
[[Image:resizable_panel.png]]<br />
|}<br />
<br />
== Input element supports inplace editing ==<br />
<br />
In ZK5, all input elements can have the in-place-editing functionality, like the combobox, textbox, datebox, and so on.<br />
<br />
For example,<br />
<source lang="xml"><br />
<textbox inplace="true"/><br />
<combobox inplace="true"/><br />
<datebox inplace="true"/><br />
</source><br />
<br />
The ''inplace'' property is used to enable or disable the in-place-editing function for the input element. More information and a live demo is available [[Small_Talks/2009/September/ZK_5:_Frozen_Column,_In-place_Editing_and_Rowspan#Live_Demo |here]]!<br />
<br />
== After clicking a button it can be disabled ==<br />
<br />
To prevent multiple clicks of a button upon clicking a button and a process executing the button is now disabled. The button is then re-enabled after the processing has finished, this is done using the autodisable feature.<br />
<br />
<source lang="xml"><br />
<button id="ok" label="OK" autodisable="self" /><br />
</source><br />
<br />
The above code demonstrates autodisable functionality, it is possible to re-enable buttons using the following method.<br />
<br />
<br />
<source lang="xml"><br />
<button label="enable all" onClick="ok.disabled = cancel.disabled =<br />
false"/></source><br />
<br />
== Timebox now supports new date format ==<br />
<br />
The ''timebox'' now supports new date formats, for example you can now use a to signify it is am or pm. The input string follows the formatting of the [http://java.sun.com/j2se/1.4.2/docs/api/java/text/SimpleDateFormat.html SimpleDateFormat].<br />
<br />
Below is an example of using a within the format.<br />
<br />
<source lang="xml"><br />
<zk><br />
<window title="Test"><br />
<timebox cols="20" format="a hh:mm:ss"/><br />
</window><br />
</zk></source><br />
<br />
== The Fisheye control supports dynamic images ==<br />
<br />
The Fisheye<ref>Available in ZK 5 PE and EE</ref> now supports dynamically created images, for example you can create an image using the Java2D libraries and then set the content of the fisheye to the create image, below is an example of how to do this.<br />
<br />
<source lang="xml"><br />
<?page title="Auto Generated index.zul"?><br />
<zk><br />
<window title="test of autodisable"><br />
<fisheyebar><fisheye id="fish1" /></fisheyebar><br />
<br />
<zscript><br />
import java.awt.*;<br />
import java.awt.image.*;<br />
import java.awt.geom.*;<br />
<br />
<br />
void draw() {<br />
BufferedImage bi = new BufferedImage(200, 200, BufferedImage.TYPE_INT_RGB);<br />
Graphics2D g2d = bi.createGraphics();<br />
Line2D line = new Line2D.Double(0, 0, bi.getWidth(), bi.getHeight());<br />
g2d.setColor(Color.blue);<br />
g2d.setStroke(new BasicStroke(100));<br />
g2d.draw(line);<br />
fish1.setImageContent(bi);<br />
}<br />
<br />
draw();<br />
</zscript> <br />
</window><br />
</zk></source><br />
<br />
== ToolbarButton enhanced ==<br />
<br />
A button supports the toolbar mold and the ''toolbarbutton'' derives from a button with the default mold set to "toolbarbutton".<br />
<br />
<source lang="xml"><br />
<window title="Test"><br />
<toolbar><toolbarbutton label="toolbarbutton" /></toolbar><br />
</window></source><br />
<br />
As a compatability note, when using the ''toolbarbutton'' when it is not in a ''toolbar'' it will produce a hyperlink. Now within ZK 5 you are able to use a new control called the ''a'' which will produce a normal hyperlink!<br />
<br />
== Overlapping windows improved ==<br />
<br />
The overlapping windows have been improved to included better pop-up functionality and the ability to close the pop-up by clicking on the area surrounding it.<br />
<br />
[[Image:zk5_overlapping_windows.png]]<br />
<br />
== Wiring components in a nested ID space ==<br />
<br />
ZK 5 can now wire components to controllers when they are in a nested ID space. For example we have two ZUL files:<br />
<br />
{|<br />
!width="350px"|'''Main file'''<br />
!width="350px"|'''Included file - includeme.zul'''<br />
|-<br />
|<br />
<source lang="xml"><br />
<window id="mywindow" apply="MyComposer"><br />
<include id="i" src="includeme.zul" /><br />
</window><br />
</source><br />
|<br />
<source lang="xml"><br />
<textbox id="username" /><br />
</source><br />
|}<br />
<br />
Before ZK 5 you could not access the textbox "username" from "MyComposer", however now you can. To do this you need to specify:<br />
<br />
<source lang="java"><br />
public class MyComposer extends GenericAutowireComposer {<br />
Textbox id_of_include$control_id;<br />
<br />
...<br />
}<br />
</syntax><br />
<br />
In the case of our example this would be:<br />
<br />
<source lang="java"><br />
public class MyComposer extends GenericAutowireComposer {<br />
Textbox i$username;<br />
<br />
...<br />
}<br />
</source><br />
<br />
==Readonly combobox supports keystroke selection of items==<br />
<br />
The combobox now supports selection of items using keystrokes.<br />
{|<br />
| width="400px"<br />
<syntax lang="xml"><br />
<zk><br />
<zscript><br />
String[] data = new String[30];<br />
for(int j=0; j &lt; data.length; ++j) {<br />
data[j] = "option "+j;<br />
}<br />
ListModel strset = new SimpleListModel(data);<br />
</zscript><br />
<br />
<window id="window" width="100%" height="100%"><br />
<combobox model="${strset}" readonly="true" /><br />
</window><br />
</zk></syntax><br />
|<br />
The code outputs:<br />
[[Image:readonly_combobox.png]]<br />
|}<br />
Refer to : [http://www.zkoss.org/smalltalks/comboboxEnhancement/ Combbox Enhancement]<br />
<br />
==Custom attributes now support databinding ==<br />
<br />
Custom attributes now support databinding, for example in the following example an instance of the class foo is bound to a '''''btn''''' attribute of a Button.<br />
<br />
<source lang="xml"><br />
<listbox id="listbox" model="@{fooList}" height="200px" selectedItem="@{selectedFoo}"><br />
<listhead sizable="true"><br />
<listheader label="bar"/><br />
</listhead><br />
<listitem self="@{each=str}" value="@{str}"><br />
<listcell><br />
<button label="drilldown..." onClick='alert(self.getAttribute("btn").item)'><br />
<custom-attributes btn="@{str}"/><br />
</button><br />
</listcell><br />
</listitem><br />
</listbox><br />
</source><br />
<br />
==Client engine supports Canvas==<br />
<br />
The client engine now supports dynamic loading of the [http://en.wikipedia.org/wiki/Canvas_(HTML_element) Canvas]. To include a dependency on ZK canvas you can specify it using ZK 5's package dependencies.<br />
<br />
The canvas support is provided by the <tt>zk.canvas</tt> package. Thus, we have to specify <tt>depends="zk.canvas"</tt> in your WPD file, or invoke <javadoc directory="jsdoc" method="load(_global_.String, _global_.Function)">_global_.zk</javadoc> explicitly. For example,<br />
<br />
<source lang="xml"><br />
<package name="foo" language="xul/html" depends="zk.canvas"><br />
...<br />
</source><br />
<br />
or<br />
<br />
<source lang="javascript"><br />
zk.load('zk.canvas', function () {...});<br />
</source><br />
<br />
For more details on dynamically loading and specifying packages in ZK 5 you can refer to [[ZK Client-side Reference/Widget Package Descriptor| this link.]]<br />
<br />
==Script directive now supports the if and unless attributes==<br />
<br />
The script directive now supports if and unless attributes granting the user the ability to control the inclusion or exclusion of a script depending upon a condition. For example a developer could include a script if a certain variable』s value was 5.<br />
<br />
The code snippet below shows an example of implementation.<br />
<br />
<source lang="xml"><br />
<?script src="myscript.js" if="myValue==5" ?><br />
</source><br />
<br />
= Configuration =<br />
<br />
<br />
== Control whether to allow content to be indexed by search engines ==<br />
<br />
With ZK 5<ref>Available in ZK 5 EE</ref>, you can control whether the generate HTML page can be indexed by the search engines (aka., crawlable). By default, it is not crawlable<ref>On the other hand, ZK 3 and prior is always crawlable.</ref>. You can enable it by using the example below.<br />
<br />
<source lang="xml"><br />
<system-config><br />
<crawlable>true</crawlable><br />
</system-config></source><br />
<br />
== Specify javascript directory ==<br />
You are now able to specify one or multiple locations of your JavaScript files, since it is overkill to place some JavaScript widgets within a JAR file. You can specify a directory using the following markup.<br />
<br />
<source lang="xml"><br />
<library-property><br />
<name>org.zkoss.web.util.resource.dir</name><br />
<value>/WEB-INF/cwr</value><br />
</library-property></source><br />
<br />
== Use ZK.xml to store application specific information ==<br />
<br />
The zk.xml file can now store application specific information, meaning that this information can be used within your own application or plug-in. This is a lot more convenient and will save developers time and effort!<br />
<br />
=Download & other resources =<br />
<br />
*[http://www.zkoss.org/download/zk.dsp Download ZK 5 here]<br />
*[http://www.zkoss.org/release/rn-5.0.0.dsp Take a look at ZK 5's release notes here]<br />
*View the [[Small_Talks/2009/December/ZK_5:_Upgrade_Notes |ZK 5: Upgrade Notes]] and a real case: [[Small Talks/2010/April/Upgrading to ZK 5|Upgrading to ZK 5]]<br />
<br />
=References=<br />
<br />
<references/><br />
<br />
<br />
[[Category:ZK]]<br />
[[Category:New Features]]<br />
[[Category:Server+Client fusion]]<br />
{{Template:CommentedSmalltalk_Footer|<br />
|name=Potix Corporation<br />
}}</div>Charhttps://www.zkoss.org/_w/index.php?title=Small_Talks/2010/August/New_Features_of_ZK_5.0.4&diff=15236Small Talks/2010/August/New Features of ZK 5.0.42010-12-21T03:06:45Z<p>Char: /* Download & other resources */</p>
<hr />
<div>{{Template:Smalltalk_Author|<br />
|author=Timothy Clare, Technology Evangelist, Potix Corporation<br />
|date=August 31st, 2010<br />
|version=ZK 5.0.4<br />
}}<br />
<br />
<br />
<br />
ZK 5.0.4 is a release focusing on memory improvements and introducing requested new features. In addition to a significant reduction in memory usage ZK 5.0.4 also introduces many new features such as communication between iFrames, new horizontal and vertical layouts and enhanced components such as the slider and combobox.<br />
<br />
=Memory usage improvements=<br />
<br />
In ZK 5.0.4 there have been many optimizations introduced which have significantly reduced the amount of memory consumed by ZK. The memory usage has reduced between 40% and 70% depending on the component tested. When testing with our Sandbox application a grand total of 63% memory was saved by upgrading to ZK 5.0.4.<br />
<br />
For more information and the test results please look at [[Small Talks/2010/August/ZK 5.0.4's memory improvements|ZK 5.0.4's memory improvements]].<br />
<br />
=Refined horizontal and vertical layouts=<br />
<br />
Two new components, <javadoc>org.zkoss.zul.Hlayout</javadoc> and <javadoc>org.zkoss.zul.Vlayout</javadoc> have been introduced to give developers more powerful options when laying out their controls. In the implementation of Vlayout and Hlayout, we use HTML Div tags to render its content, so the size of the output is reduced and the rendering time is approximately twice as fast.<br />
<br />
For more information please take a look at [http://books.zkoss.org/wiki/ZK_Component_Reference/Layouts/Hlayout ZK Component Reference: Hlayout], [http://books.zkoss.org/wiki/ZK_Component_Reference/Layouts/Hlayout Vlayout], and Jumper Chen's blog: [http://blog.zkoss.org/index.php/2010/08/17/two-new-layout-components-in-zk-5-0-4-hlayout-and-vlayout/ "Two new layout components in ZK 5.0.4, Hlayout and Vlayout"].<br />
<br />
=Namespace shortcuts=<br />
<br />
ZK 5.0.4 introduces a namespace shortcuts meaning you do not have to specify the full namespace when writing your ZUL files. For example:<br />
<br />
<source lang="xml"><br />
<n:html xmlns:n="native"><br />
<n:head><br />
</n:head><br />
</n:html><br />
</source><br />
<br />
For a complete list of namespace short cuts please [http://books.zkoss.org/wiki/ZK_Developer's_Guide/Fundamental_ZK/ZK_User_Interface_Markup_Language/Component_Sets_and_XML_Namespaces#Namespace_Shortcuts click here].<br />
<br />
=echoEvent supports any object type=<br />
<br />
Currently the function call <javadoc method="echoEvent(java.lang.String, org.zkoss.zk.ui.Component, java.lang.String)">org.zkoss.zk.ui.event.Events</javadoc> only supports String type data. However, since ZK 5.0.4 a new function <javadoc method="echoEvent(java.lang.String, org.zkoss.zk.ui.Component, java.lang.Object)">org.zkoss.zk.ui.event.Events</javadoc> was introduced to support any Object type meaning more flexibility for developers.<br />
<br />
For more information please take a look at [http://books.zkoss.org/wiki/ZK_Component_Reference/Common_Operations/Event_Handling/Event_Firing#Echo_an_Event ZK Component Reference: Event Firing].<br />
<br />
=Slider now supports clicking to increase and decrease the value=<br />
<br />
ZK 5.0.4 introduces new slider functionality enabling users to increment and decrement the slider by clicking on the position they desire. This functionality replicates desktop based slider functionality.<br />
<br />
[[Image:slider_click.png]]<br />
<br />
<br />
<source lang="xml"><br />
<groupbox mold="3d" width="250px"><br />
<caption label="Default" /><br />
<slider id="slider1" onScroll="zoom(slider1, img1)" /><br />
<image id="img1" src="/img/sun.jpg" width="10px" /><br />
</groupbox><br />
</source><br />
<br />
=Calendar supports moving to next and previous months using mouse scrolling=<br />
<br />
With the introduction of ZK 5.0.4 the calendar component has been enhanced to enable changing months using the mouse scroll wheel, similar to the functionality which is present in Windows.<br />
<br />
[[Image:calendar_slide.png]]<br />
<br />
<br />
=Radio can now be placed anywhere=<br />
<br />
Prior to ZK 5.0.4 a <javadoc>org.zkoss.zul.Radio</javadoc> control was restricted to having an ancestor which was <javadoc>org.zkoss.zul.Radiogroup</javadoc>. However, now with ZK 5.0.4 <javadoc>org.zkoss.zul.Radio</javadoc> can be placed anywhere.<br />
<br />
<source lang="xml"><br />
<radiogroup id="rg1"/><br />
<radiogroup id="rg2"/><br />
<grid width="300px"><br />
<rows><br />
<row><br />
<radio label="radio 1.1" radiogroup="rg1"/><br />
<radio label="radio 1.2" radiogroup="rg1"/><br />
<radio label="radio 1.3" radiogroup="rg1"/><br />
</row><br />
<row><br />
<radio label="radio 2.1" radiogroup="rg2"/><br />
<radio label="radio 2.2" radiogroup="rg2"/><br />
<radio label="radio 2.3" radiogroup="rg2"/><br />
</row><br />
</rows><br />
</grid><br />
</source><br />
<br />
For more information please take a look at [http://books.zkoss.org/wiki/ZK_Component_Reference/Input/Radiogroup#A_row_of_a_grid_as_a_radio_group ZK Component Reference: Radiogroup].<br />
<br />
=Combobox is selectable=<br />
<br />
In ZK 5.0.4 it is now possible to specify a selected default for the Combobox. The following example demonstrates how to do this.<br />
<br />
[[Image:combo_select.png]]<br />
<br />
<br />
<source lang="xml" high="8"><br />
<combobox id="combobox" width="100px"><br />
<attribute name="onCreate"><![CDATA[<br />
List list2 = new ArrayList();<br />
list2.add("David");<br />
list2.add("Thomas");<br />
list2.add("Steven");<br />
ListModelList lm2 = new ListModelList(list2);<br />
lm2.addSelection(lm2.get(0));<br />
combobox.setModel(lm2);<br />
]]></attribute><br />
</combobox><br />
</source><br />
<br />
=The lang.xml widget class supports EL=<br />
<br />
The language XML widget class definition now supports EL enabling dynamic loading of widget classes depending on the situation. For example the following code demonstrates the loading of a widget class dependant upon a property. <br />
<br />
<source lang="xml"><br />
<widget-class>${c:property("whatever")}</widget-class><br />
</source><br />
<br />
By use of EL, developers are allowed to provide very dynamic look for different users and conditions. For more information please take a look at Tom Yeh's blog post titled "[http://blog.zkoss.org/index.php/2010/08/02/totally-different-look-per-user-without-modifying-application/ Totally Different Look per User Without Modifying Application]".<br />
<br />
=Button supports type="submit"=<br />
<br />
Due to strong demand for integration with legacy application the <javadoc>org.zkoss.zhtml.Button</javadoc> now supports the submit type.<br />
<br />
<source lang="xml"><br />
<n:form action="a_uri" xmlns:n="native"><br />
<textbox/><br />
<button type="submit" label="Submit"/><br />
<button type="reset" label="Reset"/><br />
</n:form><br />
</source><br />
<br />
=Merging multiple JavaScript files=<br />
<br />
You can speed up page load times by combining JavaScript files into as few files as possible. Therefore ZK 5.0.4 introduces functionality enabling you to easily merge JavaScript files.<br />
<br />
Notice that the merge of JavaScript files can be done with JSP, DSP or other technologies without this feature. This feature is to provide a system-wide way to minimize the number of JavaScript files.<br />
<br />
For more information please take a look at [[ZK Developer's Reference/Performance Tips/Minimize the number of JavaScript Files to Load|ZK Developer's Reference: Performance Tips], and Jumper Chen's blog post titled [http://blog.zkoss.org/index.php/2010/08/30/speed-up-the-loading-time-of-a-zk-application/ "Speed up the loading time of a ZK Application"].<br />
<br />
=Communication between iFrames without server push=<br />
<br />
If your application contains multiple desktops due to iframes in a portal layout it is now possible to communicate between these instances without the need for server push or timer. It thus minimizes the network traffic.<br />
<br />
In ZK 5.0.4 the concept of group has been introduced which enables the use of a group-scope event queue enabling easy communication between the instances. The code below demonstrates some examples:<br />
<br />
<source lang="javascript" high="1"><br />
EventQueue que = EventQueues.lookup("groupTest", EventQueues.GROUP, true);<br />
<br />
que.subscribe(new EventListener() {<br />
public void onEvent(Event evt) {<br />
o.setValue(o.getValue() + evt.getData() + "\n");<br />
}<br />
});<br />
<br />
void publish() {<br />
String text = i.getValue();<br />
<br />
if (text.length() > 0) {<br />
i.setValue("");<br />
que.publish(new Event("onGroupTest", null, text));<br />
}<br />
}<br />
</source><br />
<br />
For more information please take a look at [http://books.zkoss.org/wiki/ZK_Component_Reference/Common_Operations/Event_Handling/Event_Queues ZK Component Reference: Event Queues]<br />
<br />
<blockquote><br />
----<br />
''This feature requires ZK EE''<br />
</blockquote><br />
<br />
=Memory minimization by not maintaining server state=<br />
<br />
ZK 5.0.4 introduces a new feature called "stub only" which will output the client side resources but will not maintain any server state for them. This is driven by an attribute 「stubonly」 which takes a Boolean value. When set to true the server side state will not be maintained. <br />
<br />
This attribute is inherited from its parent therefore the attribute will apply to any children of a parent with stubonly set to true. Please note that after the stub only component』s HTML has been rendered and sent to the client the stub only components cannot be accessed.<br />
<br />
The following sample code demonstrates stub only functionality. Please note in the example vbox, hbox, label and textbox are all stub only.<br />
<br />
<source lang="xml"><br />
<window title="test of stub-only" border="normal"><br />
<vbox stubonly="true"><br />
<hbox><br />
This is a label at Row 1, Cell 1.<br />
<textbox/><br />
Another label at Row 1, Cell 2 (previous textbox is stub-only too)<br />
</hbox><br />
<hbox><br />
Another at Row 2, Cell 1 (and the following listbox is not stub-only)<br />
<listbox stubonly="false" width="50px"><br />
<listitem label="item1"/><br />
<listitem label="item2"/><br />
</listbox><br />
</hbox><br />
</vbox><br />
</window><br />
</source><br />
<br />
For more information please take a look at [[ZK Developer's Reference/Performance Tips/Specify Stubonly for Client-only Components|ZK Developer's Reference: Performance Tips]].<br />
<br />
<blockquote><br />
----<br />
''This feature requires ZK EE''<br />
</blockquote><br />
<br />
=Download & other resources =<br />
<br />
*[http://www.zkoss.org/download/zk.dsp Download ZK 5 here]<br />
*[http://www.zkoss.org/release/rn-5.0.4.dsp Take a look at ZK 5's release notes here]<br />
*View the [[Small_Talks/2009/December/ZK_5:_Upgrade_Notes |ZK 5: Upgrade Notes]] and a real case: [[Small Talks/2010/April/Upgrading to ZK 5|Upgrading to ZK 5]]<br />
<br />
[[Category:ZK]]<br />
[[Category:New Features]]<br />
[[Category:Server+Client fusion]]<br />
{{Template:CommentedSmalltalk_Footer|<br />
|name=Potix Corporation<br />
}}</div>Charhttps://www.zkoss.org/_w/index.php?title=Small_Talks/2010/August/New_Features_of_ZK_5.0.4&diff=15235Small Talks/2010/August/New Features of ZK 5.0.42010-12-21T03:05:32Z<p>Char: /* Download & other resources */</p>
<hr />
<div>{{Template:Smalltalk_Author|<br />
|author=Timothy Clare, Technology Evangelist, Potix Corporation<br />
|date=August 31st, 2010<br />
|version=ZK 5.0.4<br />
}}<br />
<br />
<br />
<br />
ZK 5.0.4 is a release focusing on memory improvements and introducing requested new features. In addition to a significant reduction in memory usage ZK 5.0.4 also introduces many new features such as communication between iFrames, new horizontal and vertical layouts and enhanced components such as the slider and combobox.<br />
<br />
=Memory usage improvements=<br />
<br />
In ZK 5.0.4 there have been many optimizations introduced which have significantly reduced the amount of memory consumed by ZK. The memory usage has reduced between 40% and 70% depending on the component tested. When testing with our Sandbox application a grand total of 63% memory was saved by upgrading to ZK 5.0.4.<br />
<br />
For more information and the test results please look at [[Small Talks/2010/August/ZK 5.0.4's memory improvements|ZK 5.0.4's memory improvements]].<br />
<br />
=Refined horizontal and vertical layouts=<br />
<br />
Two new components, <javadoc>org.zkoss.zul.Hlayout</javadoc> and <javadoc>org.zkoss.zul.Vlayout</javadoc> have been introduced to give developers more powerful options when laying out their controls. In the implementation of Vlayout and Hlayout, we use HTML Div tags to render its content, so the size of the output is reduced and the rendering time is approximately twice as fast.<br />
<br />
For more information please take a look at [http://books.zkoss.org/wiki/ZK_Component_Reference/Layouts/Hlayout ZK Component Reference: Hlayout], [http://books.zkoss.org/wiki/ZK_Component_Reference/Layouts/Hlayout Vlayout], and Jumper Chen's blog: [http://blog.zkoss.org/index.php/2010/08/17/two-new-layout-components-in-zk-5-0-4-hlayout-and-vlayout/ "Two new layout components in ZK 5.0.4, Hlayout and Vlayout"].<br />
<br />
=Namespace shortcuts=<br />
<br />
ZK 5.0.4 introduces a namespace shortcuts meaning you do not have to specify the full namespace when writing your ZUL files. For example:<br />
<br />
<source lang="xml"><br />
<n:html xmlns:n="native"><br />
<n:head><br />
</n:head><br />
</n:html><br />
</source><br />
<br />
For a complete list of namespace short cuts please [http://books.zkoss.org/wiki/ZK_Developer's_Guide/Fundamental_ZK/ZK_User_Interface_Markup_Language/Component_Sets_and_XML_Namespaces#Namespace_Shortcuts click here].<br />
<br />
=echoEvent supports any object type=<br />
<br />
Currently the function call <javadoc method="echoEvent(java.lang.String, org.zkoss.zk.ui.Component, java.lang.String)">org.zkoss.zk.ui.event.Events</javadoc> only supports String type data. However, since ZK 5.0.4 a new function <javadoc method="echoEvent(java.lang.String, org.zkoss.zk.ui.Component, java.lang.Object)">org.zkoss.zk.ui.event.Events</javadoc> was introduced to support any Object type meaning more flexibility for developers.<br />
<br />
For more information please take a look at [http://books.zkoss.org/wiki/ZK_Component_Reference/Common_Operations/Event_Handling/Event_Firing#Echo_an_Event ZK Component Reference: Event Firing].<br />
<br />
=Slider now supports clicking to increase and decrease the value=<br />
<br />
ZK 5.0.4 introduces new slider functionality enabling users to increment and decrement the slider by clicking on the position they desire. This functionality replicates desktop based slider functionality.<br />
<br />
[[Image:slider_click.png]]<br />
<br />
<br />
<source lang="xml"><br />
<groupbox mold="3d" width="250px"><br />
<caption label="Default" /><br />
<slider id="slider1" onScroll="zoom(slider1, img1)" /><br />
<image id="img1" src="/img/sun.jpg" width="10px" /><br />
</groupbox><br />
</source><br />
<br />
=Calendar supports moving to next and previous months using mouse scrolling=<br />
<br />
With the introduction of ZK 5.0.4 the calendar component has been enhanced to enable changing months using the mouse scroll wheel, similar to the functionality which is present in Windows.<br />
<br />
[[Image:calendar_slide.png]]<br />
<br />
<br />
=Radio can now be placed anywhere=<br />
<br />
Prior to ZK 5.0.4 a <javadoc>org.zkoss.zul.Radio</javadoc> control was restricted to having an ancestor which was <javadoc>org.zkoss.zul.Radiogroup</javadoc>. However, now with ZK 5.0.4 <javadoc>org.zkoss.zul.Radio</javadoc> can be placed anywhere.<br />
<br />
<source lang="xml"><br />
<radiogroup id="rg1"/><br />
<radiogroup id="rg2"/><br />
<grid width="300px"><br />
<rows><br />
<row><br />
<radio label="radio 1.1" radiogroup="rg1"/><br />
<radio label="radio 1.2" radiogroup="rg1"/><br />
<radio label="radio 1.3" radiogroup="rg1"/><br />
</row><br />
<row><br />
<radio label="radio 2.1" radiogroup="rg2"/><br />
<radio label="radio 2.2" radiogroup="rg2"/><br />
<radio label="radio 2.3" radiogroup="rg2"/><br />
</row><br />
</rows><br />
</grid><br />
</source><br />
<br />
For more information please take a look at [http://books.zkoss.org/wiki/ZK_Component_Reference/Input/Radiogroup#A_row_of_a_grid_as_a_radio_group ZK Component Reference: Radiogroup].<br />
<br />
=Combobox is selectable=<br />
<br />
In ZK 5.0.4 it is now possible to specify a selected default for the Combobox. The following example demonstrates how to do this.<br />
<br />
[[Image:combo_select.png]]<br />
<br />
<br />
<source lang="xml" high="8"><br />
<combobox id="combobox" width="100px"><br />
<attribute name="onCreate"><![CDATA[<br />
List list2 = new ArrayList();<br />
list2.add("David");<br />
list2.add("Thomas");<br />
list2.add("Steven");<br />
ListModelList lm2 = new ListModelList(list2);<br />
lm2.addSelection(lm2.get(0));<br />
combobox.setModel(lm2);<br />
]]></attribute><br />
</combobox><br />
</source><br />
<br />
=The lang.xml widget class supports EL=<br />
<br />
The language XML widget class definition now supports EL enabling dynamic loading of widget classes depending on the situation. For example the following code demonstrates the loading of a widget class dependant upon a property. <br />
<br />
<source lang="xml"><br />
<widget-class>${c:property("whatever")}</widget-class><br />
</source><br />
<br />
By use of EL, developers are allowed to provide very dynamic look for different users and conditions. For more information please take a look at Tom Yeh's blog post titled "[http://blog.zkoss.org/index.php/2010/08/02/totally-different-look-per-user-without-modifying-application/ Totally Different Look per User Without Modifying Application]".<br />
<br />
=Button supports type="submit"=<br />
<br />
Due to strong demand for integration with legacy application the <javadoc>org.zkoss.zhtml.Button</javadoc> now supports the submit type.<br />
<br />
<source lang="xml"><br />
<n:form action="a_uri" xmlns:n="native"><br />
<textbox/><br />
<button type="submit" label="Submit"/><br />
<button type="reset" label="Reset"/><br />
</n:form><br />
</source><br />
<br />
=Merging multiple JavaScript files=<br />
<br />
You can speed up page load times by combining JavaScript files into as few files as possible. Therefore ZK 5.0.4 introduces functionality enabling you to easily merge JavaScript files.<br />
<br />
Notice that the merge of JavaScript files can be done with JSP, DSP or other technologies without this feature. This feature is to provide a system-wide way to minimize the number of JavaScript files.<br />
<br />
For more information please take a look at [[ZK Developer's Reference/Performance Tips/Minimize the number of JavaScript Files to Load|ZK Developer's Reference: Performance Tips], and Jumper Chen's blog post titled [http://blog.zkoss.org/index.php/2010/08/30/speed-up-the-loading-time-of-a-zk-application/ "Speed up the loading time of a ZK Application"].<br />
<br />
=Communication between iFrames without server push=<br />
<br />
If your application contains multiple desktops due to iframes in a portal layout it is now possible to communicate between these instances without the need for server push or timer. It thus minimizes the network traffic.<br />
<br />
In ZK 5.0.4 the concept of group has been introduced which enables the use of a group-scope event queue enabling easy communication between the instances. The code below demonstrates some examples:<br />
<br />
<source lang="javascript" high="1"><br />
EventQueue que = EventQueues.lookup("groupTest", EventQueues.GROUP, true);<br />
<br />
que.subscribe(new EventListener() {<br />
public void onEvent(Event evt) {<br />
o.setValue(o.getValue() + evt.getData() + "\n");<br />
}<br />
});<br />
<br />
void publish() {<br />
String text = i.getValue();<br />
<br />
if (text.length() > 0) {<br />
i.setValue("");<br />
que.publish(new Event("onGroupTest", null, text));<br />
}<br />
}<br />
</source><br />
<br />
For more information please take a look at [http://books.zkoss.org/wiki/ZK_Component_Reference/Common_Operations/Event_Handling/Event_Queues ZK Component Reference: Event Queues]<br />
<br />
<blockquote><br />
----<br />
''This feature requires ZK EE''<br />
</blockquote><br />
<br />
=Memory minimization by not maintaining server state=<br />
<br />
ZK 5.0.4 introduces a new feature called "stub only" which will output the client side resources but will not maintain any server state for them. This is driven by an attribute 「stubonly」 which takes a Boolean value. When set to true the server side state will not be maintained. <br />
<br />
This attribute is inherited from its parent therefore the attribute will apply to any children of a parent with stubonly set to true. Please note that after the stub only component』s HTML has been rendered and sent to the client the stub only components cannot be accessed.<br />
<br />
The following sample code demonstrates stub only functionality. Please note in the example vbox, hbox, label and textbox are all stub only.<br />
<br />
<source lang="xml"><br />
<window title="test of stub-only" border="normal"><br />
<vbox stubonly="true"><br />
<hbox><br />
This is a label at Row 1, Cell 1.<br />
<textbox/><br />
Another label at Row 1, Cell 2 (previous textbox is stub-only too)<br />
</hbox><br />
<hbox><br />
Another at Row 2, Cell 1 (and the following listbox is not stub-only)<br />
<listbox stubonly="false" width="50px"><br />
<listitem label="item1"/><br />
<listitem label="item2"/><br />
</listbox><br />
</hbox><br />
</vbox><br />
</window><br />
</source><br />
<br />
For more information please take a look at [[ZK Developer's Reference/Performance Tips/Specify Stubonly for Client-only Components|ZK Developer's Reference: Performance Tips]].<br />
<br />
<blockquote><br />
----<br />
''This feature requires ZK EE''<br />
</blockquote><br />
<br />
=Download & other resources =<br />
<br />
*[http://www.zkoss.org/download/zk.dsp Download ZK 5 here]<br />
*[http://www.zkoss.org/release/rn-5.0.4.dsp Take a look at ZK 5's release notes here]<br />
*View the [[Small_Talks/2009/December/ZK_5:_Upgrade_Notes ZK 5: Upgrade Notes]] and a real case: [[Small Talks/2010/April/Upgrading to ZK 5|Upgrading to ZK 5]]<br />
<br />
[[Category:ZK]]<br />
[[Category:New Features]]<br />
[[Category:Server+Client fusion]]<br />
{{Template:CommentedSmalltalk_Footer|<br />
|name=Potix Corporation<br />
}}</div>Charhttps://www.zkoss.org/_w/index.php?title=Small_Talks/2010/April/Upgrading_to_ZK_5&diff=15234Small Talks/2010/April/Upgrading to ZK 52010-12-21T03:02:37Z<p>Char: /* Upgrade Preparation */</p>
<hr />
<div>{{Template:Smalltalk_Author|<br />
|author=[[Image:EdwinYu.jpg]] Edwin Yu, Senior Software Engineer, [http://zes.zebra.com Zebra Enterprise Solutions]<br />
|date=April 28, 2010<br />
|version=from ZK 3.6 to ZK 5.0<br />
}}<br />
<br />
<br />
= Introduction =<br />
I'd like to share our experiences of upgrading from ZK 3.6 to ZK 5.0 in our software with the community. I hope it will help those who like to do the same upgrade.<br />
<br />
= Background =<br />
Our software doesn't use every single feature that ZK offers. Our views are composed programmatically. We don't use static zul for fixed layout and fixed content. We don't use features on zul such as EL expression and data binding. We heavily use custom macro components to encapsulate their own views, data and user interaction in pure java. We plug in our custom css theme. You may experience different upgrade issues when you use ZK differently from ours.<br />
<br />
= Upgrade Preparation =<br />
It's always helpful to read the ZK upgrade note [http://books.zkoss.org/wiki/Small_Talks/2009/December/ZK_5:_Upgrade_Notes] first. It may have something relevant to you. One thing relevant to us was that ZK 5 disables the event processing thread by default. (I'll talk about it in the next section.) The upgrade note helped me get the sense what I was going to fix in our configuration.<br />
<br />
= Event =<br />
ZK 5 disables the event processing thread by default. This affects us because we have code that expects a response value from a doModel dialog in the Zk 3 event-processing thread model. To preserve what we already have without code change, we enabled the event thread in zk.xml for ZK 5.<code><br />
<system-config><br />
<disable-event-thread>false</disable-event-thread><br />
</system-config><br />
</code><br />
<br />
= Compilation with ZK 5 =<br />
We heavily use the programming way to build our view, so we're sensitive to ZK API changes. After switching out the old ZK 3.6 jars with the ZK 5.0 jars, we had some compilation errors from our macro component code. Below are we experienced:<br />
# Bandbox.closeDropdown() is deprecated and removed. The new method is now close() in ZK 5.<br />
# Listheader.setSort() thows exception in ZK 5.0. We need to put the try/catch around the call<ref>Editor note: it will be fixed in upcoming 5.0.2.</ref>.<br />
# RowRendererExt.DETACH_ON_UNLOAD is deprecated and removed. We change to RowRendererExt.DETACH_ON_RENDER.<br />
<br />
The ZK 3.6[http://www.zkoss.org/javadoc/3.6.2/zk/] and 5[http://www.zkoss.org/javadoc/5.0/zk/] javadoc can help cope with the API changes.<br />
<br />
----<br />
<references/><br />
<br />
= Custom ZK Theme Update =<br />
After our web app was successfully built and deployed, the first thing we noticed when opening our page in a browser was that our custom theme were reverted back to the default blue, and the widgets were incorrectly aligned. The upgrade note helped a lot to get us started. We had to do the following to fix our broken custom theme.<br />
# We had many cases of hbox nested inside vbox (and vice versa), and they became mis-aligned in our app with ZK 5. So we started reviewing all our layouts and removing unnecessary nesting of hbox/vbox. <br />
# We also started using the new cell element. Nesting cell inside hbox or vbox looks better than nesting hbox/vbox each other. <br />
# In some cases, we needed to apply "stretch", "start", "center", "end" attributes to fix the alignment.<br />
# ZK 5 changed the default mold of the button component to be "os", we had to override it back to "trendy" in zk.xml.<br />
# zclass naming in css were updated in ZK 5. We had to globally search and replace the zclass names in our own custom css (img.css.dsp).<br />
# ZK 5 has new CSS styling and images. The ZK Style Guide was not up to date to help us. We had to use Firefox/Chrome to inspect the DOM/CSS in a reverse engineering way to figure out what to add to our custom CSS to override. We could've used the themeBuilder, but we were using only subset of whole ZK CSS. Reverse engineering from DOM tree inspection would be more efficient to produce a smaller set of css overrides.<br />
<br />
It took us about three days to fix our custom theme. However, once the solution had been figured out for the first fix, the rest were just tedious routine.<br />
<br />
= Selenium Tests =<br />
Our build machines reported several selenium test failures after we committed all necessary changes along with the ZK 5 library to the source code repository. We found the following.<br />
# selenium.click(menuItem) alone no longer worked with ZK 5. After talking to ZK Support, we found out that we needed to do selenium.mouseOver(menuItemParent) first, to make it work again<ref>Editor note: it was fixed in 5.0.1.</ref>.<br />
# selenium.clickAt(listheader) brought up wrong popup menu for us with ZK 5. Because we had multiple listeners on the listheader, and we were not sure whether the new problem was in our incorrect coding that was discovered by ZK 5, or in the new complexity of jquery upgrade in ZK 5. However, we found a workaround to clickAt() adjacent component that could bring the correct popup menu.<br />
<br />
Regarding to the selenium-ZK integration, the overall feeling is that our build machines had unreliable test results from the old ZK3 codebase. Meaning, some tests broke once awhile for no reason. However, with ZK5, our build machines report better consistent results.<br />
<br />
----<br />
<references/><br />
<br />
= Troubleshooting =<br />
What happens if you encounter a mysterious javascript error that you can't relate to your java code?<br />
<br />
After fixing obvious bugs and testing with ZK 5 library for days, we started to discover javascript errors with no server-side exceptions. To us, any incorrect zk programming (in pure java) should get a server-side java exception, instead of getting mysterious javascript errors. Our code are complex and dynamic, and we couldn't re-create the same bug in a simple zul page to submit a bug report. After talking to the ZK Support, I learned a good way to collect the bug information when I couldn't relate a javascript error to our java code. Maybe the steps are not new to you, but here is my general approach.<br />
* Use Firefox with the firebug plugin. In firebug's console tab, check "Show Stack Trace with Errors"<br />
* Turn on the debug flag in your zk.xml as shown below. This will allow firebug to show the uncompressed javascript code when breaking on an error.<br />
<code><br />
<client-config><br />
<debug-js>true</debug-js><br />
</client-config><br />
</code><br />
* Load your page in Firefox and get to the point where the javascript error occurs. Firebug stops Firefox and breaks on the javascript code line. There I collect the stack trace and the code line where the error occurs. Example of screenshots are below.<br />
<br />
[[Image:buga.jpg]]<br />
<br />
[[Image:bugb.jpg]]<br />
<br />
With the above information and the use case scenario description, it helped the ZK Support fix the bug. We're a ZK Enterprise Edition subscriber. The ZK Support team was very efficient to fix the bugs and produce a freshly nightly build the next day for us to download. I also tried to post a bug on the ZK forum with sample code. Someone from the ZK team read my post and created a bug report on the next day. The bug was fixed in the next freshly build a week later.<br />
<br />
= Misc =<br />
Only few things were discovered during ZK 5 upgrade that may or may not be bugs with ZK 5. We couldn't reproduce the problems in simple cases for ZK Support to investigate. However, we found workaround and we just moved on to other high priority items. But I list here just for your interest.<br />
# The hyphen inside the page id attribute, such as "some-id", in <?page id="some-id"?> doesn't work for our environment with ZK 5. It caused widgets not responding to user clicks. I had to remove "-" in <?page id=""?> in our zul.<br />
# Our own IdGenerator in zk.xml had a bug to produce non alpha-numeric characters (except for underscore) in the ID string. This caused our ZK view to produce Javascript error.<br />
<br />
= Conclusion =<br />
ZK 5 had many features we liked to use. We're glad we spent the effort to upgrade and start using the new features. I hope the path that we've gone through during the upgrade may help you too.<br />
<br />
= See Also =<br />
*[[Small_Talks/2009/December/ZK_5:_Upgrade_Notes |ZK 5: Upgrade Notes]]<br />
<br />
{{Template:CommentedSmalltalk_Footer|<br />
|name=Potix Corporation<br />
}}</div>Charhttps://www.zkoss.org/_w/index.php?title=Small_Talks/2010/April/Upgrading_to_ZK_5&diff=15232Small Talks/2010/April/Upgrading to ZK 52010-12-21T02:59:33Z<p>Char: /* Upgrade Preparation */</p>
<hr />
<div>{{Template:Smalltalk_Author|<br />
|author=[[Image:EdwinYu.jpg]] Edwin Yu, Senior Software Engineer, [http://zes.zebra.com Zebra Enterprise Solutions]<br />
|date=April 28, 2010<br />
|version=from ZK 3.6 to ZK 5.0<br />
}}<br />
<br />
<br />
= Introduction =<br />
I'd like to share our experiences of upgrading from ZK 3.6 to ZK 5.0 in our software with the community. I hope it will help those who like to do the same upgrade.<br />
<br />
= Background =<br />
Our software doesn't use every single feature that ZK offers. Our views are composed programmatically. We don't use static zul for fixed layout and fixed content. We don't use features on zul such as EL expression and data binding. We heavily use custom macro components to encapsulate their own views, data and user interaction in pure java. We plug in our custom css theme. You may experience different upgrade issues when you use ZK differently from ours.<br />
<br />
= Upgrade Preparation =<br />
It's always helpful to read the 'ZK upgrade note' [http://books.zkoss.org/wiki/Small_Talks/2009/December/ZK_5:_Upgrade_Notes] first. It may have something relevant to you. One thing relevant to us was that ZK 5 disables the event processing thread by default. (I'll talk about it in the next section.) The upgrade note helped me get the sense what I was going to fix in our configuration.<br />
<br />
= Event =<br />
ZK 5 disables the event processing thread by default. This affects us because we have code that expects a response value from a doModel dialog in the Zk 3 event-processing thread model. To preserve what we already have without code change, we enabled the event thread in zk.xml for ZK 5.<code><br />
<system-config><br />
<disable-event-thread>false</disable-event-thread><br />
</system-config><br />
</code><br />
<br />
= Compilation with ZK 5 =<br />
We heavily use the programming way to build our view, so we're sensitive to ZK API changes. After switching out the old ZK 3.6 jars with the ZK 5.0 jars, we had some compilation errors from our macro component code. Below are we experienced:<br />
# Bandbox.closeDropdown() is deprecated and removed. The new method is now close() in ZK 5.<br />
# Listheader.setSort() thows exception in ZK 5.0. We need to put the try/catch around the call<ref>Editor note: it will be fixed in upcoming 5.0.2.</ref>.<br />
# RowRendererExt.DETACH_ON_UNLOAD is deprecated and removed. We change to RowRendererExt.DETACH_ON_RENDER.<br />
<br />
The ZK 3.6[http://www.zkoss.org/javadoc/3.6.2/zk/] and 5[http://www.zkoss.org/javadoc/5.0/zk/] javadoc can help cope with the API changes.<br />
<br />
----<br />
<references/><br />
<br />
= Custom ZK Theme Update =<br />
After our web app was successfully built and deployed, the first thing we noticed when opening our page in a browser was that our custom theme were reverted back to the default blue, and the widgets were incorrectly aligned. The upgrade note helped a lot to get us started. We had to do the following to fix our broken custom theme.<br />
# We had many cases of hbox nested inside vbox (and vice versa), and they became mis-aligned in our app with ZK 5. So we started reviewing all our layouts and removing unnecessary nesting of hbox/vbox. <br />
# We also started using the new cell element. Nesting cell inside hbox or vbox looks better than nesting hbox/vbox each other. <br />
# In some cases, we needed to apply "stretch", "start", "center", "end" attributes to fix the alignment.<br />
# ZK 5 changed the default mold of the button component to be "os", we had to override it back to "trendy" in zk.xml.<br />
# zclass naming in css were updated in ZK 5. We had to globally search and replace the zclass names in our own custom css (img.css.dsp).<br />
# ZK 5 has new CSS styling and images. The ZK Style Guide was not up to date to help us. We had to use Firefox/Chrome to inspect the DOM/CSS in a reverse engineering way to figure out what to add to our custom CSS to override. We could've used the themeBuilder, but we were using only subset of whole ZK CSS. Reverse engineering from DOM tree inspection would be more efficient to produce a smaller set of css overrides.<br />
<br />
It took us about three days to fix our custom theme. However, once the solution had been figured out for the first fix, the rest were just tedious routine.<br />
<br />
= Selenium Tests =<br />
Our build machines reported several selenium test failures after we committed all necessary changes along with the ZK 5 library to the source code repository. We found the following.<br />
# selenium.click(menuItem) alone no longer worked with ZK 5. After talking to ZK Support, we found out that we needed to do selenium.mouseOver(menuItemParent) first, to make it work again<ref>Editor note: it was fixed in 5.0.1.</ref>.<br />
# selenium.clickAt(listheader) brought up wrong popup menu for us with ZK 5. Because we had multiple listeners on the listheader, and we were not sure whether the new problem was in our incorrect coding that was discovered by ZK 5, or in the new complexity of jquery upgrade in ZK 5. However, we found a workaround to clickAt() adjacent component that could bring the correct popup menu.<br />
<br />
Regarding to the selenium-ZK integration, the overall feeling is that our build machines had unreliable test results from the old ZK3 codebase. Meaning, some tests broke once awhile for no reason. However, with ZK5, our build machines report better consistent results.<br />
<br />
----<br />
<references/><br />
<br />
= Troubleshooting =<br />
What happens if you encounter a mysterious javascript error that you can't relate to your java code?<br />
<br />
After fixing obvious bugs and testing with ZK 5 library for days, we started to discover javascript errors with no server-side exceptions. To us, any incorrect zk programming (in pure java) should get a server-side java exception, instead of getting mysterious javascript errors. Our code are complex and dynamic, and we couldn't re-create the same bug in a simple zul page to submit a bug report. After talking to the ZK Support, I learned a good way to collect the bug information when I couldn't relate a javascript error to our java code. Maybe the steps are not new to you, but here is my general approach.<br />
* Use Firefox with the firebug plugin. In firebug's console tab, check "Show Stack Trace with Errors"<br />
* Turn on the debug flag in your zk.xml as shown below. This will allow firebug to show the uncompressed javascript code when breaking on an error.<br />
<code><br />
<client-config><br />
<debug-js>true</debug-js><br />
</client-config><br />
</code><br />
* Load your page in Firefox and get to the point where the javascript error occurs. Firebug stops Firefox and breaks on the javascript code line. There I collect the stack trace and the code line where the error occurs. Example of screenshots are below.<br />
<br />
[[Image:buga.jpg]]<br />
<br />
[[Image:bugb.jpg]]<br />
<br />
With the above information and the use case scenario description, it helped the ZK Support fix the bug. We're a ZK Enterprise Edition subscriber. The ZK Support team was very efficient to fix the bugs and produce a freshly nightly build the next day for us to download. I also tried to post a bug on the ZK forum with sample code. Someone from the ZK team read my post and created a bug report on the next day. The bug was fixed in the next freshly build a week later.<br />
<br />
= Misc =<br />
Only few things were discovered during ZK 5 upgrade that may or may not be bugs with ZK 5. We couldn't reproduce the problems in simple cases for ZK Support to investigate. However, we found workaround and we just moved on to other high priority items. But I list here just for your interest.<br />
# The hyphen inside the page id attribute, such as "some-id", in <?page id="some-id"?> doesn't work for our environment with ZK 5. It caused widgets not responding to user clicks. I had to remove "-" in <?page id=""?> in our zul.<br />
# Our own IdGenerator in zk.xml had a bug to produce non alpha-numeric characters (except for underscore) in the ID string. This caused our ZK view to produce Javascript error.<br />
<br />
= Conclusion =<br />
ZK 5 had many features we liked to use. We're glad we spent the effort to upgrade and start using the new features. I hope the path that we've gone through during the upgrade may help you too.<br />
<br />
= See Also =<br />
*[[Small_Talks/2009/December/ZK_5:_Upgrade_Notes |ZK 5: Upgrade Notes]]<br />
<br />
{{Template:CommentedSmalltalk_Footer|<br />
|name=Potix Corporation<br />
}}</div>Charhttps://www.zkoss.org/_w/index.php?title=Small_Talks/2010/January/Deploying_a_ZK_application_on_Amazon_EC2_using_CloudFoundry&diff=15231Small Talks/2010/January/Deploying a ZK application on Amazon EC2 using CloudFoundry2010-12-21T02:55:17Z<p>Char: /* Deployment */</p>
<hr />
<div>{{Template:Smalltalk_Author|<br />
|author=Sotohiro Terashima<br />
<br /><br />
<div><br />
<div style="border:solid 1px; padding:5px; height:110px;width:600px" ><br />
<div style="float:left;padding-bottom:25px;padding-right:10px;border:0 none;vertical-align:middle;">[[Image:sera.png]]</div>Sotohiro graduated from the Tokyo Institute of Technology and was employed to NHK(Japan Broadcasting Corporation) in 1972. He engaged in all round Broadcasting engineering and experienced many computer technologies, from a micro computer (Z80) to a main frame (IBM370). After NHK, he went to NHK Media Technology where he studied Java and Flash technology. At this time he worked on numerous systems and became enchanted by the ZK Framework. Sotohiro is the owner of the ZK development plug-in for NetBeans, REM.<br />
</div><br />
<br /><br />
|date=January 19, 2010<br />
|version=ZK 5<br />
}}<br />
<br />
=Introduction=<br />
<br />
I succeeded in running the ZK Demo program on Amazon EC2 and wanted to share my experiences with the community. Using Cloud Foundry, it was very easy to install Apache + Tomcat + MySQL on the Cloud.<br />
<br />
=About CloudFoundry=<br />
<br />
*The founder of CloudFoundry is [http://www.chrisrichardson.net/index.html Chris Richardson]<br />
*CloudFoundry was acquired by SpringSource last year<br />
*SpringSource was acquired by VMWare soon after above event<br />
**CloudFoundry is now VMWare's "Automated Deployment and Management for Java applications on Amazon EC2" tool<br />
**It is currently in beta and we can use it with no charge<br />
<br />
=Registration=<br />
<br />
In order to try Amazon EC2 using CloudFoundry we have to register with CloudFoundry. To register on Cloud Foundry we need Amazon Web Services Credentials.<br />
<br />
==Steps==<br />
<br />
*Sign up for AWS and retrieve both the key id and secret key id<br />
*Create an EC2 private keypair using the AWS Manage Console or ElasticFox plug-in<br />
*We need to reuse the Database definition after re-running the virtual server instance. Therefore we must use Amazon EBS(Elastic Block Store) to sustain the Database.<br />
<br />
<br />
==Notes==<br />
<br />
*In the step of this article, we use Putty and WinSCP to communicate with the virtual server instance <br />
*The EC2 private keypair cannot be applied as is to Putty and WinSCP <br />
**We must convert it to a Putty private key(ppk) using Puttygen.exe(Putty SSH key generation utility) <br />
*We make ports 22 and 80 available in the Security Groups of the AWS Manage Console <br />
**Port 22 is for SSH communication <br />
**Port 80 is for Web Browsing <br />
*The default account of the virtual server instance is root and no password <br />
**I kept these credentials as I was just testing and only running for a short time<br />
<br />
=Deployment=<br />
<br />
As I mentioned first,on 2009 Dec 3,I deployed 2 applications,ZK3.6.3 Demo and JPetstore which uses MySQL. Today 2010 Jan 5,I will add more ZK application which uses MySQL<br />
<br />
<br />
*This ZK application is named ZKtodoMySQL, which is derived from the tutorial [http://books.zkoss.org/wiki/ZK_Getting_Started/Creating_a_Database-driven_Application#Your_first_ZK_application_.22To-do.22_list Your first ZK application "To-do" list] <br />
*This tutorial is a sample of "A real-world application with a database", and uses HSQLDB as the database.<br />
**I migrated this to MySQL version.<br />
**The complete NetBeans Project(Using REM 3.6.3) is [https://sourceforge.net/projects/zkforge/files/Small%20Talks/Deploying%20a%20ZK%20application%20on%20Amazon%20EC2%20using%20CloudFoundry/ZKtodoMySQL.ZIP/download here].<br />
<br />
==Steps==<br />
<br />
===Home Page of CloundFoundry(after log-in)===<br />
<br />
[[Image:Home.png]]<br />
<br />
<br />
===Then click the applications tab===<br />
<br />
[[Image:Applications.png]]<br />
<br />
===Then click the Edit Icon (image of a pencil)===<br />
<br />
[[Image:BeforeAdd.png]]<br />
<br />
===Now,I will add a new application, ZKtodoMySQL===<br />
<br />
[[Image:AddWarButton.png]]<br />
<br />
===Next we click the Save Button and the Upgrading message is displayed ===<br />
<br />
[[Image:UPdating.png]]<br />
<br />
===Next we click the Deploy Button (green triangle).===<br />
<br />
Before we click the Launch Button,we add the Existing EBS Volume to the Database Storage<br />
<br />
*Device /dev/sdh<br />
*Volume vol-f73ec59e - JPetsto<br />
*Back Frequency Manual<br />
<br />
[[Image:DeployUp.png]]<br />
<br />
<br />
[[Image:DeployDown.png]]<br />
<br />
<br />
===Before Launch Deployment, we open the AWS Management Console===<br />
<br />
[[Image:AWS.png]]<br />
<br />
===Before clicking the Launch Button, we need to input the name "JPetStoreandZKtodo" at the Stage 6===<br />
<br />
After clicking the Launch Button we notice that the instance which appears here is the same as the one in the AWS Management Console.<br />
<br />
[[Image:Launched.png]]<br />
<br />
===We then use SSH by Putty to issue commands to MySQL===<br />
<br />
We use WinSCP to transport the script file into server instance and when we start Putty, we get next message.<br />
<br />
[[Image:Security.png]]<br />
<br />
===When we answer yes to this dialog we get the next window===<br />
<br />
[[Image:CloudFoundry.png]]<br />
<br />
===We transfer the script file "createtable.sql" to the server instance using WinSCP===<br />
<br />
*At server console<br />
**Create database zkmysql in MySQL <br />
***#mysqladmin -u root create zkmysql<br />
**Create table in zkmysql using scriptfile<br />
***#mysql -uroot zkmysql < createtable.sql<br />
<br />
*At MySQL console,check database<br />
**#mysql<br />
**mysql>show database;<br />
<br />
[[Image:CloudFoundryCMDS.png]]<br />
<br />
===All the tasks are completed===<br />
<br />
If we look at the server instance address by Browser,we get next page.<br />
If we look at the http://[server instance address]/ZKtodoMySQL then we get ZK application.<br />
<br />
<br />
[[Image:BrowseCloudFoundry.png]]<br />
<br />
[[Image:ZKonCloudFoundry.png]]<br />
<br />
=Download=<br />
<br />
The complete project can be found [https://sourceforge.net/projects/zkforge/files/Small%20Talks/Deploying%20a%20ZK%20application%20on%20Amazon%20EC2%20using%20CloudFoundry/ZKtodoMySQL.ZIP/download here].<br />
<br />
[[Category:Deployment]]<br />
{{Template:CommentedSmalltalk_Footer|<br />
|name=Sotohiro Terashima<br />
}}</div>Charhttps://www.zkoss.org/_w/index.php?title=Small_Talks/2008/December/Live_Data,_Paging,_setModel_and_Implement_your_own_renderer&diff=15230Small Talks/2008/December/Live Data, Paging, setModel and Implement your own renderer2010-12-21T02:51:58Z<p>Char: </p>
<hr />
<div>{{Template:Smalltalk_Author|<br />
|author=<br />
|date=December <br />
|version= <br />
}}<br />
<br />
<br />
==Overview==<br />
In a real world web application, it's common to collect data from database, and show it in <tt>listbox</tt> or <tt>grid</tt> or <tt>tree</tt>. The underlying data may be hundreds of thousands records. It's impractical to load them all to the client. Therefore ZK introduces concepts of <tt>Live Data</tt>, <tt>Paging</tt>. To separate view from data, ZK also introduces the concept of <tt>model</tt>. It is easier to use different views to show the same set of data. To show data in the view any way you like, a developer may implement his own renderer; ZK has provided a default renderer.<br />
<br />
==What's Live Data==<br />
The main idea of "live data" is to separate data from the view. Developers only have to manipulate the data model, and the data of view (UI Component) will be updated accordingly. Secondly, it shortens the response time of user since only the required data will be downloaded the first time.<br />
<br />
==What's Paging==<br />
Paging separates long content into multiple pages.<br />
<br />
A paging component is used for this purpose. For example, assume that you have 100 items and prefer to show 20 items at a time, then you can use the paging components as follows.<br />
<br />
[[Image:100000000000007A00000013F689AD21.png]]<br />
<br />
<source lang="xml" ><br />
<paging totalSize="100" pageSize="20"/><br />
</source><br />
<br />
Then, when a user clicks on the hyperlinks, the <tt>onPaging</tt> event is sent with an instance of <tt>org.zkoss.zul.event.PagingEvent</tt> to the paging component. To decide which portion of your 100 items are visible, you shall add a listener to the paging component.<br />
<br />
<source lang="xml" ><br />
<paging id="paging"/><br />
<zscript><br />
List result = new SearchEngine().find("ZK");<br />
//assume SearchEngine.find() will return a list of items.<br />
paging.setTotalSize(result.size());<br />
paging.addEventListener("onPaging", new EventListener() {<br />
public void onEvent(Event event) {<br />
int pgno = event.getPaginal().getActivePage();<br />
int ofs = pgno * event.getPaginal().getPageSize();<br />
new Viewer().redraw(result, ofs, ofs + event.getPaginal().getPageSize() - 1); //assume redraw(List result, int b, int e) will display<br />
//from the b-th item to the e-th item<br />
}<br />
});<br />
</zscript><br />
</source><br />
<br />
==What's Model==<br />
To assign data to a component (e.g. <tt>grid</tt> or <tt>listbox</tt>), you have to prepare the data in certain data model. For example, <tt>listbox</tt> and <tt>grid</tt> accept interfaces <tt>ListModel</tt> and <tt>GroupsModel</tt>, while <tt>tree</tt> only accepts <tt>TreeModel</tt>. See the <tt>setModel</tt> method of each component for the kind of model it accepts. Using the wrong type of data model will throw a cast error and is a common beginner mistake.<br />
<br />
ZK has implemented following Models:<br />
*SimpleCategoryModel<br />
*SimpleGroupsModel<br />
*SimpleListModel<br />
*SimplePieModel<br />
*SimpleTreeModel<br />
*SimpleXYModel<br />
*SimpleXYZModel<br />
*SimpleHiLoModel<br />
<br />
==What's Renderer==<br />
A renderer is responsible for rendering the layout of certain model.<br />
For example, <tt>RowRenderer</tt> is responsible for rendering data stored in the <tt>ListModel</tt> to the specified <tt>row</tt> in the <tt>Grid</tt>.<br />
<br />
ZK has provided default renders:<br />
<br />
==Three Steps to Use Live Data==<br />
*Prepare the data in the form of <tt>ListModel</tt>. ZK has a concrete implementation called <tt>org.zkoss.zul.SimpleListModel</tt> for representing an array of objects.<br />
*Implement the <tt>org.zkoss.zul.RowRenderer</tt> interface for rendering a row of data into the Grid.<br />
** This is optional. If it is not specified, the default <tt>rowrender</tt> is used to render the data into the first column.<br />
** You could implement different renderers for represent the same data in different views.<br />
*Specify the data in the <tt>model</tt> property, and, optionally, the <tt>rowrender</tt> in the <tt>rowRenderer</tt> property.<br />
<br />
==Examples==<br />
=== Single-Column Example : Using only setModel ===<br />
In the following example, an array of data("data") is prepared , it is passed as a parameter for the generation of a ListModel("strset"). Last, assign this ListModel into a Grid by setting the model of the Grid.<br />
<br />
<source lang="xml" ><br />
<window title="Live grid"><br />
<zscript><br />
<![CDATA[ <br />
String[] data = new String[30];<br />
for(int j=0; j < data.length; ++j) {<br />
data[j] = "option "+j;<br />
} <br />
ListModel strset = new SimpleListModel(data);<br />
]]><br />
</zscript><br />
<grid model="${strset}"><br />
<columns><br />
<column label="options" /><br />
</columns><br />
</grid><br />
</window><br />
</source><br />
<br />
=== Two-Columns Example : User defined renderer ===<br />
Since the default rowrender only satisfies the scenario of single-column, a customized rowrenderer must be implemented to commit the scenario of multi-column. In the following example, a two-columns live data for grid is demonstrated.<br />
<br />
====1.Prepare the Data Model====<br />
<br />
The first step is to prepare required data. A two-way array is adopted in this example and it is passed as a parameter for the generation of a ListModel which is implemented by SimpleListModel. In addition, ListModel now supports various data types,including Array, List, Map, and Set in the form of ListModelArray,ListModelList, ListModelMap,and ListModelSet.<br />
<br />
<source lang="java" ><br />
//prepare the data model <br />
String[][] model = new String[100][2]; <br />
for(int j=0; j < model.length; ++j) { <br />
model[j][0] = "key"+j;<br />
model[j][1] = "value"+j; <br />
} <br />
ListModel strset = new SimpleListModel(model);<br />
</source><br />
<br />
====2.Define the RowRenderer Class====<br />
<br />
Secondly, to define a class which implements the interface RowRenderer,its method render(Row row, java.lang.Object data) is required to be implemented.<br />
<br />
Method render(Row row, java.lang.Object data)<br />
row - The row to render the result.<br />
data - Returned from ListModel.getElementAt() <br />
<br />
In addition to pass required parameters into the method render(), the form of view (UI Component) for displaying data in the Grid also has to be defined, and any component which is supported by Grid could be adopted. In this example, Label is adopted, and the last step is to render Label into the specified row in the Grid by calling Label.setParent(Row row).<br />
<br />
<br />
MyRowRenderer.java<br />
<br />
<source lang="java" ><br />
import org.zkoss.zul.Label;<br />
import org.zkoss.zul.Row;<br />
import org.zkoss.zul.RowRenderer;<br />
<br />
//define the RowRenderer class <br />
public class MyRowRenderer implements RowRenderer{ <br />
<br />
public void render(Row row, java.lang.Object data) {<br />
String[] _data = (String[])data;<br />
new Label(_data[0]).setParent(row); <br />
new Label(_data[1]).setParent(row);<br />
}<br />
}<br />
</source><br />
<br />
====3.Specify model and rowRenderer Property====<br />
<br />
The properties of model and rowRenderer could be specified directly in the Grid. In this example,methods, Grid.setModel() and Grid.setRowRenderer() are adopted to specify required objects for realizing the idea of "live data".<br />
<br />
<source lang="xml" ><br />
<window title="Two-Column Live Data Demo" ><br />
<grid id="mygrid"><br />
<columns><br />
<column label="key" /><br />
<column label="value" /><br />
</columns><br />
</grid><br />
<zscript><![CDATA[<br />
String[][] model = new String[100][2]; <br />
<br />
for(int j=0; j < model.length; ++j) { <br />
model[j][0] = "key"+j;<br />
model[j][1] = "value"+j; <br />
} <br />
ListModel strset = new SimpleListModel(model); <br />
mygrid.setModel(strset); <br />
mygrid.setRowRenderer(new MyRowRenderer()); <br />
]]><br />
</zscript><br />
</window><br />
</source><br />
<br />
== If extreme large data set, say 1,000,000? ==<br />
[http://docs.zkoss.org/wiki/ZK/How-Tos/Concepts-and-Tricks ZK/How-Tos/Concepts-and-Tricks]<br />
<br />
Check <br />
Implement paging for listboxes with many items<br />
<br />
== Data Binding ==<br />
Not only showing the data by model, you can also modify underlying model by UI in real time. <br />
<br />
[[Example Code for Data binding with live data| Example code]]<br />
<br />
== See Also ==<br />
[http://www.zkoss.org/smalltalks/livedata/livedataforgrid.dsp How to realize the idea of live data in a Grid]: A smalltalk<br />
<br />
[http://www.zkoss.org/smalltalks/zkTreeModel/ ZK Tree Model]: A smalltalk.<br />
<br />
[http://zk1.svn.sourceforge.net/viewvc/zk1/branches/5.0/zul/src/org/zkoss/zul/Grid.java?revision=14211&view=markup Grid.java]: The source code of Grid.java. By tracing it, you'll know how renderer and setModel works, how <tt>render()</tt> is called, how the <tt>model</tt> is iterated through visible region. Keyword: render. You may also trace Tree.java and Listbox.java.<br />
<br />
[http://docs.zkoss.org/wiki/Grids%2C_Trees_and_Listbox#Live_Data Live Data] section in chapter Grids, Trees and Listbox.<br />
<br />
[http://www.zkoss.org/forum/index.zul#path%3DlistComment%3BdiscussionId%3D6320%3BcategoryId%3D14%3B Bug in Grid paging? handleError:1084]: A thread in forum.<br />
<br />
<br />
{{Template:Smalltalk_Footer|<br />
|name=Potix Corporation <br />
}}</div>Charhttps://www.zkoss.org/_w/index.php?title=Small_Talks/2008/December/Live_Data,_Paging,_setModel_and_Implement_your_own_renderer&diff=15229Small Talks/2008/December/Live Data, Paging, setModel and Implement your own renderer2010-12-21T02:44:08Z<p>Char: /* See Also */</p>
<hr />
<div>==Overview==<br />
In a real world web application, it's common to collect data from database, and show it in <tt>listbox</tt> or <tt>grid</tt> or <tt>tree</tt>. The underlying data may be hundreds of thousands records. It's impractical to load them all to the client. Therefore ZK introduces concepts of <tt>Live Data</tt>, <tt>Paging</tt>. To separate view from data, ZK also introduces the concept of <tt>model</tt>. It is easier to use different views to show the same set of data. To show data in the view any way you like, a developer may implement his own renderer; ZK has provided a default renderer.<br />
<br />
==What's Live Data==<br />
The main idea of "live data" is to separate data from the view. Developers only have to manipulate the data model, and the data of view (UI Component) will be updated accordingly. Secondly, it shortens the response time of user since only the required data will be downloaded the first time.<br />
<br />
==What's Paging==<br />
Paging separates long content into multiple pages.<br />
<br />
A paging component is used for this purpose. For example, assume that you have 100 items and prefer to show 20 items at a time, then you can use the paging components as follows.<br />
<br />
[[Image:100000000000007A00000013F689AD21.png]]<br />
<br />
<source lang="xml" ><br />
<paging totalSize="100" pageSize="20"/><br />
</source><br />
<br />
Then, when a user clicks on the hyperlinks, the <tt>onPaging</tt> event is sent with an instance of <tt>org.zkoss.zul.event.PagingEvent</tt> to the paging component. To decide which portion of your 100 items are visible, you shall add a listener to the paging component.<br />
<br />
<source lang="xml" ><br />
<paging id="paging"/><br />
<zscript><br />
List result = new SearchEngine().find("ZK");<br />
//assume SearchEngine.find() will return a list of items.<br />
paging.setTotalSize(result.size());<br />
paging.addEventListener("onPaging", new EventListener() {<br />
public void onEvent(Event event) {<br />
int pgno = event.getPaginal().getActivePage();<br />
int ofs = pgno * event.getPaginal().getPageSize();<br />
new Viewer().redraw(result, ofs, ofs + event.getPaginal().getPageSize() - 1); //assume redraw(List result, int b, int e) will display<br />
//from the b-th item to the e-th item<br />
}<br />
});<br />
</zscript><br />
</source><br />
<br />
==What's Model==<br />
To assign data to a component (e.g. <tt>grid</tt> or <tt>listbox</tt>), you have to prepare the data in certain data model. For example, <tt>listbox</tt> and <tt>grid</tt> accept interfaces <tt>ListModel</tt> and <tt>GroupsModel</tt>, while <tt>tree</tt> only accepts <tt>TreeModel</tt>. See the <tt>setModel</tt> method of each component for the kind of model it accepts. Using the wrong type of data model will throw a cast error and is a common beginner mistake.<br />
<br />
ZK has implemented following Models:<br />
*SimpleCategoryModel<br />
*SimpleGroupsModel<br />
*SimpleListModel<br />
*SimplePieModel<br />
*SimpleTreeModel<br />
*SimpleXYModel<br />
*SimpleXYZModel<br />
*SimpleHiLoModel<br />
<br />
==What's Renderer==<br />
A renderer is responsible for rendering the layout of certain model.<br />
For example, <tt>RowRenderer</tt> is responsible for rendering data stored in the <tt>ListModel</tt> to the specified <tt>row</tt> in the <tt>Grid</tt>.<br />
<br />
ZK has provided default renders:<br />
<br />
==Three Steps to Use Live Data==<br />
*Prepare the data in the form of <tt>ListModel</tt>. ZK has a concrete implementation called <tt>org.zkoss.zul.SimpleListModel</tt> for representing an array of objects.<br />
*Implement the <tt>org.zkoss.zul.RowRenderer</tt> interface for rendering a row of data into the Grid.<br />
** This is optional. If it is not specified, the default <tt>rowrender</tt> is used to render the data into the first column.<br />
** You could implement different renderers for represent the same data in different views.<br />
*Specify the data in the <tt>model</tt> property, and, optionally, the <tt>rowrender</tt> in the <tt>rowRenderer</tt> property.<br />
<br />
==Examples==<br />
=== Single-Column Example : Using only setModel ===<br />
In the following example, an array of data("data") is prepared , it is passed as a parameter for the generation of a ListModel("strset"). Last, assign this ListModel into a Grid by setting the model of the Grid.<br />
<br />
<source lang="xml" ><br />
<window title="Live grid"><br />
<zscript><br />
<![CDATA[ <br />
String[] data = new String[30];<br />
for(int j=0; j < data.length; ++j) {<br />
data[j] = "option "+j;<br />
} <br />
ListModel strset = new SimpleListModel(data);<br />
]]><br />
</zscript><br />
<grid model="${strset}"><br />
<columns><br />
<column label="options" /><br />
</columns><br />
</grid><br />
</window><br />
</source><br />
<br />
=== Two-Columns Example : User defined renderer ===<br />
Since the default rowrender only satisfies the scenario of single-column, a customized rowrenderer must be implemented to commit the scenario of multi-column. In the following example, a two-columns live data for grid is demonstrated.<br />
<br />
====1.Prepare the Data Model====<br />
<br />
The first step is to prepare required data. A two-way array is adopted in this example and it is passed as a parameter for the generation of a ListModel which is implemented by SimpleListModel. In addition, ListModel now supports various data types,including Array, List, Map, and Set in the form of ListModelArray,ListModelList, ListModelMap,and ListModelSet.<br />
<br />
<source lang="java" ><br />
//prepare the data model <br />
String[][] model = new String[100][2]; <br />
for(int j=0; j < model.length; ++j) { <br />
model[j][0] = "key"+j;<br />
model[j][1] = "value"+j; <br />
} <br />
ListModel strset = new SimpleListModel(model);<br />
</source><br />
<br />
====2.Define the RowRenderer Class====<br />
<br />
Secondly, to define a class which implements the interface RowRenderer,its method render(Row row, java.lang.Object data) is required to be implemented.<br />
<br />
Method render(Row row, java.lang.Object data)<br />
row - The row to render the result.<br />
data - Returned from ListModel.getElementAt() <br />
<br />
In addition to pass required parameters into the method render(), the form of view (UI Component) for displaying data in the Grid also has to be defined, and any component which is supported by Grid could be adopted. In this example, Label is adopted, and the last step is to render Label into the specified row in the Grid by calling Label.setParent(Row row).<br />
<br />
<br />
MyRowRenderer.java<br />
<br />
<source lang="java" ><br />
import org.zkoss.zul.Label;<br />
import org.zkoss.zul.Row;<br />
import org.zkoss.zul.RowRenderer;<br />
<br />
//define the RowRenderer class <br />
public class MyRowRenderer implements RowRenderer{ <br />
<br />
public void render(Row row, java.lang.Object data) {<br />
String[] _data = (String[])data;<br />
new Label(_data[0]).setParent(row); <br />
new Label(_data[1]).setParent(row);<br />
}<br />
}<br />
</source><br />
<br />
====3.Specify model and rowRenderer Property====<br />
<br />
The properties of model and rowRenderer could be specified directly in the Grid. In this example,methods, Grid.setModel() and Grid.setRowRenderer() are adopted to specify required objects for realizing the idea of "live data".<br />
<br />
<source lang="xml" ><br />
<window title="Two-Column Live Data Demo" ><br />
<grid id="mygrid"><br />
<columns><br />
<column label="key" /><br />
<column label="value" /><br />
</columns><br />
</grid><br />
<zscript><![CDATA[<br />
String[][] model = new String[100][2]; <br />
<br />
for(int j=0; j < model.length; ++j) { <br />
model[j][0] = "key"+j;<br />
model[j][1] = "value"+j; <br />
} <br />
ListModel strset = new SimpleListModel(model); <br />
mygrid.setModel(strset); <br />
mygrid.setRowRenderer(new MyRowRenderer()); <br />
]]><br />
</zscript><br />
</window><br />
</source><br />
<br />
== If extreme large data set, say 1,000,000? ==<br />
[http://docs.zkoss.org/wiki/ZK/How-Tos/Concepts-and-Tricks ZK/How-Tos/Concepts-and-Tricks]<br />
<br />
Check <br />
Implement paging for listboxes with many items<br />
<br />
== Data Binding ==<br />
Not only showing the data by model, you can also modify underlying model by UI in real time. <br />
<br />
[[Example Code for Data binding with live data| Example code]]<br />
<br />
== See Also ==<br />
[http://www.zkoss.org/smalltalks/livedata/livedataforgrid.dsp How to realize the idea of live data in a Grid]: A smalltalk<br />
<br />
[http://www.zkoss.org/smalltalks/zkTreeModel/ ZK Tree Model]: A smalltalk.<br />
<br />
[http://zk1.svn.sourceforge.net/viewvc/zk1/branches/5.0/zul/src/org/zkoss/zul/Grid.java?revision=14211&view=markup Grid.java]: The source code of Grid.java. By tracing it, you'll know how renderer and setModel works, how <tt>render()</tt> is called, how the <tt>model</tt> is iterated through visible region. Keyword: render. You may also trace Tree.java and Listbox.java.<br />
<br />
[http://docs.zkoss.org/wiki/Grids%2C_Trees_and_Listbox#Live_Data Live Data] section in chapter Grids, Trees and Listbox.<br />
<br />
[http://www.zkoss.org/forum/index.zul#path%3DlistComment%3BdiscussionId%3D6320%3BcategoryId%3D14%3B Bug in Grid paging? handleError:1084]: A thread in forum.</div>Charhttps://www.zkoss.org/_w/index.php?title=Small_Talks/2008/December/Live_Data,_Paging,_setModel_and_Implement_your_own_renderer&diff=15228Small Talks/2008/December/Live Data, Paging, setModel and Implement your own renderer2010-12-21T02:43:30Z<p>Char: /* If extreme large data set, say 1,000,000? */</p>
<hr />
<div>==Overview==<br />
In a real world web application, it's common to collect data from database, and show it in <tt>listbox</tt> or <tt>grid</tt> or <tt>tree</tt>. The underlying data may be hundreds of thousands records. It's impractical to load them all to the client. Therefore ZK introduces concepts of <tt>Live Data</tt>, <tt>Paging</tt>. To separate view from data, ZK also introduces the concept of <tt>model</tt>. It is easier to use different views to show the same set of data. To show data in the view any way you like, a developer may implement his own renderer; ZK has provided a default renderer.<br />
<br />
==What's Live Data==<br />
The main idea of "live data" is to separate data from the view. Developers only have to manipulate the data model, and the data of view (UI Component) will be updated accordingly. Secondly, it shortens the response time of user since only the required data will be downloaded the first time.<br />
<br />
==What's Paging==<br />
Paging separates long content into multiple pages.<br />
<br />
A paging component is used for this purpose. For example, assume that you have 100 items and prefer to show 20 items at a time, then you can use the paging components as follows.<br />
<br />
[[Image:100000000000007A00000013F689AD21.png]]<br />
<br />
<source lang="xml" ><br />
<paging totalSize="100" pageSize="20"/><br />
</source><br />
<br />
Then, when a user clicks on the hyperlinks, the <tt>onPaging</tt> event is sent with an instance of <tt>org.zkoss.zul.event.PagingEvent</tt> to the paging component. To decide which portion of your 100 items are visible, you shall add a listener to the paging component.<br />
<br />
<source lang="xml" ><br />
<paging id="paging"/><br />
<zscript><br />
List result = new SearchEngine().find("ZK");<br />
//assume SearchEngine.find() will return a list of items.<br />
paging.setTotalSize(result.size());<br />
paging.addEventListener("onPaging", new EventListener() {<br />
public void onEvent(Event event) {<br />
int pgno = event.getPaginal().getActivePage();<br />
int ofs = pgno * event.getPaginal().getPageSize();<br />
new Viewer().redraw(result, ofs, ofs + event.getPaginal().getPageSize() - 1); //assume redraw(List result, int b, int e) will display<br />
//from the b-th item to the e-th item<br />
}<br />
});<br />
</zscript><br />
</source><br />
<br />
==What's Model==<br />
To assign data to a component (e.g. <tt>grid</tt> or <tt>listbox</tt>), you have to prepare the data in certain data model. For example, <tt>listbox</tt> and <tt>grid</tt> accept interfaces <tt>ListModel</tt> and <tt>GroupsModel</tt>, while <tt>tree</tt> only accepts <tt>TreeModel</tt>. See the <tt>setModel</tt> method of each component for the kind of model it accepts. Using the wrong type of data model will throw a cast error and is a common beginner mistake.<br />
<br />
ZK has implemented following Models:<br />
*SimpleCategoryModel<br />
*SimpleGroupsModel<br />
*SimpleListModel<br />
*SimplePieModel<br />
*SimpleTreeModel<br />
*SimpleXYModel<br />
*SimpleXYZModel<br />
*SimpleHiLoModel<br />
<br />
==What's Renderer==<br />
A renderer is responsible for rendering the layout of certain model.<br />
For example, <tt>RowRenderer</tt> is responsible for rendering data stored in the <tt>ListModel</tt> to the specified <tt>row</tt> in the <tt>Grid</tt>.<br />
<br />
ZK has provided default renders:<br />
<br />
==Three Steps to Use Live Data==<br />
*Prepare the data in the form of <tt>ListModel</tt>. ZK has a concrete implementation called <tt>org.zkoss.zul.SimpleListModel</tt> for representing an array of objects.<br />
*Implement the <tt>org.zkoss.zul.RowRenderer</tt> interface for rendering a row of data into the Grid.<br />
** This is optional. If it is not specified, the default <tt>rowrender</tt> is used to render the data into the first column.<br />
** You could implement different renderers for represent the same data in different views.<br />
*Specify the data in the <tt>model</tt> property, and, optionally, the <tt>rowrender</tt> in the <tt>rowRenderer</tt> property.<br />
<br />
==Examples==<br />
=== Single-Column Example : Using only setModel ===<br />
In the following example, an array of data("data") is prepared , it is passed as a parameter for the generation of a ListModel("strset"). Last, assign this ListModel into a Grid by setting the model of the Grid.<br />
<br />
<source lang="xml" ><br />
<window title="Live grid"><br />
<zscript><br />
<![CDATA[ <br />
String[] data = new String[30];<br />
for(int j=0; j < data.length; ++j) {<br />
data[j] = "option "+j;<br />
} <br />
ListModel strset = new SimpleListModel(data);<br />
]]><br />
</zscript><br />
<grid model="${strset}"><br />
<columns><br />
<column label="options" /><br />
</columns><br />
</grid><br />
</window><br />
</source><br />
<br />
=== Two-Columns Example : User defined renderer ===<br />
Since the default rowrender only satisfies the scenario of single-column, a customized rowrenderer must be implemented to commit the scenario of multi-column. In the following example, a two-columns live data for grid is demonstrated.<br />
<br />
====1.Prepare the Data Model====<br />
<br />
The first step is to prepare required data. A two-way array is adopted in this example and it is passed as a parameter for the generation of a ListModel which is implemented by SimpleListModel. In addition, ListModel now supports various data types,including Array, List, Map, and Set in the form of ListModelArray,ListModelList, ListModelMap,and ListModelSet.<br />
<br />
<source lang="java" ><br />
//prepare the data model <br />
String[][] model = new String[100][2]; <br />
for(int j=0; j < model.length; ++j) { <br />
model[j][0] = "key"+j;<br />
model[j][1] = "value"+j; <br />
} <br />
ListModel strset = new SimpleListModel(model);<br />
</source><br />
<br />
====2.Define the RowRenderer Class====<br />
<br />
Secondly, to define a class which implements the interface RowRenderer,its method render(Row row, java.lang.Object data) is required to be implemented.<br />
<br />
Method render(Row row, java.lang.Object data)<br />
row - The row to render the result.<br />
data - Returned from ListModel.getElementAt() <br />
<br />
In addition to pass required parameters into the method render(), the form of view (UI Component) for displaying data in the Grid also has to be defined, and any component which is supported by Grid could be adopted. In this example, Label is adopted, and the last step is to render Label into the specified row in the Grid by calling Label.setParent(Row row).<br />
<br />
<br />
MyRowRenderer.java<br />
<br />
<source lang="java" ><br />
import org.zkoss.zul.Label;<br />
import org.zkoss.zul.Row;<br />
import org.zkoss.zul.RowRenderer;<br />
<br />
//define the RowRenderer class <br />
public class MyRowRenderer implements RowRenderer{ <br />
<br />
public void render(Row row, java.lang.Object data) {<br />
String[] _data = (String[])data;<br />
new Label(_data[0]).setParent(row); <br />
new Label(_data[1]).setParent(row);<br />
}<br />
}<br />
</source><br />
<br />
====3.Specify model and rowRenderer Property====<br />
<br />
The properties of model and rowRenderer could be specified directly in the Grid. In this example,methods, Grid.setModel() and Grid.setRowRenderer() are adopted to specify required objects for realizing the idea of "live data".<br />
<br />
<source lang="xml" ><br />
<window title="Two-Column Live Data Demo" ><br />
<grid id="mygrid"><br />
<columns><br />
<column label="key" /><br />
<column label="value" /><br />
</columns><br />
</grid><br />
<zscript><![CDATA[<br />
String[][] model = new String[100][2]; <br />
<br />
for(int j=0; j < model.length; ++j) { <br />
model[j][0] = "key"+j;<br />
model[j][1] = "value"+j; <br />
} <br />
ListModel strset = new SimpleListModel(model); <br />
mygrid.setModel(strset); <br />
mygrid.setRowRenderer(new MyRowRenderer()); <br />
]]><br />
</zscript><br />
</window><br />
</source><br />
<br />
== If extreme large data set, say 1,000,000? ==<br />
[http://docs.zkoss.org/wiki/ZK/How-Tos/Concepts-and-Tricks ZK/How-Tos/Concepts-and-Tricks]<br />
<br />
Check <br />
Implement paging for listboxes with many items<br />
<br />
== Data Binding ==<br />
Not only showing the data by model, you can also modify underlying model by UI in real time. <br />
<br />
[[Example Code for Data binding with live data| Example code]]<br />
<br />
== See Also ==<br />
[http://www.zkoss.org/smalltalks/livedata/livedataforgrid.dsp How to realize the idea of live data in a Grid]: A smalltalk<br />
<br />
[http://www.zkoss.org/smalltalks/zkTreeModel/ ZK Tree Model]: A smalltalk.<br />
<br />
[http://zk1.svn.sourceforge.net/viewvc/zk1/branches/5.0/zul/src/org/zkoss/zul/Grid.java?revision=14211&view=markup Grid.java]: The source code of Grid.java. By tracing it, you'll know how renderer and setModel works, how <tt>render()</tt> is called, how the <tt>model</tt> is iterated through visible region. Keyword: render. You may also trace Tree.java and Listbox.java.<br />
<br />
[[Grids%2C_Trees_and_Listbox#Live_Data | Live Data]] section in chapter Grids, Trees and Listbox.<br />
<br />
[http://www.zkoss.org/forum/index.zul#path%3DlistComment%3BdiscussionId%3D6320%3BcategoryId%3D14%3B Bug in Grid paging? handleError:1084]: A thread in forum.</div>Charhttps://www.zkoss.org/_w/index.php?title=Small_Talks/2009/December/ZK_5:_Upgrade_Notes&diff=15227Small Talks/2009/December/ZK 5: Upgrade Notes2010-12-21T02:38:16Z<p>Char: /* Animation API deprecated */</p>
<hr />
<div>{{Template:Smalltalk_Author|<br />
|author=<br />
|date=December <br />
|version= <br />
}}<br />
<br />
<br />
= Overview =<br />
<br />
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.<br />
<br />
= Server-side Upgrade Notes =<br />
<br />
== Attributes and Namespace ==<br />
=== The return type of <tt>setAttribute</tt> and <tt>removeAttribute</tt> of session/execution/application changed (from <tt>void</tt> to <tt>Object</tt>) ===<br />
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.<br />
<br />
The new signature:<br />
<syntax lang="java"><br />
Object setAttribute(String name, Object value); //returns the previous value if any<br />
Object removeAttribute(String name); //return the previous value if any<br />
</syntax><br />
<br />
=== Namespace deprecated ===<br />
<br />
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.<br />
<br />
<syntax lang="xml"><br />
<variabls foo="better"/> <!-- deprecated --><br />
<custom-attribute foo="better" scope="space"/><br />
</syntax><br />
<br />
Furthermore, ZK 5 will search the attribute scopes for any variable specified in EL or <tt>zscript</tt>.<br />
<br />
<syntax lang="xml"><br />
<window><br />
<custom-attributes a="a" b="b"/> <!-- belongs to window's attribute scope --><br />
<div><br />
<custom-attributes b="B"/> <!-- belongs to div's attribute scope --><br />
${a} and ${b} <!-- result: a and B --><br />
<zscript><br />
String s = a + b; //result: aB<br />
</zscript><br />
</div><br />
</window><br />
</syntax><br />
<br />
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.<br />
<br />
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.<br />
<br />
=== The attribute scope of the ID space is the same of the space owner's attribute scope ===<br />
<br />
In the previous version, the space owner (such as <tt>window</tt>) has two attribute scopes. For example,<br />
<br />
<syntax lang="xml"><br />
<window><br />
<custom-attributes foo="a"/><br />
<div><br />
<custom-attributes foo="b" scope="space"/><br />
</div><br />
<br />
<zscript><br />
self.getAttribute("foo"); //returns a in ZK 3<br />
self.getAttribute("foo", self.SPACE_SCOPE); //returns b<br />
</zscript><br />
</window><br />
</syntax><br />
<br />
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>.<br />
<br />
== System Level Control ==<br />
<br />
=== Event processing thread disabled by default ===<br />
<br />
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 [http://docs.zkoss.org/wiki/Performance_tip#Use_the_Servlet_Thread_to_Process_Events Performance tip#Use_the_Servlet_Thread_to_Process_Events] for how to adjust your application. For example, the <tt>if</tt> clause in the following example is never true.<br />
<br />
<source lang="java" ><br />
if (Messagebox.show("Delete?", "Prompt", Messagebox.YES|Messagebox.NO,<br />
Messagebox.QUESTION) == Messagebox.YES) {<br />
this_never_executes();<br />
}<br />
</source><br />
<br />
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.<br />
<br />
<source lang="xml"><br />
<system-config><br />
<disable-event-thread>false</disable-event-thread><br />
</system-config><br />
</source><br />
<blockquote><br />
----<br />
<references/><br />
</blockquote><br />
<br />
=== The method of <tt>ComponentCloneListener</tt> changed ===<br />
<br />
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.<br />
<br />
<source lang="java"><br />
Object willClone(Component comp);<br />
</source><br />
<br />
=== The <tt>AuPocessor</tt> interface deprecated (replaced with <tt>AuExtension</tt>) ===<br />
<br />
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.<br />
<br />
=== The <tt>addRoot</tt>, <tt>removeRoot</tt>, <tt>moveRoot</tt>, <tt>addFellow</tt> and <tt>removeFellow</tt> methods of <tt>PageCtrl</tt> removed ===<br />
<br />
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>.<br />
<br />
=== The <tt>disable-behind-modal</tt> configuration disabled (always false) ===<br />
<br />
With ZK 5, there is no need to disable widgets that don't belong to the modal window, so this configuration is meaningless.<br />
<br />
== Component Use ==<br />
<br />
=== The <tt>include</tt> component's mode default to <tt>auto</tt> ===<br />
<br />
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<br />
<br />
<source lang="javascript"><br />
<include mode="defer" src="abc.zul"/><br />
</source><br />
<br />
Or, you can specify the following configuration in zk.xml to change the default mode for the whole application.<br />
<br />
<source lang="javascript"><br />
<library-property><br />
<name>org.zkoss.zul.include.mode</name><br />
<value>defer</value><br />
</library-property><br />
</source><br />
<br />
=== The <tt>a</tt> component introduced for HTML A ===<br />
<br />
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,<br />
<br />
<source lang="xml"><br />
Refer <a href="http://www.zkoss.org" label="ZK"/> for details.<br />
Or <a href="http://www.zkoss.org/zkdemo">ZK Demo</a>.<br />
</source><br />
<br />
=== CSS <tt>fixed-layout</tt> property default for <tt>grid</tt> and <tt>listbox</tt> ===<br />
<br />
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.<br />
<br />
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://docs.zkoss.org/wiki/ZK_5:_More_Flexible_Layout#Proportional_Flexibility 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 ).<br />
<br />
<source lang="xml"><br />
<grid width="300px"><br />
<columns><br />
<column label="Order" width="20px"/><br />
<column label="Name" hflex="1"/><br />
<column label="Value" hflex="2"/><br />
</columns><br />
<rows><br />
<row><image src="foo.gif"/> username: <textbox/></row><br />
<row><image src="foo.gif"/> password: <textbox/></row><br />
</rows><br />
</grid><br />
</source><br />
<br />
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.<br />
<br />
<source lang="xml"><br />
<grid width="300px" sizedByContent="true"><br />
</source><br />
<br />
=== The <tt>alphafix</tt> mold of <tt>image</tt> and <tt>imagemap</tt> deprecated ===<br />
<br />
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.<br />
<br />
<source lang="javascript"><br />
<?script content="jq.IE6_ALPHAFIX='.png';"?><br />
</source><br />
<br />
In other words, just specify a regular expression to a JavaScript variable called <tt>jq.IE6_ALPHAFIX</tt>.<br />
<br />
=== The methods of <tt>ClientConstraint</tt> changed ===<br />
<br />
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.<br />
<br />
The typical way to implement the custom client validation is as follows.<br />
<br />
#Implementing a JavaString class, say, foo.MyValidator.<br />
<br />
#Implementing <tt>org.zkoss.zul.ClientConstraint</tt> such that<br />
<br />
<source lang="java"><br />
//Java<br />
String getClientConstraint() {<br />
return "new foo.MyValidator()";<br />
}<br />
String getClientPackages() {<br />
return "foo"; //the package name<br />
}<br />
</source><br />
<br />
=== <tt>SimpleConstraint</tt> performs all validations at client ===<br />
<br />
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,<br />
<br />
<source lang="javascript"><br />
<textbox constraint="/.+@.+\.[a-z]+/,server"/><br />
</source><br />
<br />
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>.<br />
<br />
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.<br />
<br />
<source lang="javascript"><br />
//JavaScript<br />
ClientServerConstraint = zk.$extends(zul.inp.SimpleConstraint, {<br />
serverValidate: true<br />
});<br />
</source><br />
<br />
<blockquote><br />
----<br />
<references/><br />
</blockquote><br />
<br />
=== Overlapped window within another overlapped window not cropped ===<br />
<br />
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.<br />
<br />
=== Meaning of hbox/vbox <tt>pack</tt> attribute follows XUL's specification ===<br />
<br />
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".<br />
<br />
== Component Styling ==<br />
<br />
=== The <tt>dynamic</tt> attribute of the <tt>style</tt> component deprecated ===<br />
<br />
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.<br />
<br />
=== The default mold of the <tt>button</tt> component changed to <tt>os</tt> ===<br />
<br />
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>.<br />
<br />
<source lang="xml"><br />
<library-property><br />
<name>org.zkoss.zul.Button.mold</name><br />
<value>trendy</value><br />
</library-property><br />
</source><br />
<br />
=== The default value of the <tt>zclass</tt> attribute more consistent (<tt>z-</tt> + component-name) ===<br />
<br />
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.<br />
<br />
The affected components are as follows.<br />
<br />
comboitem, bandpopup, groupfoot, listcell, listfoot,<br />
listfooter, listgroup, listgroupfoot, listhead, listheader,<br />
listitem, treecell, treechildren, treecol, treecols, treefoot,<br />
treefooter, treerow, table-children, and table-layout<br />
<br />
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>.<br />
<br />
=== Both <tt>Applet</tt> and <tt>Iframe</tt> extends from <tt>HtmlBasedComponent</tt> (instead of <tt>XulElement</tt>) ===<br />
<br />
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>.<br />
<br />
=== The <tt>ZKPrefix</tt> library property deprecated ===<br />
<br />
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.<br />
<br />
== Component Development ==<br />
<br />
The component development is changed. Refer to [http://docs.zkoss.org/wiki/ZK5:_Component_Development_Guide ZK5: Component Development Guide] for details.<br />
<br />
= Client-side Upgrade Notes =<br />
<br />
The client is rewritten, so your customization have to rewrite, too.<br />
<br />
== Client-side Action deprecated ==<br />
<br />
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,<br />
<br />
<source lang="xml"><br />
<!-- ZK 3.x: Client Side Action --><br />
<textbox<br />
action="onfocus: window.action.show(#{help1}); onblur: window.action.hide(#{help1})" /><br />
<label id="help1" visible="false" value="This is help for text1." /><br />
</source><br />
<br />
can be replaced with<br />
<br />
<source lang="xml"><br />
<!-- ZK 5 --><br />
<textbox xmlns:w="http://www.zkoss.org/2005/zk/client"<br />
w:onFocus="jq(this.$f('help1')).fadeIn()" w:onBlur="jq(this.$f('help1')).fadeOut()"/><br />
<label id="help1" visible="false" value="This is help for text1." /><br />
</source><br />
<br />
== Animation API deprecated ==<br />
<br />
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,<br />
<br />
<source lang="xml"><br />
<!-- ZK 3.x: anima --><br />
<label sclass="ctl" value="SlideDown"<br />
action="onclick: zk.hide(#{t});anima.slideDown(#{t})"/><br />
</source><br />
<br />
<source lang="xml"><br />
<!- ZK 5: with jQury --><br />
<label sclass="ctl" value="SlideDown"<br />
w:onClick="jq(this.$f('t')).hide().slideDown()"<br />
xmlns:w="http://www.zkoss.org/2005/zk/client"/><br />
</source><br />
<br />
Please refer to [http://docs.zkoss.org/wiki/ZK5:_JavaScript_API ZK5: JavaScript API] for the complete description of JavaScript API at the client.<br />
<br />
= See Also =<br />
*[http://docs.zkoss.org/wiki/Upgrading_to_ZK_5 Upgrading to ZK 5]<br />
*A forum thread : [http://www.zkoss.org/forum/listComment/11094 Upgrade to ZK5 ]<br />
<br />
<br />
<comment>http://docs.zkoss.org/wiki/ZK_5:_Upgrade_Notes</comment><br />
<br />
<br />
{{Template:Smalltalk_Footer|<br />
|name=Potix Corporation <br />
}}</div>Charhttps://www.zkoss.org/_w/index.php?title=Small_Talks/2009/December/ZK_5:_Upgrade_Notes&diff=15226Small Talks/2009/December/ZK 5: Upgrade Notes2010-12-21T02:35:45Z<p>Char: </p>
<hr />
<div>{{Template:Smalltalk_Author|<br />
|author=<br />
|date=December <br />
|version= <br />
}}<br />
<br />
<br />
= Overview =<br />
<br />
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.<br />
<br />
= Server-side Upgrade Notes =<br />
<br />
== Attributes and Namespace ==<br />
=== The return type of <tt>setAttribute</tt> and <tt>removeAttribute</tt> of session/execution/application changed (from <tt>void</tt> to <tt>Object</tt>) ===<br />
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.<br />
<br />
The new signature:<br />
<syntax lang="java"><br />
Object setAttribute(String name, Object value); //returns the previous value if any<br />
Object removeAttribute(String name); //return the previous value if any<br />
</syntax><br />
<br />
=== Namespace deprecated ===<br />
<br />
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.<br />
<br />
<syntax lang="xml"><br />
<variabls foo="better"/> <!-- deprecated --><br />
<custom-attribute foo="better" scope="space"/><br />
</syntax><br />
<br />
Furthermore, ZK 5 will search the attribute scopes for any variable specified in EL or <tt>zscript</tt>.<br />
<br />
<syntax lang="xml"><br />
<window><br />
<custom-attributes a="a" b="b"/> <!-- belongs to window's attribute scope --><br />
<div><br />
<custom-attributes b="B"/> <!-- belongs to div's attribute scope --><br />
${a} and ${b} <!-- result: a and B --><br />
<zscript><br />
String s = a + b; //result: aB<br />
</zscript><br />
</div><br />
</window><br />
</syntax><br />
<br />
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.<br />
<br />
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.<br />
<br />
=== The attribute scope of the ID space is the same of the space owner's attribute scope ===<br />
<br />
In the previous version, the space owner (such as <tt>window</tt>) has two attribute scopes. For example,<br />
<br />
<syntax lang="xml"><br />
<window><br />
<custom-attributes foo="a"/><br />
<div><br />
<custom-attributes foo="b" scope="space"/><br />
</div><br />
<br />
<zscript><br />
self.getAttribute("foo"); //returns a in ZK 3<br />
self.getAttribute("foo", self.SPACE_SCOPE); //returns b<br />
</zscript><br />
</window><br />
</syntax><br />
<br />
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>.<br />
<br />
== System Level Control ==<br />
<br />
=== Event processing thread disabled by default ===<br />
<br />
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 [http://docs.zkoss.org/wiki/Performance_tip#Use_the_Servlet_Thread_to_Process_Events Performance tip#Use_the_Servlet_Thread_to_Process_Events] for how to adjust your application. For example, the <tt>if</tt> clause in the following example is never true.<br />
<br />
<source lang="java" ><br />
if (Messagebox.show("Delete?", "Prompt", Messagebox.YES|Messagebox.NO,<br />
Messagebox.QUESTION) == Messagebox.YES) {<br />
this_never_executes();<br />
}<br />
</source><br />
<br />
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.<br />
<br />
<source lang="xml"><br />
<system-config><br />
<disable-event-thread>false</disable-event-thread><br />
</system-config><br />
</source><br />
<blockquote><br />
----<br />
<references/><br />
</blockquote><br />
<br />
=== The method of <tt>ComponentCloneListener</tt> changed ===<br />
<br />
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.<br />
<br />
<source lang="java"><br />
Object willClone(Component comp);<br />
</source><br />
<br />
=== The <tt>AuPocessor</tt> interface deprecated (replaced with <tt>AuExtension</tt>) ===<br />
<br />
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.<br />
<br />
=== The <tt>addRoot</tt>, <tt>removeRoot</tt>, <tt>moveRoot</tt>, <tt>addFellow</tt> and <tt>removeFellow</tt> methods of <tt>PageCtrl</tt> removed ===<br />
<br />
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>.<br />
<br />
=== The <tt>disable-behind-modal</tt> configuration disabled (always false) ===<br />
<br />
With ZK 5, there is no need to disable widgets that don't belong to the modal window, so this configuration is meaningless.<br />
<br />
== Component Use ==<br />
<br />
=== The <tt>include</tt> component's mode default to <tt>auto</tt> ===<br />
<br />
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<br />
<br />
<source lang="javascript"><br />
<include mode="defer" src="abc.zul"/><br />
</source><br />
<br />
Or, you can specify the following configuration in zk.xml to change the default mode for the whole application.<br />
<br />
<source lang="javascript"><br />
<library-property><br />
<name>org.zkoss.zul.include.mode</name><br />
<value>defer</value><br />
</library-property><br />
</source><br />
<br />
=== The <tt>a</tt> component introduced for HTML A ===<br />
<br />
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,<br />
<br />
<source lang="xml"><br />
Refer <a href="http://www.zkoss.org" label="ZK"/> for details.<br />
Or <a href="http://www.zkoss.org/zkdemo">ZK Demo</a>.<br />
</source><br />
<br />
=== CSS <tt>fixed-layout</tt> property default for <tt>grid</tt> and <tt>listbox</tt> ===<br />
<br />
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.<br />
<br />
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://docs.zkoss.org/wiki/ZK_5:_More_Flexible_Layout#Proportional_Flexibility 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 ).<br />
<br />
<source lang="xml"><br />
<grid width="300px"><br />
<columns><br />
<column label="Order" width="20px"/><br />
<column label="Name" hflex="1"/><br />
<column label="Value" hflex="2"/><br />
</columns><br />
<rows><br />
<row><image src="foo.gif"/> username: <textbox/></row><br />
<row><image src="foo.gif"/> password: <textbox/></row><br />
</rows><br />
</grid><br />
</source><br />
<br />
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.<br />
<br />
<source lang="xml"><br />
<grid width="300px" sizedByContent="true"><br />
</source><br />
<br />
=== The <tt>alphafix</tt> mold of <tt>image</tt> and <tt>imagemap</tt> deprecated ===<br />
<br />
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.<br />
<br />
<source lang="javascript"><br />
<?script content="jq.IE6_ALPHAFIX='.png';"?><br />
</source><br />
<br />
In other words, just specify a regular expression to a JavaScript variable called <tt>jq.IE6_ALPHAFIX</tt>.<br />
<br />
=== The methods of <tt>ClientConstraint</tt> changed ===<br />
<br />
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.<br />
<br />
The typical way to implement the custom client validation is as follows.<br />
<br />
#Implementing a JavaString class, say, foo.MyValidator.<br />
<br />
#Implementing <tt>org.zkoss.zul.ClientConstraint</tt> such that<br />
<br />
<source lang="java"><br />
//Java<br />
String getClientConstraint() {<br />
return "new foo.MyValidator()";<br />
}<br />
String getClientPackages() {<br />
return "foo"; //the package name<br />
}<br />
</source><br />
<br />
=== <tt>SimpleConstraint</tt> performs all validations at client ===<br />
<br />
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,<br />
<br />
<source lang="javascript"><br />
<textbox constraint="/.+@.+\.[a-z]+/,server"/><br />
</source><br />
<br />
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>.<br />
<br />
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.<br />
<br />
<source lang="javascript"><br />
//JavaScript<br />
ClientServerConstraint = zk.$extends(zul.inp.SimpleConstraint, {<br />
serverValidate: true<br />
});<br />
</source><br />
<br />
<blockquote><br />
----<br />
<references/><br />
</blockquote><br />
<br />
=== Overlapped window within another overlapped window not cropped ===<br />
<br />
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.<br />
<br />
=== Meaning of hbox/vbox <tt>pack</tt> attribute follows XUL's specification ===<br />
<br />
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".<br />
<br />
== Component Styling ==<br />
<br />
=== The <tt>dynamic</tt> attribute of the <tt>style</tt> component deprecated ===<br />
<br />
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.<br />
<br />
=== The default mold of the <tt>button</tt> component changed to <tt>os</tt> ===<br />
<br />
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>.<br />
<br />
<source lang="xml"><br />
<library-property><br />
<name>org.zkoss.zul.Button.mold</name><br />
<value>trendy</value><br />
</library-property><br />
</source><br />
<br />
=== The default value of the <tt>zclass</tt> attribute more consistent (<tt>z-</tt> + component-name) ===<br />
<br />
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.<br />
<br />
The affected components are as follows.<br />
<br />
comboitem, bandpopup, groupfoot, listcell, listfoot,<br />
listfooter, listgroup, listgroupfoot, listhead, listheader,<br />
listitem, treecell, treechildren, treecol, treecols, treefoot,<br />
treefooter, treerow, table-children, and table-layout<br />
<br />
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>.<br />
<br />
=== Both <tt>Applet</tt> and <tt>Iframe</tt> extends from <tt>HtmlBasedComponent</tt> (instead of <tt>XulElement</tt>) ===<br />
<br />
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>.<br />
<br />
=== The <tt>ZKPrefix</tt> library property deprecated ===<br />
<br />
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.<br />
<br />
== Component Development ==<br />
<br />
The component development is changed. Refer to [http://docs.zkoss.org/wiki/ZK5:_Component_Development_Guide ZK5: Component Development Guide] for details.<br />
<br />
= Client-side Upgrade Notes =<br />
<br />
The client is rewritten, so your customization have to rewrite, too.<br />
<br />
== Client-side Action deprecated ==<br />
<br />
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,<br />
<br />
<source lang="xml"><br />
<!-- ZK 3.x: Client Side Action --><br />
<textbox<br />
action="onfocus: window.action.show(#{help1}); onblur: window.action.hide(#{help1})" /><br />
<label id="help1" visible="false" value="This is help for text1." /><br />
</source><br />
<br />
can be replaced with<br />
<br />
<source lang="xml"><br />
<!-- ZK 5 --><br />
<textbox xmlns:w="http://www.zkoss.org/2005/zk/client"<br />
w:onFocus="jq(this.$f('help1')).fadeIn()" w:onBlur="jq(this.$f('help1')).fadeOut()"/><br />
<label id="help1" visible="false" value="This is help for text1." /><br />
</source><br />
<br />
== Animation API deprecated ==<br />
<br />
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,<br />
<br />
<source lang="xml"><br />
<!-- ZK 3.x: anima --><br />
<label sclass="ctl" value="SlideDown"<br />
action="onclick: zk.hide(#{t});anima.slideDown(#{t})"/><br />
</source><br />
<br />
<source lang="xml"><br />
<!- ZK 5: with jQury --><br />
<label sclass="ctl" value="SlideDown"<br />
w:onClick="jq(this.$f('t')).hide().slideDown()"<br />
xmlns:w="http://www.zkoss.org/2005/zk/client"/><br />
</source><br />
<br />
Please refer to [[ZK5: JavaScript API]] for the complete description of JavaScript API at the client.<br />
<br />
= See Also =<br />
*[http://docs.zkoss.org/wiki/Upgrading_to_ZK_5 Upgrading to ZK 5]<br />
*A forum thread : [http://www.zkoss.org/forum/listComment/11094 Upgrade to ZK5 ]<br />
<br />
<br />
<comment>http://docs.zkoss.org/wiki/ZK_5:_Upgrade_Notes</comment><br />
<br />
<br />
{{Template:Smalltalk_Footer|<br />
|name=Potix Corporation <br />
}}</div>Charhttps://www.zkoss.org/_w/index.php?title=Small_Talks/2008/December/Live_Data,_Paging,_setModel_and_Implement_your_own_renderer&diff=15225Small Talks/2008/December/Live Data, Paging, setModel and Implement your own renderer2010-12-21T02:29:00Z<p>Char: Created page with '==Overview== In a real world web application, it's common to collect data from database, and show it in <tt>listbox</tt> or <tt>grid</tt> or <tt>tree</tt>. The underlying data ma…'</p>
<hr />
<div>==Overview==<br />
In a real world web application, it's common to collect data from database, and show it in <tt>listbox</tt> or <tt>grid</tt> or <tt>tree</tt>. The underlying data may be hundreds of thousands records. It's impractical to load them all to the client. Therefore ZK introduces concepts of <tt>Live Data</tt>, <tt>Paging</tt>. To separate view from data, ZK also introduces the concept of <tt>model</tt>. It is easier to use different views to show the same set of data. To show data in the view any way you like, a developer may implement his own renderer; ZK has provided a default renderer.<br />
<br />
==What's Live Data==<br />
The main idea of "live data" is to separate data from the view. Developers only have to manipulate the data model, and the data of view (UI Component) will be updated accordingly. Secondly, it shortens the response time of user since only the required data will be downloaded the first time.<br />
<br />
==What's Paging==<br />
Paging separates long content into multiple pages.<br />
<br />
A paging component is used for this purpose. For example, assume that you have 100 items and prefer to show 20 items at a time, then you can use the paging components as follows.<br />
<br />
[[Image:100000000000007A00000013F689AD21.png]]<br />
<br />
<source lang="xml" ><br />
<paging totalSize="100" pageSize="20"/><br />
</source><br />
<br />
Then, when a user clicks on the hyperlinks, the <tt>onPaging</tt> event is sent with an instance of <tt>org.zkoss.zul.event.PagingEvent</tt> to the paging component. To decide which portion of your 100 items are visible, you shall add a listener to the paging component.<br />
<br />
<source lang="xml" ><br />
<paging id="paging"/><br />
<zscript><br />
List result = new SearchEngine().find("ZK");<br />
//assume SearchEngine.find() will return a list of items.<br />
paging.setTotalSize(result.size());<br />
paging.addEventListener("onPaging", new EventListener() {<br />
public void onEvent(Event event) {<br />
int pgno = event.getPaginal().getActivePage();<br />
int ofs = pgno * event.getPaginal().getPageSize();<br />
new Viewer().redraw(result, ofs, ofs + event.getPaginal().getPageSize() - 1); //assume redraw(List result, int b, int e) will display<br />
//from the b-th item to the e-th item<br />
}<br />
});<br />
</zscript><br />
</source><br />
<br />
==What's Model==<br />
To assign data to a component (e.g. <tt>grid</tt> or <tt>listbox</tt>), you have to prepare the data in certain data model. For example, <tt>listbox</tt> and <tt>grid</tt> accept interfaces <tt>ListModel</tt> and <tt>GroupsModel</tt>, while <tt>tree</tt> only accepts <tt>TreeModel</tt>. See the <tt>setModel</tt> method of each component for the kind of model it accepts. Using the wrong type of data model will throw a cast error and is a common beginner mistake.<br />
<br />
ZK has implemented following Models:<br />
*SimpleCategoryModel<br />
*SimpleGroupsModel<br />
*SimpleListModel<br />
*SimplePieModel<br />
*SimpleTreeModel<br />
*SimpleXYModel<br />
*SimpleXYZModel<br />
*SimpleHiLoModel<br />
<br />
==What's Renderer==<br />
A renderer is responsible for rendering the layout of certain model.<br />
For example, <tt>RowRenderer</tt> is responsible for rendering data stored in the <tt>ListModel</tt> to the specified <tt>row</tt> in the <tt>Grid</tt>.<br />
<br />
ZK has provided default renders:<br />
<br />
==Three Steps to Use Live Data==<br />
*Prepare the data in the form of <tt>ListModel</tt>. ZK has a concrete implementation called <tt>org.zkoss.zul.SimpleListModel</tt> for representing an array of objects.<br />
*Implement the <tt>org.zkoss.zul.RowRenderer</tt> interface for rendering a row of data into the Grid.<br />
** This is optional. If it is not specified, the default <tt>rowrender</tt> is used to render the data into the first column.<br />
** You could implement different renderers for represent the same data in different views.<br />
*Specify the data in the <tt>model</tt> property, and, optionally, the <tt>rowrender</tt> in the <tt>rowRenderer</tt> property.<br />
<br />
==Examples==<br />
=== Single-Column Example : Using only setModel ===<br />
In the following example, an array of data("data") is prepared , it is passed as a parameter for the generation of a ListModel("strset"). Last, assign this ListModel into a Grid by setting the model of the Grid.<br />
<br />
<source lang="xml" ><br />
<window title="Live grid"><br />
<zscript><br />
<![CDATA[ <br />
String[] data = new String[30];<br />
for(int j=0; j < data.length; ++j) {<br />
data[j] = "option "+j;<br />
} <br />
ListModel strset = new SimpleListModel(data);<br />
]]><br />
</zscript><br />
<grid model="${strset}"><br />
<columns><br />
<column label="options" /><br />
</columns><br />
</grid><br />
</window><br />
</source><br />
<br />
=== Two-Columns Example : User defined renderer ===<br />
Since the default rowrender only satisfies the scenario of single-column, a customized rowrenderer must be implemented to commit the scenario of multi-column. In the following example, a two-columns live data for grid is demonstrated.<br />
<br />
====1.Prepare the Data Model====<br />
<br />
The first step is to prepare required data. A two-way array is adopted in this example and it is passed as a parameter for the generation of a ListModel which is implemented by SimpleListModel. In addition, ListModel now supports various data types,including Array, List, Map, and Set in the form of ListModelArray,ListModelList, ListModelMap,and ListModelSet.<br />
<br />
<source lang="java" ><br />
//prepare the data model <br />
String[][] model = new String[100][2]; <br />
for(int j=0; j < model.length; ++j) { <br />
model[j][0] = "key"+j;<br />
model[j][1] = "value"+j; <br />
} <br />
ListModel strset = new SimpleListModel(model);<br />
</source><br />
<br />
====2.Define the RowRenderer Class====<br />
<br />
Secondly, to define a class which implements the interface RowRenderer,its method render(Row row, java.lang.Object data) is required to be implemented.<br />
<br />
Method render(Row row, java.lang.Object data)<br />
row - The row to render the result.<br />
data - Returned from ListModel.getElementAt() <br />
<br />
In addition to pass required parameters into the method render(), the form of view (UI Component) for displaying data in the Grid also has to be defined, and any component which is supported by Grid could be adopted. In this example, Label is adopted, and the last step is to render Label into the specified row in the Grid by calling Label.setParent(Row row).<br />
<br />
<br />
MyRowRenderer.java<br />
<br />
<source lang="java" ><br />
import org.zkoss.zul.Label;<br />
import org.zkoss.zul.Row;<br />
import org.zkoss.zul.RowRenderer;<br />
<br />
//define the RowRenderer class <br />
public class MyRowRenderer implements RowRenderer{ <br />
<br />
public void render(Row row, java.lang.Object data) {<br />
String[] _data = (String[])data;<br />
new Label(_data[0]).setParent(row); <br />
new Label(_data[1]).setParent(row);<br />
}<br />
}<br />
</source><br />
<br />
====3.Specify model and rowRenderer Property====<br />
<br />
The properties of model and rowRenderer could be specified directly in the Grid. In this example,methods, Grid.setModel() and Grid.setRowRenderer() are adopted to specify required objects for realizing the idea of "live data".<br />
<br />
<source lang="xml" ><br />
<window title="Two-Column Live Data Demo" ><br />
<grid id="mygrid"><br />
<columns><br />
<column label="key" /><br />
<column label="value" /><br />
</columns><br />
</grid><br />
<zscript><![CDATA[<br />
String[][] model = new String[100][2]; <br />
<br />
for(int j=0; j < model.length; ++j) { <br />
model[j][0] = "key"+j;<br />
model[j][1] = "value"+j; <br />
} <br />
ListModel strset = new SimpleListModel(model); <br />
mygrid.setModel(strset); <br />
mygrid.setRowRenderer(new MyRowRenderer()); <br />
]]><br />
</zscript><br />
</window><br />
</source><br />
<br />
== If extreme large data set, say 1,000,000? ==<br />
[[ZK/How-Tos/Concepts-and-Tricks]]<br />
<br />
Check <br />
Implement paging for listboxes with many items<br />
<br />
== Data Binding ==<br />
Not only showing the data by model, you can also modify underlying model by UI in real time. <br />
<br />
[[Example Code for Data binding with live data| Example code]]<br />
<br />
== See Also ==<br />
[http://www.zkoss.org/smalltalks/livedata/livedataforgrid.dsp How to realize the idea of live data in a Grid]: A smalltalk<br />
<br />
[http://www.zkoss.org/smalltalks/zkTreeModel/ ZK Tree Model]: A smalltalk.<br />
<br />
[http://zk1.svn.sourceforge.net/viewvc/zk1/branches/5.0/zul/src/org/zkoss/zul/Grid.java?revision=14211&view=markup Grid.java]: The source code of Grid.java. By tracing it, you'll know how renderer and setModel works, how <tt>render()</tt> is called, how the <tt>model</tt> is iterated through visible region. Keyword: render. You may also trace Tree.java and Listbox.java.<br />
<br />
[[Grids%2C_Trees_and_Listbox#Live_Data | Live Data]] section in chapter Grids, Trees and Listbox.<br />
<br />
[http://www.zkoss.org/forum/index.zul#path%3DlistComment%3BdiscussionId%3D6320%3BcategoryId%3D14%3B Bug in Grid paging? handleError:1084]: A thread in forum.</div>Charhttps://www.zkoss.org/_w/index.php?title=Small_Talks/2009/December/ZK_5:_Upgrade_Notes&diff=15224Small Talks/2009/December/ZK 5: Upgrade Notes2010-12-21T02:25:49Z<p>Char: /* See Also */</p>
<hr />
<div>= Overview =<br />
<br />
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.<br />
<br />
= Server-side Upgrade Notes =<br />
<br />
== Attributes and Namespace ==<br />
=== The return type of <tt>setAttribute</tt> and <tt>removeAttribute</tt> of session/execution/application changed (from <tt>void</tt> to <tt>Object</tt>) ===<br />
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.<br />
<br />
The new signature:<br />
<syntax lang="java"><br />
Object setAttribute(String name, Object value); //returns the previous value if any<br />
Object removeAttribute(String name); //return the previous value if any<br />
</syntax><br />
<br />
=== Namespace deprecated ===<br />
<br />
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.<br />
<br />
<syntax lang="xml"><br />
<variabls foo="better"/> <!-- deprecated --><br />
<custom-attribute foo="better" scope="space"/><br />
</syntax><br />
<br />
Furthermore, ZK 5 will search the attribute scopes for any variable specified in EL or <tt>zscript</tt>.<br />
<br />
<syntax lang="xml"><br />
<window><br />
<custom-attributes a="a" b="b"/> <!-- belongs to window's attribute scope --><br />
<div><br />
<custom-attributes b="B"/> <!-- belongs to div's attribute scope --><br />
${a} and ${b} <!-- result: a and B --><br />
<zscript><br />
String s = a + b; //result: aB<br />
</zscript><br />
</div><br />
</window><br />
</syntax><br />
<br />
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.<br />
<br />
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.<br />
<br />
=== The attribute scope of the ID space is the same of the space owner's attribute scope ===<br />
<br />
In the previous version, the space owner (such as <tt>window</tt>) has two attribute scopes. For example,<br />
<br />
<syntax lang="xml"><br />
<window><br />
<custom-attributes foo="a"/><br />
<div><br />
<custom-attributes foo="b" scope="space"/><br />
</div><br />
<br />
<zscript><br />
self.getAttribute("foo"); //returns a in ZK 3<br />
self.getAttribute("foo", self.SPACE_SCOPE); //returns b<br />
</zscript><br />
</window><br />
</syntax><br />
<br />
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>.<br />
<br />
== System Level Control ==<br />
<br />
=== Event processing thread disabled by default ===<br />
<br />
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 [http://docs.zkoss.org/wiki/Performance_tip#Use_the_Servlet_Thread_to_Process_Events Performance tip#Use_the_Servlet_Thread_to_Process_Events] for how to adjust your application. For example, the <tt>if</tt> clause in the following example is never true.<br />
<br />
<source lang="java" ><br />
if (Messagebox.show("Delete?", "Prompt", Messagebox.YES|Messagebox.NO,<br />
Messagebox.QUESTION) == Messagebox.YES) {<br />
this_never_executes();<br />
}<br />
</source><br />
<br />
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.<br />
<br />
<source lang="xml"><br />
<system-config><br />
<disable-event-thread>false</disable-event-thread><br />
</system-config><br />
</source><br />
<blockquote><br />
----<br />
<references/><br />
</blockquote><br />
<br />
=== The method of <tt>ComponentCloneListener</tt> changed ===<br />
<br />
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.<br />
<br />
<source lang="java"><br />
Object willClone(Component comp);<br />
</source><br />
<br />
=== The <tt>AuPocessor</tt> interface deprecated (replaced with <tt>AuExtension</tt>) ===<br />
<br />
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.<br />
<br />
=== The <tt>addRoot</tt>, <tt>removeRoot</tt>, <tt>moveRoot</tt>, <tt>addFellow</tt> and <tt>removeFellow</tt> methods of <tt>PageCtrl</tt> removed ===<br />
<br />
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>.<br />
<br />
=== The <tt>disable-behind-modal</tt> configuration disabled (always false) ===<br />
<br />
With ZK 5, there is no need to disable widgets that don't belong to the modal window, so this configuration is meaningless.<br />
<br />
== Component Use ==<br />
<br />
=== The <tt>include</tt> component's mode default to <tt>auto</tt> ===<br />
<br />
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<br />
<br />
<source lang="javascript"><br />
<include mode="defer" src="abc.zul"/><br />
</source><br />
<br />
Or, you can specify the following configuration in zk.xml to change the default mode for the whole application.<br />
<br />
<source lang="javascript"><br />
<library-property><br />
<name>org.zkoss.zul.include.mode</name><br />
<value>defer</value><br />
</library-property><br />
</source><br />
<br />
=== The <tt>a</tt> component introduced for HTML A ===<br />
<br />
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,<br />
<br />
<source lang="xml"><br />
Refer <a href="http://www.zkoss.org" label="ZK"/> for details.<br />
Or <a href="http://www.zkoss.org/zkdemo">ZK Demo</a>.<br />
</source><br />
<br />
=== CSS <tt>fixed-layout</tt> property default for <tt>grid</tt> and <tt>listbox</tt> ===<br />
<br />
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.<br />
<br />
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://docs.zkoss.org/wiki/ZK_5:_More_Flexible_Layout#Proportional_Flexibility 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 ).<br />
<br />
<source lang="xml"><br />
<grid width="300px"><br />
<columns><br />
<column label="Order" width="20px"/><br />
<column label="Name" hflex="1"/><br />
<column label="Value" hflex="2"/><br />
</columns><br />
<rows><br />
<row><image src="foo.gif"/> username: <textbox/></row><br />
<row><image src="foo.gif"/> password: <textbox/></row><br />
</rows><br />
</grid><br />
</source><br />
<br />
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.<br />
<br />
<source lang="xml"><br />
<grid width="300px" sizedByContent="true"><br />
</source><br />
<br />
=== The <tt>alphafix</tt> mold of <tt>image</tt> and <tt>imagemap</tt> deprecated ===<br />
<br />
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.<br />
<br />
<source lang="javascript"><br />
<?script content="jq.IE6_ALPHAFIX='.png';"?><br />
</source><br />
<br />
In other words, just specify a regular expression to a JavaScript variable called <tt>jq.IE6_ALPHAFIX</tt>.<br />
<br />
=== The methods of <tt>ClientConstraint</tt> changed ===<br />
<br />
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.<br />
<br />
The typical way to implement the custom client validation is as follows.<br />
<br />
#Implementing a JavaString class, say, foo.MyValidator.<br />
<br />
#Implementing <tt>org.zkoss.zul.ClientConstraint</tt> such that<br />
<br />
<source lang="java"><br />
//Java<br />
String getClientConstraint() {<br />
return "new foo.MyValidator()";<br />
}<br />
String getClientPackages() {<br />
return "foo"; //the package name<br />
}<br />
</source><br />
<br />
=== <tt>SimpleConstraint</tt> performs all validations at client ===<br />
<br />
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,<br />
<br />
<source lang="javascript"><br />
<textbox constraint="/.+@.+\.[a-z]+/,server"/><br />
</source><br />
<br />
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>.<br />
<br />
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.<br />
<br />
<source lang="javascript"><br />
//JavaScript<br />
ClientServerConstraint = zk.$extends(zul.inp.SimpleConstraint, {<br />
serverValidate: true<br />
});<br />
</source><br />
<br />
<blockquote><br />
----<br />
<references/><br />
</blockquote><br />
<br />
=== Overlapped window within another overlapped window not cropped ===<br />
<br />
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.<br />
<br />
=== Meaning of hbox/vbox <tt>pack</tt> attribute follows XUL's specification ===<br />
<br />
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".<br />
<br />
== Component Styling ==<br />
<br />
=== The <tt>dynamic</tt> attribute of the <tt>style</tt> component deprecated ===<br />
<br />
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.<br />
<br />
=== The default mold of the <tt>button</tt> component changed to <tt>os</tt> ===<br />
<br />
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>.<br />
<br />
<source lang="xml"><br />
<library-property><br />
<name>org.zkoss.zul.Button.mold</name><br />
<value>trendy</value><br />
</library-property><br />
</source><br />
<br />
=== The default value of the <tt>zclass</tt> attribute more consistent (<tt>z-</tt> + component-name) ===<br />
<br />
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.<br />
<br />
The affected components are as follows.<br />
<br />
comboitem, bandpopup, groupfoot, listcell, listfoot,<br />
listfooter, listgroup, listgroupfoot, listhead, listheader,<br />
listitem, treecell, treechildren, treecol, treecols, treefoot,<br />
treefooter, treerow, table-children, and table-layout<br />
<br />
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>.<br />
<br />
=== Both <tt>Applet</tt> and <tt>Iframe</tt> extends from <tt>HtmlBasedComponent</tt> (instead of <tt>XulElement</tt>) ===<br />
<br />
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>.<br />
<br />
=== The <tt>ZKPrefix</tt> library property deprecated ===<br />
<br />
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.<br />
<br />
== Component Development ==<br />
<br />
The component development is changed. Refer to [http://docs.zkoss.org/wiki/ZK5:_Component_Development_Guide ZK5: Component Development Guide] for details.<br />
<br />
= Client-side Upgrade Notes =<br />
<br />
The client is rewritten, so your customization have to rewrite, too.<br />
<br />
== Client-side Action deprecated ==<br />
<br />
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,<br />
<br />
<source lang="xml"><br />
<!-- ZK 3.x: Client Side Action --><br />
<textbox<br />
action="onfocus: window.action.show(#{help1}); onblur: window.action.hide(#{help1})" /><br />
<label id="help1" visible="false" value="This is help for text1." /><br />
</source><br />
<br />
can be replaced with<br />
<br />
<source lang="xml"><br />
<!-- ZK 5 --><br />
<textbox xmlns:w="http://www.zkoss.org/2005/zk/client"<br />
w:onFocus="jq(this.$f('help1')).fadeIn()" w:onBlur="jq(this.$f('help1')).fadeOut()"/><br />
<label id="help1" visible="false" value="This is help for text1." /><br />
</source><br />
<br />
== Animation API deprecated ==<br />
<br />
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,<br />
<br />
<source lang="xml"><br />
<!-- ZK 3.x: anima --><br />
<label sclass="ctl" value="SlideDown"<br />
action="onclick: zk.hide(#{t});anima.slideDown(#{t})"/><br />
</source><br />
<br />
<source lang="xml"><br />
<!- ZK 5: with jQury --><br />
<label sclass="ctl" value="SlideDown"<br />
w:onClick="jq(this.$f('t')).hide().slideDown()"<br />
xmlns:w="http://www.zkoss.org/2005/zk/client"/><br />
</source><br />
<br />
Please refer to [[ZK5: JavaScript API]] for the complete description of JavaScript API at the client.<br />
<br />
= See Also =<br />
*[http://docs.zkoss.org/wiki/Upgrading_to_ZK_5 Upgrading to ZK 5]<br />
*A forum thread : [http://www.zkoss.org/forum/listComment/11094 Upgrade to ZK5 ]<br />
<br />
<br />
<comment>http://docs.zkoss.org/wiki/ZK_5:_Upgrade_Notes</comment></div>Charhttps://www.zkoss.org/_w/index.php?title=Small_Talks/2009/December/ZK_5:_Upgrade_Notes&diff=15223Small Talks/2009/December/ZK 5: Upgrade Notes2010-12-21T02:24:54Z<p>Char: /* Component Development */</p>
<hr />
<div>= Overview =<br />
<br />
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.<br />
<br />
= Server-side Upgrade Notes =<br />
<br />
== Attributes and Namespace ==<br />
=== The return type of <tt>setAttribute</tt> and <tt>removeAttribute</tt> of session/execution/application changed (from <tt>void</tt> to <tt>Object</tt>) ===<br />
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.<br />
<br />
The new signature:<br />
<syntax lang="java"><br />
Object setAttribute(String name, Object value); //returns the previous value if any<br />
Object removeAttribute(String name); //return the previous value if any<br />
</syntax><br />
<br />
=== Namespace deprecated ===<br />
<br />
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.<br />
<br />
<syntax lang="xml"><br />
<variabls foo="better"/> <!-- deprecated --><br />
<custom-attribute foo="better" scope="space"/><br />
</syntax><br />
<br />
Furthermore, ZK 5 will search the attribute scopes for any variable specified in EL or <tt>zscript</tt>.<br />
<br />
<syntax lang="xml"><br />
<window><br />
<custom-attributes a="a" b="b"/> <!-- belongs to window's attribute scope --><br />
<div><br />
<custom-attributes b="B"/> <!-- belongs to div's attribute scope --><br />
${a} and ${b} <!-- result: a and B --><br />
<zscript><br />
String s = a + b; //result: aB<br />
</zscript><br />
</div><br />
</window><br />
</syntax><br />
<br />
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.<br />
<br />
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.<br />
<br />
=== The attribute scope of the ID space is the same of the space owner's attribute scope ===<br />
<br />
In the previous version, the space owner (such as <tt>window</tt>) has two attribute scopes. For example,<br />
<br />
<syntax lang="xml"><br />
<window><br />
<custom-attributes foo="a"/><br />
<div><br />
<custom-attributes foo="b" scope="space"/><br />
</div><br />
<br />
<zscript><br />
self.getAttribute("foo"); //returns a in ZK 3<br />
self.getAttribute("foo", self.SPACE_SCOPE); //returns b<br />
</zscript><br />
</window><br />
</syntax><br />
<br />
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>.<br />
<br />
== System Level Control ==<br />
<br />
=== Event processing thread disabled by default ===<br />
<br />
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 [http://docs.zkoss.org/wiki/Performance_tip#Use_the_Servlet_Thread_to_Process_Events Performance tip#Use_the_Servlet_Thread_to_Process_Events] for how to adjust your application. For example, the <tt>if</tt> clause in the following example is never true.<br />
<br />
<source lang="java" ><br />
if (Messagebox.show("Delete?", "Prompt", Messagebox.YES|Messagebox.NO,<br />
Messagebox.QUESTION) == Messagebox.YES) {<br />
this_never_executes();<br />
}<br />
</source><br />
<br />
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.<br />
<br />
<source lang="xml"><br />
<system-config><br />
<disable-event-thread>false</disable-event-thread><br />
</system-config><br />
</source><br />
<blockquote><br />
----<br />
<references/><br />
</blockquote><br />
<br />
=== The method of <tt>ComponentCloneListener</tt> changed ===<br />
<br />
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.<br />
<br />
<source lang="java"><br />
Object willClone(Component comp);<br />
</source><br />
<br />
=== The <tt>AuPocessor</tt> interface deprecated (replaced with <tt>AuExtension</tt>) ===<br />
<br />
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.<br />
<br />
=== The <tt>addRoot</tt>, <tt>removeRoot</tt>, <tt>moveRoot</tt>, <tt>addFellow</tt> and <tt>removeFellow</tt> methods of <tt>PageCtrl</tt> removed ===<br />
<br />
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>.<br />
<br />
=== The <tt>disable-behind-modal</tt> configuration disabled (always false) ===<br />
<br />
With ZK 5, there is no need to disable widgets that don't belong to the modal window, so this configuration is meaningless.<br />
<br />
== Component Use ==<br />
<br />
=== The <tt>include</tt> component's mode default to <tt>auto</tt> ===<br />
<br />
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<br />
<br />
<source lang="javascript"><br />
<include mode="defer" src="abc.zul"/><br />
</source><br />
<br />
Or, you can specify the following configuration in zk.xml to change the default mode for the whole application.<br />
<br />
<source lang="javascript"><br />
<library-property><br />
<name>org.zkoss.zul.include.mode</name><br />
<value>defer</value><br />
</library-property><br />
</source><br />
<br />
=== The <tt>a</tt> component introduced for HTML A ===<br />
<br />
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,<br />
<br />
<source lang="xml"><br />
Refer <a href="http://www.zkoss.org" label="ZK"/> for details.<br />
Or <a href="http://www.zkoss.org/zkdemo">ZK Demo</a>.<br />
</source><br />
<br />
=== CSS <tt>fixed-layout</tt> property default for <tt>grid</tt> and <tt>listbox</tt> ===<br />
<br />
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.<br />
<br />
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://docs.zkoss.org/wiki/ZK_5:_More_Flexible_Layout#Proportional_Flexibility 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 ).<br />
<br />
<source lang="xml"><br />
<grid width="300px"><br />
<columns><br />
<column label="Order" width="20px"/><br />
<column label="Name" hflex="1"/><br />
<column label="Value" hflex="2"/><br />
</columns><br />
<rows><br />
<row><image src="foo.gif"/> username: <textbox/></row><br />
<row><image src="foo.gif"/> password: <textbox/></row><br />
</rows><br />
</grid><br />
</source><br />
<br />
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.<br />
<br />
<source lang="xml"><br />
<grid width="300px" sizedByContent="true"><br />
</source><br />
<br />
=== The <tt>alphafix</tt> mold of <tt>image</tt> and <tt>imagemap</tt> deprecated ===<br />
<br />
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.<br />
<br />
<source lang="javascript"><br />
<?script content="jq.IE6_ALPHAFIX='.png';"?><br />
</source><br />
<br />
In other words, just specify a regular expression to a JavaScript variable called <tt>jq.IE6_ALPHAFIX</tt>.<br />
<br />
=== The methods of <tt>ClientConstraint</tt> changed ===<br />
<br />
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.<br />
<br />
The typical way to implement the custom client validation is as follows.<br />
<br />
#Implementing a JavaString class, say, foo.MyValidator.<br />
<br />
#Implementing <tt>org.zkoss.zul.ClientConstraint</tt> such that<br />
<br />
<source lang="java"><br />
//Java<br />
String getClientConstraint() {<br />
return "new foo.MyValidator()";<br />
}<br />
String getClientPackages() {<br />
return "foo"; //the package name<br />
}<br />
</source><br />
<br />
=== <tt>SimpleConstraint</tt> performs all validations at client ===<br />
<br />
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,<br />
<br />
<source lang="javascript"><br />
<textbox constraint="/.+@.+\.[a-z]+/,server"/><br />
</source><br />
<br />
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>.<br />
<br />
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.<br />
<br />
<source lang="javascript"><br />
//JavaScript<br />
ClientServerConstraint = zk.$extends(zul.inp.SimpleConstraint, {<br />
serverValidate: true<br />
});<br />
</source><br />
<br />
<blockquote><br />
----<br />
<references/><br />
</blockquote><br />
<br />
=== Overlapped window within another overlapped window not cropped ===<br />
<br />
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.<br />
<br />
=== Meaning of hbox/vbox <tt>pack</tt> attribute follows XUL's specification ===<br />
<br />
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".<br />
<br />
== Component Styling ==<br />
<br />
=== The <tt>dynamic</tt> attribute of the <tt>style</tt> component deprecated ===<br />
<br />
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.<br />
<br />
=== The default mold of the <tt>button</tt> component changed to <tt>os</tt> ===<br />
<br />
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>.<br />
<br />
<source lang="xml"><br />
<library-property><br />
<name>org.zkoss.zul.Button.mold</name><br />
<value>trendy</value><br />
</library-property><br />
</source><br />
<br />
=== The default value of the <tt>zclass</tt> attribute more consistent (<tt>z-</tt> + component-name) ===<br />
<br />
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.<br />
<br />
The affected components are as follows.<br />
<br />
comboitem, bandpopup, groupfoot, listcell, listfoot,<br />
listfooter, listgroup, listgroupfoot, listhead, listheader,<br />
listitem, treecell, treechildren, treecol, treecols, treefoot,<br />
treefooter, treerow, table-children, and table-layout<br />
<br />
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>.<br />
<br />
=== Both <tt>Applet</tt> and <tt>Iframe</tt> extends from <tt>HtmlBasedComponent</tt> (instead of <tt>XulElement</tt>) ===<br />
<br />
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>.<br />
<br />
=== The <tt>ZKPrefix</tt> library property deprecated ===<br />
<br />
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.<br />
<br />
== Component Development ==<br />
<br />
The component development is changed. Refer to [http://docs.zkoss.org/wiki/ZK5:_Component_Development_Guide ZK5: Component Development Guide] for details.<br />
<br />
= Client-side Upgrade Notes =<br />
<br />
The client is rewritten, so your customization have to rewrite, too.<br />
<br />
== Client-side Action deprecated ==<br />
<br />
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,<br />
<br />
<source lang="xml"><br />
<!-- ZK 3.x: Client Side Action --><br />
<textbox<br />
action="onfocus: window.action.show(#{help1}); onblur: window.action.hide(#{help1})" /><br />
<label id="help1" visible="false" value="This is help for text1." /><br />
</source><br />
<br />
can be replaced with<br />
<br />
<source lang="xml"><br />
<!-- ZK 5 --><br />
<textbox xmlns:w="http://www.zkoss.org/2005/zk/client"<br />
w:onFocus="jq(this.$f('help1')).fadeIn()" w:onBlur="jq(this.$f('help1')).fadeOut()"/><br />
<label id="help1" visible="false" value="This is help for text1." /><br />
</source><br />
<br />
== Animation API deprecated ==<br />
<br />
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,<br />
<br />
<source lang="xml"><br />
<!-- ZK 3.x: anima --><br />
<label sclass="ctl" value="SlideDown"<br />
action="onclick: zk.hide(#{t});anima.slideDown(#{t})"/><br />
</source><br />
<br />
<source lang="xml"><br />
<!- ZK 5: with jQury --><br />
<label sclass="ctl" value="SlideDown"<br />
w:onClick="jq(this.$f('t')).hide().slideDown()"<br />
xmlns:w="http://www.zkoss.org/2005/zk/client"/><br />
</source><br />
<br />
Please refer to [[ZK5: JavaScript API]] for the complete description of JavaScript API at the client.<br />
<br />
= See Also =<br />
*[[Upgrading to ZK 5]]<br />
*A forum thread : [http://www.zkoss.org/forum/listComment/11094 Upgrade to ZK5 ]<br />
<br />
<br />
<comment>http://docs.zkoss.org/wiki/ZK_5:_Upgrade_Notes</comment></div>Charhttps://www.zkoss.org/_w/index.php?title=Small_Talks/2009/December/ZK_5:_Upgrade_Notes&diff=15222Small Talks/2009/December/ZK 5: Upgrade Notes2010-12-21T02:24:05Z<p>Char: /* CSS fixed-layout property default for grid and listbox */</p>
<hr />
<div>= Overview =<br />
<br />
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.<br />
<br />
= Server-side Upgrade Notes =<br />
<br />
== Attributes and Namespace ==<br />
=== The return type of <tt>setAttribute</tt> and <tt>removeAttribute</tt> of session/execution/application changed (from <tt>void</tt> to <tt>Object</tt>) ===<br />
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.<br />
<br />
The new signature:<br />
<syntax lang="java"><br />
Object setAttribute(String name, Object value); //returns the previous value if any<br />
Object removeAttribute(String name); //return the previous value if any<br />
</syntax><br />
<br />
=== Namespace deprecated ===<br />
<br />
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.<br />
<br />
<syntax lang="xml"><br />
<variabls foo="better"/> <!-- deprecated --><br />
<custom-attribute foo="better" scope="space"/><br />
</syntax><br />
<br />
Furthermore, ZK 5 will search the attribute scopes for any variable specified in EL or <tt>zscript</tt>.<br />
<br />
<syntax lang="xml"><br />
<window><br />
<custom-attributes a="a" b="b"/> <!-- belongs to window's attribute scope --><br />
<div><br />
<custom-attributes b="B"/> <!-- belongs to div's attribute scope --><br />
${a} and ${b} <!-- result: a and B --><br />
<zscript><br />
String s = a + b; //result: aB<br />
</zscript><br />
</div><br />
</window><br />
</syntax><br />
<br />
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.<br />
<br />
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.<br />
<br />
=== The attribute scope of the ID space is the same of the space owner's attribute scope ===<br />
<br />
In the previous version, the space owner (such as <tt>window</tt>) has two attribute scopes. For example,<br />
<br />
<syntax lang="xml"><br />
<window><br />
<custom-attributes foo="a"/><br />
<div><br />
<custom-attributes foo="b" scope="space"/><br />
</div><br />
<br />
<zscript><br />
self.getAttribute("foo"); //returns a in ZK 3<br />
self.getAttribute("foo", self.SPACE_SCOPE); //returns b<br />
</zscript><br />
</window><br />
</syntax><br />
<br />
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>.<br />
<br />
== System Level Control ==<br />
<br />
=== Event processing thread disabled by default ===<br />
<br />
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 [http://docs.zkoss.org/wiki/Performance_tip#Use_the_Servlet_Thread_to_Process_Events Performance tip#Use_the_Servlet_Thread_to_Process_Events] for how to adjust your application. For example, the <tt>if</tt> clause in the following example is never true.<br />
<br />
<source lang="java" ><br />
if (Messagebox.show("Delete?", "Prompt", Messagebox.YES|Messagebox.NO,<br />
Messagebox.QUESTION) == Messagebox.YES) {<br />
this_never_executes();<br />
}<br />
</source><br />
<br />
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.<br />
<br />
<source lang="xml"><br />
<system-config><br />
<disable-event-thread>false</disable-event-thread><br />
</system-config><br />
</source><br />
<blockquote><br />
----<br />
<references/><br />
</blockquote><br />
<br />
=== The method of <tt>ComponentCloneListener</tt> changed ===<br />
<br />
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.<br />
<br />
<source lang="java"><br />
Object willClone(Component comp);<br />
</source><br />
<br />
=== The <tt>AuPocessor</tt> interface deprecated (replaced with <tt>AuExtension</tt>) ===<br />
<br />
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.<br />
<br />
=== The <tt>addRoot</tt>, <tt>removeRoot</tt>, <tt>moveRoot</tt>, <tt>addFellow</tt> and <tt>removeFellow</tt> methods of <tt>PageCtrl</tt> removed ===<br />
<br />
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>.<br />
<br />
=== The <tt>disable-behind-modal</tt> configuration disabled (always false) ===<br />
<br />
With ZK 5, there is no need to disable widgets that don't belong to the modal window, so this configuration is meaningless.<br />
<br />
== Component Use ==<br />
<br />
=== The <tt>include</tt> component's mode default to <tt>auto</tt> ===<br />
<br />
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<br />
<br />
<source lang="javascript"><br />
<include mode="defer" src="abc.zul"/><br />
</source><br />
<br />
Or, you can specify the following configuration in zk.xml to change the default mode for the whole application.<br />
<br />
<source lang="javascript"><br />
<library-property><br />
<name>org.zkoss.zul.include.mode</name><br />
<value>defer</value><br />
</library-property><br />
</source><br />
<br />
=== The <tt>a</tt> component introduced for HTML A ===<br />
<br />
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,<br />
<br />
<source lang="xml"><br />
Refer <a href="http://www.zkoss.org" label="ZK"/> for details.<br />
Or <a href="http://www.zkoss.org/zkdemo">ZK Demo</a>.<br />
</source><br />
<br />
=== CSS <tt>fixed-layout</tt> property default for <tt>grid</tt> and <tt>listbox</tt> ===<br />
<br />
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.<br />
<br />
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://docs.zkoss.org/wiki/ZK_5:_More_Flexible_Layout#Proportional_Flexibility 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 ).<br />
<br />
<source lang="xml"><br />
<grid width="300px"><br />
<columns><br />
<column label="Order" width="20px"/><br />
<column label="Name" hflex="1"/><br />
<column label="Value" hflex="2"/><br />
</columns><br />
<rows><br />
<row><image src="foo.gif"/> username: <textbox/></row><br />
<row><image src="foo.gif"/> password: <textbox/></row><br />
</rows><br />
</grid><br />
</source><br />
<br />
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.<br />
<br />
<source lang="xml"><br />
<grid width="300px" sizedByContent="true"><br />
</source><br />
<br />
=== The <tt>alphafix</tt> mold of <tt>image</tt> and <tt>imagemap</tt> deprecated ===<br />
<br />
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.<br />
<br />
<source lang="javascript"><br />
<?script content="jq.IE6_ALPHAFIX='.png';"?><br />
</source><br />
<br />
In other words, just specify a regular expression to a JavaScript variable called <tt>jq.IE6_ALPHAFIX</tt>.<br />
<br />
=== The methods of <tt>ClientConstraint</tt> changed ===<br />
<br />
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.<br />
<br />
The typical way to implement the custom client validation is as follows.<br />
<br />
#Implementing a JavaString class, say, foo.MyValidator.<br />
<br />
#Implementing <tt>org.zkoss.zul.ClientConstraint</tt> such that<br />
<br />
<source lang="java"><br />
//Java<br />
String getClientConstraint() {<br />
return "new foo.MyValidator()";<br />
}<br />
String getClientPackages() {<br />
return "foo"; //the package name<br />
}<br />
</source><br />
<br />
=== <tt>SimpleConstraint</tt> performs all validations at client ===<br />
<br />
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,<br />
<br />
<source lang="javascript"><br />
<textbox constraint="/.+@.+\.[a-z]+/,server"/><br />
</source><br />
<br />
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>.<br />
<br />
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.<br />
<br />
<source lang="javascript"><br />
//JavaScript<br />
ClientServerConstraint = zk.$extends(zul.inp.SimpleConstraint, {<br />
serverValidate: true<br />
});<br />
</source><br />
<br />
<blockquote><br />
----<br />
<references/><br />
</blockquote><br />
<br />
=== Overlapped window within another overlapped window not cropped ===<br />
<br />
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.<br />
<br />
=== Meaning of hbox/vbox <tt>pack</tt> attribute follows XUL's specification ===<br />
<br />
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".<br />
<br />
== Component Styling ==<br />
<br />
=== The <tt>dynamic</tt> attribute of the <tt>style</tt> component deprecated ===<br />
<br />
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.<br />
<br />
=== The default mold of the <tt>button</tt> component changed to <tt>os</tt> ===<br />
<br />
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>.<br />
<br />
<source lang="xml"><br />
<library-property><br />
<name>org.zkoss.zul.Button.mold</name><br />
<value>trendy</value><br />
</library-property><br />
</source><br />
<br />
=== The default value of the <tt>zclass</tt> attribute more consistent (<tt>z-</tt> + component-name) ===<br />
<br />
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.<br />
<br />
The affected components are as follows.<br />
<br />
comboitem, bandpopup, groupfoot, listcell, listfoot,<br />
listfooter, listgroup, listgroupfoot, listhead, listheader,<br />
listitem, treecell, treechildren, treecol, treecols, treefoot,<br />
treefooter, treerow, table-children, and table-layout<br />
<br />
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>.<br />
<br />
=== Both <tt>Applet</tt> and <tt>Iframe</tt> extends from <tt>HtmlBasedComponent</tt> (instead of <tt>XulElement</tt>) ===<br />
<br />
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>.<br />
<br />
=== The <tt>ZKPrefix</tt> library property deprecated ===<br />
<br />
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.<br />
<br />
== Component Development ==<br />
<br />
The component development is changed. Refer to [[ZK5: Component Development Guide]] for details.<br />
<br />
= Client-side Upgrade Notes =<br />
<br />
The client is rewritten, so your customization have to rewrite, too.<br />
<br />
== Client-side Action deprecated ==<br />
<br />
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,<br />
<br />
<source lang="xml"><br />
<!-- ZK 3.x: Client Side Action --><br />
<textbox<br />
action="onfocus: window.action.show(#{help1}); onblur: window.action.hide(#{help1})" /><br />
<label id="help1" visible="false" value="This is help for text1." /><br />
</source><br />
<br />
can be replaced with<br />
<br />
<source lang="xml"><br />
<!-- ZK 5 --><br />
<textbox xmlns:w="http://www.zkoss.org/2005/zk/client"<br />
w:onFocus="jq(this.$f('help1')).fadeIn()" w:onBlur="jq(this.$f('help1')).fadeOut()"/><br />
<label id="help1" visible="false" value="This is help for text1." /><br />
</source><br />
<br />
== Animation API deprecated ==<br />
<br />
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,<br />
<br />
<source lang="xml"><br />
<!-- ZK 3.x: anima --><br />
<label sclass="ctl" value="SlideDown"<br />
action="onclick: zk.hide(#{t});anima.slideDown(#{t})"/><br />
</source><br />
<br />
<source lang="xml"><br />
<!- ZK 5: with jQury --><br />
<label sclass="ctl" value="SlideDown"<br />
w:onClick="jq(this.$f('t')).hide().slideDown()"<br />
xmlns:w="http://www.zkoss.org/2005/zk/client"/><br />
</source><br />
<br />
Please refer to [[ZK5: JavaScript API]] for the complete description of JavaScript API at the client.<br />
<br />
= See Also =<br />
*[[Upgrading to ZK 5]]<br />
*A forum thread : [http://www.zkoss.org/forum/listComment/11094 Upgrade to ZK5 ]<br />
<br />
<br />
<comment>http://docs.zkoss.org/wiki/ZK_5:_Upgrade_Notes</comment></div>Charhttps://www.zkoss.org/_w/index.php?title=Small_Talks/2009/December/ZK_5:_Upgrade_Notes&diff=15221Small Talks/2009/December/ZK 5: Upgrade Notes2010-12-21T02:23:02Z<p>Char: /* Event processing thread disabled by default */</p>
<hr />
<div>= Overview =<br />
<br />
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.<br />
<br />
= Server-side Upgrade Notes =<br />
<br />
== Attributes and Namespace ==<br />
=== The return type of <tt>setAttribute</tt> and <tt>removeAttribute</tt> of session/execution/application changed (from <tt>void</tt> to <tt>Object</tt>) ===<br />
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.<br />
<br />
The new signature:<br />
<syntax lang="java"><br />
Object setAttribute(String name, Object value); //returns the previous value if any<br />
Object removeAttribute(String name); //return the previous value if any<br />
</syntax><br />
<br />
=== Namespace deprecated ===<br />
<br />
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.<br />
<br />
<syntax lang="xml"><br />
<variabls foo="better"/> <!-- deprecated --><br />
<custom-attribute foo="better" scope="space"/><br />
</syntax><br />
<br />
Furthermore, ZK 5 will search the attribute scopes for any variable specified in EL or <tt>zscript</tt>.<br />
<br />
<syntax lang="xml"><br />
<window><br />
<custom-attributes a="a" b="b"/> <!-- belongs to window's attribute scope --><br />
<div><br />
<custom-attributes b="B"/> <!-- belongs to div's attribute scope --><br />
${a} and ${b} <!-- result: a and B --><br />
<zscript><br />
String s = a + b; //result: aB<br />
</zscript><br />
</div><br />
</window><br />
</syntax><br />
<br />
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.<br />
<br />
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.<br />
<br />
=== The attribute scope of the ID space is the same of the space owner's attribute scope ===<br />
<br />
In the previous version, the space owner (such as <tt>window</tt>) has two attribute scopes. For example,<br />
<br />
<syntax lang="xml"><br />
<window><br />
<custom-attributes foo="a"/><br />
<div><br />
<custom-attributes foo="b" scope="space"/><br />
</div><br />
<br />
<zscript><br />
self.getAttribute("foo"); //returns a in ZK 3<br />
self.getAttribute("foo", self.SPACE_SCOPE); //returns b<br />
</zscript><br />
</window><br />
</syntax><br />
<br />
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>.<br />
<br />
== System Level Control ==<br />
<br />
=== Event processing thread disabled by default ===<br />
<br />
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 [http://docs.zkoss.org/wiki/Performance_tip#Use_the_Servlet_Thread_to_Process_Events Performance tip#Use_the_Servlet_Thread_to_Process_Events] for how to adjust your application. For example, the <tt>if</tt> clause in the following example is never true.<br />
<br />
<source lang="java" ><br />
if (Messagebox.show("Delete?", "Prompt", Messagebox.YES|Messagebox.NO,<br />
Messagebox.QUESTION) == Messagebox.YES) {<br />
this_never_executes();<br />
}<br />
</source><br />
<br />
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.<br />
<br />
<source lang="xml"><br />
<system-config><br />
<disable-event-thread>false</disable-event-thread><br />
</system-config><br />
</source><br />
<blockquote><br />
----<br />
<references/><br />
</blockquote><br />
<br />
=== The method of <tt>ComponentCloneListener</tt> changed ===<br />
<br />
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.<br />
<br />
<source lang="java"><br />
Object willClone(Component comp);<br />
</source><br />
<br />
=== The <tt>AuPocessor</tt> interface deprecated (replaced with <tt>AuExtension</tt>) ===<br />
<br />
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.<br />
<br />
=== The <tt>addRoot</tt>, <tt>removeRoot</tt>, <tt>moveRoot</tt>, <tt>addFellow</tt> and <tt>removeFellow</tt> methods of <tt>PageCtrl</tt> removed ===<br />
<br />
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>.<br />
<br />
=== The <tt>disable-behind-modal</tt> configuration disabled (always false) ===<br />
<br />
With ZK 5, there is no need to disable widgets that don't belong to the modal window, so this configuration is meaningless.<br />
<br />
== Component Use ==<br />
<br />
=== The <tt>include</tt> component's mode default to <tt>auto</tt> ===<br />
<br />
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<br />
<br />
<source lang="javascript"><br />
<include mode="defer" src="abc.zul"/><br />
</source><br />
<br />
Or, you can specify the following configuration in zk.xml to change the default mode for the whole application.<br />
<br />
<source lang="javascript"><br />
<library-property><br />
<name>org.zkoss.zul.include.mode</name><br />
<value>defer</value><br />
</library-property><br />
</source><br />
<br />
=== The <tt>a</tt> component introduced for HTML A ===<br />
<br />
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,<br />
<br />
<source lang="xml"><br />
Refer <a href="http://www.zkoss.org" label="ZK"/> for details.<br />
Or <a href="http://www.zkoss.org/zkdemo">ZK Demo</a>.<br />
</source><br />
<br />
=== CSS <tt>fixed-layout</tt> property default for <tt>grid</tt> and <tt>listbox</tt> ===<br />
<br />
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.<br />
<br />
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 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 ).<br />
<br />
<source lang="xml"><br />
<grid width="300px"><br />
<columns><br />
<column label="Order" width="20px"/><br />
<column label="Name" hflex="1"/><br />
<column label="Value" hflex="2"/><br />
</columns><br />
<rows><br />
<row><image src="foo.gif"/> username: <textbox/></row><br />
<row><image src="foo.gif"/> password: <textbox/></row><br />
</rows><br />
</grid><br />
</source><br />
<br />
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.<br />
<br />
<source lang="xml"><br />
<grid width="300px" sizedByContent="true"><br />
</source><br />
<br />
=== The <tt>alphafix</tt> mold of <tt>image</tt> and <tt>imagemap</tt> deprecated ===<br />
<br />
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.<br />
<br />
<source lang="javascript"><br />
<?script content="jq.IE6_ALPHAFIX='.png';"?><br />
</source><br />
<br />
In other words, just specify a regular expression to a JavaScript variable called <tt>jq.IE6_ALPHAFIX</tt>.<br />
<br />
=== The methods of <tt>ClientConstraint</tt> changed ===<br />
<br />
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.<br />
<br />
The typical way to implement the custom client validation is as follows.<br />
<br />
#Implementing a JavaString class, say, foo.MyValidator.<br />
<br />
#Implementing <tt>org.zkoss.zul.ClientConstraint</tt> such that<br />
<br />
<source lang="java"><br />
//Java<br />
String getClientConstraint() {<br />
return "new foo.MyValidator()";<br />
}<br />
String getClientPackages() {<br />
return "foo"; //the package name<br />
}<br />
</source><br />
<br />
=== <tt>SimpleConstraint</tt> performs all validations at client ===<br />
<br />
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,<br />
<br />
<source lang="javascript"><br />
<textbox constraint="/.+@.+\.[a-z]+/,server"/><br />
</source><br />
<br />
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>.<br />
<br />
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.<br />
<br />
<source lang="javascript"><br />
//JavaScript<br />
ClientServerConstraint = zk.$extends(zul.inp.SimpleConstraint, {<br />
serverValidate: true<br />
});<br />
</source><br />
<br />
<blockquote><br />
----<br />
<references/><br />
</blockquote><br />
<br />
=== Overlapped window within another overlapped window not cropped ===<br />
<br />
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.<br />
<br />
=== Meaning of hbox/vbox <tt>pack</tt> attribute follows XUL's specification ===<br />
<br />
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".<br />
<br />
== Component Styling ==<br />
<br />
=== The <tt>dynamic</tt> attribute of the <tt>style</tt> component deprecated ===<br />
<br />
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.<br />
<br />
=== The default mold of the <tt>button</tt> component changed to <tt>os</tt> ===<br />
<br />
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>.<br />
<br />
<source lang="xml"><br />
<library-property><br />
<name>org.zkoss.zul.Button.mold</name><br />
<value>trendy</value><br />
</library-property><br />
</source><br />
<br />
=== The default value of the <tt>zclass</tt> attribute more consistent (<tt>z-</tt> + component-name) ===<br />
<br />
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.<br />
<br />
The affected components are as follows.<br />
<br />
comboitem, bandpopup, groupfoot, listcell, listfoot,<br />
listfooter, listgroup, listgroupfoot, listhead, listheader,<br />
listitem, treecell, treechildren, treecol, treecols, treefoot,<br />
treefooter, treerow, table-children, and table-layout<br />
<br />
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>.<br />
<br />
=== Both <tt>Applet</tt> and <tt>Iframe</tt> extends from <tt>HtmlBasedComponent</tt> (instead of <tt>XulElement</tt>) ===<br />
<br />
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>.<br />
<br />
=== The <tt>ZKPrefix</tt> library property deprecated ===<br />
<br />
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.<br />
<br />
== Component Development ==<br />
<br />
The component development is changed. Refer to [[ZK5: Component Development Guide]] for details.<br />
<br />
= Client-side Upgrade Notes =<br />
<br />
The client is rewritten, so your customization have to rewrite, too.<br />
<br />
== Client-side Action deprecated ==<br />
<br />
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,<br />
<br />
<source lang="xml"><br />
<!-- ZK 3.x: Client Side Action --><br />
<textbox<br />
action="onfocus: window.action.show(#{help1}); onblur: window.action.hide(#{help1})" /><br />
<label id="help1" visible="false" value="This is help for text1." /><br />
</source><br />
<br />
can be replaced with<br />
<br />
<source lang="xml"><br />
<!-- ZK 5 --><br />
<textbox xmlns:w="http://www.zkoss.org/2005/zk/client"<br />
w:onFocus="jq(this.$f('help1')).fadeIn()" w:onBlur="jq(this.$f('help1')).fadeOut()"/><br />
<label id="help1" visible="false" value="This is help for text1." /><br />
</source><br />
<br />
== Animation API deprecated ==<br />
<br />
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,<br />
<br />
<source lang="xml"><br />
<!-- ZK 3.x: anima --><br />
<label sclass="ctl" value="SlideDown"<br />
action="onclick: zk.hide(#{t});anima.slideDown(#{t})"/><br />
</source><br />
<br />
<source lang="xml"><br />
<!- ZK 5: with jQury --><br />
<label sclass="ctl" value="SlideDown"<br />
w:onClick="jq(this.$f('t')).hide().slideDown()"<br />
xmlns:w="http://www.zkoss.org/2005/zk/client"/><br />
</source><br />
<br />
Please refer to [[ZK5: JavaScript API]] for the complete description of JavaScript API at the client.<br />
<br />
= See Also =<br />
*[[Upgrading to ZK 5]]<br />
*A forum thread : [http://www.zkoss.org/forum/listComment/11094 Upgrade to ZK5 ]<br />
<br />
<br />
<comment>http://docs.zkoss.org/wiki/ZK_5:_Upgrade_Notes</comment></div>Charhttps://www.zkoss.org/_w/index.php?title=Small_Talks/2009/June/New_Features_of_ZK_3.6.2_TW&diff=15220Small Talks/2009/June/New Features of ZK 3.6.2 TW2010-12-21T02:21:29Z<p>Char: /* 支援Google App Engine */</p>
<hr />
<div>{{Template:Smalltalk_Author|<br />
|author=Timothy Clare, Technology Evangelist, Potix Corporation<br />
|date=June 22, 2009<br />
|version=3.6.2<br />
}}<br />
<br />
<br />
<br />
ZK 最新版本3.6.2 主要重點為效能的提升,您將在各家瀏覽器直接感受到其中的差異,尤其IE6 瀏覽器最為明顯。 <br />
除了在效能方面的進步之外,<br />
相信您也能在此最新版本發現我們新增了許多強大的功能,<br />
同時也修正了48個以上的臭蟲。 <br />
現在就跟著我們一起來看3.6.2 新增了哪些功能吧!<br />
<br />
<br />
<br />
<br />
==效能改善==<br />
<br />
===效能===<br />
<br />
在最新版本裡,我們的效能已有大幅的提升和進步,其中最明顯的即是應用程式在瀏覽器IE6上運行的速度!我們在tabbox 裡測試了約430 個控制項<br />
<br />
以下圖表即為測試結果:<br />
<br />
[[Image:ini_test.png|500px|Test Result]]<br />
[[Image:changetabs_test.png|500px|Test Result]]<br />
<br />
<br />
首先,你會在圖表上注意到,ZK 3.6.2 在所有的測試中都有極為突出的表現!<br />
當執行操作系統模式初始化時,ZK 3.6.2 的速度為3.6.1 的三倍。另外,在初始化預設模式時, ZK 3.6.2 的速度也比 3.6.1 快整整兩倍。 <br />
<br />
不僅如此,在標籤轉換測試中,我們也能在操作系統按鈕模式看到顯著的效能增益:<br />
ZK 3.6.2 的速度為3.6.1的兩倍。而ZK 3.6.2 的預設按鈕模式在轉換標籤時,效能也遠超過ZK3.6.1。<br />
<br />
由測試結果來看,如果您開發的是一個非常需要高效能的應用程式時,我們將建議你使用系統按鈕模式,因為這帶來的效能增益將遠遠超過預設模式。<br />
測試用控制項完整列表如下:<br />
<br />
<br />
{|style="border:1px solid black"<br />
|-<br />
|width="300px" |MenuBar * 1 <br /><br />
Menu * 12 <br /><br />
borderlayout *2 <br /><br />
Tabbox * 1<br /><br />
Tab * 2<br /><br />
Tabpanel * 2<br /><br />
Window * 6<br /><br />
|Vbox * 2<br /><br />
Grid * 2<br /><br />
Listbox * 2<br /><br />
Listitem * 15<br /><br />
Listcell * 100<br /><br />
Label * 100<br /><br />
Button * 100<br /><br />
|}<br />
<br />
===Include模式===<br />
<br />
當我們在ZUL檔案裡使用include元件時,常會出現一些問題,問題通常發生在元件出現之前,我們無法介入元件的生命周期。<br />
而這個問題在ZK 3.6.2以後的版本將不再出現。關鍵在於我們應用了新的模式:include模式。目前共有三種include模式:延遲、即時和自動模式。而3.6.2之前版本中的include 標籤行為和目前的預設模式是相同的,皆為延遲模式。<br />
<br />
====Instant 模式====<br />
<br />
因為使用了Execution.createComponent功能,Instant模式能立即產生頁面,也就是說,因為下了初始化命令,他們可以直接與用戶連結,因此並不會有任何混亂或問題產生。 <br />
以下程式將為您示範如何設定Instant 模式:<br />
<br />
<source lang="xml"><br />
<window title="demo" border="normal"><br />
<include mode="instant" src="include.zul" /><br />
</window><br />
</source><br />
<br />
====Auto 模式====<br />
<br />
Auto模式將會挑選最適合inclusion type的模式列入類型。如果inclusion是ZUL檔,即時模式將自動被設定為最合適模式,反之,則為延遲模式。 <br />
下面的程式將為您示範如何完成自動模式設定:<br />
<br />
<source lang="xml"><br />
<window title="demo" border="normal"><br />
<include mode="auto" src="include.zul" /><br />
</window><br />
</source><br />
<br />
====將Auto 模式設為預設值====<br />
<br />
我們建議您在使用include元件時使用自動模式,同時也將自動模式設為預設值。只要將字元集變數加到您的zk.xml設定檔,即可完成。<br />
<br />
以下的XML將示範如何完成這項設定:<br />
<br />
<br />
<source lang="xml"><br />
<library-property><br />
<name>org.zkoss.zul.include.mode</name><br />
<value>auto</value><br />
</library-property><br />
</source><br />
<br />
==新功能介紹==<br />
<br />
===指令碼標籤===<br />
<br />
有些時候,你會需要include 一些JavaScript程式,但希望它是被放在head 標籤裡。我們現已在此版本引入了新的指令標籤,這將讓您能更有效率地使用該指令的指令元件。<br />
<br />
<source lang="xml"><br />
<?script type="text/javascript" src="/a/b.js"?><br />
</source><br />
<br />
===支援Google App Engine===<br />
<br />
ZK 3.6.2現已支援Google App Engine,讓您能輕鬆地在Google雲端上運行ZK應用程式!如欲了解更多詳細的安裝程序,請參閱我們的[http://books.zkoss.org/wiki/ZK_Installation_Guide/Setting_up_Servers/Google_App_Engine 操作方法]。<br />
<br />
===指令初始化===<br />
<br />
使用者現在將能給予初始化指令更有意義參數名字,而不再只是arg0或arg1,而這也將提供開發者一個更全方面的開發環境。<br />
<br />
<source lang="xml"><br />
<?init class="foo.Foo" some="a value" some2="another value"?><br />
</source><br />
<br />
===屬性文件的位置配置===<br />
<br />
ZK 3.6.2現在提供了一個更加方便和靈活的方式,讓使用者能從已知位置來下載i18n property檔案。透過使用library屬性設定,開發者將能夠改變組織文件夾的結構。<br />
<source lang="xml"><br />
<library-property><br />
<name>org.zkoss.util.label.web.location</name><br />
<value>/WEB-INF/i3-label.properties</value><br />
</library-property> <br />
</source><br />
<br />
[[Category:Release]]<br />
[[Category:ZK]]<br />
{{Template:Smalltalk_Footer|<br />
|name=Potix Corporation<br />
}}<br />
<br />
<comment>http://docs.zkoss.org/wiki/New_Features_of_ZK_3.6.2</comment></div>Charhttps://www.zkoss.org/_w/index.php?title=Small_Talks/2009/June/New_Features_of_ZK_3.6.2_TW&diff=15219Small Talks/2009/June/New Features of ZK 3.6.2 TW2010-12-21T02:21:10Z<p>Char: /* 支援Google App Engine */</p>
<hr />
<div>{{Template:Smalltalk_Author|<br />
|author=Timothy Clare, Technology Evangelist, Potix Corporation<br />
|date=June 22, 2009<br />
|version=3.6.2<br />
}}<br />
<br />
<br />
<br />
ZK 最新版本3.6.2 主要重點為效能的提升,您將在各家瀏覽器直接感受到其中的差異,尤其IE6 瀏覽器最為明顯。 <br />
除了在效能方面的進步之外,<br />
相信您也能在此最新版本發現我們新增了許多強大的功能,<br />
同時也修正了48個以上的臭蟲。 <br />
現在就跟著我們一起來看3.6.2 新增了哪些功能吧!<br />
<br />
<br />
<br />
<br />
==效能改善==<br />
<br />
===效能===<br />
<br />
在最新版本裡,我們的效能已有大幅的提升和進步,其中最明顯的即是應用程式在瀏覽器IE6上運行的速度!我們在tabbox 裡測試了約430 個控制項<br />
<br />
以下圖表即為測試結果:<br />
<br />
[[Image:ini_test.png|500px|Test Result]]<br />
[[Image:changetabs_test.png|500px|Test Result]]<br />
<br />
<br />
首先,你會在圖表上注意到,ZK 3.6.2 在所有的測試中都有極為突出的表現!<br />
當執行操作系統模式初始化時,ZK 3.6.2 的速度為3.6.1 的三倍。另外,在初始化預設模式時, ZK 3.6.2 的速度也比 3.6.1 快整整兩倍。 <br />
<br />
不僅如此,在標籤轉換測試中,我們也能在操作系統按鈕模式看到顯著的效能增益:<br />
ZK 3.6.2 的速度為3.6.1的兩倍。而ZK 3.6.2 的預設按鈕模式在轉換標籤時,效能也遠超過ZK3.6.1。<br />
<br />
由測試結果來看,如果您開發的是一個非常需要高效能的應用程式時,我們將建議你使用系統按鈕模式,因為這帶來的效能增益將遠遠超過預設模式。<br />
測試用控制項完整列表如下:<br />
<br />
<br />
{|style="border:1px solid black"<br />
|-<br />
|width="300px" |MenuBar * 1 <br /><br />
Menu * 12 <br /><br />
borderlayout *2 <br /><br />
Tabbox * 1<br /><br />
Tab * 2<br /><br />
Tabpanel * 2<br /><br />
Window * 6<br /><br />
|Vbox * 2<br /><br />
Grid * 2<br /><br />
Listbox * 2<br /><br />
Listitem * 15<br /><br />
Listcell * 100<br /><br />
Label * 100<br /><br />
Button * 100<br /><br />
|}<br />
<br />
===Include模式===<br />
<br />
當我們在ZUL檔案裡使用include元件時,常會出現一些問題,問題通常發生在元件出現之前,我們無法介入元件的生命周期。<br />
而這個問題在ZK 3.6.2以後的版本將不再出現。關鍵在於我們應用了新的模式:include模式。目前共有三種include模式:延遲、即時和自動模式。而3.6.2之前版本中的include 標籤行為和目前的預設模式是相同的,皆為延遲模式。<br />
<br />
====Instant 模式====<br />
<br />
因為使用了Execution.createComponent功能,Instant模式能立即產生頁面,也就是說,因為下了初始化命令,他們可以直接與用戶連結,因此並不會有任何混亂或問題產生。 <br />
以下程式將為您示範如何設定Instant 模式:<br />
<br />
<source lang="xml"><br />
<window title="demo" border="normal"><br />
<include mode="instant" src="include.zul" /><br />
</window><br />
</source><br />
<br />
====Auto 模式====<br />
<br />
Auto模式將會挑選最適合inclusion type的模式列入類型。如果inclusion是ZUL檔,即時模式將自動被設定為最合適模式,反之,則為延遲模式。 <br />
下面的程式將為您示範如何完成自動模式設定:<br />
<br />
<source lang="xml"><br />
<window title="demo" border="normal"><br />
<include mode="auto" src="include.zul" /><br />
</window><br />
</source><br />
<br />
====將Auto 模式設為預設值====<br />
<br />
我們建議您在使用include元件時使用自動模式,同時也將自動模式設為預設值。只要將字元集變數加到您的zk.xml設定檔,即可完成。<br />
<br />
以下的XML將示範如何完成這項設定:<br />
<br />
<br />
<source lang="xml"><br />
<library-property><br />
<name>org.zkoss.zul.include.mode</name><br />
<value>auto</value><br />
</library-property><br />
</source><br />
<br />
==新功能介紹==<br />
<br />
===指令碼標籤===<br />
<br />
有些時候,你會需要include 一些JavaScript程式,但希望它是被放在head 標籤裡。我們現已在此版本引入了新的指令標籤,這將讓您能更有效率地使用該指令的指令元件。<br />
<br />
<source lang="xml"><br />
<?script type="text/javascript" src="/a/b.js"?><br />
</source><br />
<br />
===支援Google App Engine===<br />
<br />
ZK 3.6.2現已支援Google App Engine,讓您能輕鬆地在Google雲端上運行ZK應用程式!如欲了解更多詳細的安裝程序,請參閱我們的[http://books.zkoss.org/wiki/ZK_Installation_Guide/Setting_up_Servers/Google_App_Engine 操作方法]。<br />
<br />
===指令初始化===<br />
<br />
使用者現在將能給予初始化指令更有意義參數名字,而不再只是arg0或arg1,而這也將提供開發者一個更全方面的開發環境。<br />
<br />
<source lang="xml"><br />
<?init class="foo.Foo" some="a value" some2="another value"?><br />
</source><br />
<br />
===屬性文件的位置配置===<br />
<br />
ZK 3.6.2現在提供了一個更加方便和靈活的方式,讓使用者能從已知位置來下載i18n property檔案。透過使用library屬性設定,開發者將能夠改變組織文件夾的結構。<br />
<source lang="xml"><br />
<library-property><br />
<name>org.zkoss.util.label.web.location</name><br />
<value>/WEB-INF/i3-label.properties</value><br />
</library-property> <br />
</source><br />
<br />
[[Category:Release]]<br />
[[Category:ZK]]<br />
{{Template:Smalltalk_Footer|<br />
|name=Potix Corporation<br />
}}<br />
<br />
<comment>http://docs.zkoss.org/wiki/New_Features_of_ZK_3.6.2</comment></div>Charhttps://www.zkoss.org/_w/index.php?title=Small_Talks/2009/June/New_Features_of_ZK_3.6.2&diff=15218Small Talks/2009/June/New Features of ZK 3.6.22010-12-21T02:20:23Z<p>Char: /* Support for Google App Engine */</p>
<hr />
<div>{{Template:Smalltalk_Author|<br />
|author=Timothy Clare, Technology Evangelist, Potix Corporation<br />
|date=June 22, 2009<br />
|version=3.6.2<br />
}}<br />
<br />
<br />
<br />
The main focus of ZK 3.6.2 was improving performance, especially in IE6. In addition to the great strides in performance more powerful features have been introduced and 48 bugs have been fixed!<br />
<br />
The following paragraphs outline just some of the exciting improvements and new features in ZK 3.6.2.<br />
<br />
<br />
<br />
==Improvements==<br />
<br />
===Performance===<br />
<br />
We have made strides to increase the performance, including a significant speed boost in IE6! We conducted tests with approximately 430 controls within a tabbox. <br />
<br />
The graphs below show the results of these tests.<br />
<br />
[[Image:ini_test.png|Test Result]]<br />
[[Image:changetabs_test.png|Test Result]]<br />
<br />
<br />
The first thing you will notice on the graphs is ZK 3.6.2 performed better in all the tests with the greatest performance jump occurring when using default OS mode buttons. When initializing the OS mode buttons ZK 3.6.2 was three times faster than 3.6.1. In addition, when initializing the default button mode, ZK 3.6.2 was twice as fast as 3.6.1. <br />
<br />
When changing tabs, the OS button mode also saw most of the performance gain, with ZK 3.6.2 being twice as fast as 3.6.1. ZK 3.6.2’s default button mode also posted an increase in performance over its’ 3.6.1 counterpart when changing tab.<br />
<br />
It is recommended when creating an application which is reliant on performance that you use the OS button mode as the performance in this mode typically outweighs that of the default mode.<br />
<br />
<br />
<br />
A full list of controls used in the test are included below:<br />
<br />
{|style="border:1px solid black"<br />
|-<br />
|width="300px" |MenuBar * 1 <br /><br />
Menu * 12 <br /><br />
borderlayout *2 <br /><br />
Tabbox * 1<br /><br />
Tab * 2<br /><br />
Tabpanel * 2<br /><br />
Window * 6<br /><br />
|Vbox * 2<br /><br />
Grid * 2<br /><br />
Listbox * 2<br /><br />
Listitem * 15<br /><br />
Listcell * 100<br /><br />
Label * 100<br /><br />
Button * 100<br /><br />
|}<br />
<br />
===Include modes===<br />
<br />
When using the '''include''' component within ZUL files we can experience problems if the included file's components need to be accessed before they have been created and rendered.<br />
<br />
This problem has been solved in ZK 3.6.2 with the introduction of new include modes. There are now three include modes, defer, instant and auto. The behavior of the include tag prior to version 3.6.2 is the same as the default mode, defer. <br />
<br />
====Instant====<br />
<br />
The instant mode allows pages to be created immediately using the Execution.createComponent function, meaning that they are instantly accessible to the user and therefore no confusion or problems arise due to the initialization order.<br />
<br />
The code below demonstrates how to use the instant mode:<br />
<br />
<source lang="xml"><br />
<window title="demo" border="normal"><br />
<include mode="instant" src="include.zul" /><br />
</window><br />
</source><br />
<br />
====Auto====<br />
<br />
The auto mode selects which mode is most suited for the inclusion type. If the inclusion is a ZUL file then the instant mode will be used and if not the defer mode will be.<br />
<br />
The code below demonstrates how to use the auto mode:<br />
<br />
<br />
<source lang="xml"><br />
<window title="demo" border="normal"><br />
<include mode="auto" src="include.zul" /><br />
</window><br />
</source><br />
<br />
====Making auto your default mode====<br />
<br />
We recommend the use of auto mode when using include components and would recommend making auto your default mode. You can set auto mode as default by including a library variable in your zk.xml configuration file. <br />
<br />
The XML below demonstrates how to do this:<br />
<br />
<source lang="xml"><br />
<library-property><br />
<name>org.zkoss.zul.include.mode</name><br />
<value>auto</value><br />
</library-property><br />
</source><br />
<br />
==New features==<br />
<br />
===Script tag===<br />
<br />
Sometimes you need to include javascript code but want it to be included within the head tags. We have introduced a new script tag allowing you to do this in a more efficient way than using the script component.<br />
<br />
<source lang="xml"><br />
<?script type="text/javascript" src="/a/b.js"?><br />
</source><br />
<br />
===Support for Google App Engine===<br />
<br />
ZK 3.6.2 supports Google App Engine, allowing you to run ZK in the Google cloud! For more details on the installation procedure please refer to our [http://books.zkoss.org/wiki/ZK_Installation_Guide/Setting_up_Servers/Google_App_Engine how-to].<br />
<br />
===Initialization directive===<br />
<br />
You now have the ability to give the initialization directive meaningful argument names rather than arg0, arg1, providing more context for the developer.<br />
<br />
<source lang="xml"><br />
<?init class="foo.Foo" some="a value" some2="another value"?><br />
</source><br />
<br />
===Configuring property file locations===<br />
<br />
ZK 3.6.2 now provides a more convenient and flexible way to load i18n property files from provided locations. Hence by using the library-property the developer is able to change the organization of the folder structure.<br />
<br />
<source lang="xml"><br />
<library-property><br />
<name>org.zkoss.util.label.web.location</name><br />
<value>/WEB-INF/i3-label.properties</value><br />
</library-property> <br />
</source><br />
<br />
[[Category:Release]]<br />
[[Category:ZK]]<br />
[[Category:New Features]]<br />
{{Template:Smalltalk_Footer|<br />
|name=Potix Corporation<br />
}}<br />
<br />
<comment>http://docs.zkoss.org/wiki/New_Features_of_ZK_3.6.2</comment></div>Charhttps://www.zkoss.org/_w/index.php?title=Small_Talks/2009/October/ZK_5.0_Component_Imagepicker&diff=15217Small Talks/2009/October/ZK 5.0 Component Imagepicker2010-12-21T02:17:17Z<p>Char: /* Adds the widget definition to zk */</p>
<hr />
<div>{{Template:Smalltalk_Author|<br />
|author=Jimmy Shiau, Engineer, Potix Corporation<br />
|date=October 27, 2009<br />
|version=Applicable to ZK 5.0 and later<br />
}}<br />
<br />
= Introduction =<br />
<br />
When we create an application such as an image manager for a blog we would always provide the user with an easy way to select images and move them from one category to another. We could use components such as checkboxes or radio components for the selection, but that doesn’t provide a very user friendly experience.<br />
In this small talk, I will introduce this new component for ZK 5.<br />
This component is a container in which you can place images. It is then possible to select images by clicking or dragging your mouse just as you would in Windows Explorer. This provides better user functionality and makes it much easier to select the items the user desires.<br />
<br />
= Live Demo =<br />
Let's have a look at the demo of the ZK Imagepicker. <br />
<br />
<gflash width="1200" height="700">Imagepicker.swf</gflash><br />
<br />
The following code fragment demonstrates how to use the Imagepicker component<br />
<source lang="javascript"><br />
<imagepicker itemWidth="100px" itemHeight="100" itemPadding="5" itemMargin="5" ><br />
<image src="/1.jpg" /><br />
<image src="/2.jpg" /> <br />
</imagepicker><br />
</source><br />
<br />
You can place an image into imagepicker tag and set the height and width of it. The result can then be placed into a container such as a window.<br />
<br />
= Component Usage =<br />
<br />
Here is the Imagepicker's attribute specification table: <br />
<br />
{|border="1"<br />
|-<br />
!Attribute||Usage||Default Value<br />
|-<br />
||itemWidth<br />
||Sets the width of the item <br />
||"100" (unit is pixel) <br />
|-<br />
||itemHeight <br />
||Sets the height of the item<br />
||"100" (unit is pixel)<br />
|-<br />
||itemPadding <br />
||Sets the padding of the item <br />
||"5" (unit is pixel)<br />
|-<br />
||itemMargin<br />
||Sets the margin of the item<br />
||"5" (unit is pixel)<br />
|}<br />
<br />
= Event Listeners =<br />
<br />
The Imagepicker component provides one event. This event allows the user to execute code when an item of the Imagepicker is selected:<br />
<br />
#'''onSelect''': The event is triggered when a user selects an item.<br />
<br />
= Behind The Scene: How to Implement a ZK5 component =<br />
<br />
Firstly you can refer to [http://books.zkoss.org/wiki/ZK_Component_Development_Essentials http://books.zkoss.org/wiki/ZK_Component_Development_Essentials] to read about ZK 5’s Basic Concepts.<br />
<br />
=== A component class in Java ===<br />
<br />
The component class must extend from AbstractComponent or one of its derived class. There are several skeletal implementations available and you can choose the appropriate one for your usage. For this component, we will use the XulElement, <br />
<br />
[[Image:Example.jpg]]<br />
<br />
You can create a java class extends XulElement, then provide getter and setter methods for all attributes. The setter methods must be updated using '''smartUpdate'''. <br />
<br />
<source lang="java"><br />
public String getItemWidth() {<br />
return _itemwd;<br />
}<br />
<br />
public void setItemWidth(String itemwd) throws WrongValueException {<br />
if (itemwd != null && itemwd.length() == 0)<br />
itemwd = null;<br />
if (!Objects.equals(_itemwd, itemwd)) {<br />
_itemwd = itemwd; <br />
smartUpdate("itemWidth", itemwd);<br />
}<br />
}<br />
</source><br />
<br />
Then we need to override the functions '''beforeChildAdded''', '''service''', '''renderProperties'''.<br />
<br />
#'''beforeChildAdded''': used to limit the type of the child.<br />
#'''service''': Define what to do on server side when event triggered, like “onSelect”, and you must register “onSelect” event.<br />
#'''renderProperties''': used to render all attribute<br />
<br />
<source lang="java"><br />
public void beforeChildAdded(Component newChild, Component refChild) {<br />
if (!(newChild instanceof Image)) <br />
throw new UiException("Unsupported child for Datapicker: "+newChild); <br />
super.beforeChildAdded(newChild, refChild);<br />
}<br />
<br />
static { <br />
addClientEvent(Imagepicker.class, Events.ON_SELECT, 0);<br />
} <br />
<br />
public void service(org.zkoss.zk.au.AuRequest request, boolean everError) {<br />
final String cmd = request.getCommand();<br />
if (cmd.equals(Events.ON_SELECT)) {<br />
Events.postEvent(SelectEvent.getSelectEvent(request)); <br />
} else {<br />
super.service(request, everError);<br />
}<br />
}<br />
<br />
protected void renderProperties(org.zkoss.zk.ui.sys.ContentRenderer renderer) throws IOException {<br />
super.renderProperties(renderer);<br />
if (!"100".equals(_itemwd))<br />
render(renderer, "itemWidth", _itemwd);<br />
if (!"100".equals(_itemhgh))<br />
render(renderer, "itemHeight", _itemhgh);<br />
if (!"5".equals(_itemPadding))<br />
render(renderer, "itemPadding", _itemPadding);<br />
if (!"5".equals(_itemMargin))<br />
render(renderer, "itemMargin", _itemMargin); <br />
}<br />
</source><br />
<br />
=== Why renderProperties and smartUpdate? ===<br />
<br />
A common question is why <code>renderProperties</code> (and <code>redraw</code>) are required to render <code>value</code> again when we notify the client with <code>smartUpdate</code> in <code>setValue</code>?<br />
<br />
The simple answer is <code>renderProperties</code> is used to send all properties at once when a component is attached to the page at the first time. On the other hand, <code>smartUpdate</code> is used to send a property that was modified after the initial attachment. <br />
<br />
=== A widget class in JavaScript ===<br />
<br />
You can create javascript which extends zul.Widget, then define a setter and getter of all attributes by '''$define'''.<br />
<br />
The '''$define''' function is a util function to declare set/get/is functions automatically<br />
<br />
All attributes within the '''$define''' function will have set/get/is functions created automatically for them by zk.js<br />
<br />
<source lang="javascript"><br />
imagepicker.Imagepicker = zk.$extends(zul.Widget, {<br />
<br />
$define: {<br />
itemWidth : _zkf = function() {<br />
this.syncAttr();<br />
},<br />
itemHeight : _zkf,<br />
itemPadding : _zkf,<br />
itemMargin : _zkf<br />
},<br />
<br />
syncAttr: function() {<br />
if (!this.$n()) return; <br />
<br />
//do realign<br />
<br />
}, <br />
</source><br />
*_zkf is a temporary variable to cache a function<br />
The function within $define will call syncAttr() to realign all images when some images have their values set.<br />
<br />
The four class attributes will also call the same method (syncAttr()) after an attribute has a new value set.<br />
<br />
You can then override the '''doClick_''', '''doMouseOver_''', and '''doMouseOut_''' functions, to change the CSS of the target (div) when an event is triggered, <br />
<br />
#'''doClick_''' , '''doMouseOver_''' , '''doMouseOut_''': you can receive the clicked target by event.Target, or domTarget by event.domTarget, and change target’s css, then the function must be call this.$supers('doClick_', arguments) at last, doMouseOver_ and doMouseOut_ are the same with pervious one.<br />
<br />
<source lang="javascript"><br />
doClick_ : function(evt) {<br />
var target = evt.domTarget;<br />
//do xxx<br />
this.$supers('doClick_', arguments);<br />
}, <br />
doMouseOver_ : function(evt) {<br />
var target = evt.domTarget;<br />
//do xxx<br />
this.$supers('doMouseOver_', arguments);<br />
}, <br />
doMouseOut_ : function(evt) {<br />
var target = evt.domTarget;<br />
//do xxx<br />
this.$supers('doMouseOut_', arguments);<br />
}, <br />
</source><br />
<br />
Regarding the Widget event, you can refer to [http://docs.zkoss.org/wiki/Zk.Event Zk.Event]<br />
<br />
After this we create a div as a selector, and monitor all edges of the selector, check the position of all items. If the edge of the selector touches any items, those items will be selected. We use this.fire(‘onSelect’) to notify the server side when an image is selected.<br />
<br />
=== A JavaScript method to generate the DOM content (so-called mold) === <br />
<br />
The DOM content of a widget is called a mold. A widget can have several molds and each mold should be placed in an independent JavaScript file.<br />
<br />
You can refer to [http://books.zkoss.org/wiki/ZK_Component_Development_Essentials/Creating_a_simple_ZK_Component/Rendering_Widgets/Implementing_Molds SimpleLabel:Widgets Mold] for more information on widget molds.<br />
<br />
This component is created by div tags. We use div tags to define the container area, then enclose all children because we want the div to “frame” each image, and every div will change color (modify css) when some specific event is triggered.<br />
<br />
<source lang="javascript"><br />
<br />
function (out) {<br />
out.push('<div', this.domAttrs_(), '><div id="',<br />
this.uuid, '-cave"', 'class="', this.getZclass(),'-inner">'); <br />
for (var w = this.firstChild; w; w = w.nextSibling){<br />
out.push('<div class="', this.getZclass(),'-item">');<br />
w.redraw(out);<br />
out.push('</div>');<br />
}<br />
out.push('</div></div>');<br />
}<br />
<br />
</source><br />
<br />
'''domAttrs_''' is a (protected) method inherited from zk.Widget. It returns all HTML attributes required, such as style, id and so on. You can override it if you want. <br />
<br />
<br />
At previous widget class in JavaScript, it needs to override '''insertChildHTML_''' and '''removeChildHTML_''', used to enclose child by div tag, and remove div when child be remove,<br />
<br />
<source lang="javascript"><br />
insertChildHTML_: function (child, before, desktop) {<br />
//enclose child by div<br />
}, <br />
removeChildHTML_: function (child, prevsib) {<br />
//distory div after it's child was be removed<br />
},<br />
</source><br />
<br />
=== Add the component definition to lang-addon.xml (or lang.xml) (so-called Language Addon) ===<br />
<br />
You can refer to [http://books.zkoss.org/wiki/ZK_Component_Development_Essentials/Creating_the_Configuration_Files/The_language-addon SimpleLabel:Language Addon] define your lang-addon.xml file.<br />
<br />
=== Adds the widget definition to zk ===<br />
<br />
Create a zk.wpd file to define your widget’s package. You can refer to [http://books.zkoss.org/wiki/ZK_Component_Development_Essentials/Creating_the_Configuration_Files/The_Widget_Package_Descriptor SimpleLabel:Widget Package Descriptor] for more information.<br />
<br />
=== Debugging Setting ===<br />
<br />
To debug your component you should change your settings in your zk.xml file to those displayed below:<br />
<br />
<source lang="javascript"><br />
<client-config><br />
<debug-js>true</debug-js><br />
</client-config><br />
<br />
<library-property><br />
<name>org.zkoss.web.classWebResource.cache</name><br />
<value>false</value><br />
</library-property><br />
</source><br />
<br />
'''debug-js:'''<br />
<br />
The ''debug-js'' attribute specifies whether to turn on the debugging of JavaScript files. By default, it is false and the compressed version of JavaScript files will be loaded which are hard to read and debug, though the footprint is much smaller.<br />
<br />
To debug JavaScript files, you can set the attribute to true and the original uncompressed JavaScript files will be loaded instead.<br />
<br />
'''org.zkoss.web.classWebResource.cache:'''<br />
<br />
ZK, by default, allows the browser to cache static resources like images and JavaScript files. When you are developing a component, it is better to turn it off.<br />
<br />
=Download=<br />
<br />
* Download <tracker url="https://sourceforge.net/projects/zkforge/files/Small%20Talks/ZK%205%20Component%20Imagepicker/Imagepicker.war/download" > imagepickerApp</tracker> war file or <tracker url="https://zkforge.svn.sourceforge.net/svnroot/zkforge/trunk/dist/lib/imagepicker.jar" > imagepicker</tracker> jar file<br />
*SVN: [https://zkforge.svn.sourceforge.net/svnroot/zkforge/trunk/imagepicker https://zkforge.svn.sourceforge.net/svnroot/zkforge/trunk/imagepicker]<br />
<br />
= Summary =<br />
<br />
The Imagepicker is an image container, creating a transparent frame for image selection. The component not only provides a click action for selecting images but a lasso effect similar to Windows Explorer, making it easy to use. <br />
<br />
ZK 5 component operations can be split between the server-side and/or the client-side. The java class handles the server-side’s component tree and the javascript widget class handles the widget tree of client side. The widget tree will be create a dom tree in the browser and the component tree updates the widget tree by calling the methods renderProperties() or smartUpdate().<br />
<br />
<comment>http://docs.zkoss.org/wiki/ZK_5.0_Component_Imagepicker</comment><br />
<br />
[[Category:ZK]]<br />
[[Category:New Features]]<br />
{{Template:Smalltalk_Footer|<br />
|name=Potix Corporation<br />
}}</div>Charhttps://www.zkoss.org/_w/index.php?title=Small_Talks/2009/October/ZK_5.0_Component_Imagepicker&diff=15216Small Talks/2009/October/ZK 5.0 Component Imagepicker2010-12-21T02:16:46Z<p>Char: /* Add the component definition to lang-addon.xml (or lang.xml) (so-called Language Addon) */</p>
<hr />
<div>{{Template:Smalltalk_Author|<br />
|author=Jimmy Shiau, Engineer, Potix Corporation<br />
|date=October 27, 2009<br />
|version=Applicable to ZK 5.0 and later<br />
}}<br />
<br />
= Introduction =<br />
<br />
When we create an application such as an image manager for a blog we would always provide the user with an easy way to select images and move them from one category to another. We could use components such as checkboxes or radio components for the selection, but that doesn’t provide a very user friendly experience.<br />
In this small talk, I will introduce this new component for ZK 5.<br />
This component is a container in which you can place images. It is then possible to select images by clicking or dragging your mouse just as you would in Windows Explorer. This provides better user functionality and makes it much easier to select the items the user desires.<br />
<br />
= Live Demo =<br />
Let's have a look at the demo of the ZK Imagepicker. <br />
<br />
<gflash width="1200" height="700">Imagepicker.swf</gflash><br />
<br />
The following code fragment demonstrates how to use the Imagepicker component<br />
<source lang="javascript"><br />
<imagepicker itemWidth="100px" itemHeight="100" itemPadding="5" itemMargin="5" ><br />
<image src="/1.jpg" /><br />
<image src="/2.jpg" /> <br />
</imagepicker><br />
</source><br />
<br />
You can place an image into imagepicker tag and set the height and width of it. The result can then be placed into a container such as a window.<br />
<br />
= Component Usage =<br />
<br />
Here is the Imagepicker's attribute specification table: <br />
<br />
{|border="1"<br />
|-<br />
!Attribute||Usage||Default Value<br />
|-<br />
||itemWidth<br />
||Sets the width of the item <br />
||"100" (unit is pixel) <br />
|-<br />
||itemHeight <br />
||Sets the height of the item<br />
||"100" (unit is pixel)<br />
|-<br />
||itemPadding <br />
||Sets the padding of the item <br />
||"5" (unit is pixel)<br />
|-<br />
||itemMargin<br />
||Sets the margin of the item<br />
||"5" (unit is pixel)<br />
|}<br />
<br />
= Event Listeners =<br />
<br />
The Imagepicker component provides one event. This event allows the user to execute code when an item of the Imagepicker is selected:<br />
<br />
#'''onSelect''': The event is triggered when a user selects an item.<br />
<br />
= Behind The Scene: How to Implement a ZK5 component =<br />
<br />
Firstly you can refer to [http://books.zkoss.org/wiki/ZK_Component_Development_Essentials http://books.zkoss.org/wiki/ZK_Component_Development_Essentials] to read about ZK 5’s Basic Concepts.<br />
<br />
=== A component class in Java ===<br />
<br />
The component class must extend from AbstractComponent or one of its derived class. There are several skeletal implementations available and you can choose the appropriate one for your usage. For this component, we will use the XulElement, <br />
<br />
[[Image:Example.jpg]]<br />
<br />
You can create a java class extends XulElement, then provide getter and setter methods for all attributes. The setter methods must be updated using '''smartUpdate'''. <br />
<br />
<source lang="java"><br />
public String getItemWidth() {<br />
return _itemwd;<br />
}<br />
<br />
public void setItemWidth(String itemwd) throws WrongValueException {<br />
if (itemwd != null && itemwd.length() == 0)<br />
itemwd = null;<br />
if (!Objects.equals(_itemwd, itemwd)) {<br />
_itemwd = itemwd; <br />
smartUpdate("itemWidth", itemwd);<br />
}<br />
}<br />
</source><br />
<br />
Then we need to override the functions '''beforeChildAdded''', '''service''', '''renderProperties'''.<br />
<br />
#'''beforeChildAdded''': used to limit the type of the child.<br />
#'''service''': Define what to do on server side when event triggered, like “onSelect”, and you must register “onSelect” event.<br />
#'''renderProperties''': used to render all attribute<br />
<br />
<source lang="java"><br />
public void beforeChildAdded(Component newChild, Component refChild) {<br />
if (!(newChild instanceof Image)) <br />
throw new UiException("Unsupported child for Datapicker: "+newChild); <br />
super.beforeChildAdded(newChild, refChild);<br />
}<br />
<br />
static { <br />
addClientEvent(Imagepicker.class, Events.ON_SELECT, 0);<br />
} <br />
<br />
public void service(org.zkoss.zk.au.AuRequest request, boolean everError) {<br />
final String cmd = request.getCommand();<br />
if (cmd.equals(Events.ON_SELECT)) {<br />
Events.postEvent(SelectEvent.getSelectEvent(request)); <br />
} else {<br />
super.service(request, everError);<br />
}<br />
}<br />
<br />
protected void renderProperties(org.zkoss.zk.ui.sys.ContentRenderer renderer) throws IOException {<br />
super.renderProperties(renderer);<br />
if (!"100".equals(_itemwd))<br />
render(renderer, "itemWidth", _itemwd);<br />
if (!"100".equals(_itemhgh))<br />
render(renderer, "itemHeight", _itemhgh);<br />
if (!"5".equals(_itemPadding))<br />
render(renderer, "itemPadding", _itemPadding);<br />
if (!"5".equals(_itemMargin))<br />
render(renderer, "itemMargin", _itemMargin); <br />
}<br />
</source><br />
<br />
=== Why renderProperties and smartUpdate? ===<br />
<br />
A common question is why <code>renderProperties</code> (and <code>redraw</code>) are required to render <code>value</code> again when we notify the client with <code>smartUpdate</code> in <code>setValue</code>?<br />
<br />
The simple answer is <code>renderProperties</code> is used to send all properties at once when a component is attached to the page at the first time. On the other hand, <code>smartUpdate</code> is used to send a property that was modified after the initial attachment. <br />
<br />
=== A widget class in JavaScript ===<br />
<br />
You can create javascript which extends zul.Widget, then define a setter and getter of all attributes by '''$define'''.<br />
<br />
The '''$define''' function is a util function to declare set/get/is functions automatically<br />
<br />
All attributes within the '''$define''' function will have set/get/is functions created automatically for them by zk.js<br />
<br />
<source lang="javascript"><br />
imagepicker.Imagepicker = zk.$extends(zul.Widget, {<br />
<br />
$define: {<br />
itemWidth : _zkf = function() {<br />
this.syncAttr();<br />
},<br />
itemHeight : _zkf,<br />
itemPadding : _zkf,<br />
itemMargin : _zkf<br />
},<br />
<br />
syncAttr: function() {<br />
if (!this.$n()) return; <br />
<br />
//do realign<br />
<br />
}, <br />
</source><br />
*_zkf is a temporary variable to cache a function<br />
The function within $define will call syncAttr() to realign all images when some images have their values set.<br />
<br />
The four class attributes will also call the same method (syncAttr()) after an attribute has a new value set.<br />
<br />
You can then override the '''doClick_''', '''doMouseOver_''', and '''doMouseOut_''' functions, to change the CSS of the target (div) when an event is triggered, <br />
<br />
#'''doClick_''' , '''doMouseOver_''' , '''doMouseOut_''': you can receive the clicked target by event.Target, or domTarget by event.domTarget, and change target’s css, then the function must be call this.$supers('doClick_', arguments) at last, doMouseOver_ and doMouseOut_ are the same with pervious one.<br />
<br />
<source lang="javascript"><br />
doClick_ : function(evt) {<br />
var target = evt.domTarget;<br />
//do xxx<br />
this.$supers('doClick_', arguments);<br />
}, <br />
doMouseOver_ : function(evt) {<br />
var target = evt.domTarget;<br />
//do xxx<br />
this.$supers('doMouseOver_', arguments);<br />
}, <br />
doMouseOut_ : function(evt) {<br />
var target = evt.domTarget;<br />
//do xxx<br />
this.$supers('doMouseOut_', arguments);<br />
}, <br />
</source><br />
<br />
Regarding the Widget event, you can refer to [http://docs.zkoss.org/wiki/Zk.Event Zk.Event]<br />
<br />
After this we create a div as a selector, and monitor all edges of the selector, check the position of all items. If the edge of the selector touches any items, those items will be selected. We use this.fire(‘onSelect’) to notify the server side when an image is selected.<br />
<br />
=== A JavaScript method to generate the DOM content (so-called mold) === <br />
<br />
The DOM content of a widget is called a mold. A widget can have several molds and each mold should be placed in an independent JavaScript file.<br />
<br />
You can refer to [http://books.zkoss.org/wiki/ZK_Component_Development_Essentials/Creating_a_simple_ZK_Component/Rendering_Widgets/Implementing_Molds SimpleLabel:Widgets Mold] for more information on widget molds.<br />
<br />
This component is created by div tags. We use div tags to define the container area, then enclose all children because we want the div to “frame” each image, and every div will change color (modify css) when some specific event is triggered.<br />
<br />
<source lang="javascript"><br />
<br />
function (out) {<br />
out.push('<div', this.domAttrs_(), '><div id="',<br />
this.uuid, '-cave"', 'class="', this.getZclass(),'-inner">'); <br />
for (var w = this.firstChild; w; w = w.nextSibling){<br />
out.push('<div class="', this.getZclass(),'-item">');<br />
w.redraw(out);<br />
out.push('</div>');<br />
}<br />
out.push('</div></div>');<br />
}<br />
<br />
</source><br />
<br />
'''domAttrs_''' is a (protected) method inherited from zk.Widget. It returns all HTML attributes required, such as style, id and so on. You can override it if you want. <br />
<br />
<br />
At previous widget class in JavaScript, it needs to override '''insertChildHTML_''' and '''removeChildHTML_''', used to enclose child by div tag, and remove div when child be remove,<br />
<br />
<source lang="javascript"><br />
insertChildHTML_: function (child, before, desktop) {<br />
//enclose child by div<br />
}, <br />
removeChildHTML_: function (child, prevsib) {<br />
//distory div after it's child was be removed<br />
},<br />
</source><br />
<br />
=== Add the component definition to lang-addon.xml (or lang.xml) (so-called Language Addon) ===<br />
<br />
You can refer to [http://books.zkoss.org/wiki/ZK_Component_Development_Essentials/Creating_the_Configuration_Files/The_language-addon SimpleLabel:Language Addon] define your lang-addon.xml file.<br />
<br />
=== Adds the widget definition to zk ===<br />
<br />
Create a zk.wpd file to define your widget’s package. You can refer to [http://books.zkoss.org/wiki/ZK_Component_Development_Essentials/Creating_the_Configuration_Files/The_Widget_Package_Descriptor SimpleLabel:_Widget_Package_Descriptor] for more information.<br />
<br />
=== Debugging Setting ===<br />
<br />
To debug your component you should change your settings in your zk.xml file to those displayed below:<br />
<br />
<source lang="javascript"><br />
<client-config><br />
<debug-js>true</debug-js><br />
</client-config><br />
<br />
<library-property><br />
<name>org.zkoss.web.classWebResource.cache</name><br />
<value>false</value><br />
</library-property><br />
</source><br />
<br />
'''debug-js:'''<br />
<br />
The ''debug-js'' attribute specifies whether to turn on the debugging of JavaScript files. By default, it is false and the compressed version of JavaScript files will be loaded which are hard to read and debug, though the footprint is much smaller.<br />
<br />
To debug JavaScript files, you can set the attribute to true and the original uncompressed JavaScript files will be loaded instead.<br />
<br />
'''org.zkoss.web.classWebResource.cache:'''<br />
<br />
ZK, by default, allows the browser to cache static resources like images and JavaScript files. When you are developing a component, it is better to turn it off.<br />
<br />
=Download=<br />
<br />
* Download <tracker url="https://sourceforge.net/projects/zkforge/files/Small%20Talks/ZK%205%20Component%20Imagepicker/Imagepicker.war/download" > imagepickerApp</tracker> war file or <tracker url="https://zkforge.svn.sourceforge.net/svnroot/zkforge/trunk/dist/lib/imagepicker.jar" > imagepicker</tracker> jar file<br />
*SVN: [https://zkforge.svn.sourceforge.net/svnroot/zkforge/trunk/imagepicker https://zkforge.svn.sourceforge.net/svnroot/zkforge/trunk/imagepicker]<br />
<br />
= Summary =<br />
<br />
The Imagepicker is an image container, creating a transparent frame for image selection. The component not only provides a click action for selecting images but a lasso effect similar to Windows Explorer, making it easy to use. <br />
<br />
ZK 5 component operations can be split between the server-side and/or the client-side. The java class handles the server-side’s component tree and the javascript widget class handles the widget tree of client side. The widget tree will be create a dom tree in the browser and the component tree updates the widget tree by calling the methods renderProperties() or smartUpdate().<br />
<br />
<comment>http://docs.zkoss.org/wiki/ZK_5.0_Component_Imagepicker</comment><br />
<br />
[[Category:ZK]]<br />
[[Category:New Features]]<br />
{{Template:Smalltalk_Footer|<br />
|name=Potix Corporation<br />
}}</div>Charhttps://www.zkoss.org/_w/index.php?title=Small_Talks/2009/October/ZK_5.0_Component_Imagepicker&diff=15215Small Talks/2009/October/ZK 5.0 Component Imagepicker2010-12-21T02:16:10Z<p>Char: /* A JavaScript method to generate the DOM content (so-called mold) */</p>
<hr />
<div>{{Template:Smalltalk_Author|<br />
|author=Jimmy Shiau, Engineer, Potix Corporation<br />
|date=October 27, 2009<br />
|version=Applicable to ZK 5.0 and later<br />
}}<br />
<br />
= Introduction =<br />
<br />
When we create an application such as an image manager for a blog we would always provide the user with an easy way to select images and move them from one category to another. We could use components such as checkboxes or radio components for the selection, but that doesn’t provide a very user friendly experience.<br />
In this small talk, I will introduce this new component for ZK 5.<br />
This component is a container in which you can place images. It is then possible to select images by clicking or dragging your mouse just as you would in Windows Explorer. This provides better user functionality and makes it much easier to select the items the user desires.<br />
<br />
= Live Demo =<br />
Let's have a look at the demo of the ZK Imagepicker. <br />
<br />
<gflash width="1200" height="700">Imagepicker.swf</gflash><br />
<br />
The following code fragment demonstrates how to use the Imagepicker component<br />
<source lang="javascript"><br />
<imagepicker itemWidth="100px" itemHeight="100" itemPadding="5" itemMargin="5" ><br />
<image src="/1.jpg" /><br />
<image src="/2.jpg" /> <br />
</imagepicker><br />
</source><br />
<br />
You can place an image into imagepicker tag and set the height and width of it. The result can then be placed into a container such as a window.<br />
<br />
= Component Usage =<br />
<br />
Here is the Imagepicker's attribute specification table: <br />
<br />
{|border="1"<br />
|-<br />
!Attribute||Usage||Default Value<br />
|-<br />
||itemWidth<br />
||Sets the width of the item <br />
||"100" (unit is pixel) <br />
|-<br />
||itemHeight <br />
||Sets the height of the item<br />
||"100" (unit is pixel)<br />
|-<br />
||itemPadding <br />
||Sets the padding of the item <br />
||"5" (unit is pixel)<br />
|-<br />
||itemMargin<br />
||Sets the margin of the item<br />
||"5" (unit is pixel)<br />
|}<br />
<br />
= Event Listeners =<br />
<br />
The Imagepicker component provides one event. This event allows the user to execute code when an item of the Imagepicker is selected:<br />
<br />
#'''onSelect''': The event is triggered when a user selects an item.<br />
<br />
= Behind The Scene: How to Implement a ZK5 component =<br />
<br />
Firstly you can refer to [http://books.zkoss.org/wiki/ZK_Component_Development_Essentials http://books.zkoss.org/wiki/ZK_Component_Development_Essentials] to read about ZK 5’s Basic Concepts.<br />
<br />
=== A component class in Java ===<br />
<br />
The component class must extend from AbstractComponent or one of its derived class. There are several skeletal implementations available and you can choose the appropriate one for your usage. For this component, we will use the XulElement, <br />
<br />
[[Image:Example.jpg]]<br />
<br />
You can create a java class extends XulElement, then provide getter and setter methods for all attributes. The setter methods must be updated using '''smartUpdate'''. <br />
<br />
<source lang="java"><br />
public String getItemWidth() {<br />
return _itemwd;<br />
}<br />
<br />
public void setItemWidth(String itemwd) throws WrongValueException {<br />
if (itemwd != null && itemwd.length() == 0)<br />
itemwd = null;<br />
if (!Objects.equals(_itemwd, itemwd)) {<br />
_itemwd = itemwd; <br />
smartUpdate("itemWidth", itemwd);<br />
}<br />
}<br />
</source><br />
<br />
Then we need to override the functions '''beforeChildAdded''', '''service''', '''renderProperties'''.<br />
<br />
#'''beforeChildAdded''': used to limit the type of the child.<br />
#'''service''': Define what to do on server side when event triggered, like “onSelect”, and you must register “onSelect” event.<br />
#'''renderProperties''': used to render all attribute<br />
<br />
<source lang="java"><br />
public void beforeChildAdded(Component newChild, Component refChild) {<br />
if (!(newChild instanceof Image)) <br />
throw new UiException("Unsupported child for Datapicker: "+newChild); <br />
super.beforeChildAdded(newChild, refChild);<br />
}<br />
<br />
static { <br />
addClientEvent(Imagepicker.class, Events.ON_SELECT, 0);<br />
} <br />
<br />
public void service(org.zkoss.zk.au.AuRequest request, boolean everError) {<br />
final String cmd = request.getCommand();<br />
if (cmd.equals(Events.ON_SELECT)) {<br />
Events.postEvent(SelectEvent.getSelectEvent(request)); <br />
} else {<br />
super.service(request, everError);<br />
}<br />
}<br />
<br />
protected void renderProperties(org.zkoss.zk.ui.sys.ContentRenderer renderer) throws IOException {<br />
super.renderProperties(renderer);<br />
if (!"100".equals(_itemwd))<br />
render(renderer, "itemWidth", _itemwd);<br />
if (!"100".equals(_itemhgh))<br />
render(renderer, "itemHeight", _itemhgh);<br />
if (!"5".equals(_itemPadding))<br />
render(renderer, "itemPadding", _itemPadding);<br />
if (!"5".equals(_itemMargin))<br />
render(renderer, "itemMargin", _itemMargin); <br />
}<br />
</source><br />
<br />
=== Why renderProperties and smartUpdate? ===<br />
<br />
A common question is why <code>renderProperties</code> (and <code>redraw</code>) are required to render <code>value</code> again when we notify the client with <code>smartUpdate</code> in <code>setValue</code>?<br />
<br />
The simple answer is <code>renderProperties</code> is used to send all properties at once when a component is attached to the page at the first time. On the other hand, <code>smartUpdate</code> is used to send a property that was modified after the initial attachment. <br />
<br />
=== A widget class in JavaScript ===<br />
<br />
You can create javascript which extends zul.Widget, then define a setter and getter of all attributes by '''$define'''.<br />
<br />
The '''$define''' function is a util function to declare set/get/is functions automatically<br />
<br />
All attributes within the '''$define''' function will have set/get/is functions created automatically for them by zk.js<br />
<br />
<source lang="javascript"><br />
imagepicker.Imagepicker = zk.$extends(zul.Widget, {<br />
<br />
$define: {<br />
itemWidth : _zkf = function() {<br />
this.syncAttr();<br />
},<br />
itemHeight : _zkf,<br />
itemPadding : _zkf,<br />
itemMargin : _zkf<br />
},<br />
<br />
syncAttr: function() {<br />
if (!this.$n()) return; <br />
<br />
//do realign<br />
<br />
}, <br />
</source><br />
*_zkf is a temporary variable to cache a function<br />
The function within $define will call syncAttr() to realign all images when some images have their values set.<br />
<br />
The four class attributes will also call the same method (syncAttr()) after an attribute has a new value set.<br />
<br />
You can then override the '''doClick_''', '''doMouseOver_''', and '''doMouseOut_''' functions, to change the CSS of the target (div) when an event is triggered, <br />
<br />
#'''doClick_''' , '''doMouseOver_''' , '''doMouseOut_''': you can receive the clicked target by event.Target, or domTarget by event.domTarget, and change target’s css, then the function must be call this.$supers('doClick_', arguments) at last, doMouseOver_ and doMouseOut_ are the same with pervious one.<br />
<br />
<source lang="javascript"><br />
doClick_ : function(evt) {<br />
var target = evt.domTarget;<br />
//do xxx<br />
this.$supers('doClick_', arguments);<br />
}, <br />
doMouseOver_ : function(evt) {<br />
var target = evt.domTarget;<br />
//do xxx<br />
this.$supers('doMouseOver_', arguments);<br />
}, <br />
doMouseOut_ : function(evt) {<br />
var target = evt.domTarget;<br />
//do xxx<br />
this.$supers('doMouseOut_', arguments);<br />
}, <br />
</source><br />
<br />
Regarding the Widget event, you can refer to [http://docs.zkoss.org/wiki/Zk.Event Zk.Event]<br />
<br />
After this we create a div as a selector, and monitor all edges of the selector, check the position of all items. If the edge of the selector touches any items, those items will be selected. We use this.fire(‘onSelect’) to notify the server side when an image is selected.<br />
<br />
=== A JavaScript method to generate the DOM content (so-called mold) === <br />
<br />
The DOM content of a widget is called a mold. A widget can have several molds and each mold should be placed in an independent JavaScript file.<br />
<br />
You can refer to [http://books.zkoss.org/wiki/ZK_Component_Development_Essentials/Creating_a_simple_ZK_Component/Rendering_Widgets/Implementing_Molds SimpleLabel:Widgets Mold] for more information on widget molds.<br />
<br />
This component is created by div tags. We use div tags to define the container area, then enclose all children because we want the div to “frame” each image, and every div will change color (modify css) when some specific event is triggered.<br />
<br />
<source lang="javascript"><br />
<br />
function (out) {<br />
out.push('<div', this.domAttrs_(), '><div id="',<br />
this.uuid, '-cave"', 'class="', this.getZclass(),'-inner">'); <br />
for (var w = this.firstChild; w; w = w.nextSibling){<br />
out.push('<div class="', this.getZclass(),'-item">');<br />
w.redraw(out);<br />
out.push('</div>');<br />
}<br />
out.push('</div></div>');<br />
}<br />
<br />
</source><br />
<br />
'''domAttrs_''' is a (protected) method inherited from zk.Widget. It returns all HTML attributes required, such as style, id and so on. You can override it if you want. <br />
<br />
<br />
At previous widget class in JavaScript, it needs to override '''insertChildHTML_''' and '''removeChildHTML_''', used to enclose child by div tag, and remove div when child be remove,<br />
<br />
<source lang="javascript"><br />
insertChildHTML_: function (child, before, desktop) {<br />
//enclose child by div<br />
}, <br />
removeChildHTML_: function (child, prevsib) {<br />
//distory div after it's child was be removed<br />
},<br />
</source><br />
<br />
=== Add the component definition to lang-addon.xml (or lang.xml) (so-called Language Addon) ===<br />
<br />
You can refer to [http://books.zkoss.org/wiki/ZK_Component_Development_Essentials/Creating_the_Configuration_Files/The_language-addon SimpleLabel:_Language_Addon] define your lang-addon.xml file.<br />
<br />
=== Adds the widget definition to zk ===<br />
<br />
Create a zk.wpd file to define your widget’s package. You can refer to [http://books.zkoss.org/wiki/ZK_Component_Development_Essentials/Creating_the_Configuration_Files/The_Widget_Package_Descriptor SimpleLabel:_Widget_Package_Descriptor] for more information.<br />
<br />
=== Debugging Setting ===<br />
<br />
To debug your component you should change your settings in your zk.xml file to those displayed below:<br />
<br />
<source lang="javascript"><br />
<client-config><br />
<debug-js>true</debug-js><br />
</client-config><br />
<br />
<library-property><br />
<name>org.zkoss.web.classWebResource.cache</name><br />
<value>false</value><br />
</library-property><br />
</source><br />
<br />
'''debug-js:'''<br />
<br />
The ''debug-js'' attribute specifies whether to turn on the debugging of JavaScript files. By default, it is false and the compressed version of JavaScript files will be loaded which are hard to read and debug, though the footprint is much smaller.<br />
<br />
To debug JavaScript files, you can set the attribute to true and the original uncompressed JavaScript files will be loaded instead.<br />
<br />
'''org.zkoss.web.classWebResource.cache:'''<br />
<br />
ZK, by default, allows the browser to cache static resources like images and JavaScript files. When you are developing a component, it is better to turn it off.<br />
<br />
=Download=<br />
<br />
* Download <tracker url="https://sourceforge.net/projects/zkforge/files/Small%20Talks/ZK%205%20Component%20Imagepicker/Imagepicker.war/download" > imagepickerApp</tracker> war file or <tracker url="https://zkforge.svn.sourceforge.net/svnroot/zkforge/trunk/dist/lib/imagepicker.jar" > imagepicker</tracker> jar file<br />
*SVN: [https://zkforge.svn.sourceforge.net/svnroot/zkforge/trunk/imagepicker https://zkforge.svn.sourceforge.net/svnroot/zkforge/trunk/imagepicker]<br />
<br />
= Summary =<br />
<br />
The Imagepicker is an image container, creating a transparent frame for image selection. The component not only provides a click action for selecting images but a lasso effect similar to Windows Explorer, making it easy to use. <br />
<br />
ZK 5 component operations can be split between the server-side and/or the client-side. The java class handles the server-side’s component tree and the javascript widget class handles the widget tree of client side. The widget tree will be create a dom tree in the browser and the component tree updates the widget tree by calling the methods renderProperties() or smartUpdate().<br />
<br />
<comment>http://docs.zkoss.org/wiki/ZK_5.0_Component_Imagepicker</comment><br />
<br />
[[Category:ZK]]<br />
[[Category:New Features]]<br />
{{Template:Smalltalk_Footer|<br />
|name=Potix Corporation<br />
}}</div>Charhttps://www.zkoss.org/_w/index.php?title=Small_Talks/2009/October/ZK_5.0_Component_Imagepicker&diff=15214Small Talks/2009/October/ZK 5.0 Component Imagepicker2010-12-21T02:11:32Z<p>Char: /* Adds the widget definition to zk */</p>
<hr />
<div>{{Template:Smalltalk_Author|<br />
|author=Jimmy Shiau, Engineer, Potix Corporation<br />
|date=October 27, 2009<br />
|version=Applicable to ZK 5.0 and later<br />
}}<br />
<br />
= Introduction =<br />
<br />
When we create an application such as an image manager for a blog we would always provide the user with an easy way to select images and move them from one category to another. We could use components such as checkboxes or radio components for the selection, but that doesn’t provide a very user friendly experience.<br />
In this small talk, I will introduce this new component for ZK 5.<br />
This component is a container in which you can place images. It is then possible to select images by clicking or dragging your mouse just as you would in Windows Explorer. This provides better user functionality and makes it much easier to select the items the user desires.<br />
<br />
= Live Demo =<br />
Let's have a look at the demo of the ZK Imagepicker. <br />
<br />
<gflash width="1200" height="700">Imagepicker.swf</gflash><br />
<br />
The following code fragment demonstrates how to use the Imagepicker component<br />
<source lang="javascript"><br />
<imagepicker itemWidth="100px" itemHeight="100" itemPadding="5" itemMargin="5" ><br />
<image src="/1.jpg" /><br />
<image src="/2.jpg" /> <br />
</imagepicker><br />
</source><br />
<br />
You can place an image into imagepicker tag and set the height and width of it. The result can then be placed into a container such as a window.<br />
<br />
= Component Usage =<br />
<br />
Here is the Imagepicker's attribute specification table: <br />
<br />
{|border="1"<br />
|-<br />
!Attribute||Usage||Default Value<br />
|-<br />
||itemWidth<br />
||Sets the width of the item <br />
||"100" (unit is pixel) <br />
|-<br />
||itemHeight <br />
||Sets the height of the item<br />
||"100" (unit is pixel)<br />
|-<br />
||itemPadding <br />
||Sets the padding of the item <br />
||"5" (unit is pixel)<br />
|-<br />
||itemMargin<br />
||Sets the margin of the item<br />
||"5" (unit is pixel)<br />
|}<br />
<br />
= Event Listeners =<br />
<br />
The Imagepicker component provides one event. This event allows the user to execute code when an item of the Imagepicker is selected:<br />
<br />
#'''onSelect''': The event is triggered when a user selects an item.<br />
<br />
= Behind The Scene: How to Implement a ZK5 component =<br />
<br />
Firstly you can refer to [http://books.zkoss.org/wiki/ZK_Component_Development_Essentials http://books.zkoss.org/wiki/ZK_Component_Development_Essentials] to read about ZK 5’s Basic Concepts.<br />
<br />
=== A component class in Java ===<br />
<br />
The component class must extend from AbstractComponent or one of its derived class. There are several skeletal implementations available and you can choose the appropriate one for your usage. For this component, we will use the XulElement, <br />
<br />
[[Image:Example.jpg]]<br />
<br />
You can create a java class extends XulElement, then provide getter and setter methods for all attributes. The setter methods must be updated using '''smartUpdate'''. <br />
<br />
<source lang="java"><br />
public String getItemWidth() {<br />
return _itemwd;<br />
}<br />
<br />
public void setItemWidth(String itemwd) throws WrongValueException {<br />
if (itemwd != null && itemwd.length() == 0)<br />
itemwd = null;<br />
if (!Objects.equals(_itemwd, itemwd)) {<br />
_itemwd = itemwd; <br />
smartUpdate("itemWidth", itemwd);<br />
}<br />
}<br />
</source><br />
<br />
Then we need to override the functions '''beforeChildAdded''', '''service''', '''renderProperties'''.<br />
<br />
#'''beforeChildAdded''': used to limit the type of the child.<br />
#'''service''': Define what to do on server side when event triggered, like “onSelect”, and you must register “onSelect” event.<br />
#'''renderProperties''': used to render all attribute<br />
<br />
<source lang="java"><br />
public void beforeChildAdded(Component newChild, Component refChild) {<br />
if (!(newChild instanceof Image)) <br />
throw new UiException("Unsupported child for Datapicker: "+newChild); <br />
super.beforeChildAdded(newChild, refChild);<br />
}<br />
<br />
static { <br />
addClientEvent(Imagepicker.class, Events.ON_SELECT, 0);<br />
} <br />
<br />
public void service(org.zkoss.zk.au.AuRequest request, boolean everError) {<br />
final String cmd = request.getCommand();<br />
if (cmd.equals(Events.ON_SELECT)) {<br />
Events.postEvent(SelectEvent.getSelectEvent(request)); <br />
} else {<br />
super.service(request, everError);<br />
}<br />
}<br />
<br />
protected void renderProperties(org.zkoss.zk.ui.sys.ContentRenderer renderer) throws IOException {<br />
super.renderProperties(renderer);<br />
if (!"100".equals(_itemwd))<br />
render(renderer, "itemWidth", _itemwd);<br />
if (!"100".equals(_itemhgh))<br />
render(renderer, "itemHeight", _itemhgh);<br />
if (!"5".equals(_itemPadding))<br />
render(renderer, "itemPadding", _itemPadding);<br />
if (!"5".equals(_itemMargin))<br />
render(renderer, "itemMargin", _itemMargin); <br />
}<br />
</source><br />
<br />
=== Why renderProperties and smartUpdate? ===<br />
<br />
A common question is why <code>renderProperties</code> (and <code>redraw</code>) are required to render <code>value</code> again when we notify the client with <code>smartUpdate</code> in <code>setValue</code>?<br />
<br />
The simple answer is <code>renderProperties</code> is used to send all properties at once when a component is attached to the page at the first time. On the other hand, <code>smartUpdate</code> is used to send a property that was modified after the initial attachment. <br />
<br />
=== A widget class in JavaScript ===<br />
<br />
You can create javascript which extends zul.Widget, then define a setter and getter of all attributes by '''$define'''.<br />
<br />
The '''$define''' function is a util function to declare set/get/is functions automatically<br />
<br />
All attributes within the '''$define''' function will have set/get/is functions created automatically for them by zk.js<br />
<br />
<source lang="javascript"><br />
imagepicker.Imagepicker = zk.$extends(zul.Widget, {<br />
<br />
$define: {<br />
itemWidth : _zkf = function() {<br />
this.syncAttr();<br />
},<br />
itemHeight : _zkf,<br />
itemPadding : _zkf,<br />
itemMargin : _zkf<br />
},<br />
<br />
syncAttr: function() {<br />
if (!this.$n()) return; <br />
<br />
//do realign<br />
<br />
}, <br />
</source><br />
*_zkf is a temporary variable to cache a function<br />
The function within $define will call syncAttr() to realign all images when some images have their values set.<br />
<br />
The four class attributes will also call the same method (syncAttr()) after an attribute has a new value set.<br />
<br />
You can then override the '''doClick_''', '''doMouseOver_''', and '''doMouseOut_''' functions, to change the CSS of the target (div) when an event is triggered, <br />
<br />
#'''doClick_''' , '''doMouseOver_''' , '''doMouseOut_''': you can receive the clicked target by event.Target, or domTarget by event.domTarget, and change target’s css, then the function must be call this.$supers('doClick_', arguments) at last, doMouseOver_ and doMouseOut_ are the same with pervious one.<br />
<br />
<source lang="javascript"><br />
doClick_ : function(evt) {<br />
var target = evt.domTarget;<br />
//do xxx<br />
this.$supers('doClick_', arguments);<br />
}, <br />
doMouseOver_ : function(evt) {<br />
var target = evt.domTarget;<br />
//do xxx<br />
this.$supers('doMouseOver_', arguments);<br />
}, <br />
doMouseOut_ : function(evt) {<br />
var target = evt.domTarget;<br />
//do xxx<br />
this.$supers('doMouseOut_', arguments);<br />
}, <br />
</source><br />
<br />
Regarding the Widget event, you can refer to [http://docs.zkoss.org/wiki/Zk.Event Zk.Event]<br />
<br />
After this we create a div as a selector, and monitor all edges of the selector, check the position of all items. If the edge of the selector touches any items, those items will be selected. We use this.fire(‘onSelect’) to notify the server side when an image is selected.<br />
<br />
=== A JavaScript method to generate the DOM content (so-called mold) === <br />
<br />
The DOM content of a widget is called a mold. A widget can have several molds and each mold should be placed in an independent JavaScript file.<br />
<br />
You can refer to [http://docs.zkoss.org/wiki/SimpleLabel:_Widget_Mold http://docs.zkoss.org/wiki/SimpleLabel:_Widget_Mold] for more information on widget molds.<br />
<br />
This component is created by div tags. We use div tags to define the container area, then enclose all children because we want the div to “frame” each image, and every div will change color (modify css) when some specific event is triggered.<br />
<br />
<source lang="javascript"><br />
<br />
function (out) {<br />
out.push('<div', this.domAttrs_(), '><div id="',<br />
this.uuid, '-cave"', 'class="', this.getZclass(),'-inner">'); <br />
for (var w = this.firstChild; w; w = w.nextSibling){<br />
out.push('<div class="', this.getZclass(),'-item">');<br />
w.redraw(out);<br />
out.push('</div>');<br />
}<br />
out.push('</div></div>');<br />
}<br />
<br />
</source><br />
<br />
'''domAttrs_''' is a (protected) method inherited from zk.Widget. It returns all HTML attributes required, such as style, id and so on. You can override it if you want. <br />
<br />
<br />
At previous widget class in JavaScript, it needs to override '''insertChildHTML_''' and '''removeChildHTML_''', used to enclose child by div tag, and remove div when child be remove,<br />
<br />
<source lang="javascript"><br />
insertChildHTML_: function (child, before, desktop) {<br />
//enclose child by div<br />
}, <br />
removeChildHTML_: function (child, prevsib) {<br />
//distory div after it's child was be removed<br />
},<br />
</source><br />
<br />
=== Add the component definition to lang-addon.xml (or lang.xml) (so-called Language Addon) ===<br />
<br />
You can refer to [http://books.zkoss.org/wiki/ZK_Component_Development_Essentials/Creating_the_Configuration_Files/The_language-addon SimpleLabel:_Language_Addon] define your lang-addon.xml file.<br />
<br />
=== Adds the widget definition to zk ===<br />
<br />
Create a zk.wpd file to define your widget’s package. You can refer to [http://books.zkoss.org/wiki/ZK_Component_Development_Essentials/Creating_the_Configuration_Files/The_Widget_Package_Descriptor SimpleLabel:_Widget_Package_Descriptor] for more information.<br />
<br />
=== Debugging Setting ===<br />
<br />
To debug your component you should change your settings in your zk.xml file to those displayed below:<br />
<br />
<source lang="javascript"><br />
<client-config><br />
<debug-js>true</debug-js><br />
</client-config><br />
<br />
<library-property><br />
<name>org.zkoss.web.classWebResource.cache</name><br />
<value>false</value><br />
</library-property><br />
</source><br />
<br />
'''debug-js:'''<br />
<br />
The ''debug-js'' attribute specifies whether to turn on the debugging of JavaScript files. By default, it is false and the compressed version of JavaScript files will be loaded which are hard to read and debug, though the footprint is much smaller.<br />
<br />
To debug JavaScript files, you can set the attribute to true and the original uncompressed JavaScript files will be loaded instead.<br />
<br />
'''org.zkoss.web.classWebResource.cache:'''<br />
<br />
ZK, by default, allows the browser to cache static resources like images and JavaScript files. When you are developing a component, it is better to turn it off.<br />
<br />
=Download=<br />
<br />
* Download <tracker url="https://sourceforge.net/projects/zkforge/files/Small%20Talks/ZK%205%20Component%20Imagepicker/Imagepicker.war/download" > imagepickerApp</tracker> war file or <tracker url="https://zkforge.svn.sourceforge.net/svnroot/zkforge/trunk/dist/lib/imagepicker.jar" > imagepicker</tracker> jar file<br />
*SVN: [https://zkforge.svn.sourceforge.net/svnroot/zkforge/trunk/imagepicker https://zkforge.svn.sourceforge.net/svnroot/zkforge/trunk/imagepicker]<br />
<br />
= Summary =<br />
<br />
The Imagepicker is an image container, creating a transparent frame for image selection. The component not only provides a click action for selecting images but a lasso effect similar to Windows Explorer, making it easy to use. <br />
<br />
ZK 5 component operations can be split between the server-side and/or the client-side. The java class handles the server-side’s component tree and the javascript widget class handles the widget tree of client side. The widget tree will be create a dom tree in the browser and the component tree updates the widget tree by calling the methods renderProperties() or smartUpdate().<br />
<br />
<comment>http://docs.zkoss.org/wiki/ZK_5.0_Component_Imagepicker</comment><br />
<br />
[[Category:ZK]]<br />
[[Category:New Features]]<br />
{{Template:Smalltalk_Footer|<br />
|name=Potix Corporation<br />
}}</div>Charhttps://www.zkoss.org/_w/index.php?title=Small_Talks/2009/October/ZK_5.0_Component_Imagepicker&diff=15213Small Talks/2009/October/ZK 5.0 Component Imagepicker2010-12-21T02:10:46Z<p>Char: /* Add the component definition to lang-addon.xml (or lang.xml) (so-called Language Addon) */</p>
<hr />
<div>{{Template:Smalltalk_Author|<br />
|author=Jimmy Shiau, Engineer, Potix Corporation<br />
|date=October 27, 2009<br />
|version=Applicable to ZK 5.0 and later<br />
}}<br />
<br />
= Introduction =<br />
<br />
When we create an application such as an image manager for a blog we would always provide the user with an easy way to select images and move them from one category to another. We could use components such as checkboxes or radio components for the selection, but that doesn’t provide a very user friendly experience.<br />
In this small talk, I will introduce this new component for ZK 5.<br />
This component is a container in which you can place images. It is then possible to select images by clicking or dragging your mouse just as you would in Windows Explorer. This provides better user functionality and makes it much easier to select the items the user desires.<br />
<br />
= Live Demo =<br />
Let's have a look at the demo of the ZK Imagepicker. <br />
<br />
<gflash width="1200" height="700">Imagepicker.swf</gflash><br />
<br />
The following code fragment demonstrates how to use the Imagepicker component<br />
<source lang="javascript"><br />
<imagepicker itemWidth="100px" itemHeight="100" itemPadding="5" itemMargin="5" ><br />
<image src="/1.jpg" /><br />
<image src="/2.jpg" /> <br />
</imagepicker><br />
</source><br />
<br />
You can place an image into imagepicker tag and set the height and width of it. The result can then be placed into a container such as a window.<br />
<br />
= Component Usage =<br />
<br />
Here is the Imagepicker's attribute specification table: <br />
<br />
{|border="1"<br />
|-<br />
!Attribute||Usage||Default Value<br />
|-<br />
||itemWidth<br />
||Sets the width of the item <br />
||"100" (unit is pixel) <br />
|-<br />
||itemHeight <br />
||Sets the height of the item<br />
||"100" (unit is pixel)<br />
|-<br />
||itemPadding <br />
||Sets the padding of the item <br />
||"5" (unit is pixel)<br />
|-<br />
||itemMargin<br />
||Sets the margin of the item<br />
||"5" (unit is pixel)<br />
|}<br />
<br />
= Event Listeners =<br />
<br />
The Imagepicker component provides one event. This event allows the user to execute code when an item of the Imagepicker is selected:<br />
<br />
#'''onSelect''': The event is triggered when a user selects an item.<br />
<br />
= Behind The Scene: How to Implement a ZK5 component =<br />
<br />
Firstly you can refer to [http://books.zkoss.org/wiki/ZK_Component_Development_Essentials http://books.zkoss.org/wiki/ZK_Component_Development_Essentials] to read about ZK 5’s Basic Concepts.<br />
<br />
=== A component class in Java ===<br />
<br />
The component class must extend from AbstractComponent or one of its derived class. There are several skeletal implementations available and you can choose the appropriate one for your usage. For this component, we will use the XulElement, <br />
<br />
[[Image:Example.jpg]]<br />
<br />
You can create a java class extends XulElement, then provide getter and setter methods for all attributes. The setter methods must be updated using '''smartUpdate'''. <br />
<br />
<source lang="java"><br />
public String getItemWidth() {<br />
return _itemwd;<br />
}<br />
<br />
public void setItemWidth(String itemwd) throws WrongValueException {<br />
if (itemwd != null && itemwd.length() == 0)<br />
itemwd = null;<br />
if (!Objects.equals(_itemwd, itemwd)) {<br />
_itemwd = itemwd; <br />
smartUpdate("itemWidth", itemwd);<br />
}<br />
}<br />
</source><br />
<br />
Then we need to override the functions '''beforeChildAdded''', '''service''', '''renderProperties'''.<br />
<br />
#'''beforeChildAdded''': used to limit the type of the child.<br />
#'''service''': Define what to do on server side when event triggered, like “onSelect”, and you must register “onSelect” event.<br />
#'''renderProperties''': used to render all attribute<br />
<br />
<source lang="java"><br />
public void beforeChildAdded(Component newChild, Component refChild) {<br />
if (!(newChild instanceof Image)) <br />
throw new UiException("Unsupported child for Datapicker: "+newChild); <br />
super.beforeChildAdded(newChild, refChild);<br />
}<br />
<br />
static { <br />
addClientEvent(Imagepicker.class, Events.ON_SELECT, 0);<br />
} <br />
<br />
public void service(org.zkoss.zk.au.AuRequest request, boolean everError) {<br />
final String cmd = request.getCommand();<br />
if (cmd.equals(Events.ON_SELECT)) {<br />
Events.postEvent(SelectEvent.getSelectEvent(request)); <br />
} else {<br />
super.service(request, everError);<br />
}<br />
}<br />
<br />
protected void renderProperties(org.zkoss.zk.ui.sys.ContentRenderer renderer) throws IOException {<br />
super.renderProperties(renderer);<br />
if (!"100".equals(_itemwd))<br />
render(renderer, "itemWidth", _itemwd);<br />
if (!"100".equals(_itemhgh))<br />
render(renderer, "itemHeight", _itemhgh);<br />
if (!"5".equals(_itemPadding))<br />
render(renderer, "itemPadding", _itemPadding);<br />
if (!"5".equals(_itemMargin))<br />
render(renderer, "itemMargin", _itemMargin); <br />
}<br />
</source><br />
<br />
=== Why renderProperties and smartUpdate? ===<br />
<br />
A common question is why <code>renderProperties</code> (and <code>redraw</code>) are required to render <code>value</code> again when we notify the client with <code>smartUpdate</code> in <code>setValue</code>?<br />
<br />
The simple answer is <code>renderProperties</code> is used to send all properties at once when a component is attached to the page at the first time. On the other hand, <code>smartUpdate</code> is used to send a property that was modified after the initial attachment. <br />
<br />
=== A widget class in JavaScript ===<br />
<br />
You can create javascript which extends zul.Widget, then define a setter and getter of all attributes by '''$define'''.<br />
<br />
The '''$define''' function is a util function to declare set/get/is functions automatically<br />
<br />
All attributes within the '''$define''' function will have set/get/is functions created automatically for them by zk.js<br />
<br />
<source lang="javascript"><br />
imagepicker.Imagepicker = zk.$extends(zul.Widget, {<br />
<br />
$define: {<br />
itemWidth : _zkf = function() {<br />
this.syncAttr();<br />
},<br />
itemHeight : _zkf,<br />
itemPadding : _zkf,<br />
itemMargin : _zkf<br />
},<br />
<br />
syncAttr: function() {<br />
if (!this.$n()) return; <br />
<br />
//do realign<br />
<br />
}, <br />
</source><br />
*_zkf is a temporary variable to cache a function<br />
The function within $define will call syncAttr() to realign all images when some images have their values set.<br />
<br />
The four class attributes will also call the same method (syncAttr()) after an attribute has a new value set.<br />
<br />
You can then override the '''doClick_''', '''doMouseOver_''', and '''doMouseOut_''' functions, to change the CSS of the target (div) when an event is triggered, <br />
<br />
#'''doClick_''' , '''doMouseOver_''' , '''doMouseOut_''': you can receive the clicked target by event.Target, or domTarget by event.domTarget, and change target’s css, then the function must be call this.$supers('doClick_', arguments) at last, doMouseOver_ and doMouseOut_ are the same with pervious one.<br />
<br />
<source lang="javascript"><br />
doClick_ : function(evt) {<br />
var target = evt.domTarget;<br />
//do xxx<br />
this.$supers('doClick_', arguments);<br />
}, <br />
doMouseOver_ : function(evt) {<br />
var target = evt.domTarget;<br />
//do xxx<br />
this.$supers('doMouseOver_', arguments);<br />
}, <br />
doMouseOut_ : function(evt) {<br />
var target = evt.domTarget;<br />
//do xxx<br />
this.$supers('doMouseOut_', arguments);<br />
}, <br />
</source><br />
<br />
Regarding the Widget event, you can refer to [http://docs.zkoss.org/wiki/Zk.Event Zk.Event]<br />
<br />
After this we create a div as a selector, and monitor all edges of the selector, check the position of all items. If the edge of the selector touches any items, those items will be selected. We use this.fire(‘onSelect’) to notify the server side when an image is selected.<br />
<br />
=== A JavaScript method to generate the DOM content (so-called mold) === <br />
<br />
The DOM content of a widget is called a mold. A widget can have several molds and each mold should be placed in an independent JavaScript file.<br />
<br />
You can refer to [http://docs.zkoss.org/wiki/SimpleLabel:_Widget_Mold http://docs.zkoss.org/wiki/SimpleLabel:_Widget_Mold] for more information on widget molds.<br />
<br />
This component is created by div tags. We use div tags to define the container area, then enclose all children because we want the div to “frame” each image, and every div will change color (modify css) when some specific event is triggered.<br />
<br />
<source lang="javascript"><br />
<br />
function (out) {<br />
out.push('<div', this.domAttrs_(), '><div id="',<br />
this.uuid, '-cave"', 'class="', this.getZclass(),'-inner">'); <br />
for (var w = this.firstChild; w; w = w.nextSibling){<br />
out.push('<div class="', this.getZclass(),'-item">');<br />
w.redraw(out);<br />
out.push('</div>');<br />
}<br />
out.push('</div></div>');<br />
}<br />
<br />
</source><br />
<br />
'''domAttrs_''' is a (protected) method inherited from zk.Widget. It returns all HTML attributes required, such as style, id and so on. You can override it if you want. <br />
<br />
<br />
At previous widget class in JavaScript, it needs to override '''insertChildHTML_''' and '''removeChildHTML_''', used to enclose child by div tag, and remove div when child be remove,<br />
<br />
<source lang="javascript"><br />
insertChildHTML_: function (child, before, desktop) {<br />
//enclose child by div<br />
}, <br />
removeChildHTML_: function (child, prevsib) {<br />
//distory div after it's child was be removed<br />
},<br />
</source><br />
<br />
=== Add the component definition to lang-addon.xml (or lang.xml) (so-called Language Addon) ===<br />
<br />
You can refer to [http://books.zkoss.org/wiki/ZK_Component_Development_Essentials/Creating_the_Configuration_Files/The_language-addon SimpleLabel:_Language_Addon] define your lang-addon.xml file.<br />
<br />
=== Adds the widget definition to zk ===<br />
<br />
Create a zk.wpd file to define your widget’s package. You can refer to [http://docs.zkoss.org/wiki/SimpleLabel:_Widget_Package_Descriptor SimpleLabel:_Widget_Package_Descriptor] for more information.<br />
<br />
=== Debugging Setting ===<br />
<br />
To debug your component you should change your settings in your zk.xml file to those displayed below:<br />
<br />
<source lang="javascript"><br />
<client-config><br />
<debug-js>true</debug-js><br />
</client-config><br />
<br />
<library-property><br />
<name>org.zkoss.web.classWebResource.cache</name><br />
<value>false</value><br />
</library-property><br />
</source><br />
<br />
'''debug-js:'''<br />
<br />
The ''debug-js'' attribute specifies whether to turn on the debugging of JavaScript files. By default, it is false and the compressed version of JavaScript files will be loaded which are hard to read and debug, though the footprint is much smaller.<br />
<br />
To debug JavaScript files, you can set the attribute to true and the original uncompressed JavaScript files will be loaded instead.<br />
<br />
'''org.zkoss.web.classWebResource.cache:'''<br />
<br />
ZK, by default, allows the browser to cache static resources like images and JavaScript files. When you are developing a component, it is better to turn it off.<br />
<br />
=Download=<br />
<br />
* Download <tracker url="https://sourceforge.net/projects/zkforge/files/Small%20Talks/ZK%205%20Component%20Imagepicker/Imagepicker.war/download" > imagepickerApp</tracker> war file or <tracker url="https://zkforge.svn.sourceforge.net/svnroot/zkforge/trunk/dist/lib/imagepicker.jar" > imagepicker</tracker> jar file<br />
*SVN: [https://zkforge.svn.sourceforge.net/svnroot/zkforge/trunk/imagepicker https://zkforge.svn.sourceforge.net/svnroot/zkforge/trunk/imagepicker]<br />
<br />
= Summary =<br />
<br />
The Imagepicker is an image container, creating a transparent frame for image selection. The component not only provides a click action for selecting images but a lasso effect similar to Windows Explorer, making it easy to use. <br />
<br />
ZK 5 component operations can be split between the server-side and/or the client-side. The java class handles the server-side’s component tree and the javascript widget class handles the widget tree of client side. The widget tree will be create a dom tree in the browser and the component tree updates the widget tree by calling the methods renderProperties() or smartUpdate().<br />
<br />
<comment>http://docs.zkoss.org/wiki/ZK_5.0_Component_Imagepicker</comment><br />
<br />
[[Category:ZK]]<br />
[[Category:New Features]]<br />
{{Template:Smalltalk_Footer|<br />
|name=Potix Corporation<br />
}}</div>Charhttps://www.zkoss.org/_w/index.php?title=Small_Talks/2009/October/ZK_5.0_Component_Imagepicker&diff=15212Small Talks/2009/October/ZK 5.0 Component Imagepicker2010-12-21T02:09:34Z<p>Char: /* Add the component definition to lang-addon.xml (or lang.xml) (so-called Language Addon) */</p>
<hr />
<div>{{Template:Smalltalk_Author|<br />
|author=Jimmy Shiau, Engineer, Potix Corporation<br />
|date=October 27, 2009<br />
|version=Applicable to ZK 5.0 and later<br />
}}<br />
<br />
= Introduction =<br />
<br />
When we create an application such as an image manager for a blog we would always provide the user with an easy way to select images and move them from one category to another. We could use components such as checkboxes or radio components for the selection, but that doesn’t provide a very user friendly experience.<br />
In this small talk, I will introduce this new component for ZK 5.<br />
This component is a container in which you can place images. It is then possible to select images by clicking or dragging your mouse just as you would in Windows Explorer. This provides better user functionality and makes it much easier to select the items the user desires.<br />
<br />
= Live Demo =<br />
Let's have a look at the demo of the ZK Imagepicker. <br />
<br />
<gflash width="1200" height="700">Imagepicker.swf</gflash><br />
<br />
The following code fragment demonstrates how to use the Imagepicker component<br />
<source lang="javascript"><br />
<imagepicker itemWidth="100px" itemHeight="100" itemPadding="5" itemMargin="5" ><br />
<image src="/1.jpg" /><br />
<image src="/2.jpg" /> <br />
</imagepicker><br />
</source><br />
<br />
You can place an image into imagepicker tag and set the height and width of it. The result can then be placed into a container such as a window.<br />
<br />
= Component Usage =<br />
<br />
Here is the Imagepicker's attribute specification table: <br />
<br />
{|border="1"<br />
|-<br />
!Attribute||Usage||Default Value<br />
|-<br />
||itemWidth<br />
||Sets the width of the item <br />
||"100" (unit is pixel) <br />
|-<br />
||itemHeight <br />
||Sets the height of the item<br />
||"100" (unit is pixel)<br />
|-<br />
||itemPadding <br />
||Sets the padding of the item <br />
||"5" (unit is pixel)<br />
|-<br />
||itemMargin<br />
||Sets the margin of the item<br />
||"5" (unit is pixel)<br />
|}<br />
<br />
= Event Listeners =<br />
<br />
The Imagepicker component provides one event. This event allows the user to execute code when an item of the Imagepicker is selected:<br />
<br />
#'''onSelect''': The event is triggered when a user selects an item.<br />
<br />
= Behind The Scene: How to Implement a ZK5 component =<br />
<br />
Firstly you can refer to [http://books.zkoss.org/wiki/ZK_Component_Development_Essentials http://books.zkoss.org/wiki/ZK_Component_Development_Essentials] to read about ZK 5’s Basic Concepts.<br />
<br />
=== A component class in Java ===<br />
<br />
The component class must extend from AbstractComponent or one of its derived class. There are several skeletal implementations available and you can choose the appropriate one for your usage. For this component, we will use the XulElement, <br />
<br />
[[Image:Example.jpg]]<br />
<br />
You can create a java class extends XulElement, then provide getter and setter methods for all attributes. The setter methods must be updated using '''smartUpdate'''. <br />
<br />
<source lang="java"><br />
public String getItemWidth() {<br />
return _itemwd;<br />
}<br />
<br />
public void setItemWidth(String itemwd) throws WrongValueException {<br />
if (itemwd != null && itemwd.length() == 0)<br />
itemwd = null;<br />
if (!Objects.equals(_itemwd, itemwd)) {<br />
_itemwd = itemwd; <br />
smartUpdate("itemWidth", itemwd);<br />
}<br />
}<br />
</source><br />
<br />
Then we need to override the functions '''beforeChildAdded''', '''service''', '''renderProperties'''.<br />
<br />
#'''beforeChildAdded''': used to limit the type of the child.<br />
#'''service''': Define what to do on server side when event triggered, like “onSelect”, and you must register “onSelect” event.<br />
#'''renderProperties''': used to render all attribute<br />
<br />
<source lang="java"><br />
public void beforeChildAdded(Component newChild, Component refChild) {<br />
if (!(newChild instanceof Image)) <br />
throw new UiException("Unsupported child for Datapicker: "+newChild); <br />
super.beforeChildAdded(newChild, refChild);<br />
}<br />
<br />
static { <br />
addClientEvent(Imagepicker.class, Events.ON_SELECT, 0);<br />
} <br />
<br />
public void service(org.zkoss.zk.au.AuRequest request, boolean everError) {<br />
final String cmd = request.getCommand();<br />
if (cmd.equals(Events.ON_SELECT)) {<br />
Events.postEvent(SelectEvent.getSelectEvent(request)); <br />
} else {<br />
super.service(request, everError);<br />
}<br />
}<br />
<br />
protected void renderProperties(org.zkoss.zk.ui.sys.ContentRenderer renderer) throws IOException {<br />
super.renderProperties(renderer);<br />
if (!"100".equals(_itemwd))<br />
render(renderer, "itemWidth", _itemwd);<br />
if (!"100".equals(_itemhgh))<br />
render(renderer, "itemHeight", _itemhgh);<br />
if (!"5".equals(_itemPadding))<br />
render(renderer, "itemPadding", _itemPadding);<br />
if (!"5".equals(_itemMargin))<br />
render(renderer, "itemMargin", _itemMargin); <br />
}<br />
</source><br />
<br />
=== Why renderProperties and smartUpdate? ===<br />
<br />
A common question is why <code>renderProperties</code> (and <code>redraw</code>) are required to render <code>value</code> again when we notify the client with <code>smartUpdate</code> in <code>setValue</code>?<br />
<br />
The simple answer is <code>renderProperties</code> is used to send all properties at once when a component is attached to the page at the first time. On the other hand, <code>smartUpdate</code> is used to send a property that was modified after the initial attachment. <br />
<br />
=== A widget class in JavaScript ===<br />
<br />
You can create javascript which extends zul.Widget, then define a setter and getter of all attributes by '''$define'''.<br />
<br />
The '''$define''' function is a util function to declare set/get/is functions automatically<br />
<br />
All attributes within the '''$define''' function will have set/get/is functions created automatically for them by zk.js<br />
<br />
<source lang="javascript"><br />
imagepicker.Imagepicker = zk.$extends(zul.Widget, {<br />
<br />
$define: {<br />
itemWidth : _zkf = function() {<br />
this.syncAttr();<br />
},<br />
itemHeight : _zkf,<br />
itemPadding : _zkf,<br />
itemMargin : _zkf<br />
},<br />
<br />
syncAttr: function() {<br />
if (!this.$n()) return; <br />
<br />
//do realign<br />
<br />
}, <br />
</source><br />
*_zkf is a temporary variable to cache a function<br />
The function within $define will call syncAttr() to realign all images when some images have their values set.<br />
<br />
The four class attributes will also call the same method (syncAttr()) after an attribute has a new value set.<br />
<br />
You can then override the '''doClick_''', '''doMouseOver_''', and '''doMouseOut_''' functions, to change the CSS of the target (div) when an event is triggered, <br />
<br />
#'''doClick_''' , '''doMouseOver_''' , '''doMouseOut_''': you can receive the clicked target by event.Target, or domTarget by event.domTarget, and change target’s css, then the function must be call this.$supers('doClick_', arguments) at last, doMouseOver_ and doMouseOut_ are the same with pervious one.<br />
<br />
<source lang="javascript"><br />
doClick_ : function(evt) {<br />
var target = evt.domTarget;<br />
//do xxx<br />
this.$supers('doClick_', arguments);<br />
}, <br />
doMouseOver_ : function(evt) {<br />
var target = evt.domTarget;<br />
//do xxx<br />
this.$supers('doMouseOver_', arguments);<br />
}, <br />
doMouseOut_ : function(evt) {<br />
var target = evt.domTarget;<br />
//do xxx<br />
this.$supers('doMouseOut_', arguments);<br />
}, <br />
</source><br />
<br />
Regarding the Widget event, you can refer to [http://docs.zkoss.org/wiki/Zk.Event Zk.Event]<br />
<br />
After this we create a div as a selector, and monitor all edges of the selector, check the position of all items. If the edge of the selector touches any items, those items will be selected. We use this.fire(‘onSelect’) to notify the server side when an image is selected.<br />
<br />
=== A JavaScript method to generate the DOM content (so-called mold) === <br />
<br />
The DOM content of a widget is called a mold. A widget can have several molds and each mold should be placed in an independent JavaScript file.<br />
<br />
You can refer to [http://docs.zkoss.org/wiki/SimpleLabel:_Widget_Mold http://docs.zkoss.org/wiki/SimpleLabel:_Widget_Mold] for more information on widget molds.<br />
<br />
This component is created by div tags. We use div tags to define the container area, then enclose all children because we want the div to “frame” each image, and every div will change color (modify css) when some specific event is triggered.<br />
<br />
<source lang="javascript"><br />
<br />
function (out) {<br />
out.push('<div', this.domAttrs_(), '><div id="',<br />
this.uuid, '-cave"', 'class="', this.getZclass(),'-inner">'); <br />
for (var w = this.firstChild; w; w = w.nextSibling){<br />
out.push('<div class="', this.getZclass(),'-item">');<br />
w.redraw(out);<br />
out.push('</div>');<br />
}<br />
out.push('</div></div>');<br />
}<br />
<br />
</source><br />
<br />
'''domAttrs_''' is a (protected) method inherited from zk.Widget. It returns all HTML attributes required, such as style, id and so on. You can override it if you want. <br />
<br />
<br />
At previous widget class in JavaScript, it needs to override '''insertChildHTML_''' and '''removeChildHTML_''', used to enclose child by div tag, and remove div when child be remove,<br />
<br />
<source lang="javascript"><br />
insertChildHTML_: function (child, before, desktop) {<br />
//enclose child by div<br />
}, <br />
removeChildHTML_: function (child, prevsib) {<br />
//distory div after it's child was be removed<br />
},<br />
</source><br />
<br />
=== Add the component definition to lang-addon.xml (or lang.xml) (so-called Language Addon) ===<br />
<br />
You can refer to [http://books.zkoss.org/wiki/ZK_Component_Development_Essentials SimpleLabel:_Language_Addon] define your lang-addon.xml file.<br />
<br />
=== Adds the widget definition to zk ===<br />
<br />
Create a zk.wpd file to define your widget’s package. You can refer to [http://docs.zkoss.org/wiki/SimpleLabel:_Widget_Package_Descriptor SimpleLabel:_Widget_Package_Descriptor] for more information.<br />
<br />
=== Debugging Setting ===<br />
<br />
To debug your component you should change your settings in your zk.xml file to those displayed below:<br />
<br />
<source lang="javascript"><br />
<client-config><br />
<debug-js>true</debug-js><br />
</client-config><br />
<br />
<library-property><br />
<name>org.zkoss.web.classWebResource.cache</name><br />
<value>false</value><br />
</library-property><br />
</source><br />
<br />
'''debug-js:'''<br />
<br />
The ''debug-js'' attribute specifies whether to turn on the debugging of JavaScript files. By default, it is false and the compressed version of JavaScript files will be loaded which are hard to read and debug, though the footprint is much smaller.<br />
<br />
To debug JavaScript files, you can set the attribute to true and the original uncompressed JavaScript files will be loaded instead.<br />
<br />
'''org.zkoss.web.classWebResource.cache:'''<br />
<br />
ZK, by default, allows the browser to cache static resources like images and JavaScript files. When you are developing a component, it is better to turn it off.<br />
<br />
=Download=<br />
<br />
* Download <tracker url="https://sourceforge.net/projects/zkforge/files/Small%20Talks/ZK%205%20Component%20Imagepicker/Imagepicker.war/download" > imagepickerApp</tracker> war file or <tracker url="https://zkforge.svn.sourceforge.net/svnroot/zkforge/trunk/dist/lib/imagepicker.jar" > imagepicker</tracker> jar file<br />
*SVN: [https://zkforge.svn.sourceforge.net/svnroot/zkforge/trunk/imagepicker https://zkforge.svn.sourceforge.net/svnroot/zkforge/trunk/imagepicker]<br />
<br />
= Summary =<br />
<br />
The Imagepicker is an image container, creating a transparent frame for image selection. The component not only provides a click action for selecting images but a lasso effect similar to Windows Explorer, making it easy to use. <br />
<br />
ZK 5 component operations can be split between the server-side and/or the client-side. The java class handles the server-side’s component tree and the javascript widget class handles the widget tree of client side. The widget tree will be create a dom tree in the browser and the component tree updates the widget tree by calling the methods renderProperties() or smartUpdate().<br />
<br />
<comment>http://docs.zkoss.org/wiki/ZK_5.0_Component_Imagepicker</comment><br />
<br />
[[Category:ZK]]<br />
[[Category:New Features]]<br />
{{Template:Smalltalk_Footer|<br />
|name=Potix Corporation<br />
}}</div>Charhttps://www.zkoss.org/_w/index.php?title=Small_Talks/2010/April/Upgrading_to_ZK_5&diff=15211Small Talks/2010/April/Upgrading to ZK 52010-12-21T02:02:10Z<p>Char: /* See Also */</p>
<hr />
<div>{{Template:Smalltalk_Author|<br />
|author=[[Image:EdwinYu.jpg]] Edwin Yu, Senior Software Engineer, [http://zes.zebra.com Zebra Enterprise Solutions]<br />
|date=April 28, 2010<br />
|version=from ZK 3.6 to ZK 5.0<br />
}}<br />
<br />
<br />
= Introduction =<br />
I'd like to share our experiences of upgrading from ZK 3.6 to ZK 5.0 in our software with the community. I hope it will help those who like to do the same upgrade.<br />
<br />
= Background =<br />
Our software doesn't use every single feature that ZK offers. Our views are composed programmatically. We don't use static zul for fixed layout and fixed content. We don't use features on zul such as EL expression and data binding. We heavily use custom macro components to encapsulate their own views, data and user interaction in pure java. We plug in our custom css theme. You may experience different upgrade issues when you use ZK differently from ours.<br />
<br />
= Upgrade Preparation =<br />
It's always helpful to read the ZK upgrade note[http://docs.zkoss.org/wiki/ZK_5:_Upgrade_Notes] first. It may have something relevant to you. One thing relevant to us was that ZK 5 disables the event processing thread by default. (I'll talk about it in the next section.) The upgrade note helped me get the sense what I was going to fix in our configuration.<br />
<br />
= Event =<br />
ZK 5 disables the event processing thread by default. This affects us because we have code that expects a response value from a doModel dialog in the Zk 3 event-processing thread model. To preserve what we already have without code change, we enabled the event thread in zk.xml for ZK 5.<code><br />
<system-config><br />
<disable-event-thread>false</disable-event-thread><br />
</system-config><br />
</code><br />
<br />
= Compilation with ZK 5 =<br />
We heavily use the programming way to build our view, so we're sensitive to ZK API changes. After switching out the old ZK 3.6 jars with the ZK 5.0 jars, we had some compilation errors from our macro component code. Below are we experienced:<br />
# Bandbox.closeDropdown() is deprecated and removed. The new method is now close() in ZK 5.<br />
# Listheader.setSort() thows exception in ZK 5.0. We need to put the try/catch around the call<ref>Editor note: it will be fixed in upcoming 5.0.2.</ref>.<br />
# RowRendererExt.DETACH_ON_UNLOAD is deprecated and removed. We change to RowRendererExt.DETACH_ON_RENDER.<br />
<br />
The ZK 3.6[http://www.zkoss.org/javadoc/3.6.2/zk/] and 5[http://www.zkoss.org/javadoc/5.0/zk/] javadoc can help cope with the API changes.<br />
<br />
----<br />
<references/><br />
<br />
= Custom ZK Theme Update =<br />
After our web app was successfully built and deployed, the first thing we noticed when opening our page in a browser was that our custom theme were reverted back to the default blue, and the widgets were incorrectly aligned. The upgrade note helped a lot to get us started. We had to do the following to fix our broken custom theme.<br />
# We had many cases of hbox nested inside vbox (and vice versa), and they became mis-aligned in our app with ZK 5. So we started reviewing all our layouts and removing unnecessary nesting of hbox/vbox. <br />
# We also started using the new cell element. Nesting cell inside hbox or vbox looks better than nesting hbox/vbox each other. <br />
# In some cases, we needed to apply "stretch", "start", "center", "end" attributes to fix the alignment.<br />
# ZK 5 changed the default mold of the button component to be "os", we had to override it back to "trendy" in zk.xml.<br />
# zclass naming in css were updated in ZK 5. We had to globally search and replace the zclass names in our own custom css (img.css.dsp).<br />
# ZK 5 has new CSS styling and images. The ZK Style Guide was not up to date to help us. We had to use Firefox/Chrome to inspect the DOM/CSS in a reverse engineering way to figure out what to add to our custom CSS to override. We could've used the themeBuilder, but we were using only subset of whole ZK CSS. Reverse engineering from DOM tree inspection would be more efficient to produce a smaller set of css overrides.<br />
<br />
It took us about three days to fix our custom theme. However, once the solution had been figured out for the first fix, the rest were just tedious routine.<br />
<br />
= Selenium Tests =<br />
Our build machines reported several selenium test failures after we committed all necessary changes along with the ZK 5 library to the source code repository. We found the following.<br />
# selenium.click(menuItem) alone no longer worked with ZK 5. After talking to ZK Support, we found out that we needed to do selenium.mouseOver(menuItemParent) first, to make it work again<ref>Editor note: it was fixed in 5.0.1.</ref>.<br />
# selenium.clickAt(listheader) brought up wrong popup menu for us with ZK 5. Because we had multiple listeners on the listheader, and we were not sure whether the new problem was in our incorrect coding that was discovered by ZK 5, or in the new complexity of jquery upgrade in ZK 5. However, we found a workaround to clickAt() adjacent component that could bring the correct popup menu.<br />
<br />
Regarding to the selenium-ZK integration, the overall feeling is that our build machines had unreliable test results from the old ZK3 codebase. Meaning, some tests broke once awhile for no reason. However, with ZK5, our build machines report better consistent results.<br />
<br />
----<br />
<references/><br />
<br />
= Troubleshooting =<br />
What happens if you encounter a mysterious javascript error that you can't relate to your java code?<br />
<br />
After fixing obvious bugs and testing with ZK 5 library for days, we started to discover javascript errors with no server-side exceptions. To us, any incorrect zk programming (in pure java) should get a server-side java exception, instead of getting mysterious javascript errors. Our code are complex and dynamic, and we couldn't re-create the same bug in a simple zul page to submit a bug report. After talking to the ZK Support, I learned a good way to collect the bug information when I couldn't relate a javascript error to our java code. Maybe the steps are not new to you, but here is my general approach.<br />
* Use Firefox with the firebug plugin. In firebug's console tab, check "Show Stack Trace with Errors"<br />
* Turn on the debug flag in your zk.xml as shown below. This will allow firebug to show the uncompressed javascript code when breaking on an error.<br />
<code><br />
<client-config><br />
<debug-js>true</debug-js><br />
</client-config><br />
</code><br />
* Load your page in Firefox and get to the point where the javascript error occurs. Firebug stops Firefox and breaks on the javascript code line. There I collect the stack trace and the code line where the error occurs. Example of screenshots are below.<br />
<br />
[[Image:buga.jpg]]<br />
<br />
[[Image:bugb.jpg]]<br />
<br />
With the above information and the use case scenario description, it helped the ZK Support fix the bug. We're a ZK Enterprise Edition subscriber. The ZK Support team was very efficient to fix the bugs and produce a freshly nightly build the next day for us to download. I also tried to post a bug on the ZK forum with sample code. Someone from the ZK team read my post and created a bug report on the next day. The bug was fixed in the next freshly build a week later.<br />
<br />
= Misc =<br />
Only few things were discovered during ZK 5 upgrade that may or may not be bugs with ZK 5. We couldn't reproduce the problems in simple cases for ZK Support to investigate. However, we found workaround and we just moved on to other high priority items. But I list here just for your interest.<br />
# The hyphen inside the page id attribute, such as "some-id", in <?page id="some-id"?> doesn't work for our environment with ZK 5. It caused widgets not responding to user clicks. I had to remove "-" in <?page id=""?> in our zul.<br />
# Our own IdGenerator in zk.xml had a bug to produce non alpha-numeric characters (except for underscore) in the ID string. This caused our ZK view to produce Javascript error.<br />
<br />
= Conclusion =<br />
ZK 5 had many features we liked to use. We're glad we spent the effort to upgrade and start using the new features. I hope the path that we've gone through during the upgrade may help you too.<br />
<br />
= See Also =<br />
*[[Small_Talks/2009/December/ZK_5:_Upgrade_Notes |ZK 5: Upgrade Notes]]<br />
<br />
{{Template:CommentedSmalltalk_Footer|<br />
|name=Potix Corporation<br />
}}</div>Charhttps://www.zkoss.org/_w/index.php?title=Small_Talks/2009/December/ZK_5:_Upgrade_Notes&diff=15210Small Talks/2009/December/ZK 5: Upgrade Notes2010-12-21T02:01:36Z<p>Char: Created page with '= 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…'</p>
<hr />
<div>= Overview =<br />
<br />
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.<br />
<br />
= Server-side Upgrade Notes =<br />
<br />
== Attributes and Namespace ==<br />
=== The return type of <tt>setAttribute</tt> and <tt>removeAttribute</tt> of session/execution/application changed (from <tt>void</tt> to <tt>Object</tt>) ===<br />
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.<br />
<br />
The new signature:<br />
<syntax lang="java"><br />
Object setAttribute(String name, Object value); //returns the previous value if any<br />
Object removeAttribute(String name); //return the previous value if any<br />
</syntax><br />
<br />
=== Namespace deprecated ===<br />
<br />
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.<br />
<br />
<syntax lang="xml"><br />
<variabls foo="better"/> <!-- deprecated --><br />
<custom-attribute foo="better" scope="space"/><br />
</syntax><br />
<br />
Furthermore, ZK 5 will search the attribute scopes for any variable specified in EL or <tt>zscript</tt>.<br />
<br />
<syntax lang="xml"><br />
<window><br />
<custom-attributes a="a" b="b"/> <!-- belongs to window's attribute scope --><br />
<div><br />
<custom-attributes b="B"/> <!-- belongs to div's attribute scope --><br />
${a} and ${b} <!-- result: a and B --><br />
<zscript><br />
String s = a + b; //result: aB<br />
</zscript><br />
</div><br />
</window><br />
</syntax><br />
<br />
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.<br />
<br />
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.<br />
<br />
=== The attribute scope of the ID space is the same of the space owner's attribute scope ===<br />
<br />
In the previous version, the space owner (such as <tt>window</tt>) has two attribute scopes. For example,<br />
<br />
<syntax lang="xml"><br />
<window><br />
<custom-attributes foo="a"/><br />
<div><br />
<custom-attributes foo="b" scope="space"/><br />
</div><br />
<br />
<zscript><br />
self.getAttribute("foo"); //returns a in ZK 3<br />
self.getAttribute("foo", self.SPACE_SCOPE); //returns b<br />
</zscript><br />
</window><br />
</syntax><br />
<br />
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>.<br />
<br />
== System Level Control ==<br />
<br />
=== Event processing thread disabled by default ===<br />
<br />
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 [[Performance tip#Use_the_Servlet_Thread_to_Process_Events]] for how to adjust your application. For example, the <tt>if</tt> clause in the following example is never true.<br />
<br />
<source lang="java" ><br />
if (Messagebox.show("Delete?", "Prompt", Messagebox.YES|Messagebox.NO,<br />
Messagebox.QUESTION) == Messagebox.YES) {<br />
this_never_executes();<br />
}<br />
</source><br />
<br />
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.<br />
<br />
<source lang="xml"><br />
<system-config><br />
<disable-event-thread>false</disable-event-thread><br />
</system-config><br />
</source><br />
<blockquote><br />
----<br />
<references/><br />
</blockquote><br />
<br />
=== The method of <tt>ComponentCloneListener</tt> changed ===<br />
<br />
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.<br />
<br />
<source lang="java"><br />
Object willClone(Component comp);<br />
</source><br />
<br />
=== The <tt>AuPocessor</tt> interface deprecated (replaced with <tt>AuExtension</tt>) ===<br />
<br />
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.<br />
<br />
=== The <tt>addRoot</tt>, <tt>removeRoot</tt>, <tt>moveRoot</tt>, <tt>addFellow</tt> and <tt>removeFellow</tt> methods of <tt>PageCtrl</tt> removed ===<br />
<br />
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>.<br />
<br />
=== The <tt>disable-behind-modal</tt> configuration disabled (always false) ===<br />
<br />
With ZK 5, there is no need to disable widgets that don't belong to the modal window, so this configuration is meaningless.<br />
<br />
== Component Use ==<br />
<br />
=== The <tt>include</tt> component's mode default to <tt>auto</tt> ===<br />
<br />
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<br />
<br />
<source lang="javascript"><br />
<include mode="defer" src="abc.zul"/><br />
</source><br />
<br />
Or, you can specify the following configuration in zk.xml to change the default mode for the whole application.<br />
<br />
<source lang="javascript"><br />
<library-property><br />
<name>org.zkoss.zul.include.mode</name><br />
<value>defer</value><br />
</library-property><br />
</source><br />
<br />
=== The <tt>a</tt> component introduced for HTML A ===<br />
<br />
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,<br />
<br />
<source lang="xml"><br />
Refer <a href="http://www.zkoss.org" label="ZK"/> for details.<br />
Or <a href="http://www.zkoss.org/zkdemo">ZK Demo</a>.<br />
</source><br />
<br />
=== CSS <tt>fixed-layout</tt> property default for <tt>grid</tt> and <tt>listbox</tt> ===<br />
<br />
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.<br />
<br />
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 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 ).<br />
<br />
<source lang="xml"><br />
<grid width="300px"><br />
<columns><br />
<column label="Order" width="20px"/><br />
<column label="Name" hflex="1"/><br />
<column label="Value" hflex="2"/><br />
</columns><br />
<rows><br />
<row><image src="foo.gif"/> username: <textbox/></row><br />
<row><image src="foo.gif"/> password: <textbox/></row><br />
</rows><br />
</grid><br />
</source><br />
<br />
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.<br />
<br />
<source lang="xml"><br />
<grid width="300px" sizedByContent="true"><br />
</source><br />
<br />
=== The <tt>alphafix</tt> mold of <tt>image</tt> and <tt>imagemap</tt> deprecated ===<br />
<br />
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.<br />
<br />
<source lang="javascript"><br />
<?script content="jq.IE6_ALPHAFIX='.png';"?><br />
</source><br />
<br />
In other words, just specify a regular expression to a JavaScript variable called <tt>jq.IE6_ALPHAFIX</tt>.<br />
<br />
=== The methods of <tt>ClientConstraint</tt> changed ===<br />
<br />
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.<br />
<br />
The typical way to implement the custom client validation is as follows.<br />
<br />
#Implementing a JavaString class, say, foo.MyValidator.<br />
<br />
#Implementing <tt>org.zkoss.zul.ClientConstraint</tt> such that<br />
<br />
<source lang="java"><br />
//Java<br />
String getClientConstraint() {<br />
return "new foo.MyValidator()";<br />
}<br />
String getClientPackages() {<br />
return "foo"; //the package name<br />
}<br />
</source><br />
<br />
=== <tt>SimpleConstraint</tt> performs all validations at client ===<br />
<br />
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,<br />
<br />
<source lang="javascript"><br />
<textbox constraint="/.+@.+\.[a-z]+/,server"/><br />
</source><br />
<br />
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>.<br />
<br />
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.<br />
<br />
<source lang="javascript"><br />
//JavaScript<br />
ClientServerConstraint = zk.$extends(zul.inp.SimpleConstraint, {<br />
serverValidate: true<br />
});<br />
</source><br />
<br />
<blockquote><br />
----<br />
<references/><br />
</blockquote><br />
<br />
=== Overlapped window within another overlapped window not cropped ===<br />
<br />
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.<br />
<br />
=== Meaning of hbox/vbox <tt>pack</tt> attribute follows XUL's specification ===<br />
<br />
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".<br />
<br />
== Component Styling ==<br />
<br />
=== The <tt>dynamic</tt> attribute of the <tt>style</tt> component deprecated ===<br />
<br />
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.<br />
<br />
=== The default mold of the <tt>button</tt> component changed to <tt>os</tt> ===<br />
<br />
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>.<br />
<br />
<source lang="xml"><br />
<library-property><br />
<name>org.zkoss.zul.Button.mold</name><br />
<value>trendy</value><br />
</library-property><br />
</source><br />
<br />
=== The default value of the <tt>zclass</tt> attribute more consistent (<tt>z-</tt> + component-name) ===<br />
<br />
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.<br />
<br />
The affected components are as follows.<br />
<br />
comboitem, bandpopup, groupfoot, listcell, listfoot,<br />
listfooter, listgroup, listgroupfoot, listhead, listheader,<br />
listitem, treecell, treechildren, treecol, treecols, treefoot,<br />
treefooter, treerow, table-children, and table-layout<br />
<br />
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>.<br />
<br />
=== Both <tt>Applet</tt> and <tt>Iframe</tt> extends from <tt>HtmlBasedComponent</tt> (instead of <tt>XulElement</tt>) ===<br />
<br />
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>.<br />
<br />
=== The <tt>ZKPrefix</tt> library property deprecated ===<br />
<br />
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.<br />
<br />
== Component Development ==<br />
<br />
The component development is changed. Refer to [[ZK5: Component Development Guide]] for details.<br />
<br />
= Client-side Upgrade Notes =<br />
<br />
The client is rewritten, so your customization have to rewrite, too.<br />
<br />
== Client-side Action deprecated ==<br />
<br />
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,<br />
<br />
<source lang="xml"><br />
<!-- ZK 3.x: Client Side Action --><br />
<textbox<br />
action="onfocus: window.action.show(#{help1}); onblur: window.action.hide(#{help1})" /><br />
<label id="help1" visible="false" value="This is help for text1." /><br />
</source><br />
<br />
can be replaced with<br />
<br />
<source lang="xml"><br />
<!-- ZK 5 --><br />
<textbox xmlns:w="http://www.zkoss.org/2005/zk/client"<br />
w:onFocus="jq(this.$f('help1')).fadeIn()" w:onBlur="jq(this.$f('help1')).fadeOut()"/><br />
<label id="help1" visible="false" value="This is help for text1." /><br />
</source><br />
<br />
== Animation API deprecated ==<br />
<br />
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,<br />
<br />
<source lang="xml"><br />
<!-- ZK 3.x: anima --><br />
<label sclass="ctl" value="SlideDown"<br />
action="onclick: zk.hide(#{t});anima.slideDown(#{t})"/><br />
</source><br />
<br />
<source lang="xml"><br />
<!- ZK 5: with jQury --><br />
<label sclass="ctl" value="SlideDown"<br />
w:onClick="jq(this.$f('t')).hide().slideDown()"<br />
xmlns:w="http://www.zkoss.org/2005/zk/client"/><br />
</source><br />
<br />
Please refer to [[ZK5: JavaScript API]] for the complete description of JavaScript API at the client.<br />
<br />
= See Also =<br />
*[[Upgrading to ZK 5]]<br />
*A forum thread : [http://www.zkoss.org/forum/listComment/11094 Upgrade to ZK5 ]<br />
<br />
<br />
<comment>http://docs.zkoss.org/wiki/ZK_5:_Upgrade_Notes</comment></div>Charhttps://www.zkoss.org/_w/index.php?title=Small_Talks/2009/November/New_Features_of_ZK_3.6.3_TW&diff=15209Small Talks/2009/November/New Features of ZK 3.6.3 TW2010-12-21T01:50:14Z<p>Char: /* 藉伺服端傳送錯誤報告 */</p>
<hr />
<div>{{Template:Smalltalk_Author|<br />
|author=Timothy Clare, Technology Evangelist, Potix Corporation<br />
|date=October 29, 2009<br />
|version=3.6.3<br />
}}<br />
<br />
ZK 最新版本3.6.3 主要重點為效能的提升, 不論是在記憶體消耗或是應用程式展現的效能上都有大幅改善。 除了在效能方面的進步之外,我們也在此最新版本新增了許多新功能,同時修正了70個以上的臭蟲。現在就跟著我們一起來看3.6.3 與原先的版本之差異、及新增了哪些功能吧! <br />
<br />
<br />
= 效能提昇 =<br />
<br />
== 記憶體用量 ==<br />
<br />
ZK 3.6.3 的內存記憶體消耗已得到優化, 所以記憶體消耗將會比ZK 3.6.2來的少. 該問題的起因源自 Internet Explorer 一直以來的缺陷, 隨之而來的是在執行模式對話框(modal dialog)和控制網格(grid control)時的記憶體大量消耗. 在 ZK 3.6.3 裡, 這些問題都已得到解決, 因此在 Internet Explorer 上的記憶體消耗問題也已大大改善.<br />
<br />
== ZK的靜態資源緩存 ==<br />
<br />
位於ZK JAR檔裡的ZK靜態資源現在將在瀏覽器緩存,一直到升級到另一個ZK版本。這意味著瀏覽器不需要重載這些項目,效能也相對地提高許多。 <br />
<br />
在開發一個主題或元件時,我們可能不希望啟用高速緩存,所以我們可以在zk.xml 檔案裡指定一個資料庫屬性(library-property), 再將其關閉。此範例程式碼如下: <br />
<br />
<source lang="xml"><br />
<library-property><br />
<name>org.zkoss.web.classWebResource.cache</name><br />
<value>false</value><br />
</library-property></source><br />
<br />
= 目錄(Menus)和目錄欄(Menubar)=<br />
<br />
== 新增橫項捲動功能 ==<br />
<br />
目錄欄.(<Javadoc>org.zkoss.zul.Menubar</Javadoc>) 現已支援橫項捲動功能, 有了這項功能, 開發者將可輕鬆地在應用程式內加入便於使用者的直覺式的設計.<br />
<br />
[[Image:menu_side_scrolling_zk3.6.3.PNG]]<br />
<br />
以下的程式碼將為您示範, 目錄欄.(<Javadoc>org.zkoss.zul.Menubar</Javadoc>) 橫項捲動這項功能其實很簡單就可以辦到!<br />
<br />
<source lang="xml"><br />
<menubar width="150px" scrollable="true"><br />
<menu label="Menu1"><br />
<menupopup><br />
<menuitem label="Submenu"/><br />
</menupopup><br />
</menu><br />
<menu label="Menu2"><br />
<menupopup><br />
<menuitem label="Submenu"/><br />
</menupopup><br />
</menu><br />
<menu label="Menu3"><br />
<menupopup><br />
<menuitem label="Submenu"/><br />
</menupopup><br />
</menu><br />
</menubar></source><br />
<br />
==支援 onClick 功能==<br />
<br />
目錄元件(<Javadoc>org.zkoss.zul.Menu</Javadoc>) 現已支援 onClick 事件. 從以下目錄元件(<Javadoc>org.zkoss.zul.Menu</Javadoc>)的截圖中以紅框標記的部分來看, 我們可以發現點擊右手邊的箭頭, 下方會顯示功能列表, 而點擊主按鈕後, 即會執行onClick 事件. <br />
其中圖示內的紅色框線是為了突顯目錄元件(<Javadoc>org.zkoss.zul.Menu</Javadoc>)可點擊的區域範圍. 如圖示:<br />
<br />
[[Image:menu_onclick_zk3.6.3.PNG]]<br />
<br />
欲執行onClick 事件的程式碼如下:<br />
<br />
<source lang="xml"><br />
<menu label="Topmost" onClick='alert(1);'></source><br />
<br />
=Tabbox 支援 Tabbar 裡的其他控制項=<br />
<br />
<Javadoc>org.zkoss.zul.Tabbox</Javadoc> 現已支援 Tabbar 裡的其他控制項, 而這將帶給開發者更大自由和選擇. 以下的截圖為<Javadoc>org.zkoss.zul.Tabbox</Javadoc> 的範例圖 - 目錄系統, 其中包括許多Tabbar 的其他控制項, 附圖如下:<br />
<br />
[[Image:tabs_zk3.6.3.png]]<br />
<br />
以下的程式碼將為您示範如何在Tab bar中嵌入控制項:<br />
<br />
<source lang="xml"><br />
<zk><br />
<tabbox width="250px"><br />
<tabs><br />
<tab label="Tab 1" closable="true" /><br />
<tab label="Tab 2" closable="true" /><br />
<tab label="Tab 3" closable="true" /><br />
<tab label="Tab 4" closable="true" /><br />
<tab label="Tab 5" closable="true" /><br />
</tabs><br />
<toolbar><br />
<toolbarbutton image="/img/live.gif" onClick='alert("Live")' /><br />
<toolbarbutton image="/img/defender.gif"<br />
onClick='alert("Defender")' /><br />
<toolbarbutton image="/img/battery.gif"<br />
onClick='alert("Battery")' /><br />
</toolbar><br />
<tabpanels><br />
<tabpanel>This is panel 1</tabpanel><br />
<tabpanel>This is panel 2 The second panel</tabpanel><br />
<tabpanel>This is panel 3</tabpanel><br />
<tabpanel>This is panel 4</tabpanel><br />
<tabpanel>This is panel 5</tabpanel><br />
</tabpanels><br />
</tabbox><br />
</zk><br />
</source><br />
<br />
=改善圖表元件(chart) =<br />
<br />
==新增儀表板元件(dial) ==<br />
<br />
我們在此新版本新增了一項新的圖表元件 - 儀表板元件(dial) . 利用此圖表, 你可以自由定義縮放比率, 並針對不同區塊設定不同顏色. 同時你也可以進一步將此功能運用在風險管理的呈現上.<br />
<br />
以下即為此新增元件的圖示和程式碼:<br />
<br />
[[Image:dial_chart_zk3.6.3.PNG]]<br />
<br />
<source lang="java"><br />
<window onOK="doOK()" width="350px"><br />
<zscript><br />
<![CDATA[<br />
import org.zkoss.zul.DialModel;<br />
import org.zkoss.zul.DialModelScale;<br />
<br />
int val= 40;<br />
<br />
DialModel dialmodel = new DialModel();<br />
DialModelScale scale = dialmodel.newScale(0.0, 100.0, -120.0, -300.0, 10.0, 4);//scale's configuration data<br />
scale.setText("Temperature (F)");<br />
scale.newRange(80, 100, "#FF0000", 0.83, 0.89);<br />
scale.newRange(60, 80, "#FFC426", 0.83, 0.89);<br />
scale.setValue(val);<br />
<br />
doOK() {<br />
val = dbx.getValue();<br />
if (val > 100) {<br />
val = 100;<br />
} else if (val < 0) {<br />
val = 0;<br />
}<br />
dbx.value = val;<br />
slx.curpos = val;<br />
scale.setValue(val);<br />
if (val > 80) {<br />
scale.setNeedleColor(scale.getRange(0).getRangeColor());<br />
} else if (val > 60) {<br />
scale.setNeedleColor(scale.getRange(1).getRangeColor());<br />
} else {<br />
scale.setNeedleColor(dialmodel.getFrameFgColor());<br />
}<br />
}<br />
]]><br />
</zscript><br />
<chart id="dial" title="Dial Plot" width="300" height="300" type="dial" threeD="false" fgAlpha="128"/><br />
<zscript><br />
dial.setModel(dialmodel);<br />
</zscript><br />
<hbox><br />
<slider id="slx" curpos="${val}" onScroll="dbx.value=self.curpos; doOK()"/><br />
<intbox id="dbx" value="${val}" onChange="doOK()"/><br />
</hbox><br />
</window></source><br />
<br />
==圖表(Charts) 支援字型設定==<br />
<br />
我們現在已經可以在圖表中設定我們想要的字型, 如果您希望在圖表中使用外語, 那這項新功能的出現將會特別有幫助. 以下的範例將以中文為例為您示範字型的設定:<br />
<br />
<source lang="java"><br />
<vbox><br />
<zscript><br />
import java.awt.Font;<br />
String fontname = "Dialog";<br />
Font tfont = new Font(fontname, Font.BOLD, 16); //for title<br />
Font lfont = new Font(fontname, Font.PLAIN, 10); //for legend<br />
Font lbfont = new Font(fontname, Font.PLAIN, 12); //for label<br />
<br />
//create and set the model of the bar chart here<br />
</zscript><br />
<br />
<chart id="barchart" title="長條圖 Bar Chart" width="500" height="250" type="bar" threeD="false" fgAlpha="128" <br />
titleFont="${tfont}" legendFont="${lfont}" xAxisFont="${lbfont}" xAxisTickFont="${lbfont}" /><br />
</vbox><br />
</source><br />
<br />
[[Image:bar_chart_font_zk3.6.3.PNG]]<br />
<br />
=彈出視窗(POPUP), 提示工具(Tooltip)和文字位置=<br />
<br />
彈出視窗(POPUP), 提示工具(Tooltip)和文字位置元件功能都已增強. 以下即是新增的的文字位置設定:<br />
<br />
[[Image:zk3.6.3_positions2.jpg]]<br />
<br />
您可以利用以下這段程式碼指定這些位置<br />
<br />
<source lang="javascript"><br />
<button id="btn" label="overlap" width="300px" height="300px" popup="component_id, position=overlap_end"/></source><br />
<br />
除此之外, 你也可以利用x 和 y 的屬性設定來達到欲調整效果, 程式碼如下:<br />
<br />
<source lang="javascript"><br />
<button id="btn" label="overlap" width="300px" height="300px" popup="component_id, x=50,y=50"/></source><br />
<br />
== 提示工具(Tooltip)的延遲時間設定==<br />
<br />
提示工具(Tooltip) 屬性設定現已支援延遲時間設定, 只需加入下面的程式碼即可達到效果.<br />
<br />
<source lang="xml"><br />
<label label="Tooltip" tootlip="id, position=before_start, delay=500"/></source><br />
<br />
=新增客戶端自動逾時(Timeout)功能=<br />
<br />
當ZK應用程式連線逾時發生時,通常需要使用者的交互動作使它重新導向到逾時頁面。在ZK 3.6.3 則不需要使用者的交互動作,客戶端會自動被通知逾時,進而採取適當的行動。 <br />
<br />
自動逾時(automatic-timeout)可在zk.xml session-config 內做設定。以下即為範例,如果自動逾時(automatic-timeout) 元件被設置為真(true),那麼客戶端將立即被導向至適當頁面。如果它被設置為否(false),那麼應用程式將等待用戶交互引導向前。<br />
<br />
<source lang="xml"><br />
<session-config><br />
<device-type>ajax</device-type><br />
<automatic-timeout/> <!-- the same as <automatic-timeout>true</automatic-timeout> --><br />
<timeout-uri>/timeout.zul</timeout-uri><br />
</session-config></source><br />
<br />
=藉伺服端傳送錯誤報告=<br />
<br />
錯誤報告的傳送設定是藉由client-config裡的錯誤重載元件(error-reload element) 來執行的, 這些元件都在 zk.xml 檔案裡設定. 以下程式碼即為讀取到錯誤報告時的範例:<br />
<br />
<source lang="xml"><br />
<error-reload><br />
<device-type>ajax</device-type><br />
<error-code>410</error-code><br />
<reload-uri>/login.zul</reload-uri><br />
</error-reload></source><br />
<br />
以410錯誤報告為例, 錯誤報告出現時, 頁面會被導到 login.zul. 然而, 當 <reload-url> 為空白時, 頁面將重新被載入一次. 在ZK 3.6.3 裡, 您將有另一個選擇, 我們可以將 <connection-type> 設定如下:<br />
<br />
<source lang="xml"><br />
<connection-type>server-push</connection-type></source><br />
<br />
<connection-type> 代表的是錯誤報告被傳送的路徑. 系統預設值是藉 AU channel 傳送, 而這部分的請求會藉widgets 傳送並在客戶端執行。<br />
如果您想藉伺服端傳送錯誤報告, 那你就必須將<connection-type> 設定為server-push.<br />
<br />
如需更多相關資訊, 請查看[http://books.zkoss.org/wiki/ZK_Configuration_Reference/zk.xml/The_client-config_Element 此連結]<br />
<br />
=日曆元件 (Datebox) 支援時區設定=<br />
<br />
從以下圖示您可以發現在最新版本裡, 日曆元件( <Javadoc>org.zkoss.zul.Datebox</Javadoc>) 新增了時區設定這項功能, 使用者可以依自己的需求從預設的時區內設定適合的時區. 而開發者可自由指定這些選項並限制可用的時區選項. 在以下的圖片中我們可以看到現在設定的時區是 "GMT+12, GMT+8". <br />
<br />
[[Image:datebox_timezone_zk3.6.3.png]]<br />
<br />
<source lang="xml"><br />
<datebox id="datebox1" format="M/d/yy KK:mm:ss a" width="150px" displayedTimeZones="GMT+12,GMT+8" timeZone="GMT+8" timeZonesReadonly="false"/></source><br />
<br />
=訊息視窗 (Messagebox) 維持單字完整性=<br />
<br />
訊息視窗(<Javadoc>org.zkoss.zul.Messagebox</Javadoc>) 現已有單字斷行設定, 即使是再長的單字也都能完整的呈現.<br />
<br />
<source lang="java"><br />
Messagebox.show("Would you like to save a longerrrrrrrrrrrrrrrrrrr word? Would you like to save a longerrrrrrrrrrrrrrrrrrr word? Would you like to save a longerrrrrrrrrrrrrrrrrrr word?", "The long word can be broken correctly", Messagebox.OK, Messagebox.EXCLAMATION);</source><br />
<br />
[[Image:messagebox_wrap_zk3.6.3.PNG]]<br />
<br />
[[Category:Release]]<br />
[[Category:ZK]]<br />
[[Category:New Features]]<br />
{{Template:Smalltalk_Footer|<br />
|name=Potix Corporation<br />
}}<br />
<br />
<br />
<comment>http://docs.zkoss.org/wiki/New_Features_of_ZK_3.6.3</comment></div>Charhttps://www.zkoss.org/_w/index.php?title=Small_Talks/2009/November/New_Features_of_ZK_3.6.3&diff=15208Small Talks/2009/November/New Features of ZK 3.6.32010-12-21T01:48:53Z<p>Char: /* Server push error feedback */</p>
<hr />
<div>{{Template:Smalltalk_Author|<br />
|author=Timothy Clare, Technology Evangelist, Potix Corporation<br />
|date=November 3, 2009<br />
|version=3.6.3<br />
}}<br />
<br />
<br />
<br />
ZK 3.6.3 brings about large improvements in memory usage and the performance of applications in addition to introducing several new features and fixing over 70 bugs.<br />
<br />
The following paragraphs outline some of the exciting improvements and new features in ZK 3.6.3.<br />
<br />
<br />
<br />
= Performance enhancements =<br />
<br />
== Memory usage ==<br />
<br />
ZK 3.6.3's memory consumption has been optimized and thus uses less memory than ZK 3.6.2. The problem originated from the notorious Internet Explorer bugs which cased memory leak issues with the modal dialog and grid control. These issues have now been resolved and thus the memory usage in Internet Explorer has been drastically improved.<br />
<br />
== ZK's static resources cached ==<br />
<br />
ZK static resources which are located in the ZK JAR files are now cached within the browser, until upgrading to another ZK version. This means that the browser does not have to reload these items thus leading to improved performance.<br />
<br />
When developing a theme or component we might not want to have caching enabled therefore we can specify a library-property in the zk.xml file to turn it off. An example of this code is provided below.<br />
<br />
<source lang="xml"><br />
<library-property><br />
<name>org.zkoss.web.classWebResource.cache</name><br />
<value>false</value><br />
</library-property></source><br />
<br />
= Menus and the Menubar=<br />
<br />
== Sidescrolling support ==<br />
<br />
The <Javadoc>org.zkoss.zul.Menubar</Javadoc> now supports sideways scrolling meaning it is easier to build more intuitive layouts for users.<br />
<br />
[[Image:menu_side_scrolling_zk3.6.3.PNG]]<br />
<br />
The code below demonstrates how easy it is to make the <Javadoc>org.zkoss.zul.Menubar</Javadoc> scrollable!<br />
<br />
<source lang="xml" high="1"><br />
<menubar width="150px" scrollable="true"><br />
<menu label="Menu1"><br />
<menupopup><br />
<menuitem label="Submenu"/><br />
</menupopup><br />
</menu><br />
<menu label="Menu2"><br />
<menupopup><br />
<menuitem label="Submenu"/><br />
</menupopup><br />
</menu><br />
<menu label="Menu3"><br />
<menupopup><br />
<menuitem label="Submenu"/><br />
</menupopup><br />
</menu><br />
</menubar></source><br />
<br />
==onClick Support ==<br />
<br />
The <Javadoc>org.zkoss.zul.Menu</Javadoc> now supports an onClick event. If we take a look at the screenshot of the <Javadoc>org.zkoss.zul.Menu</Javadoc> below both the right hand side and left hand side have been outlined in red. Clicking the arrow on the right hand side will show the menu whereas clicking the main button (the left hand side) will fire the onClick event. The red outline is used to highlight the clickable areas of the <Javadoc>org.zkoss.zul.Menu</Javadoc>.<br />
<br />
[[Image:menu_onclick_zk3.6.3.PNG]]<br />
<br />
The code to register an onClick event is shown below:<br />
<br />
<source lang="xml"><br />
<menu label="Topmost" onClick='alert(1);'></source><br />
<br />
=Tabbox supports other controls in the tabbar=<br />
<br />
The <Javadoc>org.zkoss.zul.Tabbox</Javadoc> now supports the inclusion of other controls within its tab bar, thus allowing more freedom and layout options when creating layouts which include a <Javadoc>org.zkoss.zul.Tabbox</Javadoc>. The screenshot below demonstrates an example <Javadoc>org.zkoss.zul.Tabbox</Javadoc> which includes extra controls in the tab bar acting like a menu system.<br />
<br />
[[Image:tabs_zk3.6.3.png]]<br />
<br />
The code below demonstrates how to embed controls within the tab bar.<br />
<br />
<source lang="xml" high="9,10,11,12,13,14,15"><br />
<tabbox width="250px"><br />
<tabs><br />
<tab label="Tab 1" closable="true" /><br />
<tab label="Tab 2" closable="true" /><br />
<tab label="Tab 3" closable="true" /><br />
<tab label="Tab 4" closable="true" /><br />
<tab label="Tab 5" closable="true" /><br />
</tabs><br />
<toolbar><br />
<toolbarbutton image="/img/live.gif" onClick='alert("Live")' /><br />
<toolbarbutton image="/img/defender.gif"<br />
onClick='alert("Defender")' /><br />
<toolbarbutton image="/img/battery.gif"<br />
onClick='alert("Battery")' /><br />
</toolbar><br />
<tabpanels><br />
<tabpanel>This is panel 1</tabpanel><br />
<tabpanel>This is panel 2 The second panel</tabpanel><br />
<tabpanel>This is panel 3</tabpanel><br />
<tabpanel>This is panel 4</tabpanel><br />
<tabpanel>This is panel 5</tabpanel><br />
</tabpanels><br />
</tabbox><br />
</source><br />
<br />
=Charting improvements=<br />
<br />
==New dial chart==<br />
<br />
We have introduced a new chart called a dial. The chart allows us to define a scale and then define a color for values which fall between certain ranges. This is useful for displaying certain information such as risk.<br />
<br />
The code and image below demonstrate the new chart.<br />
<br />
[[Image:dial_chart_zk3.6.3.PNG]]<br />
<br />
<source lang="java"><br />
<window onOK="doOK()" width="350px"><br />
<zscript><br />
<![CDATA[<br />
import org.zkoss.zul.DialModel;<br />
import org.zkoss.zul.DialModelScale;<br />
<br />
int val= 40;<br />
<br />
DialModel dialmodel = new DialModel();<br />
DialModelScale scale = dialmodel.newScale(0.0, 100.0, -120.0, -300.0, 10.0, 4);//scale's configuration data<br />
scale.setText("Temperature (F)");<br />
scale.newRange(80, 100, "#FF0000", 0.83, 0.89);<br />
scale.newRange(60, 80, "#FFC426", 0.83, 0.89);<br />
scale.setValue(val);<br />
<br />
doOK() {<br />
val = dbx.getValue();<br />
if (val > 100) {<br />
val = 100;<br />
} else if (val < 0) {<br />
val = 0;<br />
}<br />
dbx.value = val;<br />
slx.curpos = val;<br />
scale.setValue(val);<br />
if (val > 80) {<br />
scale.setNeedleColor(scale.getRange(0).getRangeColor());<br />
} else if (val > 60) {<br />
scale.setNeedleColor(scale.getRange(1).getRangeColor());<br />
} else {<br />
scale.setNeedleColor(dialmodel.getFrameFgColor());<br />
}<br />
}<br />
]]><br />
</zscript><br />
<chart id="dial" title="Dial Plot" width="300" height="300" type="dial" threeD="false" fgAlpha="128"/><br />
<zscript><br />
dial.setModel(dialmodel);<br />
</zscript><br />
<hbox><br />
<slider id="slx" curpos="${val}" onScroll="dbx.value=self.curpos; doOK()"/><br />
<intbox id="dbx" value="${val}" onChange="doOK()"/><br />
</hbox><br />
</window></source><br />
<br />
==Charts support setting the font==<br />
<br />
We can now specify what font we want a chart to use, this is useful when employing a foreign language within your chart. The example demonstrates setting a font and using it with a foreign language, in this case Chinese.<br />
<br />
<source lang="java"><br />
<vbox><br />
<zscript><br />
import java.awt.Font;<br />
String fontname = "Dialog";<br />
Font tfont = new Font(fontname, Font.BOLD, 16); //for title<br />
Font lfont = new Font(fontname, Font.PLAIN, 10); //for legend<br />
Font lbfont = new Font(fontname, Font.PLAIN, 12); //for label<br />
<br />
//create and set the model of the bar chart here<br />
</zscript><br />
<br />
<chart id="barchart" title="長條圖 Bar Chart" width="500" height="250" type="bar" threeD="false" fgAlpha="128" <br />
titleFont="${tfont}" legendFont="${lfont}" xAxisFont="${lbfont}" xAxisTickFont="${lbfont}" /><br />
</vbox><br />
</source><br />
<br />
[[Image:bar_chart_font_zk3.6.3.PNG]]<br />
<br />
=Popup, tooltip and context positions=<br />
<br />
The popup, tooltip and context attributes positional ability has been expanded. The following new positions are now supported:<br />
<br />
[[Image:zk3.6.3_positions2.jpg]]<br />
<br />
You are able to specify these positions using the following code.<br />
<br />
<source lang="javascript"><br />
<button id="btn" label="overlap" width="300px" height="300px" popup="component_id, position=overlap_end"/></source><br />
<br />
In addition to this more options are available such as positioning by x and y co-ordinates as demonstrated below.<br />
<br />
<source lang="javascript"><br />
<button id="btn" label="overlap" width="300px" height="300px" popup="component_id, x=50,y=50"/></source><br />
<br />
== Tooltip delay==<br />
<br />
The tooltip attribute can also support a delay, the following code outlines how to accomplish this.<br />
<br />
<source lang="xml"><br />
<label label="Tooltip" tootlip="id, position=before_start, delay=500"/></source><br />
<br />
=An automatic timeout at the client=<br />
<br />
When a ZK application is times out, user interaction is required for it to redirect to the timed out page. In ZK 3.6.3 instead of needing user interaction the client will automatically be informed of the time out and thus take appropriate action.<br />
<br />
The automatic timeout can be configured inside the zk.xml』s session-config element. An example of the markup is given below, if the automatic-timeout element is set to true then the client will be redirected as soon as it times out. If it is set to false then the application will wait for user interaction before redirecting.<br />
<br />
<source lang="xml"><br />
<session-config><br />
<device-type>ajax</device-type><br />
<automatic-timeout/> <!-- the same as <automatic-timeout>true</automatic-timeout> --><br />
<timeout-uri>/timeout.zul</timeout-uri><br />
</session-config></source><br />
<br />
=Server push error feedback=<br />
<br />
The configuration of the errors is handled by the error-reload element within the client-config element. These elements are specified within the zk.xml file. The markup below demonstrates an example of catching an error:<br />
<br />
<source lang="xml"><br />
<error-reload><br />
<device-type>ajax</device-type><br />
<error-code>410</error-code><br />
<reload-uri>/login.zul</reload-uri><br />
</error-reload></source><br />
<br />
In the above case upon a 410 error the page will be redirected to login.zul. However, if reload-url is left blank then the page will be reloaded. With 3.6.3, there is now another available option, we can specify the connection-type element as demonstrated below.<br />
<br />
<source lang="xml"><br />
<connection-type>server-push</connection-type></source><br />
<br />
The connection-type element specifies through which channel the requests are sent. By default it is the AU channel in which Ajax requests are sent by widgets running at the client. If you would like to specify the error page for server-push then connection-type must be set to server-push.<br />
<br />
For more information please take a look [http://books.zkoss.org/wiki/ZK_Configuration_Reference/zk.xml/The_client-config_Element here.]<br />
<br />
=Datebox supports the setting of the timezone=<br />
<br />
The image below shows the new <Javadoc>org.zkoss.zul.Datebox</Javadoc> functionality which allows the user to change the time zone to other predefined time zones. Viewing the zul markup provided below the image we can see that the displayedTimeZones is set to "GMT+12,GMT+8". These options are specified by the developer and restrict the user to the available time zones.<br />
<br />
[[Image:datebox_timezone_zk3.6.3.png]]<br />
<br />
<source lang="xml"><br />
<datebox id="datebox1" format="M/d/yy KK:mm:ss a" width="150px" displayedTimeZones="GMT+12,GMT+8" timeZone="GMT+8" timeZonesReadonly="false"/></source><br />
<br />
=Messagebox is wrapped nicely=<br />
<br />
The <Javadoc>org.zkoss.zul.Messagebox</Javadoc> now supports wrapping of long text as demonstrated below. <br />
<br />
<source lang="java"><br />
Messagebox.show("Would you like to save a longerrrrrrrrrrrrrrrrrrr word? Would you like to save a longerrrrrrrrrrrrrrrrrrr word? Would you like to save a longerrrrrrrrrrrrrrrrrrr word?", "The long word can be broken correctly", Messagebox.OK, Messagebox.EXCLAMATION);</source><br />
<br />
<br />
[[Image:messagebox_wrap_zk3.6.3.PNG]]<br />
<br />
<br />
=Download & Other resources=<br />
<br />
*[http://www.zkoss.org/download/zk3.6.dsp Download ZK 3.6.3]<br />
*[http://www.zkoss.org/release/rn-3.6.3.dsp View the release notes]<br />
<br />
<br />
<br />
[[Category:Release]]<br />
[[Category:ZK]]<br />
[[Category:New Features]]<br />
{{Template:Smalltalk_Footer|<br />
|name=Potix Corporation<br />
}}<br />
<br />
<br />
<comment>http://docs.zkoss.org/wiki/New_Features_of_ZK_3.6.3</comment></div>Charhttps://www.zkoss.org/_w/index.php?title=Small_Talks/2009/July/ZK_5.0_and_Server%2BClient_Fusion&diff=15207Small Talks/2009/July/ZK 5.0 and Server+Client Fusion2010-12-21T01:41:38Z<p>Char: /* See Also */</p>
<hr />
<div>{{Template:Smalltalk_Author|<br />
|author=Robbie Cheng, Technology Evangelist, Potix Corporation<br />
|date=July 14, 2009<br />
|version=ZK 5.0<br />
}}<br />
<br />
==Introduction==<br />
Since ZK 5, developers can not only leverage the ease of development of the server-centric architecture, but also the full controllability of client-side programming. It's developer's choice to implement a function using either server-side or client side development according to their requirements.<br />
<br />
In this article, we will demonstrate two different approaches, pure server-centric, and client/server development to implement a real-world application.<br />
<br />
==Resources==<br />
<br />
<imagelink link="http://www.zkoss.org/download/zk.dsp" image="http://www.zkoss.org/img/DownloadNow.jpg" text="Download ZK 5" /><br />
<imagelink link="http://www.zkoss.org/zkdemo/userguide/" image="http://www.zkoss.org/img/LiveDemo.jpg" text="Live Demo" /><br />
<imagelink link="http://docs.zkoss.org/wiki/Documentation" image="http://www.zkoss.org/img/Doc.jpg" text="Documentation" /><br />
<br />
==The Application: ZK Finance==<br />
ZK finance is real-world application; users can look up the historical price of stocks, and see the result in a table, and a chart. Here is the snapshot of this application, including a search box on the left panel, and a table, and chart on the right panel.<br />
[[Image:zkfinance.png|300]]<br />
<br />
==Pure Server-centric approach==<br />
First of all, we use the pure server-centric approach to implement this application using MVC (Model-View-Controller) pattern.<br />
===Model===<br />
There are two objects of this application, including Stock, and Price. The relationship between Stock and Price is one-to-many. Each stock has more than one Price objects to represent its historical price.<br />
<br />
'''Stock.java'''<br />
<source lang="java"><br />
public class Stock {<br />
private int _id;<br />
private String _name;<br />
private List _priceItems = new ArrayList();<br />
....<br />
getter and setter methods<br />
}<br />
</source><br />
'''Price.java'''<br />
<source lang="java"><br />
public class Price {<br />
private String _date;<br />
private double _open;<br />
private double _high;<br />
private double _low;<br />
private double _close;<br />
private int _volumn;<br />
....<br />
getter and setter methods<br />
}<br />
</source><br />
<br />
Moreover, we create a DAO object which is responsible for providing data of stock.<br />
'''StockDAO.java'''<br />
<source lang="java"><br />
public class StockDAO {<br />
private List stocks = new LinkedList();<br />
public Stock getStock(int id) {}<br />
public List findAll() {}<br />
<br />
}<br />
</source><br />
<br />
===View===<br />
We provide a search function, and show the search result in a Listbox.<br />
<br />
'''index.zul'''<br />
<source lang="xml"><br />
<?init class="org.zkoss.zkplus.databind.AnnotateDataBinderInit"?><br />
<borderlayout id="main" apply="StockController"><br />
<west title="ZK Finance" size="250px" flex="true"<br />
splittable="true" minsize="210" maxsize="500" collapsible="true"><br />
<panel><br />
<toolbar><br />
<label value="Search:" /><br />
<textbox id="searchBox" ctrlKeys="#down#up"<br />
focus="true" sclass="demo-search-inp" /><br />
</toolbar><br />
<panelchildren><br />
<listbox id="itemList" model="@{main$composer.stocks}"<br />
fixedLayout="true" vflex="true"> <br />
<listitem self="@{each='stock'}" value="@{stock}"><br />
<listcell label="@{stock.name}" /><br />
</listitem><br />
</listbox><br />
</panelchildren><br />
</panel><br />
</west><br />
<center><br />
<include id="detail"/><br />
</center><br />
</borderlayout><br />
</source><br />
<br />
Regarding historical price of a stock, we use Grid, and line Chart to show the result.<br />
<br />
'''price.zul'''<br />
<source lang="xml"><br />
<?init class="org.zkoss.zkplus.databind.AnnotateDataBinderInit"?><br />
<window id="main2" apply="PriceController"><br />
<grid id="history" model="@{main2$PriceController.prices}" ><br />
<columns menupopup="auto"><br />
<column label="Date" /><br />
<column label="Open" /><br />
<column label="High" /><br />
<column label="Low" /><br />
<column label="Close" /><br />
<column label="Volumn" /><br />
</columns><br />
<rows><br />
<row self="@{each='price'}"><br />
<label value="@{price.date}"/><br />
<label value="@{price.open}"/><br />
<label value="@{price.high}"/><br />
<label value="@{price.low}"/><br />
<label value="@{price.close}"/><br />
<label value="@{price.volumn}"/><br />
</row><br />
</rows><br />
</grid><br />
<br />
<chart id="line" width="500" height="250" type="line"<br />
fgAlpha="128" model="@{main2$PriceController.cateModel}"/><br />
</window><br />
</source><br />
<br />
===Controller===<br />
====Search function====<br />
In StockController.java, we register onChanging event listener on Textbox component to get user’s input instantly, and then list all stocks that match the query in the Listbox component. <br />
<br />
'''StockController.java'''<br />
<source lang="java"><br />
public class StockController extends GenericForwardComposer { <br />
Textbox searchBox;<br />
Listbox itemList;<br />
Include detail;<br />
StockDAO dao = new StockDAO();<br />
private static String DETAIL_URL = "price.zul";<br />
<br />
public void onCreate$main(){ <br />
itemList.setSelectedIndex(0); <br />
Events.postEvent(new Event(Events.ON_SELECT, itemList));<br />
}<br />
<br />
public void onSelect$itemList(){<br />
int id = ((Stock)itemList.getSelectedItem().getValue()).getId();<br />
detail.setSrc(DETAIL_URL + "?id=" + id);<br />
} <br />
<br />
public void onChanging$searchBox(InputEvent event) {<br />
String key = event.getValue();<br />
LinkedList item = new LinkedList();<br />
List items = dao.findAll();<br />
<br />
if (key.trim().length() != 0) {<br />
for (Iterator iterator = items.iterator(); iterator.hasNext();) {<br />
Stock st = (Stock) iterator.next();<br />
if (st.getName().toLowerCase()<br />
.indexOf(key.toLowerCase()) != -1)<br />
item.add(st);<br />
<br />
}<br />
itemList.setModel(new ListModelList(item));<br />
} else itemList.setModel(new ListModelList(items));<br />
}<br />
<br />
public List getStocks(){<br />
return dao.findAll();<br />
}<br />
}<br />
</source><br />
<br />
Once the user clicks any Stock in the result, we register onSelect event listener to show the historical prices by reloading the price.zul page.<br />
onSelect$itemList()<br />
<br />
====Showing the result in table and chart====<br />
To show the historical prices of certain stock, in PriceController.java, we get prices data from StockDAO, and create required data model for chart component.<br />
<br />
'''PriceController.java'''<br />
<source lang="java"><br />
public class PriceController extends GenericAutowireComposer {<br />
<br />
private StockDAO dao = new StockDAO();<br />
private CategoryModel cateModel; <br />
private List items;<br />
<br />
public PriceController() {<br />
init();<br />
}<br />
<br />
public void init() {<br />
//get stock id<br />
int id = Integer.parseInt((String) Executions.getCurrent().getParameter("id")); <br />
Stock stock = dao.getStock(id);<br />
items = stock.getPriceItems(); <br />
//create category model for chart<br />
cateModel = new SimpleCategoryModel();<br />
for (Iterator iterator = items.iterator(); iterator.hasNext();) {<br />
Price price = (Price) iterator.next();<br />
cateModel.setValue(stock.getName(), price.getDate(), price.getClose());<br />
}<br />
}<br />
public List getPrices(){<br />
return items;<br />
}<br />
public CategoryModel getCateModel() {<br />
return cateModel;<br />
} <br />
}<br />
</source><br />
<br />
==Server+client Fusion approach==<br />
In addition to the pure server-centric approach, we will illustrate a hybrid approach here. Let us say we want to improve the responsiveness of the search, then we can move the corresponding code to the client. In the following paragraphs, we use search function as an example.<br />
<br />
===Modification of existing code===<br />
To implement search function at client side, first of all, we have to load the stock data to client. We use an include component to load the data source, data.xml, from the server.<br />
<source lang="xml"><br />
<include id="data" src="data.xml" comment="true"/><br />
</source><br />
<br />
Secondly, at the server side, the control code (StockController.java) shall be removed from index.zul since we will implement this function at client side. <br />
<source lang="xml"><br />
<borderlayout id="main"><br />
</source><br />
<br />
In addition, we no longer generate the stock list at the server-side so we remove code related to generating the search result, too.<br />
<source lang="xml"><br />
<listbox id="list" rows="10" width="300px"><br />
</source><br />
<br />
===Client side programming===<br />
To implement the search function at client side, we create an update function in listbox where it generates stock items according to user’s input.<br />
<source lang="xml"><br />
<zk xmlns:w="http://www.zkoss.org/2005/zk/client"><br />
<script src="/zkau/web/js/zk.xml.wpd"/><br />
<br />
....<br />
<listbox id="list" rows="10" width="300px"><br />
<attribute w:name="update"><![CDATA[<br />
(function () {<br />
var data;<br />
function loadData(w) {<br />
var xmlDoc = zk.xml.Utl.parseXML(jq(w).html().replace(/<!--|-->/g, '').trim()),<br />
ids = xmlDoc.getElementsByTagName("id"),<br />
labels = xmlDoc.getElementsByTagName("name");<br />
<br />
data = [];<br />
jq(ids).each(function (i) {<br />
data.push({id: this.firstChild.nodeValue, label: labels[i].firstChild.nodeValue});<br />
});<br />
}<br />
function createItems (listbox, data) {<br />
if (!data.length) return;<br />
jq(data).each(function () {<br />
listbox.appendChild(new zul.sel.Listitem({label: this.label, uuid: this.id}));<br />
});<br />
}<br />
return function (txt) {<br />
txt = txt || '';<br />
if (!data) loadData(this.$f('data'));<br />
this.clear();<br />
createItems(this, jq.grep(data, function (item) {<br />
return item.label.toLowerCase().indexOf(txt.toLowerCase()) != -1;<br />
}));<br />
this.stripe();<br />
};<br />
})()<br />
]]></attribute><br />
</listbox><br />
</source><br />
*zk.xml.Utl.parseXML() is defined inside <code>zk/src/archive/web/js/zk/xml/utl.js</code>. To use it, we have to include its source by <code><script src="/zkau/web/js/zk.xml.wpd"/></code><br />
*$f (id), a way to get fellow component. It is the same as getFellow(id), i.e., an alias of getFellow.<br />
*<nowiki>http://www.zkoss.org/2005/zk/client</nowiki> is the so-called client namespace that tells ZK engines to generate the code at the client-side instead of server-side.<br />
<br />
Then, we register onChanging event listener on textbox to invoke the update function of listbox at clien-side, too. Notice that we have to specify the client namespace (<tt>w:</tt>), since the listener is running at the client.<br />
<source lang="xml"><br />
<textbox id="inp" w:onChanging="this.$f('list').update(event.data.value)"/><br />
</source><br />
<br />
Besides, if we would like to show all stock items in the beginning, we have to invoke update function of listbox component at initialization by registering bind_ function to do the initialization.<br />
<source lang="xml"><br />
<listbox id="list" rows="10" width="300px"><br />
<attribute w:name="bind_"><br />
function (desktop, skipper, after) {<br />
this.$bind_.apply(this, arguments);<br />
var self = this;<br />
after.push(function () {<br />
self.update();<br />
self.firstChild.setSelected(true);<br />
});<br />
}<br />
</attribute><br />
....<br />
</listbox><br />
</source><br />
<br />
===Interacting with server-side components===<br />
So far, we’ve migrated the search function to client-side, the last mile is to communicate with server to update the historical prices of selected stock item. To make sure the onSelect event will be send to server instantly, we simply register the onSelect event at listbox component. Thus, once users click any stock item, the ZK engine will sends an onSelect event to server. <br />
<source lang="xml"><br />
<listbox id="list" onSelect="" rows="10" width="300px"><br />
....<br />
</source><br />
<br />
Next, to handle the onSelect event directly at server, we could implement a service at server side; then, we can update the content of historical price accordingly.<br />
<source lang="xml"><br />
<listbox id="list" onSelect="" rows="10" width="300px"><br />
....<br />
</listbox><br />
<br />
<include id="content" src="price.zul?id=1"/><br />
<zscript><br />
public class MyService implements org.zkoss.zk.au.AuService {<br />
public boolean service(org.zkoss.zk.au.AuRequest request, boolean everError) {<br />
final String cmd = request.getCommand();<br />
if (cmd.equals(Events.ON_SELECT)) {<br />
String uuid = ((List)request.getData().get("items")).get(0);<br />
System.out.println("selected:" + uuid);<br />
content.setSrc("price.zul?id=" + uuid);<br />
return true;<br />
}<br />
return false;<br />
}<br />
}<br />
list.setAuService(new MyService());<br />
</zscript><br />
</source><br />
<br />
==Summary==<br />
In above paragraphs, we demonstrate two different approached to implement the same application using either pure server-side, or a hybrid approach. Whether to use server-centric or client-centric development are developers’ choices, ZK 5 points out a new way to implement Rich Internet Application that developers can leverage both ease of development, and controllability at the same time.<br />
<br />
==Download==<br />
The application could be downloaded [https://sourceforge.net/projects/zkforge/files/Small%20Talks/zk5Client%2BServerFusion.zip/download here]. <br />
<br />
== See Also ==<br />
#[http://books.zkoss.org/wiki/ZK_Client-side_Reference/General_Control ZK5: Client Computing with ZUML]<br />
#[[ZUML Reference/ZUML/Namespaces/Client|Client Namespace]]<br />
#[[Small_Talks/2009/July/ZK_5.0_and_jQuery|ZK 5.0 and jQuery]]<br />
#[[Small_Talks/2009/July/ZK_5.0_and_jQuery_part_2|ZK 5.0 and jQuery part 2]]<br />
#<javadoc directory="jsdoc">zk.Widget</javadoc> -- See the usage of $f(), $n(), bind_, init_, zk.widget.$()<br />
#[http://books.zkoss.org/wiki/ZK_Client-side_Reference Client Side Actions] -- Deprecated since ZK5<br />
<br />
<br />
[[Category:ZK]]<br />
[[Category:Overview]]<br />
[[Category:Small Talk]]<br />
[[Category:Server+Client fusion]]<br />
{{Template:Smalltalk_Footer|<br />
|name=Potix Corp<br />
}}<br />
<br />
<comment>http://docs.zkoss.org/wiki/ZK_5.0_and_Client%2BServer_Fusion</comment></div>Charhttps://www.zkoss.org/_w/index.php?title=Small_Talks/2010/April/Client_Side_Programming&diff=15206Small Talks/2010/April/Client Side Programming2010-12-21T01:40:43Z<p>Char: /* See Also */</p>
<hr />
<div>{{Template:Smalltalk_Author|<br />
|author=Peter Kuo, Engineer, Potix Corporation<br />
|date=April 20, 2010<br />
|version=ZK 5.0 and above<br />
}}<br />
<br />
== Introduction ==<br />
<br />
In ZK 5 we continue to focus on our strong Server-side approach which boosts your productivity but now provides developers the option to control the client side programming. We have dubbed this blending of technology, Server+client Fusion.<br />
<br />
In order to execute application-specific code at the client, ZK introduces the concept of the Client Namespace <ref>For ZK 3.6 and prior, please use [http://books.zkoss.org/wiki/ZK_Client-side_References Client Side Actions] instead.</ref>. With the Client Namespace, developers are able to listen to any client-side event, override ZK methods and execute any custom client-side code.<br />
<br />
----<br />
<references/><br />
<br />
== Before writing JavaScript in a ZUL file ==<br />
<br />
<br />
=== Define ZK Client Namespace ===<br />
In order to write client-side code, you are required to specify the XML namespace which is named http://www.zkoss.org/2005/zk/client. In the following example, you can see the <mp>onClick</mp> event is handled by client side JavaScript.<br />
<source lang="xml"><br />
<button label="client" xmlns:w="http://www.zkoss.org/2005/zk/client" w:onClick="alert('clicked')"/><br />
</source><br />
<br />
=== How to Get Widget Reference in JavaScript ===<br />
<br />
When the client event is invoked, you can reference the widget using <mp>this</mp>. In the below example this refers to the label.<br />
<br />
<source lang="xml"><br />
<window xmlns:w="http://www.zkoss.org/2005/zk/client"><br />
<label value="change me by click" w:onClick="this.setValue('clicked');"/> <br />
</window><br />
</source><br />
<br />
<javadoc directory="jsdoc">zk.widget</javadoc> can retrieve other widgets using the function <mp>$f</mp>. This works in a similar manner as <mp>getFellow</mp>. <br />
<br />
In additions, you can use jQuery to select a DOM element of a widget<ref>Since ZK 5.0.2</ref>. For example <code>jq("@window")</code> will select DOM elements of all window widget. And, <code>jq("$win1")</code> will select DOM elements of all widgets whose ID is <code>win1</code>. (see <javadoc directory="jsdoc">_global_.jq</javadoc>). <br />
<br />
<source lang="xml"><br />
<window xmlns:w="http://www.zkoss.org/2005/zk/client"><br />
<vbox><br />
<label id="labelone" value="click to change"<br />
w:onClick="this.setValue('changed by click label');" /><br />
<br />
<button label="button"<br />
w:onClick="this.$f('labelone').setValue('changed by button');" /><br />
<br />
<html><![CDATA[<br />
<a href="javascript:;" onclick="zk.Widget.$(jq('$labelone')[0]).setValue('changed with jq');">not widget</a><br />
]]></html> <br />
<br />
</vbox><br />
</window><br />
</source><br />
<br />
<code>zk.Widget.$</code> is a utility to return particular zk widget by given id of dom element. (see <javadoc directory="jsdoc">zk.Widget</javadoc>). <br />
<br />
----<br />
<references/><br />
<br />
=== Execute JavaScript After All Widgets Are Loaded ===<br />
Set <code>defer</code> attribute of <code>script</code> to "true", if you want to access widgets. It means deferring the execution of the script codes until the widget is instantiated and mounted. Note that <code>script</code> here is a zk component, not an HTML tag. Similarly, <code>defer</code> here is not in the same context as HTML . More detail at <javadoc>org.zkoss.zul.api.Script</javadoc>.<br />
<source lang="xml"><br />
<script defer="true"><br />
..........<br />
</script><br />
</source><br />
<br />
== Things you can do ==<br />
===Define a Client-side Listener of ZK Widget event===<br />
For example, handle <code>onClick</code> event of a <code>label</code> component's corresponding widget at the client side.<br />
<br />
<source lang="xml"><br />
<window xmlns:w="http://www.zkoss.org/2005/zk/client"><br />
<label value="change me by click" w:onClick="this.setValue('clicked');"/> <br />
</window><br />
</source><br />
<br />
In an event listener, you can access the widget by using <code>this</code> as shown above. In addition, you can access the event (an instance of <javadoc directory="jsdoc">zk.Event</javadoc>) by using <code>event</code>.<br />
<br />
You can find more detail at [[ZK Client-side Reference]] and [http://docs.zkoss.org/wiki/ZK5:_Client_Computing_with_ZUML ZK5: Client Computing with ZUML].<br />
<br />
===Override a Widget Method===<br />
For example, override the <code>setValue</code> implementation of a <code>label</code> widget.<br />
<br />
<source lang="xml"><br />
<window xmlns:w="http://www.zkoss.org/2005/zk/client"><br />
<label><br />
<attribute w:name="setValue"><br />
function (value) {<br />
this.$setValue(value); //call the original method<br />
if (this.desktop) {<br />
this._flag = !this._flag;<br />
this.setStyle('background:'+(this._flag ? 'red':'green'));<br />
}<br />
}<br />
</attribute><br />
</label><br />
</window><br />
</source><br />
<br />
You can find more detail at [[ZK Client-side Reference]] and [http://docs.zkoss.org/wiki/ZK5:_Client_Computing_with_ZUML ZK5: Client Computing with ZUML].<br />
<br />
EL expressions is allowed <ref>EL expressions are allowed since ZK 5.0.2</ref><ref> EL is evaluated when rendering a page. In other words, it is evaluated before sending the JavaScript code to the client for execution later.</ref> to simplify the passing of data from server to client. For example, you could pass a Java bean's property to the client as shown below.<br />
<br />
<source lang="javascript"><br />
w:setValue='function (value) { this.$setValue(value + "${foo.description}")}';<br />
</source><br />
<br />
<references/><br />
<br />
=== Override a Default Widget Method ===<br />
In previous section, we showed how to override method of a particular widget we declared. But how to override the default widget method for all such widgets? We can modify it by overwriting the widget's <code>prototype</code> implementation. The following is a sample to modify the default <code>setValue</code> of <code>label</code><br />
<source lang="xml"><br />
<window xmlns:w="http://www.zkoss.org/2005/zk/client"><br />
<label id="labelone" value="label one"/><br />
<label id="labeltwo" value="label two"/><br />
<script defer="true"><br />
old = zul.wgt.Label.prototype.setValue; <br />
zul.wgt.Label.prototype.setValue = function (){<br />
arguments[0]="modified prototype"+arguments[0];<br />
old.apply(this,arguments);<br />
} <br />
</script><br />
<button label="change" onClick='labelone.setValue((new Date()).toString());labeltwo.setValue((new Date()).toString());'/> <br />
</window><br />
</source><br />
<br />
=== Override a Default Widget Method for Whole Application ===<br />
In additions to specifying the JavaScript code or file in each page, you can configure ZK to load one or more particular JavaScript files.<br />
<br />
First, you have to modify <code>zk.xml</code> to specify a so-called <i>lang-addon</i> XML file. For example,<br />
<br />
<source lang="xml"><br />
<zk><br />
......<br />
<language-config><br />
<addon-uri>/WEB-INF/mylabel-lang-addon.xml</addon-uri><br />
</language-config> <br />
......<br />
</zk><br />
</source><br />
<br />
Then, you can specify the JavaScript files to load with each ZK page in this XML file as follows.<br />
<br />
<source lang="xml"><br />
<?xml version="1.0" encoding="UTF-8"?><br />
<language-addon><br />
<language-name>xul/html</language-name><br />
<javascript src="/mylabel.js" charset="UTF-8"/> <br />
</language-addon><br />
</source><br />
<br />
The content of the JavaScript file, of course, could be anything you want. For example, if you want to customize the behavior of <javadoc directory="jsdoc">zul.wgt.Label</javadoc>, the JavaScript file could be as follows:<br />
<br />
<source lang="javascript"><br />
zk.afterLoad("zul.wgt",function(){<br />
old = zul.wgt.Label.prototype.setValue; <br />
zul.wgt.Label.prototype.setValue = function (){<br />
arguments[0]="lang-addon "+arguments[0];<br />
old.apply(this,arguments);<br />
} <br />
});<br />
</source><br />
<br />
Notice that it is important to use <javadoc method="afterLoad(_global_.String, _global_.Function)" directory="jsdoc">_global_.zk</javadoc> to specify the customization code, since ZK JavaScript packages are loaded only when required. In other words, the customization code has to wait until the package is loaded. In this example, we have to wait for the zul.wgt package being loaded to execute the customization code.<br />
<br />
===Define a New Widget Method===<br />
For example, in [[Small_Talks/2009/July/ZK_5.0_and_Server%2BClient_Fusion|ZK 5.0 and Server+Client Fusion]], we defined an <code>update</code> function for <code>listbox</code><br />
<br />
<source lang="xml"><br />
<zk xmlns:w="http://www.zkoss.org/2005/zk/client"><br />
....<br />
<listbox id="list" rows="10" width="300px"><br />
<attribute w:name="update"><![CDATA[<br />
....<br />
]]></attribute><br />
</listbox><br />
</source><br />
<br />
===Define a DOM Attribute===<br />
<br />
[Since 5.0.3]<br />
<br />
Sometimes we need to specify a DOM attribute that is not generated by a ZK widget. It can be done by use the client-attribute namespace: <cdoe>http://www.zkoss.org/2005/zk/client/attribute"</code>. For example, if you want to generate the onload attribute for the iframe component, then you can do as follows:<br />
<br />
<source lang="xml"><br />
<iframe src="http://www.google.com" width="100%" height="300px"<br />
xmlns:wa="http://www.zkoss.org/2005/zk/client/attribute"<br />
wa:onload="alert(window.location.href)"/><br />
</source><br />
<br />
The generate DOM element will then have an attribute called <code>onload</code>.<br />
<br />
===Specify a Different Widget Class===<br />
<br />
You could specify your own implementation instead of the default widget class (at the client) as follows.<br />
<br />
<source lang="xml"><br />
<zk xmlns:w="http://www.zkoss.org/2005/zk/client"><br />
...<br />
<button w:use="foo.MyButton"/><br />
</zk><br />
</source><br />
<br />
where <code>foo.MyButton</code> is a widget you implement. For example,<br />
<br />
<source lang="javascript"><br />
zk.$package("foo").MyButton = zk.$extends(zul.wgt.Button, {<br />
setLabel: function (label) {<br />
this.$supers("setLabel", arguments);<br />
//do whatever you want<br />
}<br />
});<br />
</source><br />
<br />
=== ''Watch''': ZK Client Engine Event ===<br />
To implement a ZK widget, traditional DOM events are not enough. Therefore, ZK defines extra widget related events like <code>onHide</code>,<code>onFloatUp</code> and system-level events such as '''watch'''. ZK provide its mechanism to fire and listen to '''watch'''.<br />
<source lang="xml"><br />
<window xmlns:w="http://www.zkoss.org/2005/zk/client"><br />
<button label="show" onClick="b1.setVisible(true);" /><br />
<button label="hide" onClick="b1.setVisible(false);" /><br />
<!--<br />
onShow is not called when first time rendering.<br />
It is called while setVisible="false", and then setVisible="true" <br />
--><br />
<button label="if onShow" id="b1"<br />
style="position:relative;zoom:1"><br />
<attribute w:name="onShow"><br />
alert("listened to onShow");<br />
</attribute><br />
<attribute w:name="bind_"><br />
function () { this.$bind_(); zWatch.listen({onShow: this});}<br />
</attribute><br />
</button><br />
</window><br />
</source><br />
<references/><br />
<br />
=== Use Third Party JavaScript Library ===<br />
[[Small_Talks/2009/July/ZK_5.0_and_jQuery_part_2|ZK 5.0 and jQuery part 2]] demonstrates how to utilize [http://jqueryui.com jQuery UI Tools] for low-level interaction, animation and more.<br />
<br />
=== Listen to DOM event ===<br />
For more sophisticated control, you can listen to DOM events. The following example demonstrates two different ways to handle the <code>onblur</code> event. <br />
<source lang="xml"><br />
<window title="listen dom event" border="normal"<br />
xmlns:w="http://www.zkoss.org/2005/zk/client"><br />
<textbox value="onBlur to alert" w:onBlur="alert('onBlur by zk')" /><br />
<textbox value="onblur to alert"><br />
<attribute w:name="bind_"><br />
function () { <br />
this.$bind_(); <br />
jq(this).bind('blur',function(event){alert('blurred by jquery')});<br />
}<br />
</attribute><br />
</textbox><br />
</window><br />
</source><br />
<br />
=== Animation ===<br />
Please visit [http://www.zkoss.org/zkdemo/userguide/ ZK Live Demo] and search for "animations". The following is a simplified example.<br />
<source lang="xml"><br />
<zk xmlns:w="http://www.zkoss.org/2005/zk/client"><br />
<button label="slideDown"<br />
w:onClick="jq(this.$f('t')).hide().slideDown()" /><br />
<div id="t"><br />
<button label="target" /><br />
</div><br />
</zk><br />
</source><br />
<br />
* Since 5.0.2, there is an alternative way to look for a fellow:<br />
<br />
<source lang="javascript"><br />
this.$f().fellowId<br />
</source><br />
<br />
=== Communicate to Server ===<br />
<javadoc directory="jsdoc">_global_.zAu</javadoc> is an utility to communicate with the server. In other words, it handles AU requests and responses. The following example sends a customized <code>onUser</code> event to the server.<br />
<br />
<source lang="xml" ><br />
<window><br />
<html onUser='l.value ="onUser "+org.zkoss.lang.Objects.toString(event.data)'><![CDATA[<br />
<a href="javascript:;" onclick="zAu.send(new zk.Event(zk.Widget.$(this), 'onUser',[1,2]));">onUser with [1, 2]</a><br />
]]></html> <br />
<label id="l"/> <br />
</window><br />
</source><br />
<br />
== Summary ==<br />
The ability to do client side programming allows developers to easily access and control ZK widgets. ZK retains its server-centric philosophy for productivity but enhances the controllability at client side with this capability; making it just as customizable as any client centric framework. The possibilities are limiteless.<br />
<br />
== Download ==<br />
I've created a project named [http://code.google.com/p/zk-sample/ zk-sample] host on google code. The related sample code can be found on its repository.<br />
<br />
== See Also ==<br />
*[[ZK Client-side Reference/General Control|ZK Client-side Reference]]<br />
#[[Small_Talks/2009/July/ZK_5.0_and_Server%2BClient_Fusion|ZK 5.0 and Server+Client Fusion]]<br />
#[[Small_Talks/2009/July/ZK_5.0_and_jQuery|ZK 5.0 and jQuery]]<br />
#[[Small_Talks/2009/July/ZK_5.0_and_jQuery_part_2|ZK 5.0 and jQuery part 2]]<br />
#[http://books.zkoss.org/wiki/ZK_Client-side_Reference/General_Control ZK5: Client Computing with ZUML]<br />
#<javadoc directory="jsdoc">_global_.jq</javadoc> -- jQuery selector for ZK widget.<br />
#<javadoc directory="jsdoc">zk.Widget</javadoc> -- See the usage of $f(), $n(), bind_(), $()<br />
#[[ZK Client-side Reference/Notifications/Client Activity Watches|Client Activity Watches]] -- onShow, onHide in ZK5<br />
#[http://www.zkoss.org/javadoc/latest/jsdoc/ JavaScript API] -- Documentation for ZK JavaScript API.<br />
#[http://www.zkoss.org/forum/listComment/12420 Customizing Error Box] -- from Forum<br />
#[http://www.zkoss.org/forum/listComment/12445 How to position image after label text on each tab of tabbox?] -- from Forum, modify domContent_ is a good way to customize a little bit.<br />
<br />
[[Category:Small Talk]]<br />
{{Template:CommentedSmalltalk_Footer|<br />
|name=Potix Corporation <br />
}}</div>Charhttps://www.zkoss.org/_w/index.php?title=ZK_Component_Reference/Essential_Components/Script&diff=15205ZK Component Reference/Essential Components/Script2010-12-21T01:40:00Z<p>Char: /* Use Cases */</p>
<hr />
<div>{{ZKComponentReferencePageHeader}}<br />
<br />
= Script =<br />
*Demonstration: [http://www.zkoss.org/zkdemo/effects/upload_effect Script]<br />
*Java API: <javadoc>org.zkoss.zul.Script</javadoc><br />
*JavaScript API: <javadoc directory="jsdoc">zul.utl.Script</javadoc><br />
*Style Guide: N/A<br />
<br />
= Employment/Purpose =<br />
The script component is used to specify the script codes running at the browser. Notice that, unlike zscript, the script codes are running at the browser. They are usually written in JavaScript which is supported by the most of browsers. The simplest format is as follows.<br />
<br />
==Alternatives==<br />
<br />
Instead of using the script component, you could use [[ZUML_Reference/ZUML/Processing_Instructions/script|the script directive]] instead. It does not support defer, but it is more efficient since no component is created.<br />
<br />
<source lang="xml"><br />
<?script src="~./js/zk.debug.wpd"?><br />
<?script content="jq.IE6_ALPHAFIX='.png';"?><br />
</source><br />
<br />
where the first statement loads the debug utility and the second generates JavaScript code snippet directly.<br />
<br />
Another alternative is HTML SCRIPT. For example, we could define global variables and functions as follows<br />
<br />
<source lang="xml"><br />
<script xmlns:n="native"><!-- use the native namespace --><br />
var a_global_variable;<br />
function a_global_function () {<br />
alert("native script");<br />
}<br />
alert("you can not access this as widget but evaluated immediately");<br />
</script><br />
</source><br />
<br />
= Example =<br />
<br />
[[Image:ZKComRef_Script_Example.png ]] <br />
<br />
<syntax lang="xml" ><br />
<zk><br />
<window id="win"><br />
<button label="change color" onClick='Clients.evalJavaScript("myfunc()")' /><br />
</window><br />
<script type="text/javascript"><br />
function myfunc() {<br />
jq("$win").css("backgroundColor", "blue");<br />
}<br />
</script><br />
</zk><br />
</syntax><br />
<br />
=Defer the Evaluation=<br />
<br />
By default, the specified JavaScript code will be evaluated as soon as the page is loaded. There is an attribute called defer. By specifying true, the JavaScript code won't be evaluated until all widgets are created and bound to the DOM tree.<br />
<br />
<syntax lang="xml"><br />
<textbox id="inp"/><br />
<script defer="true"><br />
this.$f("inp").setValue("initialized");<br />
</script><br />
</syntax><br />
<br />
The defer attribute can be used with a JavaScript file as shown below. Then, the JavaScript file will be loaded after all widgets are created and bound to the DOM tree.<br />
<br />
<syntax lang="xml"><br />
<script src="/js/foo.js" defer="true"/><br />
</syntax><br />
<br />
=Supported Events=<br />
<br />
{| border="1" | width="100%"<br />
! <center>Name</center><br />
! <center>Event Type</center><br />
|-<br />
| None<br />
| None<br />
|}<br />
*Inherited Supported Events: [[ZK_Component_Reference/Base_Components/AbstractComponent#Supported_Events | AbstractComponent]]<br />
<br />
=Supported Children=<br />
<br />
*NONE<br />
<br />
=Use Cases=<br />
<br />
{| border='1px' | width="100%"<br />
! Version !! Description !! Example Location<br />
|-<br />
| 5.0<br />
| Overview and Tutorial<br />
|[[Small_Talks/2010/April/Client_Side_Programming |Client Side Programming]]<br />
http://books.zkoss.org/wiki/ZK_Client-side_Reference/General_Control<br />
|}<br />
<br />
=Version History=<br />
{{LastUpdated}}<br />
{| border='1px' | width="100%"<br />
! Version !! Date !! Content<br />
|-<br />
| &nbsp;<br />
| &nbsp;<br />
| &nbsp;<br />
|}<br />
<br />
{{ZKComponentReferencePageFooter}}</div>Charhttps://www.zkoss.org/_w/index.php?title=ZK_Developer%27s_Reference/Performance_Tips/Specify_Stubonly_for_Client-only_Components&diff=15204ZK Developer's Reference/Performance Tips/Specify Stubonly for Client-only Components2010-12-21T01:39:06Z<p>Char: /* Client-side Programming */</p>
<hr />
<div>{{ZKDevelopersReferencePageHeader}}<br />
<br />
__TOC__<br />
<br />
= Overview =<br />
[since 5.0.4][ZK EE]<br />
<br />
It is common that the states of some components are not required to maintain at the server. A typical example is that an application might use some components, such as <tt>hbox</tt>, for layout and won't access it again after rendered. To minimize the memory footprint, ZK supports a special property called <tt>stubonly</tt> (<javadoc method="setStubonly(java.lang.String)">org.zkoss.zk.ui.Component</javadoc>). Once specified with <tt>true</tt>, its states won't be maintained at the server (and all states are maintained at the client). For example,<br />
<br />
<syntax lang="xml"><br />
<hbox stubonly="true"><br />
</hbox><br />
</syntax><br />
<br />
* Notice this feature is available since ZK 5.0.4 EE.<br />
<br />
== Values of Stubonly: true, false and inherit ==<br />
<br />
The default value of the <tt>stubonly</tt> property is <tt>inherit</tt>. It means the value is the same as its parent's, if any, or <tt>false</tt>, if no parent at all. Thus, if a component's <tt>stubonly</tt> is specified with <tt>true</tt>, all its descendants are stub-only too, unless <tt>false</tt> is specified explicitly. For example, in the following snippet, only <tt>textbox</tt> is <i>not</i> stub-only, while <tt>hbox</tt>, <tt>splitter</tt>, <tt>listbox</tt>,<br />
<tt>listitem</tt> and labels are all stub-only.<br />
<br />
<syntax lang="xml"><br />
<hbox stubonly="true"><br />
a stub-only label<br />
<textbox stubonly="false"/><br />
<splitter/><br />
<listbox><br />
<listitem label="also stubonly"/><br />
</listbox><br />
</hbox><br />
</syntax><br />
<br />
= Limitation of Stub Components =<br />
<br />
When a component is stub only, it will be replaced with a special component called a stub component (<javadoc>org.zkoss.zk.ui.StubComponent</javadoc>) after rendered. In additions, adjacent stub components might be merged to minimize the memory further. Thus, the application shall not access the component again at the server, if it is specified as stub only.<br />
<br />
== Invalidation ==<br />
<br />
While a stub component cannot be invalidated directly, it is safe to invalidate its parent. ZK will rerender all non-stub components and retain the states of stub components at the client. For example, in the following snippet, it is safe to click the <tt>invalidate</tt> button. For end user's point of view, there is no difference whether <tt>stubonly</tt> is specified or not.<br />
<br />
<syntax lang="xml"><br />
<window><br />
<button label="self.parent.invalidate()"/><br />
<vbox stubonly="true"><br />
stubonly <textbox/><br />
</vbox><br />
</window><br />
</syntax><br />
<br />
== Event Handling ==<br />
<br />
ZK will preserve all registered event listeners and handlers, when converting a stub-only component to a stub component. In other words, the listener will be called if the corresponding event is fired. However, since the original component no longer exists, the event is fired in the most generic format: an instance of <javadoc>org.zkoss.zk.ui.event.Event</javadoc>, rather than a derived class.<br />
<br />
For example, in the following snippet, "org.zkoss.zk.ui.event.Event:onChange" will be generated to <tt>System.out</tt>.<br />
<br />
<syntax lang="xml"><br />
<textbox stubonly="true" onChange='System.out.println(event.getClass().getName()+":"+event.getName())'/><br />
</syntax><br />
<br />
In addition, the target (<javadoc method="getTarget()">org.zkoss.zk.ui.event.Event</javadoc>) is the stub component rather than the original one (<tt>text</tt>).<br />
<br />
== Client-side Programming ==<br />
<br />
The client-side widget of a component is the same no matter if it is stub only. Thus, the application can have the full control by registering the client side event listener, such as<br />
<br />
<syntax lang="xml"><br />
<textbox stubonly="true" w:onChange="doSomething(this.value)" xmlns:w="client"/><br />
</syntax><br />
<br />
In other words, stub-only components behave the same at the client.<br />
<br />
Refer to [[Small_Talks/2010/April/Client_Side_Programming |Client Side Programming]] and [http://books.zkoss.org/wiki/ZK_Client-side_Reference/General_Control Client Computing with ZUML] for more information.<br />
<br />
=Version History=<br />
<br />
{| border='1px' | width="100%"<br />
! Version !! Date !! Content<br />
|-<br />
| &nbsp;<br />
| &nbsp;<br />
| &nbsp;<br />
|}<br />
<br />
{{ ZKDevelopersReferencePageFooter}}</div>Char