Version Upgrade
Versioning
ZK products follow semantic versioning, where the three digits refer to MAJOR.MINOR.PATCH respectively. In the case where a hotfix is required, a fourth digit is introduced. Except for major (first digit) upgrades, compatibility is generally maintained, or a fall-back mechanism is available.
Upgrade References
An introductory smalltalk is published for every MAJOR and MINOR release. For example New Features of ZK 9.5. The smalltalk highlights the most important changes as well as provides upgrade tips for upgrading to that specific version. View all New Features articles.
A detailed release note containing a list of fixed issues is available for every new release, including hotfixes. For example, ZK 9.0.0 release notes. The full release history can be found here.
An “upgrade notes” section will be included at the end of a release note when needed. The “upgrade notes” section points out API changes or changes that developers will most likely need to take actions accordingly.
You can follow the same naming conventions as the examples provided above to search for the upgrade references you are looking for.
Important/breaking changes
| Version | Description | Reference |
|---|---|---|
| ZK 5.0 | 1. A major architectural change was made in ZK 5, affecting theming, UI creation, and client-side rendering. Upgrading from ZK 2.x or ZK 3.x to ZK 5 requires more effort. 2. Event thread is now disabled by default. You can enable it in zk.xml if you need to use it. |
Release Smalltalk |
| ZK 6.0 | 1. Requires JDK 5 or higher |
Release Smalltalk |
| ZK 6.5 | 1. Introduced Mobile/Tablet support, EE edition will have a different style and behavior on a mobile device. You can turn it off in zk.xml if that's not desired. |
Release Smalltalk |
| ZK 7.0 | 1. Re-implement the theme with new client technologies including CSS3 and LESS, and the DOM structure of components changes a lot. To upgrade a custom theme for an older version, you will need to redo the style customization based on the new theme. Please refer to Upgrade From ZK 6.5. 2. Drop IE6 & IE7 support. |
Custom Style Upgrade Guide |
| ZK 8.0 | 1. A new form binding based on proxy is introduced. If you have been using MVVM org.zkoss.bind.SimpleForm, |
ZK 8 new form binding |
| ZK 8.5 | 1. A new and default theme Iceblue is introduced. The new theme has larger margin and padding from the previous themes. If you are not ready to use the new default theme, you can switch back to the previous themes, or, use ZK 8.6’s compact theme. 2. Drop IE8 support. |
Release Smalltalk |
| ZK 9.0 | 1. ZK 9 requires JDK 8 or later versions. 2. ZK Flex uses CSS 3 Flex instead. You can disable css flex and fall back to the previous implementation if needed. 3. Packaging change: ZK Data binding 1 is moved to "zkplus-legacy"; ZK DSP Library is moved to a new module "zweb-dsp". |
Release Smalltalk |
| ZK 9.1 | 1. The underlying jQuery version has been upgraded from jQuery 1.12 to jQuery 3.5. If you have custom javascript code that relies on jQuery, you may need to update accordingly. | Release Notes |
| ZK 9.5 | 1. Optional libraries(slf4j-jdk14 and closure-compiler-unshaded) are no longer provided by default. You can plugin your preferred libraries if needed. | Release Smalltalk |
| ZK 9.6 | 1. The default desktop ID generator was replaced by a more secured one. If your tests depend on the previous generator, you can set it in system-config. 2. Deprecated the method of isEditionValid() and encodeWithZK() of org.zkoss.zk.fn.ZkFns and core.dsp.tld. |
Release Smalltalk |
Upgrade Process
Upgrading from ZK 5 (or later) to the latest version should be manageable. The steps are:
Specify the version you wish to upgrade to in your maven POM file, or, download corresponding binary files manually and put them into your project. It is important to make sure all ZK jar files are in the same version.
Then, fix any compilation errors and configure required fallback settings by referencing the Upgrade References.