Jacob Schmidt 89169f1e84 Update documentation and add new client usage guides

- Revised README.md for the Forge Client Example Addon to clarify its purpose as a template.
- Enhanced MODULE_REFERENCE.md to categorize guides into Server and Extension guides and Client guides.
- Created detailed usage guides for various client addons including Actor, Bank, CAD, Garage, Locker, Notifications, Organization, Phone, and Store.
- Added a Client Common Usage Guide to outline shared browser UI bridge patterns.
- Introduced a Client Main Usage Guide to define the foundational elements for client addons.
- Established authoritative state notes and usage rules across new guides to ensure clarity on server ownership and client responsibilities.

2026-04-18 13:04:01 -05:00

2.7 KiB

Raw Blame History

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