Plugin: ZK Pivottable 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 Pivottable or ZK Charts.
• Source: GitHub repository
• Dependencies: This plugin depends on both ZK Pivottable and ZK Charts – it uses the first for the cross tabulation and the second to chart it. Both are commercial products and are not covered by this plugin’s open-source license. Users must obtain valid licenses separately for production use.
• 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.
• ZK Pivottable and ZK Charts are commercial products (evaluation is available via ZK download center).

A pivot cross tabulation charted with ZK Charts

Requirements

Item	Version
iDempiere	13 (use the v12 branch for iDempiere 12)
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.

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 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.

Features

• 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.
• A ZK Charts chart underneath that follows the pivot layout.
• 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.
• 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

• Open ZK Charts Sales Pivot Analysis from the menu. 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.
• Right click a row or column field for sorting and subtotal options.
• Demo builds may include evaluation versions of ZK Pivottable and ZK Charts for demonstration purposes only. A valid commercial license is required for production use.

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.

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
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

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

See also

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