ZK 6: Upgrade Notes
ZK Team, Potix Corporation
February 14, 2012
ZK 6
Overview
In additions to new features, ZK 6 also cleans up some API that are confusing, redundant or over complicated. The effort to upgrade depends on what features your application uses. Many of them shall run without modification. It is suggested to re-compile the applications and replace the code that use the deprecated API.
The must-do upgrade steps
First, you have to upgrade the following addons if you ever use them:
zel.jar
replaceszcommons-el.jar
to support EL 2.2. It is shipped with ZK's binary distribution, so just copy it from thedist/lib
folder.[1]. Though optional, it is suggested to removezcommons-el.jar
.- ZK JSP 2.0 or later. Download here.
- ZK Calendar 2.1.1 or later. Download here.
- ZK CKeditor 3.6.0.1 or later. It is shipped with ZK's binary distribution, so just copy it from the
dist/lib/zkforge
folder.
Second, you have to remove breeze.jar
since breeze has become the standard theme. Without removing the old breeze.jar
, it might cause some CSS conflicts.
Third, search if you implemented any renderer in zscript, such as ListitemRenderer, RowRenderer and TreeitemRenderer[2]. If so, please refer to this section for how to fix them.
Fourth, If you ever use the autowiring feature of macro components (i.e., wiring child components to data members automatically), please refer to this section for how to fix it.
Finally, clean and compile your project. If there is a compile error, please check the corresponding section below. On the other hand, it is OK to ignore the warnings of deprecation and generic-type checks, though it is a good idea to fix them too.
- ↑ If you prefer EL 1.1 (i.e., backward compatible with ZK 5), please remove
zel.jar
and copyzcommons-el.jar
to your project instead. Notice that ZK Bind (our new generation of data binding) utilizes EL 2.2 to support two-way binding, so don't usezcommons-el.jar
if you want to use the new data binding.- ↑ If you implement them in pure Java, the compiler will identify the errors for you.
API that are changed
org.zkoss.zk.zul.api.* are removed
The component's API interfaces (org.zkoss.zk.ui.api.*
, org.zkoss.zul.api.*
...) are removed[1]. Please replace them with the concrete classes. For example, use org.zkoss.zul.Window
instead of org.zkoss.zul.api.Window
.
You could use the search-and-replace or refactor feature in your IDE to replace the package name. Here is an example that uses Eclipse to replace the package name.
- ↑ The reason to remove them is they cause more confusion than the abstraction benefit. In additions, they are costly and error-prone to maintain.
The render method of ListitemRender, RowRender, TreeitemRender and ComboitemRender are changed
For sake of performance and consistency, the render method of ListitemRenderer, RowRenderer, ComboitemRenderer, TreeitemRenderer are changed. An additional argument called index was introduced. You can use it instead of accessing the component's index (such as Listitem.getIndex() for better performance.
Notice that while Java compiler will detect the changes automatically, you have to maintain zscript manually if you have implemented them in zscript.
addSelection/removeSelection methods of Selectable are changed
For ease of understanding, addSelection method of Selectable has been changed to addToSelection(), while removeSelection method of Selectable has been changed to removeFromSelection().
org.zkoss.zk.ui.util.Initiator is simplified
For easy extension and better consistency[1], the Initiator class now has only one method called doInit
. The doAfterComposer
, doCatch
and doFinally
methods are moved to InitiatorExt. In other words, if you'd like to override any of these methods, your initiator has to implement both Initiator and InitiatorExt.
org.zkoss.xel.FunctionMapper is simplified
For easy extension[1], the getClassNames
and resolveClass
methods of the org.zkoss.xel.FunctionMapper
class are removed. On the other hand, org.zkoss.xel.FunctionMapperExt
was introduced to have these methods. In other words, you'd like to implement any of these methods, you have to implement both FunctionMapper
and FunctionMapperExt
.
- ↑ The
getClassNames
andresolveClass
methods are useful only for special evaluators, such as MVEL and OGNL
i3-label.properties is renamed to zk-label.properties
To avoid confusion, the default properties file for the internationalization labels is renamed to zk-label.properties
[1].
- ↑ For backward compatibility,
i3-label.properties
will be loaded ifzk-label.properties
is not found.
The selection and opened objects are maintained in model, not UI
In ZK 5, we didn't draw a clear line between when to access component and when to access the model. For example, there is no easy way to change the selection in Java[1], and two components can't share the same model. To make the code more solid and the spec more flexible, since ZK 6, all information, including selection, opened objects, sorting and multiple selection, shall be maintained in the model, and the application shall only access the model. It is the component's job to update the change of the model to UI, while the implementation of the model has to fire the event to notify the change.
For example, the application shall invoke Selectable.addToSelection(E) (of the model) to add the selection, invoke Selectable.getSelection() to retrieve the selection, and invoke Sortable.sort(Comparator, boolean) (of the model) to sort the data rather than manipulating the component directly. Of course, it also means your implementation of the model, if any, has to fire the data change event correctly.
To simplify the upgrading from ZK 5, Listbox.setMultiple(boolean) and Tree.setMultiple(boolean) can be called and the state will be reflected to the model automatically (of course, changing the multiple
state of the model will be reflected to the UI too). However, the calling sequence is important. For example, if your old model doesn't maintain the multiple
state, you shall assign model first and then multiple, such as
<listbox model="${foo}" multiple="true">
...
- ↑ It is also important to note that the selection and other information in the component might not be complete because of render-on-demand. For example, if the first and the last item are both selected, then Listbox.getSelectedItems() might return only the first item, since the last item is not loaded and rendered (for sake of better performance). Thus, the application shall access the model where all data are available.
The selection and open contract between Tree and TreeModel become TreeSelectableModel and TreeOpenableModel
For better performance, TreeSelectableModel and TreeOpenableModel are introduced to replace Selectable and Openable for maintaining the selection and open objects. In short, they depend on the tree path rather than the data objects.
For backward compatibility, AbstractTreeModel also implements Selectable and Openable. Application is free to access it, though ZK doesn't count on them. However, since their contract is based the data objects, TreeModel.getPath(E) will be called to get the tree path. Thus, make sure your implementation is good if you invoke them a lot.
SimpleTreeModel and SimpleTreeNode are removed
The org.zkoss.zul.SimpleTreeModel
and org.zkoss.zul.SimpleTreeNode
classes are removed[1], and replaced with DefaultTreeModel and DefaultTreeNode.
- ↑ It was deprecated in ZK 5.0.6.
Autowiring of macro components are changed
The default autowiring of data members in a macro component becomes CSS-selector based. In other words, it is the same approach as SelectorComposer does.
If you want to autowire by name convention feature of macro components (i.e., wiring child components to data members automatically), you can specify the library property called org.zkoss.zk.ui.macro.autowire.convention to true
in WEB-INF/zk.xml
.
<library-property>
<name>org.zkoss.zk.ui.macro.autowire.convention</name>
<value>true</value>
<library-property>
On the other hand, if you prefer to use the CSS-selector approach, you can refer to ZK Developer's Reference: Wire Components to upgrade your implementation.
The isClose and setClose methods of GroupsModel are deprecated
To be consistent with the naming of other models, these two methods are replaced with GroupsModel.isGroupOpened(int), GroupsModel.addOpenGroup(int) and GroupsModel.removeOpenGroup(int).
GenericForwardComposer and GenericAutowireComposer won't wire variables defined in zscript and variable resolvers
For sake of better performance, GenericForwardComposer and GenericAutowireComposer won't wire variables defined in zscript and variable resolvers. If you prefer to write them as ZK 5 and earlier does, you could specify the library properties called org.zkoss.zk.ui.composer.autowire.zscript and org.zkoss.zk.ui.composer.autowire.xel to true
.
API returns Iterable instead Iterator
To use with Java 5's for statement, the return type of the following APIs are changed to java.lang.Iterable
:
- Execution:
getHeaders
andgetHeaderNames
- WebApp:
getInitParameterNames
- RichletConfig:
getInitParameterNames
Window, Messagebox and Fileupload won't throw InterruptedException
Window, Messagebox and Fileupload won't throw java.lang.InterruptedException
anymore, since it won't happen if the event processing thread is disabled (default). If the event processing thread is enabled, InterruptedException
will be wrapped with UiException.
addEventListener allows the same listener registered multiple times
Component's addEventListener
now allows the same listener being registered multiple times, and the listener will be called multiple times.
If you prefer to ignore the second registration of the same listener (i.e., backward compatible with ZK 5 and earlier), you could specify a library property called org.zkoss.zk.ui.EventListener.duplicateIgnored
to true
in WEB-INF/zk.xml
.
The return type of Annotation.getAttributes() is changed
The return type is changed from Map<String, String>
to Map<String, String[]>
, since the annotation now allows multiple values per attribute.
UiFactory's newComponent is changed
The newComponent
method of the UiFactory is changed. In additions, two new methods newComposer
and newServerPush
were introduced to allow developers have more control of the instantiations.
The support of Comet is available in PE
The support of Comet is available in ZK PE, while ZK EE supports Servlet 3 Asynchronous Processing-based Comet.
Component's newChildren and newExtraCtrl are removed
The newChildren
and newExtraCtrl
methods of AbstractComponent are removed since they are redundant. Please override the getChildren
and getExtraCtrl
instead.
Component's setVariable is removed
Component's setVariable
method is removed[1]. Please use Component.setAttribute(name, value, SPACE_SCOPE)
instead. In other words, you could store the variables in the attributes of the space owner (Component.getSpaceOwner()).
- ↑ It was deprecated in ZK 5, since we don't maintain a separate namespace for each ID space.
ListX, TreeArray and CheckableTreeArray are removed
The org.zkoss.util.ListX
, org.zkoss.util.TreeArray
and org.zkoss.util.CheckableTreeArray
are removed. Please use java.util.LinkedList
or java.util.ArrayList
instead.
If you need them, please copy the code from ZK 5's Git repository.
ClassWebServlet and several other never-used classes are removed
The following classes are removed, since they are never used and introduce unnecessary complication to API:
org.zkoss.web.util.resource.ClassWebServlet, org.zkoss.web.servlet.ForwardServlet, org.zkoss.web.servlet.http.HttpServlet, org.zkoss.io.PrintWriterX, org.zkoss.io.FileWatchdog, org.zkoss.media.Photo, org.zkoss.lang.WarningException, org.zkoss.lang.Warning, org.zkoss.util.InvalidValueException, org.zkoss.util.ModificationException, org.zkoss.util.ScalableTimer, org.zkoss.util.ScalableTimerTask, org.zkoss.util.ScalableTimerTask, org.zkoss.util.ThreadLocalCache
If you need them, please copy the code from ZK 5's Git repository.
The configuration of logging is changed
ZK core's logging is still based on Java standard logging. However, the configuration is simplified and changed. Please refer to ZK Developer's Reference: Logger if you need it.
API that are deprecated
ListModelExt, TreeModelExt and GroupsModelExt are deprecated
The org.zkoss.zul.ListModelExt
and org.zkoss.zul.TreeModelExt
interface are deprecated, and replaced with Sortable. Also, org.zkoss.zul.GroupsModelExt
is deprecated and replaced with GroupsSortableModel.
org.zkoss.zk.ui.event.Express is deprecated
The org.zkoss.zk.ui.event.Express
interface is deprecated. Please use the Component.addEventListener(int, String, EventListener) instead, and assign the priority as 1000.
HTMLs, StyleSheet and JavaScript are moved
The HTMLs
, StyleSheet
and JavaScript
classes are moved to the package called org.zkoss.html
.
Notice the previous classes are still available but deprecated (and not found in JavaDoc).
Theme and UI
Breeze is the default theme
The breeze theme has become the default styling, without the need to include breeze.jar
. Please make sure you remove breeze.jar
from your project. On the other hand, the sapphire and silvertail themes are packaged and delivered as they were in ZK 5. Of course, you have to upgrade to the version shipped with ZK 6's binary distribution.
Tablechildren and Columnchidlren support any child
Tablechildren and Columnchildren support any kind of child components, not limited to Panel. Thus, if you don't need the feature of Panel, you could remove it from your UI to make the layout structure simpler.
Groupbox's zclass is renamed to z-groupbox
To be consistent, the zclass of Groupbox's default mold is renamed to z-groupbox
(it was called z-fieldset
in ZK 5). The zclass of the 3d mold is renamed to z-groupbox-3d
(it was called z-groupbox
).
To be consistent with other naming, we rename their z-class name as follows. Please update your CSS file if you ever override them.
z-menu-item -> z-menuitem
z-menu-popup -> z-menupopup
z-menu-separator -> z-menuseparator
z-panel-children -> z-panelchildren
Some nested CSS class names of calendar are changed
To avoid confusion with other components, the CSS class names must follow the same rule: z-class-xxxx
. We fix calendar to follow this rule. Please update your CSS file if you ever override them.
.z-weekend -> .z-calendar-caldow .z-calendar-wkend
.z-weekday -> .z-calendar-caldow .z-calendar-wkday
.z-outside -> .z-calendar-outside
The vflex and hflex of Panelchildren are deprecated
The hflex/vflex properties of Panelchildren are determined by its parent Panel's hflex/vflex properties. The setHflex
and setVflex
methods of Panelchildren will throw UnsupportedOperationException. In other words, you shall control Panel rather than Panelchildren.
The hflex and width of Treerow, Rows... is deprecated
As the sizing of Grid/Listbox/Tree are controlled by Grid/Listbox/Tree and the header components (such as Treecol, Listheader and Column). By others, the hflex and width properties of them are irrelevant. Their setHflex
and setWidth
methods are deprecated. These components include:
Treeitem, Treerow, Treecell, Treechildren, Treecols, Treefoot, Rows, Columns, Row, Cell, Foot, Listitem, Listcell, Listhead, Listfoot.
Messagebox's template is changed
Messagebox's template (i.e., ~./zul/html/messagebox.zul
) is changed to support the new features such as reordering and custom labels. If you ever customized it, please refer to the source code for the details.
iZUML uses #{...} to represent an expression
The format of the expression used in iZUML (client-side ZUML) has become #{...}
, such that it is easier to embed in a ZUML page where ${...}
is used. In additions, iZUML is supported by ZK CE since ZK 6.
The library property called org.zkoss.zul.Separator.spaceWithMargin is removed
We don't support the margin approach found in ZK 2 any more.
Optional but suggested
Use ZK Bind instead of old data binding
ZK Bind (org.zkoss.bind.*
) is our new generation of data binding. It is more powerful and controllable, though the first version of data binding (org.zkoss.zkplus.databind.*
) is still maintained. For more information, please refer to Envisage ZK 6: The Next Generation Data Binding System and ZK Developer's Reference: Data Binding.
Notice that ZK Bind supports both data binding and MVVM. Data binding, as you are already familiar with, minimizes the effort to access database, while MVVM introduces additional abstract layer isolating the view dependence from the controller.
Use SelectorComposer instead of GenericForwardComposer
The SelectorComposer class provides more control how to wire the members. It is generally recommended. Of course, some might find GenericForwardComposer's wire-by-convention is more convenient to use, and it is still supported.
ZK Bind Since 6.0.2
Accessing children and custom attribute in @Init method is no longer supported
The invocation of current @Init tagged method in VM class is moved from BindComposer's doAfterCompose to earlier stage doBeforeComposeChildren, which means it's no longer applicable if you want to initiate your VM based on host component scope (ex: child components and custom attributes) in an @Init tagged method. Instead you should use @AfterCompose tagged method which is newly introduced since this version.
AnnotateBinder API definition change
Since 6.0.2, compare to old AnnotateBinder#init() current AnnotateBinder#init() will only take care of super#init(), you'll have to call AnnotateBinder#initAnnotatedBindings() separately to initiate and register Bindings based on Zul component's annotation.
Comments
Copyright © Potix Corporation. This article is licensed under GNU Free Documentation License. |