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 or ZK Pivottable.
• Source: GitHub repository
• Dependencies: This plugin depends on ZK Charts, and optionally on ZK Pivottable for the pivot analysis demo. Both are commercial products and are not covered by this plugin’s open-source license. Users must obtain valid licenses for these components separately for production use.

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 three 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.
  3. With a pivot table – a ZK Pivottable whose current cross tabulation is charted live, so the chart follows whatever the user drags onto the row, column and data axis.
• ZK Charts and ZK Pivottable are commercial products (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
ZK Pivottable	3.0.0-Eval (only for the pivot analysis demo)

Components

Bundle	Kind	Purpose
org.idempiere.zkcharts.fragment	OSGi fragment	Attaches ZK Charts to the class loader of org.adempiere.ui.zk. Required by everything else.
org.idempiere.zkpivot.fragment	OSGi fragment	The same for ZK Pivottable. Only needed by the pivot analysis demo.
org.idempiere.zkcharts.renderer	Plugin	The global chart renderer.
org.idempiere.zkcharts.example	Plugin	The example and demo forms.

• The two plugins are independent – install either one on its own, or both. Both need the ZK Charts fragment.

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 and ZK Pivottable jars are delivered as fragments 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.

Sales pivot analysis

• Menu: ZK Charts Sales Pivot Analysis
• A Pivottable with a pivot-field-control beside it – drag Year, Month, Business Partner, Product Category or Product onto the row, column and data axis – and a ZK Charts chart underneath that follows the pivot.
• The chart is not a second query. The values are read back out of the live PivotModel: each pivot row becomes a category, each pivot column becomes a series. The chart therefore cannot disagree with the numbers on screen, and it honours whatever summary calculator the user picked.
• Leave Sync chart with pivot ticked and the chart follows every drag; untick it and Chart this pivot charts the current layout on demand. The chart type can be switched between column, stacked column, bar, line, area and pie. The pie collapses the columns and plots one slice per pivot row, which is the only reading of a cross tabulation a pie can have.

Installation

• Download the release / install package from the GitHub repository.
• Install the OSGi plugins and fragments 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. Install org.idempiere.zkpivot.fragment as well, if you want the pivot analysis demo.
  3. Restart the iDempiere runtime.
  4. Install org.idempiere.zkcharts.renderer and/or org.idempiere.zkcharts.example.
  5. On the Bundles page, confirm the fragments show as Fragment and the plugins as Active – not merely Resolved.
  6. Log out and back in, so the menu tree is rebuilt with the entries the plugin adds.
• The example plugin adds its menu entries through an incremental 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 and ZK Pivottable 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	A required fragment is missing, or the runtime was not restarted after installing one	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: ~./zul/pivot/...	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 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-zkcharts-plugin.git
cd zkoss-idempiere-zkcharts-plugin/org.idempiere.zkcharts.fragment && mvn clean verify
cd ../org.idempiere.zkpivot.fragment && mvn clean verify
cd ../org.idempiere.zkcharts.renderer && mvn clean verify
cd ../org.idempiere.zkcharts.example && mvn clean verify

• The first build must have network access: ZK Charts and ZK Pivottable are 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

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