Plugin: ZK Pivottable Components

Creator: James Chu
SPONSOR: zkoss.org
License: The plugin source code is licensed under the GNU GPLv2 or later. The fragment you download does embed commercially licensed ZK Evaluation binaries – see Licensing.
Source: GitHub repository
Related: Plugin: ZK Charts Components – lives in the same repository, and its ZK Charts fragment is a prerequisite for this one.

Description

This plugin adds a ZK Pivottable to iDempiere without modifying iDempiere core, and wires it to a ZK Charts chart.
Users drag Year, Month, Business Partner, Product Category or Product onto the row, column and data axis, and the chart underneath follows whatever the pivot currently shows.
The intent is to make the kind of ad-hoc cross tabulation people normally export to Excel available inside iDempiere itself.
Install and uninstall it like any other iDempiere OSGi plugin. Nothing in the iDempiere repository or in the application dictionary is changed.

A pivot cross tabulation charted with ZK Charts

What makes this more than a grid

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 honors whatever summary calculator the user picked. A second SQL query would drift the moment the two definitions diverged.
Cross tabulation is interactive, not a report parameter. Users rearrange the axes themselves; nobody has to define a new report for each question.
Layout and chart stay in step, or deliberately do not. Leave Sync chart with pivot ticked and the chart follows every drag; untick it and Chart this pivot charts the current layout on demand – useful while rearranging a large model.

Requirements

Item	Version
iDempiere	13
Java runtime	17
ZK CE bundled with iDempiere	10.0.1
ZK Pivottable	3.0.0-Eval
ZK Charts	12.5.0.0-Eval

ZK Pivottable 3.0.0 targets ZK 10.0.0 or later, which matches the ZK CE 10.0.1 that iDempiere 13 bundles. It depends only on zcommon and zul, so no ZK EE bundle is required – this plugin does not need Plugin: ZK Enterprise Components.

Components

Bundle	Kind	Purpose
`org.idempiere.zkpivottable.fragment`	OSGi fragment	Attaches ZK Pivottable to the class loader of `org.adempiere.ui.zk`.
`org.idempiere.zkcharts.fragment`	OSGi fragment	The same for ZK Charts. Also required, because the form charts the pivot result. Documented in Plugin: ZK Charts Components.
`org.idempiere.zkcharts.zkpivottable`	Plugin	The pivot analysis form.

This plugin is independent of the other two plugins in the repository: neither the chart renderer nor the dashboard has to be installed. Both fragments do have to be installed.

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.
The fragment exports the org.zkoss.pivot* packages through its host, so a plugin that requires org.adempiere.ui.zk can use them from Java.
It deliberately does not export org.zkoss.pivot.util.poi. That package needs zpoi, which iDempiere does not ship, and only the pivot table's own Excel export depends on it – so that one feature is unavailable, and nothing else is affected.

Installation

Prebuilt jars are attached to each GitHub release – nothing has to be built to try this. All three are required:

File	Purpose
`org.idempiere.zkpivottable.fragment-13.0.0.jar`	The ZK Pivottable fragment
`org.idempiere.zkcharts.fragment-13.0.0.jar`	The ZK Charts fragment – the form charts the pivot result
`org.idempiere.zkcharts.zkpivottable-13.0.0.jar`	The pivot analysis form

To build them yourself instead, see Building from source at the end of this page.
The order matters – a fragment only takes effect after its host bundle is re-resolved, which means a restart:
1. Install org.idempiere.zkpivottable.fragment and org.idempiere.zkcharts.fragment through the Felix Web Console (/osgi/system/console/bundles).
2. Restart the iDempiere runtime.
3. Install org.idempiere.zkcharts.zkpivottable.
4. On the Bundles page, confirm both fragments show as Fragment and the plugin as Active – not merely Resolved. If it stays Resolved, a fragment is missing or the restart was skipped.
5. Log out and back in, so the menu tree is rebuilt with the entry the plugin adds.
The plugin adds its menu entry through a 2Pack applied by its bundle activator; no manual import is required.

Usage

Menu: ZK Charts Sales Pivot Analysis
A Pivottable with a pivot-field-control beside it, over completed sales order lines, with an optional date range. Both date boxes start empty, meaning no date restriction, and the status label reports how many order lines were loaded.
Drag fields between Rows, Columns, Values and Unused. The pivot recalculates, and the chart follows.
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.
Right click a row or column field for sorting and subtotal options.

The client you log in as matters

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

Using ZK Pivottable in your own plugin

1. Compile-time dependency. Add the ZK Evaluation repository and the jars to your bundle's pom.xml. Tycho puts them on the compile classpath; they are not embedded in your jar.

<repositories>
  <repository>
    <id>ZK PE/EE Evaluation</id>
    <url>https://mavensync.zkoss.org/eval/</url>
  </repository>
</repositories>
<dependencies>
  <!-- Compile time only: at runtime the classes come from the fragments -->
  <dependency>
    <groupId>org.zkoss.pivot</groupId>
    <artifactId>pivottable</artifactId>
    <version>3.0.0-Eval</version>
  </dependency>
  <dependency>
    <groupId>org.zkoss.chart</groupId>
    <artifactId>zkcharts</artifactId>
    <version>12.5.0.0-Eval</version>
  </dependency>
</dependencies>

2. Runtime wiring in META-INF/MANIFEST.MF. You do not import org.zkoss.pivot directly. The fragment exports those packages through its host, so requiring the host bundle is what makes them visible:

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"

3. The rule. You compile against a jar on the Maven classpath but resolve at runtime through the fragment – so your bundle will not resolve unless both fragments are installed and the runtime has been restarted since. A bundle stuck at Resolved is almost always this.
4. Loading your own ZUL. ZK resolves a ~./ page through the thread context class loader, and under OSGi that fails in both directions: the ambient loader cannot see your bundle, while replacing it with your bundle's loader hides everything a fragment contributed – including the ZUL pages PivotFieldControl loads for itself, which then fail with Page not found. Chain the loaders instead of replacing them, so both stay visible for the duration of the call:

Thread thread = Thread.currentThread();
ClassLoader original = thread.getContextClassLoader();
thread.setContextClassLoader(new ChainedClassLoader(
        original,
        CustomForm.class.getClassLoader(),   // org.adempiere.ui.zk + every fragment
        getClass().getClassLoader()));       // this bundle, holding your own ZUL
try {
    return Executions.createComponents(uri, parent, null);
} finally {
    thread.setContextClassLoader(original);
}

ChainedClassLoader is a small ClassLoader built with a null parent that asks each delegate in turn from findClass, findResource and findResources. The full source is in the repository, as ZulLoader.
5. Lazily loaded dialogs are a separate case. The chaining above only covers pages loaded during createComponents. PivotFieldControl loads its Subtotals dialog on a click, long after the finally restored the loader. The repository subclasses the control and re-establishes the loader around that one handler. Verify before copying it – if the ambient loader already resolves the dialog in your runtime, the subclass is dead code.

Creating test data

The pivot reads 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
Bundle stays Resolved, never Active	One of the two fragments is missing, or the runtime was not restarted after installing them	Install both fragments, then restart
The pivot shows only Grand Total	The query returned no rows	Read the status label – it distinguishes "no completed sales orders found" from a failure. Check which client you are logged in to
The pivot's own Excel export fails	`org.zkoss.pivot.util.poi` needs `zpoi`, which iDempiere does not ship	Not supported in this build. The ZK Charts export menu below the pivot is unaffected
`Page not found: ~./zul/pivot/...`	The thread context class loader was replaced with a single bundle's, hiding what the fragments contribute	Chain the loaders instead of replacing – see Using ZK Pivottable in your own plugin
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 organization and currency	Use Standard Order with payment rule On Credit, or create a bank account in the same organization – the lookup matches `AD_Org_ID` exactly, so one on `*` will not do

Licensing

The plugin source is GPLv2 or later. Nothing in the iDempiere repository is modified.
The fragment you download is not. A fragment exists to put the product jars on the host bundle's class loader, so the released fragment embeds them – org.idempiere.zkpivottable.fragment carries ZK Pivottable and org.idempiere.zkcharts.fragment carries ZK Charts. Those are commercially licensed Evaluation binaries governed by ZK's license, not by the GPL. The other bundles in this plugin contain only this project's own code and are GPLv2 throughout.
ZK Pivottable and ZK Charts are commercial products and are not covered by the plugin's open-source license – this form needs both, the first for the cross tabulation and the second to chart it. The build pulls them from ZK's Evaluation repository, so everything on this page can be tried at no cost; valid licenses must be obtained separately before production use.
No lock-in. Uninstalling removes one menu entry and nothing else – the application dictionary was never touched and no other iDempiere screen depends on this plugin. Evaluating it is a reversible decision.
To obtain a license or ask about terms, contact the ZK Framework team at [email protected], or see the ZK Pivottable and ZK Charts product pages.

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.zkpivottable.fragment && mvn clean verify)
(cd org.idempiere.zkcharts.zkpivottable && mvn clean verify)

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

Plugin: ZK Pivottable Components

Contents

Description

What makes this more than a grid

Requirements

Components

Why a fragment is needed

Installation

Usage

The client you log in as matters

Using ZK Pivottable in your own plugin

Creating test data

Troubleshooting

Licensing

Building from source

Feedback

See also