Client Common Usage Guide

The client common addon contains shared browser UI bridge declarations and common client-side browser integration patterns.

Purpose

Use forge_client_common when a browser-backed feature UI needs reusable screen lifecycle behavior:

• active browser control tracking
• browser ready state
• pending event queues
• ExecJS payload delivery
• shared bridge object inheritance through createHashMapObject

Feature addons still own their app-specific events and server RPC mapping.

Shared Bridge

Initialize the bridge declarations with:

private _webUIDeclarations = call forge_client_common_fnc_initWebUIBridge;
private _bridgeDeclaration = _webUIDeclarations get "bridgeDeclaration";

Feature bridges can inherit from the shared declaration:

GVAR(MyUIBridgeBaseClass) = compileFinal createHashMapFromArray [
    ["#base", _bridgeDeclaration],
    ["#type", "MyUIBridgeBaseClass"],
    ["handleReady", compileFinal {
        params [["_control", controlNull, [controlNull]]];

        _self call ["setActiveBrowserControl", [_control]];
        _self call ["sendEvent", ["myAddon::hydrate", createHashMap, _control]];
    }]
];

Event Delivery

sendEvent builds this payload:

{
  "event": "myAddon::event",
  "data": {}
}

If the browser control is missing or not ready, the payload is queued on the screen object. When the screen marks ready, flushPendingEvents delivers the queue.

Screen Lifecycle

The shared screen object tracks:

Call handleClose or dispose when a display closes so stale controls and queued events are cleared.

Current Consumers

The common bridge pattern is used by the newer bank, CAD, garage, and organization client bridges. Store currently keeps its own bridge object and browser bridge function names.

Usage Rules

• Keep bridge inheritance in feature addons thin and explicit.
• Keep shared code generic; do not add bank, CAD, org, or store-specific logic to common.
• Prefer namespaced events such as garage::sync.
• Send hash maps or arrays that can be safely serialized with toJSON.
• Avoid direct extension calls from the client bridge; send CBA server events.

Related Guides

• Client Usage Guide
• Client Bank Usage Guide
• Client CAD Usage Guide
• Client Garage Usage Guide
• Client Organization Usage Guide