iDempiere OSGI JavaScript 七擒孟獲：五次失敗與一次攻心

Prelude to the Southern Campaign: The Barbarian King Stirs

Since ancient times, wild frontiers breed untamed kings. And in the land of iDempiere OSGI, one barbarian king reigns supreme.

In our previous tale, the Chancellor (Zhuge Liang) demonstrated the Eight Formations strategy — teaching the world how to deploy a CustomForm in iDempiere, conquering everything from OSGI ClassLoader supply lines to ZK MVVM battle flags. Just as the Chancellor was about to return to the capital for a well-earned cup of tea, a scout galloped in: “Chancellor! The southern barbarians have risen again!”

And who is this barbarian king? JavaScript.

That JavaScript — accustomed to running wild in browsers — refuses to submit even on ZK Framework’s turf. Want to load ECharts CDN in an OSGI plugin’s CustomForm? Denied. Want to use ZUL’s <script> tag to import custom JS? It laughs at your naivety. Want to sneak in via <?script?> Processing Instruction? Every path is blocked.

The Chancellor knew well: you cannot subdue the barbarian king by brute force alone. Only by winning hearts and minds can you prevail. And so he marched south — capturing and releasing Meng Huo five times — until the JavaScript barbarian king finally submitted, kneeling beneath the banner of Clients.evalJavaScript().

This article chronicles that entire southern campaign — five failed approaches (the five captures and releases), one ultimate solution (winning hearts and minds), and four rebel officers subdued along the march. All code is battle-tested. Copy and deploy.

First Capture: Frontal Assault — <script> as a <borderlayout> Child

Battle cry: “We need JavaScript? Just shove a <script> tag in there!”

The Chancellor started simple enough: Meng Huo is just JavaScript, right? Surely the mighty Han dynasty can handle a frontal assault — drop two <script> tags inside <borderlayout>, one for CDN, one for custom JS, and call it a day.

<borderlayout>
    <script src="https://cdn.jsdelivr.net/npm/echarts@5/dist/echarts.min.js"/>
    <script src="~./js/rnd-charts.js"/>
    <north>...</north>
</borderlayout>

The result? Meng Huo roared with laughter and sauntered away. ZK slapped back with:

Unsupported child for Borderlayout: <Script null>

Turns out ZK’s <borderlayout> is an extremely picky eater — it only accepts five children: <north>, <south>, <east>, <west>, <center>. Shoving a <script> in there is like bringing a barbarian envoy into the imperial throne room — the palace guards block you at the door: “This person is not on the guest list.”

First capture. Meng Huo is unimpressed. Released.

Second Capture: The Ambush — <script> Inside a Conditionally Visible Container

Battle cry: “Frontal assault failed? Let’s set an ambush! Hide it inside vlayout!”

After reviewing the first defeat, the Chancellor opted for subterfuge. Hide the <script> inside a conditionally visible <vlayout>, and load it when the time is right:

<vlayout visible="@load(not vm.testEntryMode)">
    <script src="https://cdn.jsdelivr.net/npm/echarts@5/dist/echarts.min.js"/>
    <script src="~./js/rnd-charts.js"/>
    <div id="chartContainer"/>
</vlayout>

No structural error this time. The Chancellor thought: “Brilliant, the ambush worked—” Before the words left his mouth, the console fired back:

renderTestTrendChart is not defined

Meng Huo doubled over laughing: “Your ambush troops never even attacked!”

The problem: a <script> inside a conditionally hidden container has completely unpredictable execution timing. When the container is visible="false", the scripts inside may never execute at all. When the container becomes visible, the execution order is chaos. It’s like stationing three thousand soldiers in a mountain pass — the horn sounds, but they’re still asleep. Wrong timing, and even the most brilliant ambush is worthless.

Second capture. Meng Huo remains defiant. Released again.

Third Capture: Flanking Maneuver — <?script?> Processing Instruction + ~./ Path

Battle cry: “Can’t breach the gates? Take the mountain trail!”

The Chancellor consulted the ZK military manual (official docs) and found a side path: <?script?> Processing Instruction. This isn’t a ZK component — it’s a page-level directive, free from <borderlayout>‘s picky diet:

<?script src="https://cdn.jsdelivr.net/npm/echarts@5/dist/echarts.min.js"?>
<?script src="~./js/rnd-charts.js"?>
<borderlayout>...</borderlayout>

The Chancellor was thrilled: “Brilliant! A flanking maneuver — Meng Huo won’t see this coming!”

The CDN path worked — ECharts loaded successfully. But the custom rnd-charts.js? The console replied coldly:

renderTestTrendChart is not defined

Meng Huo chuckled: “Your supply line went to the wrong camp.”

The issue is the ~./ path. <?script?> is page-level processing, so ~./ resolves to the main webapp (/webui/), not your OSGI bundle’s Web-ContextPath. The CDN is an external URL, so it’s fine — but your bundle’s JS files? The quartermaster drove the supply wagons ten miles… straight into someone else’s camp.

Third capture. Meng Huo laughs heartily and walks away. Released.

Fourth Capture: Rerouting — <?script?> + Absolute Path

Battle cry: “~./ went wrong? I’ll use an absolute path!”

The Chancellor was getting frustrated. If ~./ resolves incorrectly, then surely using the OSGI bundle’s Web-ContextPath as an absolute path should work?

<?script src="/rnd/js/rnd-charts.js"?>

Deployed with full confidence…

File still not found

Meng Huo didn’t even bother laughing this time. Just shook his head: “This road doesn’t exist.”

The OSGI bundle’s Web-ContextPath: /rnd doesn’t necessarily serve static JS files correctly. This depends on iDempiere’s web resource configuration. The bundle’s Web-ContextPath is primarily for ZK’s ~./ mechanism, not a general-purpose static file server. You picked a different road, but that road simply doesn’t exist — drawn on the map, but a cliff in reality.

Fourth capture. Meng Huo shakes his head with a sigh. Released.

Fifth Capture: Turning a Spy — w:onCreate to Set DOM ID

Battle cry: “Can’t break in? Let’s turn someone on the inside!”

Four frontal engagements, four defeats. The Chancellor changed tactics — instead of loading JS from outside, plant a mole inside ZK’s rendered DOM. Use w:onCreate to manually set a fixed DOM ID on the client side, so JavaScript can find the chart container via getElementById:

<div id="trendChart" w:onCreate="this.$n().id = 'rndTrendChart';"/>

Then in JavaScript:

document.getElementById('rndTrendChart')

Seems airtight? The spy has infiltrated enemy territory, just waiting for the signal to open the gates…

Then the spy defected.

ZK’s widget lifecycle has its own rules: it may overwrite your manually set DOM ID during certain rendering phases, or the widget might not be fully initialized when you call getElementById. The spy (DOM ID) was planted, but under pressure from ZK’s lifecycle, he “surrendered” — sometimes it works, sometimes the element can’t be found. Completely unreliable.

It’s like turning one of Meng Huo’s generals and agreeing to open the gates at high noon — only for the general to discover at the appointed hour that the gate key isn’t in his hands, and he’s not entirely sure where the gate is either.

Fifth capture. Meng Huo smirks coldly. The Chancellor sits in silence. Five captures, five releases. The score remains unsettled.

Total Submission: Winning Hearts and Minds — Clients.evalJavaScript()

Grand strategy: “Attacking the city is inferior; winning hearts is supreme. The highest art of war is to conquer the whole nation intact.”

Five head-on collisions, five retreats. The Chancellor sat alone in his tent for three days, poring over every military text, until he arrived at a single insight: It’s not that JavaScript won’t obey — you’ve been commanding it the wrong way all along.

ZUL’s <script> and <?script?> both load JS on “ZK’s territory” — paths follow ZK’s rules, timing depends on ZK’s mood. But Clients.evalJavaScript() is different. It sends JavaScript directly from the Java side to the browser for execution, bypassing all of ZK’s path resolution and component lifecycle restrictions.

This is winning hearts and minds — don’t fight the barbarian king on his turf. Walk straight into his heart, and he’ll serve you willingly.

Strategy One: loadChartScripts() — Dynamic CDN Loading + Function Definition

Step one: in Form.java’s initForm(), use Clients.evalJavaScript() to dynamically create a <script> element that loads the ECharts CDN, then define custom functions after the CDN loads.

@Override
protected void initForm() {
    // ... ZUL loading, WSearchEditor setup ...

    // Load ECharts CDN + define chart function
    loadChartScripts();
}

private void loadChartScripts() {
    String loadECharts = "if(!window.echarts){"
        + "var s=document.createElement('script');"
        + "s.src='https://cdn.jsdelivr.net/npm/echarts@5/dist/echarts.min.js';"
        + "s.onload=function(){" + getChartFunctionJs() + "};"
        + "document.head.appendChild(s);"
        + "}else if(!window.myChartFunction){" + getChartFunctionJs() + "}";
    Clients.evalJavaScript(loadECharts);
}

private String getChartFunctionJs() {
    return "window.myChartFunction=function(dom,data){...};";
}

The brilliance lies in three layers of defense:

• Layer one: if(!window.echarts) — If ECharts isn’t loaded yet, dynamically create a <script> element with an onload callback. Custom functions are defined only after the CDN finishes loading. Supplies first, then train the troops.
• Layer two: s.onload — Ensures functions are defined only after the CDN is fully loaded. No jumping the gun.
• Layer three: else if(!window.myChartFunction) — If the user reopens the Form and ECharts is already in memory, just define the functions — no redundant CDN loading. Veteran soldiers need no retraining; deploy them straight to battle.

Strategy Two: CSS Class Container — No DOM ID Dependency

Step two: in ZUL, mark the chart container with sclass (CSS class). Do not use id or w:onCreate to set a DOM ID.

<div sclass="rnd-trend-chart" hflex="1" height="750px"
     visible="@load(not empty vm.testResults)"/>

Why? Because the painful lesson of the fifth capture taught us: ZK owns its DOM IDs. You hardcode one, and it’s like nailing a nameplate to someone else’s door — the landlord can rip it off anytime. But CSS classes? ZK doesn’t touch those. Using sclass to mark a container is like planting a flag on Meng Huo’s tent — the flag stays, and JavaScript can always find it.

Strategy Three: querySelector + setTimeout Retry Mechanism

Step three: in the ViewModel, use document.querySelector to find the container, paired with an IIFE + setTimeout retry mechanism to wait for the asynchronous CDN load to complete.

@Command
public void refreshChart() {
    String jsonData = buildJsonData();

    Clients.evalJavaScript(
        "(function _try(){"
        + "var dom=document.querySelector('.rnd-trend-chart');"
        + "if(!dom||!window.echarts){setTimeout(_try,200);return;}"
        + "var chart=echarts.getInstanceByDom(dom)||echarts.init(dom);"
        + "// ... chart.setOption(...) ..."
        + "})()");
}

The essence of this code is a self-retrying IIFE (Immediately Invoked Function Expression):

• document.querySelector('.rnd-trend-chart') — Finds the DOM element by CSS class. Rock solid.
• if(!dom||!window.echarts) — If the container hasn’t rendered yet, or the ECharts CDN hasn’t finished loading, retry in 200 milliseconds.
• echarts.getInstanceByDom(dom)||echarts.init(dom) — Reuse the existing chart instance if one exists; create a new one otherwise.

This is the highest form of winning hearts and minds: no rushing, no pressure, just patient waiting until conditions are ripe. Meng Huo, whenever you’re ready, I’ll be here — I check in every 200 milliseconds anyway.

After five captures, total submission. The barbarian king finally kneels.

March Formation: Layout Pitfalls

Formation rule: “Fail to survey the terrain, and the entire army perishes.”

Meng Huo has submitted, but the road home has two treacherous stretches. This isn’t about the enemy — it’s your own marching formation that’s out of order.

Hazard One: Fixed-Height Chart + vflex Conflict

What happens when you put a 750px-tall ECharts chart and a vflex="1" listbox inside the same <vlayout>?

<!-- Wrong: 750px chart crushes vflex="1" listbox to 0 height -->
<vlayout vflex="1">
    <listbox vflex="1"/>        <!-- gets crushed -->
    <div height="750px"/>       <!-- eats all space -->
</vlayout>

Answer: the listbox gets crushed to a sliver — zero height. The 750px general plants himself there and devours all available space, leaving the other soldiers pressed against the wall.

Fix: Give the listbox a fixed height too, and add overflow-y:auto to the outer <vlayout> for scrolling. Marching column too long for the road? Let the column scroll — don’t force everyone to squeeze into a single lane:

<vlayout hflex="1" vflex="1" style="overflow-y:auto;">
    <listbox height="200px"/>
    <groupbox>
        <listbox height="150px"/>
    </groupbox>
    <div sclass="rnd-trend-chart" height="750px"/>
</vlayout>

Hazard Two: Dynamic Height for Multiple Sub-Charts

When multiple TestSpecs require sub-charts, a fixed 750px height isn’t enough. You need to dynamically adjust the container height based on the number of sub-charts. It’s like encountering mountains mid-march — the terrain changed, so the formation must adapt:

var n = data.specs.length || 1;
dom.style.height = (n * 250) + 'px';
// dispose then init — force ECharts to recalculate dimensions
var chart = echarts.getInstanceByDom(dom);
if (chart) { chart.dispose(); }
chart = echarts.init(dom);

The key is dispose() before init(). ECharts memorizes the container’s dimensions at initialization. If you change the height without reinitializing, it still draws at the old size — like soldiers marching in plains formation on a mountain trail. Of course they’ll crash into walls.

Subduing the Remaining Rebels: Four Officers Brought to Heel

Mopping-up rule: “The king has surrendered, but his lieutenants still roam free.”

The JavaScript barbarian king has submitted, but four of his officers remain at large, each with their own attitude problem. Leave them unsettled, and your CustomForm will never know peace.

The Deaf Lieutenant: @bind Missing getter/setter

ZUL declares a two-way @bind:

<listbox selectedItem="@bind(vm.selectedItem)"/>

But the ViewModel only has a getter and no setter:

public MyType getSelectedItem() { return selectedItem; }
public void setSelectedItem(MyType item) { this.selectedItem = item; }

Missing the setter causes PropertyNotWritableException. This lieutenant can report intelligence (getter), but when you give orders he can’t hear you (no setter) — his ears are purely decorative. @bind is bidirectional. Getter and setter are both mandatory.

The Shape-Shifting General: Yes-No Boolean/String Conflict

iDempiere’s Yes-No field (AD_Reference_ID=20) stores char(1) (Y/N) in the database, but PO.get_Value() returns a Boolean. If the generated X_ class getter uses (String)get_Value(...) directly, you’ll get slapped with a ClassCastException — because what you received is a Boolean, not a String.

This general enters camp claiming to be a String (the DB stores char), but once inside the tent, he shapeshifts into a Boolean. A classic two-faced officer.

Fix: Check the type before casting:

public String getIsComplete() {
    Object oo = get_Value(COLUMNNAME_IsComplete);
    if (oo instanceof Boolean) return ((Boolean)oo) ? "Y" : "N";
    return (String)oo;
}

The Undersized Armor: varchar(1) Can Only Store One Character

Database column Result varchar(1) can only store a single character. Your ViewModel returns "Pass" or "Fail"? Way too long — it won’t fit. This officer’s armor only comes in XS, and you’re trying to force him into XXL. Naturally, it doesn’t fit.

Fix: Store abbreviations in the DB, display full names in the UI. Two separate logics:

public String getPassFail() {    // for DB storage
    if (...) return "F";
    return "P";
}
public String getPassFailLabel() {  // for ZUL display
    String pf = getPassFail();
    if ("P".equals(pf)) return "Pass";
    if ("F".equals(pf)) return "Fail";
    return "";
}

The Redundant Overseer: Unnecessary apply="BindComposer"

When ZUL already specifies viewModel="@id('vm') @init(...)", ZK automatically applies BindComposer. Adding apply="org.zkoss.bind.BindComposer" on top of that is like assigning two overseers to the same army — conflicting orders and a flood of parser warnings.

This overseer is entirely redundant and can be safely removed. One fewer person barking orders, and morale actually improves.

Meng Huo’s Surrender Speech

I am JavaScript — Meng Huo, King of the Southern Barbarians.

Since the dawn of the browser, I have ruled the DOM, conquered the window object, and none have dared defy me.

In the first battle, the Chancellor sent <script> charging straight into <borderlayout>, only to be blocked at the gate by the Five Brothers (north, south, east, west, center). I watched from the ramparts, laughing myself hoarse.

In the second battle, the Chancellor hid <script> in ambush inside a <vlayout>. All I had to do was wait for the timing to unravel — one is not defined and the ambush collapsed. Didn’t even break a sweat.

In the third battle, the Chancellor took the <?script?> back trail, but the ~./ supply route led him straight into someone else’s camp. I didn’t even have to lift a finger — he got lost on his own.

In the fourth battle, the Chancellor tried the absolute path /rnd/. The road didn’t exist. I lounged on the hilltop, watching him wander the wilderness all night.

In the fifth battle, the Chancellor turned a DOM ID as his inside man. But ZK’s lifecycle gave one order, and the spy defected right back to me. The Chancellor’s man was always ZK’s man.

Five battles. Five victories! I was riding high, thinking this Zhuge Liang was nothing special — the wild frontier would forever be my domain.

And then the Chancellor deployed Clients.evalJavaScript() — no siege, no ambush, no detour, no espionage. He walked straight into my heart and settled everything with three strategies: dynamic loading to ensure timing, CSS classes to ensure targeting, setTimeout to ensure patience.

I submit.

From this day forward, I shall no longer attempt to escape through ZUL, no longer rely on unreliable DOM IDs. I shall stand obediently beneath the banner of evalJavaScript(). When the Chancellor commands me to draw charts, I draw charts. When the Chancellor commands me to retry, I report for duty every 200 milliseconds.

The southern barbarians shall never rebel again.