forge/2.common.md at 9b31184f0ccfd7299ebe468a5681ea83272107c3

Jacob Schmidt a4d5c2fd4d Enhance documentation structure and content across multiple guides

- Added frontmatter to various markdown files for better metadata handling.
- Updated site URLs in configuration files for consistency.
- Improved content organization and clarity in getting started, server extension, and client addon guides.

2026-05-16 10:33:17 -05:00

2.7 KiB

Raw Blame History

title, description

title	description
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:

Field	Purpose
`control`	Active browser control.
`readyState`	Whether the browser app has sent its ready event.
`pendingEvents`	Outbound events waiting for a ready browser.

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.

2.7 KiB Raw Blame History