iDempiere CustomForm 八陣圖：以 MVVM 兵法統御 ZK 前線

Prologue: Mustering the Troops

In the era of the Three Kingdoms, the great strategist Zhuge Liang governed with brilliance, conquering on every front. Yet one challenge kept him up at night — iDempiere CustomForm development.

Beneath its surface, iDempiere’s WebUI is a deep-water zone of ZK Framework + OSGI. Want to build a custom form? Just getting the screen to appear requires fighting through five garrisons: the OSGI ClassLoader refuses to see your files, ZK’s ~./ path can’t find your resources, @NotifyChange stubbornly refuses to update the UI… Each pitfall is enough to make you throw your hands up and cry: “I was but a humble farmer, tilling my fields in Nanyang, asking nothing of OSGI!”

But a master strategist is a master strategist. After three days and three nights, he distilled every nuance of CustomForm development into a single battle plan — the Eight Formations — six major formations plus a post-battle debriefing, each formation interlocking with the next. Follow the diagram, and even a raw recruit on their first campaign can make it through alive.

This article uses Zhuge Liang’s Art of the Eight Formations to walk you through the complete iDempiere CustomForm + ZK MVVM development workflow. All code has been battle-tested and is ready to deploy.

The Eight Formations: Overview of the Four Cornerstones

The Strategist’s Maxim: “With this map in hand, the realm is mine.”

The strategist unfurls his bamboo scroll and sketches the overall CustomForm architecture. The formation has four cornerstones — remove any one, and the entire formation collapses:

┌─────────────────────────────────────────────────────┐
│ iDempiere CustomForm Architecture                    │
│                                                     │
│  ┌──────────────┐    creates    ┌──────────────────┐ │
│  │ IFormFactory  │─────────────▶│ ADForm           │ │
│  │ (OSGI Service)│              │ (Form Controller)│ │
│  └──────────────┘              └────────┬─────────┘ │
│                                         │           │
│                          initForm()     │           │
│                          ┌──────────────┘           │
│                          ▼                          │
│              ┌──────────────────────┐               │
│              │ createComponents()   │               │
│              │ "~./zul/MyForm.zul"  │               │
│              └──────────┬───────────┘               │
│                         │                           │
│          ┌──────────────┼──────────────┐             │
│          ▼              ▼              ▼             │
│  ┌─────────────┐ ┌───────────┐ ┌────────────────┐  │
│  │ POJO        │ │ ZUL       │ │ iDempiere      │  │
│  │ ViewModel   │ │ Template  │ │ WebUI Components│  │
│  │ (@Command)  │ │ (MVVM)    │ │ (WSearchEditor)│  │
│  └─────────────┘ └───────────┘ └────────────────┘  │
└─────────────────────────────────────────────────────┘

The four cornerstones, each with a distinct role:

Formation One: Opening the Supply Lines — OSGI Resource Path ~./ Configuration

The Strategist’s Maxim: “If the supply lines aren’t open, no army moves.”

Before troops march, supplies must flow. In the OSGI world, “supplies” are your ZUL files, images, and CSS resources. If the supply lines are blocked, your screen is blank white — emptier than the Empty Fort Strategy, and at least that one had the gates open.

ZK ~./ Mechanism

ZK’s ~./ prefix is the password to enter the supply depot — it means “load from the web/ directory on the classpath.” Give the right password, supplies arrive. Give the wrong one, the enemy storms in:

~./zul/MyForm.zul → classpath: web/zul/MyForm.zul

Bundle-ClassPath Configuration

In META-INF/MANIFEST.MF, the Bundle-ClassPath must include . (the bundle root directory) so that the web/ directory lands on the classpath. Think of it as marking the granary’s location on the map — mark it wrong, and the supply officer will run his legs off without finding a single grain:

Bundle-ClassPath: src/,
 .

Note: . represents the bundle root directory. With it, web/ under the bundle root becomes web/ on the classpath, and ZK’s ~./ can find your resources. Miss this single dot, and the entire supply line is severed.

build.properties Configuration

Ensure the web/ directory is included in the build output — loading the supplies onto the wagon but forgetting to bring the wagon along is the same as not loading them at all:

bin.includes = META-INF/,\
               .,\
               src/,\
               web/,\
               OSGI-INF/rnd_form_factory.xml
source.. = src/
src.includes = src/,\
               web/
output.. = bin/

ClassLoader Switch (Borrowing the East Wind!)

This is the most arcane technique in the entire formation — comparable to Zhuge Liang’s legendary feat of “borrowing the east wind” at the Battle of Red Cliffs. (For those unfamiliar: Zhuge Liang allegedly summoned a favorable wind to enable a fire attack on Cao Cao’s fleet. In our case, we’re summoning a favorable ClassLoader to enable ZK to find our files.)

In the OSGI environment, ZK uses the Thread Context ClassLoader to resolve ~./ paths. But iDempiere’s Thread Context ClassLoader defaults to the Web Application’s classloader — it can see every highway in the realm, except the little alley inside your bundle where the web/ directory lives.

The wind is ready to blow, but the conditions aren’t right. You must change the conditions yourself — switch the Thread Context ClassLoader to your bundle’s own classloader:

@Override
protected void initForm() {
    // 1) Save the original classloader
    ClassLoader cl = Thread.currentThread().getContextClassLoader();
    try {
        // 2) Switch to the bundle's classloader
        Thread.currentThread().setContextClassLoader(getClass().getClassLoader());

        // 3) Now ~./ resolves correctly
        Executions.createComponents("~./zul/RND_DispensingForm.zul", this, args);

    } finally {
        // 4) Always restore the classloader
        Thread.currentThread().setContextClassLoader(cl);
    }
}

Breaking it down:

• getClass().getClassLoader() — Returns the OSGI bundle’s classloader, which can see the bundle’s web/ directory (the east wind has arrived)
• Thread.currentThread().getContextClassLoader() — Defaults to the web app classloader, which cannot see bundle resources (the wind is blowing the wrong way)
• After the switch, ZK can resolve ~./ to find ZUL files inside the bundle (fire ships launched, mission accomplished)

Critical: The finally block must restore the classloader. Borrow the east wind and never return it, and the next person who needs that wind will be left stranded.

Directory Structure

Finally, here is the full layout of the supply depot — every sack of grain in its proper place:

tw.topgiga.rnd/
├── META-INF/
│   └── MANIFEST.MF          ← Bundle-ClassPath includes "."
├── OSGI-INF/
│   └── rnd_form_factory.xml  ← OSGI service declaration
├── src/
│   └── tw/topgiga/rnd/
│       ├── form/
│       │   └── DispensingForm.java
│       ├── viewmodel/
│       │   └── DispensingVM.java
│       └── factories/
│           └── RNDFormFactory.java
├── web/                      ← ~./ root directory
│   ├── zul/
│   │   └── RND_DispensingForm.zul
│   └── images/
│       └── header_banner.png
└── build.properties          ← bin.includes includes web/

Formation Two: The Commander Takes the Field — Form Controller

The Strategist’s Maxim: “Without a commander at the helm, the army has no direction.”

Supply lines open, time for the commander to take the field. The Form Controller extends ADForm and implements IFormController — like the commander donning armor and taking his seat at the command post. He is responsible for four things:

1. Loading the ZUL template (unfurling the battle standards)
2. Creating and passing the ViewModel (summoning the strategist to the tent)
3. Injecting iDempiere WebUI components (requisitioning weapons)
4. Listening to component events and updating the ViewModel (relaying field reports to the strategist)

Full Example: DispensingForm.java

package tw.topgiga.rnd.form;

import java.util.HashMap;
import java.util.Map;
import java.util.logging.Logger;

import org.adempiere.webui.editor.WSearchEditor;
import org.adempiere.webui.event.ValueChangeEvent;
import org.adempiere.webui.event.ValueChangeListener;
import org.adempiere.webui.panel.ADForm;
import org.adempiere.webui.panel.IFormController;
import org.compiere.model.MColumn;
import org.compiere.model.MLookup;
import org.compiere.model.MLookupFactory;
import org.compiere.util.DisplayType;
import org.compiere.util.Env;
import org.zkoss.bind.Binder;
import org.zkoss.zk.ui.Component;
import org.zkoss.zk.ui.Executions;
import org.zkoss.zk.ui.select.Selectors;
import org.zkoss.zk.ui.select.annotation.Wire;

import tw.topgiga.rnd.viewmodel.DispensingVM;

public class DispensingForm extends ADForm
        implements IFormController, ValueChangeListener {

    private static final long serialVersionUID = 1L;
    private static final Logger log =
            Logger.getLogger(DispensingForm.class.getName());

    // iDempiere WebUI component (not native ZK)
    private WSearchEditor fProject;

    // @Wire binds to the ZUL component with id="projectEditorContainer"
    @Wire("#projectEditorContainer")
    private Component projectEditorContainer;

    // @Wire binds to the ZUL root component, used to get Binder → ViewModel
    @Wire("#dispensingVMContainer")
    private Component dispensingVMContainer;

    @Override
    protected void initForm() {
        // ClassLoader switch: lets ~./ resolve bundle resources in OSGI
        ClassLoader cl = Thread.currentThread().getContextClassLoader();
        try {
            Thread.currentThread().setContextClassLoader(
                    getClass().getClassLoader());

            // Create ViewModel and pass it to ZUL via args
            Map<String, Object> args = new HashMap<>();
            args.put("vm", new DispensingVM());
            Executions.createComponents(
                    "~./zul/RND_DispensingForm.zul", this, args);

            // Wire ZUL components to Java fields (@Wire annotations)
            Selectors.wireComponents(this, this, false);

            // Create iDempiere WSearchEditor (Lookup component)
            MLookup projectLookup = MLookupFactory.get(
                    Env.getCtx(), 0, 0,
                    MColumn.getColumn_ID("RND_Project", "RND_Project_ID"),
                    DisplayType.Search);
            fProject = new WSearchEditor(
                    "RND_Project_ID", false, false, true, projectLookup);
            fProject.setMandatory(true);
            fProject.addValueChangeListener(this);

            // Append the WSearchEditor's ZK component to the ZUL container
            if (projectEditorContainer != null) {
                projectEditorContainer.appendChild(fProject.getComponent());
            }
        } catch (Exception e) {
            log.severe("Failed to init DispensingForm: " + e.getMessage());
        } finally {
            Thread.currentThread().setContextClassLoader(cl);
        }
    }

    /**
     * Listen for iDempiere component value changes, forward to ViewModel
     */
    @Override
    public void valueChange(ValueChangeEvent evt) {
        if (evt.getSource() == fProject) {
            Integer projectId = (Integer) evt.getNewValue();
            DispensingVM vm = getViewModel();
            if (vm != null) {
                vm.setSelectedProjectId(projectId);
            }
        }
    }

    /**
     * Retrieve the ViewModel instance from the ZK Binder
     */
    private DispensingVM getViewModel() {
        if (dispensingVMContainer == null) return null;
        Binder binder = (Binder) dispensingVMContainer
                .getAttribute("binder");
        if (binder == null) return null;
        Object vmInstance = binder.getViewModel();
        if (vmInstance instanceof DispensingVM) {
            return (DispensingVM) vmInstance;
        }
        return null;
    }

    @Override
    public ADForm getForm() {
        return this;
    }
}

Formation Three: The Strategist’s Tent — POJO ViewModel

The Strategist’s Maxim: “The strategist wears no armor, yet holds the power of life and death.”

The ViewModel is the brain of the entire Eight Formations. And here is the beautiful part — it is a pure POJO, extending no ZK classes whatsoever. Like Zhuge Liang himself: no armor, no sword, just a white robe and a feather fan, yet commanding the outcome of battles a thousand miles away from the comfort of his tent.

The strategist relies not on brute force, but on an elegant system of command flags and signal fires:

Example: DispensingVM.java

public class DispensingVM {

    private Integer selectedProjectId;
    private List<MFormula> projectFormulas = new ArrayList<>();
    private Set<MFormula> selectedFormulas = new HashSet<>();
    private List<MBatchTicket> batchTickets = new ArrayList<>();
    private BigDecimal scaleFactor = BigDecimal.ONE;

    @Init
    public void init() {
        // Initialization; in this example, project ID is set externally by Form Controller
    }

    @Command
    @NotifyChange({"projectFormulas", "selectedFormulas", "batchTickets"})
    public void loadProjectData() {
        projectFormulas.clear();
        if (selectedProjectId == null) return;

        List<MFormula> formulas = new Query(
                Env.getCtx(), MFormula.Table_Name,
                "RND_Project_ID = ? AND IsActive='Y'", null)
                .setParameters(selectedProjectId)
                .setOrderBy("Name")
                .list();

        if (formulas != null) projectFormulas.addAll(formulas);
        loadBatchTickets();
    }

    @Command
    @NotifyChange("batchTickets")
    public void generateBatchTickets() {
        if (selectedFormulas.isEmpty()) {
            Clients.showNotification("Please select at least one formula.",
                    "warning", null, "end_center", 3000);
            return;
        }
        MFormula[] formulas = selectedFormulas.toArray(new MFormula[0]);
        FormulaFactory.createBatchTicket(formulas, scaleFactor);
        loadBatchTickets();
    }

    @Command
    @NotifyChange({"selectedFormula", "formulaLines"})
    public void selectFormula(
            @BindingParam("formula") MFormula formula) {
        this.selectedFormula = formula;
        formulaLines.clear();
        if (formula != null) {
            for (MFormulaLine line : formula.getLines()) {
                formulaLines.add(line);
            }
        }
    }

    @DependsOn("selectedFormulas")
    public String getSelectedCountText() {
        int count = selectedFormulas != null ? selectedFormulas.size() : 0;
        return "Selected: " + count;
    }

    /**
     * Called by Form Controller (not a ZK Command).
     * Uses BindUtils.postNotifyChange to notify ZK to update the UI.
     */
    public void setSelectedProjectId(Integer projectId) {
        this.selectedProjectId = projectId;
        loadProjectData();
        BindUtils.postNotifyChange(null, null, this, "projectFormulas");
        BindUtils.postNotifyChange(null, null, this, "batchTickets");
    }

    // Getters/Setters (required by ZK MVVM)
    public List<MFormula> getProjectFormulas() { return projectFormulas; }
    public Set<MFormula> getSelectedFormulas() { return selectedFormulas; }
    public BigDecimal getScaleFactor() { return scaleFactor; }

    @NotifyChange("scaleFactor")
    public void setScaleFactor(BigDecimal sf) { this.scaleFactor = sf; }
}

Signal Fires vs. Carrier Pigeons: @NotifyChange vs. BindUtils.postNotifyChange

This is the most commonly confused pair of communication systems in the strategist’s arsenal. Mix them up, and the front line wins a victory that nobody hears about — the UI stays frozen:

Important: When the Commander (Form Controller) directly calls the Strategist’s (ViewModel’s) methods — such as setSelectedProjectId — this is not triggered by a Command Flag (@Command), so the signal fires will not light automatically. You must manually release the carrier pigeons (BindUtils.postNotifyChange), or the victory report will never reach the UI.

Formation Four: Planting the Battle Standards — ZUL Templates

The Strategist’s Maxim: “If the flag signals don’t work, orders never reach the troops.”

The ZUL template is the battle standard layout on the field — where to place the infantry, where to station the cavalry, which flag directs which unit. It is all spelled out in this diagram.

ViewModel Initialization

First, the battle standards must recognize the strategist. Use arg.vm to receive the pre-built ViewModel passed in by the Form Controller:

<borderlayout hflex="1" vflex="1" id="dispensingVMContainer"
              apply="org.zkoss.bind.BindComposer"
              viewModel="@id('vm') @init(arg.vm)">
    ...
</borderlayout>

Three critical settings:

• apply="org.zkoss.bind.BindComposer" — Activates ZK MVVM binding (turns on the flag signal system)
• viewModel="@id('vm') @init(arg.vm)" — Uses the VM instance passed from Java, rather than letting ZK create a new one (the strategist was summoned by the commander, not picked up off the street)
• id="dispensingVMContainer" — Allows the Form Controller to @Wire this component and access the VM through the Binder (the commander needs to be able to find the strategist’s tent)

Data Binding Syntax

The flag signals come in several varieties, each with a specific purpose:

<!-- One-way binding (VM → UI): strategist gives orders, flag bearer obeys -->
<label value="@load(vm.selectedCountText)"/>

<!-- Two-way binding (VM ↔ UI): field reports + strategist commands, bidirectional -->
<doublebox value="@bind(vm.scaleFactor)" format="##0.###"/>

<!-- List binding: strategist unfurls the roster, calling each name -->
<listbox model="@load(vm.projectFormulas)"
         selectedItems="@bind(vm.selectedFormulas)"
         checkmark="true" multiple="true">
    <template name="model" var="f">
        <listitem onClick="@command('selectFormula', formula=f)">
            <listcell label="@load(f.name)"/>
        </listitem>
    </template>
</listbox>

<!-- Command invocation: wave the command flag -->
<button label="Generate" onClick="@command('generateBatchTickets')"/>

<!-- Conditional disabled: can't march without selecting troops -->
<button label="Compare"
        onClick="@command('compareFormulas')"
        disabled="@load(empty vm.selectedFormulas)"/>

iDempiere Component Container

Reserve an empty <div> in the ZUL — like clearing a patch of ground in the camp, ready for weapons requisitioned from iDempiere:

<div id="projectEditorContainer" width="250px"
     style="min-height:25px;"/>

The commander uses @Wire to grab this patch of ground, then places the requisitioned iDempiere component on it:

@Wire("#projectEditorContainer")
private Component projectEditorContainer;

// in initForm():
projectEditorContainer.appendChild(fProject.getComponent());

Formation Five: Straw Boats Borrowing Arrows — Injecting iDempiere WebUI Components

The Strategist’s Maxim: “Don’t make arrows, don’t buy arrows — borrow them from the enemy.”

This is the most ingenious stratagem in the entire Eight Formations. In the classic tale, Zhuge Liang sailed straw-covered boats toward Cao Cao’s camp in heavy fog. Cao Cao’s archers, unable to see clearly, fired volley after volley — and every arrow lodged neatly in the straw. Zhuge Liang sailed home with 100,000 free arrows. Here, iDempiere has a treasure trove of ready-made WebUI components — WSearchEditor, WTableDirEditor, and more — precision-crafted arrows courtesy of Cao Cao’s armory. You don’t need to forge your own. Just borrow them.

WSearchEditor (Lookup Search Component)

// 1) Create MLookup (define which table and column to search)
MLookup projectLookup = MLookupFactory.get(
        Env.getCtx(),
        0,                   // windowNo
        0,                   // tabNo (not used for search)
        MColumn.getColumn_ID("RND_Project", "RND_Project_ID"),
        DisplayType.Search); // Search display type

// 2) Create WSearchEditor
WSearchEditor editor = new WSearchEditor(
        "RND_Project_ID",    // column name
        false,               // mandatory (initial)
        false,               // readOnly
        true,                // updateable
        projectLookup);      // lookup

// 3) Set properties
editor.setMandatory(true);

// 4) Listen for value changes
editor.addValueChangeListener(this);

// 5) Append to ZUL container
container.appendChild(editor.getComponent());

ValueChangeListener Bridge

The arrows borrowed from the straw boats need someone to catch them. The Form Controller implements ValueChangeListener, receives iDempiere component events, and relays them to the strategist (ViewModel):

@Override
public void valueChange(ValueChangeEvent evt) {
    if (evt.getSource() == fProject) {
        Integer projectId = (Integer) evt.getNewValue();
        DispensingVM vm = getViewModel();
        if (vm != null) {
            vm.setSelectedProjectId(projectId);
        }
    }
}

Accessing the ViewModel

Since the strategist (ViewModel) is managed by the ZK Binder, the commander must go through the Binder — a go-between — to reach the strategist:

private DispensingVM getViewModel() {
    if (dispensingVMContainer == null) return null;

    // ZK sets a "binder" attribute on components with apply="BindComposer"
    Binder binder = (Binder) dispensingVMContainer
            .getAttribute("binder");
    if (binder == null) return null;

    Object vmInstance = binder.getViewModel();
    if (vmInstance instanceof DispensingVM) {
        return (DispensingVM) vmInstance;
    }
    return null;
}

Formation Six: The Tiger Tally — IFormFactory and OSGI Registration

The Strategist’s Maxim: “Without the Tiger Tally, even a general may not command troops.”

In ancient China, the Tiger Tally was a bronze tiger split in two halves — the emperor kept one, the general kept the other. Only when both halves matched could troops be mobilized. The formation is set, the strategist is in place, the battle standards are planted — but without the Tiger Tally, this army never appears on the battlefield. IFormFactory is the Tiger Tally: iDempiere uses it to decide “when a user opens a form, which Java class should be created.”

IFormFactory Implementation

package tw.topgiga.rnd.factories;

import org.adempiere.webui.factory.IFormFactory;
import org.adempiere.webui.panel.ADForm;
import tw.topgiga.rnd.form.DispensingForm;

public class RNDFormFactory implements IFormFactory {

    @Override
    public ADForm newFormInstance(String formName) {
        if (formName == null) return null;

        if (formName.equals(DispensingForm.class.getName()))
            return new DispensingForm();

        return null;
    }
}

OSGI Service Component Declaration

Having the tally isn’t enough — it must be registered with the Ministry of War (OSGI). OSGI-INF/rnd_form_factory.xml:

<?xml version="1.0" encoding="UTF-8"?>
<scr:component xmlns:scr="http://www.osgi.org/xmlns/scr/v1.1.0"
               name="tw.topgiga.rnd.factories.RNDFormFactory">
   <implementation class="tw.topgiga.rnd.factories.RNDFormFactory"/>
   <property name="service.ranking" type="Integer" value="10"/>
   <service>
      <provide interface="org.adempiere.webui.factory.IFormFactory"/>
   </service>
</scr:component>

Service-Component in MANIFEST.MF

Finally, declare where the Tiger Tally is stored in the MANIFEST.MF:

Service-Component: OSGI-INF/rnd_form_factory.xml

AD_Form Configuration in iDempiere

Create a Form record in the Application Dictionary — like registering a new general on the official roster of the court:

• Classname: tw.topgiga.rnd.form.DispensingForm
• Create a Menu item pointing to this Form

Complete MANIFEST.MF Example

Here is the complete Ministry of War dossier, for reference:

Manifest-Version: 1.0
Bundle-ManifestVersion: 2
Bundle-Name: Rnd
Bundle-SymbolicName: tw.topgiga.rnd
Bundle-Version: 1.0.0.qualifier
Automatic-Module-Name: tw.topgiga.rnd
Bundle-ClassPath: src/,
 .
Bundle-RequiredExecutionEnvironment: JavaSE-17
Bundle-ActivationPolicy: lazy
Service-Component: OSGI-INF/rnd_form_factory.xml
Require-Bundle: org.adempiere.base;bundle-version="12.0.0",
 org.adempiere.ui.zk;bundle-version="12.0.0",
 zul;bundle-version="9.6.0",
 zk;bundle-version="9.6.0",
 zkbind;bundle-version="9.6.0",
 zcommon;bundle-version="9.6.0"
Import-Package: org.compiere.model,
 org.compiere.process,
 org.compiere.util,
 org.adempiere.base,
 org.adempiere.webui.editor,
 org.adempiere.webui.event,
 org.adempiere.webui.factory,
 org.adempiere.webui.panel,
 org.zkoss.bind,
 org.zkoss.bind.annotation,
 org.zkoss.zk.ui,
 org.zkoss.zk.ui.event,
 org.zkoss.zk.ui.select,
 org.zkoss.zk.ui.select.annotation,
 org.zkoss.zk.ui.util,
 org.zkoss.zul
Web-ContextPath: /rnd

Post-Battle Debriefing — FAQ

The Strategist’s Maxim: “Victory and defeat are the common lot of war; it is the debriefing that transmits the true art.”

What follows are every pitfall the strategist personally stumbled into. Each one was paid for in blood, sweat, and lost hair. Study them well — they might save you a few follicles.

Q: Page not found: ~./zul/MyForm.zul

What happened: You painstakingly wrote your ZUL template, opened the form, and got “page not found.” The file is sitting right there in web/zul/, but the system acts like it doesn’t exist. Imagine stacking grain in the granary while the supply officer insists “the warehouse is empty.”

Root cause: The Thread Context ClassLoader is not the bundle’s classloader, so ZK cannot find web/zul/MyForm.zul on the classpath.

Fix: Add the ClassLoader switch in initForm() (see Formation One: Borrowing the East Wind).

Q: CSS background: url('~./images/bg.png') doesn’t work

What happened: You thought ~./ would work inside CSS too? How naive. The background image refuses to load, the screen stays white, and you begin to question your career choices.

Root cause: CSS url() is resolved by the browser, not by ZK’s server-side ~./ path resolver. The browser has no idea what ~./ means — it only understands HTTP paths and Base64.

Fix: Embed the image as a Base64 Data URI:

<div style="background: url('data:image/jpeg;base64,/9j/4AAQ...') center/cover;"/>

Generating the Base64 string:

base64 -i web/images/header_banner.png | tr -d '\n' > web/images/header_banner.b64

Q: @NotifyChange doesn’t trigger UI updates

What happened: The strategist clearly updated the data, but the UI doesn’t budge. You’re hammering F5 like a madman — nothing changes. The signal fire tower is right there, but the fire just won’t light.

Root cause: Only methods annotated with @Command automatically process @NotifyChange. If a method is called directly from Java code (not via a ZK Command), @NotifyChange has no effect. Signal fires only ignite automatically when a command flag is waved; messages from outside the formation are ignored by the signal tower.

Fix: Use carrier pigeons — BindUtils.postNotifyChange:

public void setSelectedProjectId(Integer id) {
    this.selectedProjectId = id;
    loadProjectData();
    BindUtils.postNotifyChange(null, null, this, "projectFormulas");
}

Q: Selectors.wireComponents — @Wire fields are null

What happened: All your @Wire-annotated fields come back null. You triple-checked the IDs, the syntax is correct, and yet — null. It’s like sending a scout to find a camp that hasn’t been built yet. Of course he can’t find it.

Root cause: wireComponents must be called after createComponents. The ZUL components must exist before they can be wired. No camp, no scout report.

Fix: Ensure the correct call order — build the camp first, then send the scouts:

// 1) Create components first
Executions.createComponents("~./zul/MyForm.zul", this, args);
// 2) Then wire
Selectors.wireComponents(this, this, false);
// 3) Only now can you use @Wire fields
if (projectEditorContainer != null) { ... }

Q: Does MANIFEST.MF need Export-Package?

What happened: Someone asks: “Do I need to export my packages so ZK can find the ZUL files?”

Answer: No. The ~./ path resolution accesses resources inside the bundle via the ClassLoader. There is no need to export packages to other bundles. Think of it this way: the grain in the granary is for your own army — you don’t need to open the gates to every other warlord in the realm.

Thus Spoke Zhuge Liang

Thus spoke Zhuge Liang: “I laid the Eight Formations upon iDempiere, passing through seven trials: the Supply Lines, Borrowing the East Wind, the Commander’s Field Post, the Strategist’s Tent, the Battle Standards, Straw Boats Borrowing Arrows, and the Tiger Tally. The difficulty of the CustomForm path lies not in the code itself, but in the depths of OSGI, the treachery of ClassLoaders, and the roundabout ways of ZK MVVM. The world assumes that writing Java is sufficient, never suspecting that within the OSGI domain, a single ClassLoader mismatch can rout an entire army and leave the screen white as snow.

Yet once the formations are understood, follow the diagram and you may advance and retreat with composure even amid ten thousand enemies. Remember the four precepts: open the supply lines first; borrow the east wind first; never confuse command flags with signal fires; always register the Tiger Tally. Those who master this art need fear neither OSGI nor ClassLoaders, will wield MVVM as naturally as their own arm, and will craft CustomForms as easily as drawing breath.”

May your iDempiere development journey, from this day forward, be guarded by the Eight Formations — and may you never see “Page Not Found” again.