Plugin: ZK Charts Components

• Creator: James Chu
• SPONSOR: zkoss.org
• License: This plugin is licensed under the GNU GPLv2 or later. The plugin source code itself does not include ZK Charts.
• Source: GitHub repository
• Dependencies: This plugin depends on ZK Charts, a commercial product that is not covered by this plugin’s open-source license. Users must obtain a valid license separately for production use.
• Related: Plugin: ZK Pivottable Components – lives in the same repository and builds on this one.

Description

• This plugin enables iDempiere implementors to use ZK Charts components in iDempiere without modifying iDempiere core. It is designed as an optional add-on: you can install/uninstall it as a standard iDempiere OSGi plugin.
• It covers two ways of using ZK Charts:
  1. Globally – replace the chart rendering iDempiere already does, so that every existing dashboard chart, performance goal and chart field is drawn with ZK Charts, without changing a single application dictionary record.
  2. In a dashboard – a sales and inventory dashboard that redraws itself through ZK server push whenever an order or shipment is saved.
• ZK Charts is a commercial product (evaluation is available via ZK download center).

Requirements

Item	Version
iDempiere	13 (use the v12 branch for iDempiere 12)
Java runtime	17
ZK CE bundled with iDempiere	10.0.1
ZK Charts	12.5.0.0-Eval

Components

Bundle	Kind	Purpose
org.idempiere.zkcharts.fragment	OSGi fragment	Attaches ZK Charts to the class loader of org.adempiere.ui.zk. Required by both plugins below.
org.idempiere.zkcharts.renderer	Plugin	The global chart renderer.
org.idempiere.zkcharts.dashboard	Plugin	The live sales dashboard, plus a minimal <charts> ZUL sample.

• The two plugins are independent – install either on its own, or both. Both need the ZK Charts fragment.
• The same repository also contains Plugin: ZK Pivottable Components, which is documented separately.

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 Charts jar is delivered as a fragment of org.adempiere.ui.zk rather than embedded in the plugins.

Features

• Integrate ZK Charts libraries into the iDempiere runtime as an optional add-on.
• Replace iDempiere's built-in chart rendering with ZK Charts, with no application dictionary change.
• Provide example window/form(s) to verify charts render correctly in iDempiere.
• Keep iDempiere core unchanged (plugin-based integration).

Rendering every iDempiere chart with ZK Charts

• org.idempiere.zkcharts.renderer needs no configuration and adds no menu entry. It registers an implementation of the OSGi service IChartRendererService with a higher service ranking than the ones in core, and iDempiere then asks it first.

Implementation	service.ranking
org.idempiere.zkcharts.renderer (this plugin)	100
org.idempiere.zk.billboard.chart (billboard.js, the v13 default)	0
org.adempiere.webui.apps.graph.jfreegraph (JFreeChart, deprecated since v13)	-1

• Everything that draws a chart in the web UI goes through that service, so all of the following change at once:

Consumer	What it draws
DashboardController	PA_DashboardContent chart gadgets
WGraph	PA_Goal performance graphs
WPerformanceIndicator	PA_Goal performance indicators, drawn as a gauge
WChartEditor	Chart fields inside a window

• The data loading is deliberately identical to the core billboard renderer, so existing AD_Chart definitions keep producing exactly the same numbers – only the widget is swapped. What you gain is interactive tooltips, legend toggling, animation and the built-in export menu. Click-to-zoom still opens the underlying records.
• Uninstalling the bundle silently restores the core rendering, and any exception during rendering makes the service return false so that iDempiere falls through to the next renderer rather than showing an empty panel.

Chart type mapping

AD_Chart.ChartType	ZK Charts
Bar / 3D Bar	column, or bar when Chart Orientation is Horizontal
Stacked Bar / 3D Stacked Bar	the same, with stacking: normal
Line / 3D Line	line
Area	area
Stacked Area	area with stacking: normal
Pie / 3D Pie	pie
Ring	pie with innerSize: 60%
Waterfall	waterfall, running totals converted to per-step deltas

• 3D variants render as their 2D counterpart, which is also what the core billboard renderer does. PA_Goal indicators render as a gauge whose plot bands come from the goal's colour schema.

Live sales and inventory dashboard

• Menu: ZK Charts Live Sales Dashboard
• Four KPI tiles and three charts – sales by month, top products by sales, and top products on hand. Nothing has to be refreshed by hand:
  1. An OSGi EventHandler subscribes to PO_POST_CREATE, PO_POST_UPADTE and PO_POST_DELETE, filtered to C_Order, C_OrderLine, M_InOut and M_InOutLine. These post topics fire after the transaction commits, so the reload never reads uncommitted rows.
  2. The handler runs on whichever thread saved the record, so it does nothing beyond Executions.schedule(...), which hands the reload to the desktop's event thread.
  3. ZK server push sends the new data to the browser.
• Two details worth copying into your own plugin:
  • Coalescing. Completing one order fires a burst of events; an AtomicBoolean collapses them into a single reload.
  • Unregistering. The handler is removed in onPageDetached, otherwise every tab a user ever opened would keep a live subscription for the lifetime of the runtime.
• This module also carries the smallest possible example of using <charts> in a ZUL. Its menu entry ships deactivated because the dashboard supersedes it; reactivate the AD_Menu and AD_Form records named "ZK Charts Example" to bring it back.

Installation

• Download the release / install package from the GitHub repository.
• Install the OSGi plugin and fragment into your iDempiere runtime (same way as other plugins). The order matters – a fragment only takes effect after its host bundle is re-resolved, which means a restart:
  1. Install org.idempiere.zkcharts.fragment through the Felix Web Console (/osgi/system/console/bundles).
  2. Restart the iDempiere runtime.
  3. Install org.idempiere.zkcharts.renderer and/or org.idempiere.zkcharts.dashboard.
  4. On the Bundles page, confirm the fragment shows as Fragment and the plugins as Active – not merely Resolved.
  5. Log out and back in, so the menu tree is rebuilt with the entries the plugin adds.
• The dashboard plugin adds its menu entries through a 2Pack applied by its bundle activator; no manual import is required.

Usage

• After installation, open the included examples from the iDempiere menu and verify charts render correctly.
• To use charts in your own windows/forms, add dependencies on this plugin and develop with ZK Charts as usual.
• Demo builds may include evaluation versions of ZK Charts for demonstration purposes only. A valid commercial license is required for production use.

The client you log in as matters

• Every chart is scoped to the logged in client, and most of them to completed sales orders.
• SuperUser signs in to the System client (AD_Client_ID = 0), which by design holds the dictionary and no business data at all – so every chart is legitimately empty and nothing is broken.
• Log in as GardenAdmin to the GardenWorld client instead.

Verifying the renderer

• The renderer has no menu entry, so it is verified by opening things iDempiere already draws.
  1. Felix Console → Components: ...renderer.ChartRendererServiceImpl must be satisfied/active. A bundle showing Active does not by itself mean the service registered.
  2. Open the Chart window and pick any chart definition. The preview should show hover tooltips, an entry animation and an export menu.
  3. The decisive test: Stop the renderer bundle in the Felix Console and reload the record – the chart falls back to billboard. Start it again and reload – ZK Charts is back.
  4. Click a bar or a slice; it must still zoom to the underlying records.
  5. Open a Performance Goal record to cover the goal graph and the gauge indicator.
  6. Any Failed to render ... with ZK Charts warning in the log means that path silently fell back to billboard.

Creating test data

• The charts read C_Order and C_OrderLine only – no shipment, invoice or accounting document is required.
• Create a Business Partner: Search Key, Name, a Business Partner Group (mandatory, with no default), and tick Customer. Add a row on the Location tab, otherwise an order cannot be raised.
• Create a Sales Order with the document type Standard Order, add lines with products that carry a price, then press Complete.
• Use Standard Order deliberately: unlike POS Order and On Credit Order it does not auto-generate an invoice on completion, which keeps the accounting setup out of the picture entirely.

Troubleshooting

Symptom	Cause	Fix
Every chart empty, KPIs all zero	Signed in to the System client, which holds no business data	Log in to GardenWorld or another client with data
Bundle stays Resolved, never Active	The fragment is missing, or the runtime was not restarted after installing it	Install the fragment, then restart
Charts still look unchanged after installing the renderer	The declarative service did not register	Check Components, not just Bundles
Completing an order fails with No account defined for this organization / currency	Despite the wording this is a bank account: the payment rule is Cash and the document type auto-creates an invoice, but no C_BankAccount matches the order's organisation and currency	Use Standard Order with payment rule On Credit, or create a bank account in the same organisation – the lookup matches AD_Org_ID exactly, so one on * will not do

When developing your own plugin with these components

Symptom	Cause	Fix
Page not found: ~./... for a page that belongs to a ZK component	The thread's context class loader was replaced with your own bundle's, which hides everything contributed by a fragment	Chain the class loaders instead of replacing
SEVERE TableName not correctly parsed in the log	MRole.addAccessSQL expects the alias of the first table in the FROM clause	Pass that alias

Building from source

• Requires Git, Maven, JDK 17 and a local p2 repository built from iDempiere core. Full instructions, including the target platform fix-ups, are in the repository README.

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-addon-plugin.git
cd zkoss-idempiere-addon-plugin
(cd org.idempiere.zkcharts.fragment  && mvn clean verify)
(cd org.idempiere.zkcharts.renderer  && mvn clean verify)
(cd org.idempiere.zkcharts.dashboard && mvn clean verify)

• The first build must have network access: ZK Charts is downloaded from the ZK Evaluation repository, not from Maven Central.

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

• Plugin: ZK Pivottable Components
• Developing Plug-Ins - Get your Plug-In running
• Make Zk WebApp OSGi
• ZK Charts