Plugin: ZK Enterprise Components

• Creator: James Chu
• SPONSOR: zkoss.org
• iDempiere version: 12 and 13
• License: The plugin source code is licensed under the GNU GPLv2 or later and contains no ZK binaries. See Licensing for what that means in practice.
• Source: GitHub repository
• Related: Plugin: ZK Charts Components and Plugin: Keikai Spreadsheet Enterprise Component – the same fragment pattern, different ZK products.

Description

• iDempiere ships ZK CE as its UI framework. This plugin makes the ZK Enterprise (EE) component set available to the iDempiere runtime as an optional OSGi add-on, without modifying iDempiere core.
• It is the reference implementation of the fragment + plugin pattern that the other ZK plugins for iDempiere follow. If you are writing your own plugin around any commercial ZK product, start here: the repository's plugin creation guide is the fullest write-up of the pattern.
• Install and uninstall it like any other iDempiere OSGi plugin. Nothing in the iDempiere repository or in the application dictionary is changed.

What ZK EE adds on top of ZK CE

• The fragment attaches these ZK EE modules to the runtime. Each one contributes its own lang-addon.xml, so its components and shadow elements become usable in any ZUL once the fragment is installed.

Module	What it brings
zkex	The ZK PE component set – for example <timepicker>, and the extended layout and input components
zkmax	The ZK EE component set and server-side features on top of zkex
zuti	Shadow elements: <if>, <forEach>, <choose>/<when>/<otherwise>, <apply> – template logic in the ZUL instead of in Java
client-bind	Client MVVM – the same MVVM binding annotations evaluated in the browser rather than on the server, so simple binding updates cost no round trip
za11y	The ZK accessibility module

• ZK EE requires a commercial licence or subscription from ZK; see Licensing. The build here uses Evaluation artifacts so the plugin can be tried at no cost.

Requirements

Item	Version
iDempiere	13 (use the v12 branch for iDempiere 12)
Java runtime	17
ZK CE bundled with iDempiere	10.0.1
ZK EE	10.0.1-Eval (deliberately the same version as the ZK CE in the host, so the EE jars sit on a matching core)

iDempiere 13 highlights

• Added client-bind, zuti and za11y to the fragment, alongside zkex and zkmax.
• Enabled Client MVVM through fragment-level ZK configuration – the fragment's src/metainfo/zk/zk.xml registers org.zkoss.clientbind.BinderPropertiesRenderer as a listener, so no per-plugin configuration is needed.
• Disabled ZK EE's inaccessible-widget-block service (org.zkoss.zkmax.au.IWBS.disable = true) in the same file, for compatibility with the iDempiere login flow.

Components

Bundle	Kind	Purpose
org.idempiere.zkee.comps.fragment	OSGi fragment	Attaches the ZK EE jars to the class loader of org.adempiere.ui.zk, and carries the EE-specific zk.xml. Required.
org.idempiere.zkee.comps.example	Plugin	An example form that proves the EE components resolve and render at runtime. Optional.

Why a fragment is needed

• ZK discovers its components through metainfo/zk/lang-addon.xml, which is loaded with the class loader of the bundle ZK runs in – in iDempiere that is org.adempiere.ui.zk.
• OSGi bundles have isolated class loaders, and a fragment is the only standard way to add resources to another bundle's class loader without modifying it.
• That is why the ZK EE jars are delivered as a fragment of org.adempiere.ui.zk rather than embedded in a plugin.

Installation

• Obtain the two jars – see Building from source.
• The order matters – a fragment only takes effect after its host bundle is re-resolved, which means a restart:
  1. Install org.idempiere.zkee.comps.fragment through the Felix Web Console (/osgi/system/console/bundles).
  2. Restart the iDempiere runtime. This is not optional: besides re-resolving the host, ZK reads the fragment's zk.xml library properties during web application initialisation, so hot-deploying alone will not enable Client MVVM.
  3. Install org.idempiere.zkee.comps.example if you want the example form.
  4. On the Bundles page, confirm the fragment shows as Fragment and the example plugin as Active – not merely Resolved.
  5. Log out and back in, so the menu tree is rebuilt with the entry the plugin adds.
• The example plugin registers its menu entry through a 2Pack applied by its bundle activator; no manual import is required.

Usage

Verifying the installation

• Open ZK EE Components Example from the menu. It exercises three different things at once, and each one proves a different jar resolved:

What you see	What it proves
A time picker	zkex resolved and its lang-addon.xml was discovered through the host
Server MVVM – a datebox and label bound through BindComposer	ZK CE binding still works normally alongside the fragment
Client MVVM – the same two components bound through ClientBindComposer	client-bind resolved and the fragment's zk.xml listener was picked up. If this half is dead while the server half works, the runtime was not restarted
A Shadow section rendered by <if test="true">	zuti resolved

Using ZK EE components in your own plugin

• In ZUL – nothing to declare. Once the fragment is installed, the EE components and shadow elements are part of the xul/html language for every ZUL in the runtime, including ZULs inside your own bundle. Your bundle needs only the usual iDempiere requirements:

Require-Bundle: org.adempiere.base;bundle-version="13.0.0",
 org.adempiere.ui.zk;bundle-version="13.0.0",
 zk;bundle-version="10.0.1",
 zul;bundle-version="10.0.1"

• In Java – one extra step. The fragment declares no Export-Package, because the example plugin only uses the EE components from ZUL. The moment you want to import org.zkoss.zkex... or org.zkoss.zkmax... in Java, you must add those packages to the fragment's Export-Package and rebuild it – otherwise the classes are on the host's class loader but not visible to your bundle. (The ZK Charts fragment does export its packages, and is the example to copy.)
• The rule that follows from the design. You compile against a jar on the Maven classpath but resolve at runtime through the fragment – so your bundle will not resolve unless the fragment is installed and the runtime has been restarted since. A bundle stuck at Resolved or Installed is almost always this.
• A full walkthrough of building such a plugin from scratch – manifests, pom.xml, activator, 2Pack, deployment – is in the repository's plugin creation guide, and the upgrade guide covers moving an existing plugin to a new iDempiere release.

Troubleshooting

Symptom	Cause	Fix
Bundle stays Resolved or Installed, never Active	The fragment is missing, or the runtime was not restarted after installing it	Install the fragment, then restart
The fragment itself stays Resolved	Expected – fragments never become Active	No action needed; check that it is listed as a fragment of org.adempiere.ui.zk
Server MVVM works but Client MVVM does not	The fragment's zk.xml was not read; ZK loads library properties at web application initialisation	Restart the web application, not just the bundle
ClassNotFoundException: org.zkoss.zkex... from your own plugin	Java-level access needs the package on the fragment's Export-Package	Add the package to the fragment manifest and rebuild the fragment
ZK component not found in a ZUL	The corresponding jar is not in Bundle-ClassPath, or its lang-addon.xml was not discovered	Check that every jar listed in Bundle-ClassPath actually exists under lib/ in the built fragment

Licensing

• The plugin source is GPLv2 or later and contains no ZK binaries. Nothing in the iDempiere repository is modified.
• ZK EE is a commercial product and is not covered by the plugin's open-source licence. The build pulls the jars from ZK's Evaluation repository, so everything on this page can be tried at no cost; a valid licence or subscription must be obtained separately before production use.
• What uninstalling gives back. Removing the fragment returns the runtime to plain ZK CE, and iDempiere core is untouched either way. Be aware this is not as free as it is for Plugin: ZK Charts Components, which falls back to core rendering: any form you wrote against an EE component stops working when the fragment goes, so plan that boundary deliberately.
• To obtain a licence or ask about terms, contact the ZK Framework team at [email protected] or see the ZK product page.

Building from source

• Requires Git, Maven, JDK 17 and a local p2 repository built from iDempiere core. The full procedure, including the target-platform fix-ups, is in the repository's step-by-step guide.

git clone --branch release-13 https://github.com/idempiere/idempiere.git idempiere
cd idempiere && mvn clean install

git clone https://github.com/zkoss-demo/zkoss-idempiere-ee-plugin.git
cd zkoss-idempiere-ee-plugin
mvn clean verify -f parent-repository-pom.xml

• The first build must have network access: the ZK EE jars come from the ZK Evaluation repository, not from Maven Central.
• Every jar named in the fragment's Bundle-ClassPath must exist under lib/ after the build – the Maven validate phase copies them there. If you add a module, keep pom.xml, MANIFEST.MF and build.properties in step.

Feedback

• If you would like to discuss specific use cases or workflows for this plugin, we’d be happy to hear from you. Please feel free to contact the ZK Framework team at [email protected].
• If you want to provide additional comments, please use:
  • General support forum: iDempiere Community
  • Issues for this plugin: GitHub Issues

See also

• Other ZK plugins for iDempiere:
  • Plugin: ZK Charts Components
  • Plugin: ZK Pivottable Components
  • Plugin: Keikai Spreadsheet Enterprise Component
• Plugin development:
  • Developing Plug-Ins - Get your Plug-In running
  • Make Zk WebApp OSGi
• ZK · ZK live demo