App Composer Components: Data Hub

(this page was created automatically. In case of formatting issues, please visit the official Wiki Page)

Audience: Low‑code builders (Dynamic Content Editor) and developers wiring dynamic actions / elements.

0. Why The Data Hub Exists

App composer components often need lightweight shared state for itself, boardlet to boardlet communication (app scope) or app to app communication (global). In earlier iterations we used "global parameters" (added to the URL / shared via route state) for cross‑element exchange. That approach has limits:

Data Hub solves these by offering an in‑memory, non‑URL, structured store with three explicit scopes and predictable precedence.

The Data Hub provides:

• Zero‑config ephemeral state (in‑memory, auto‑clears on reload)
• Simple key/value API with three intention‑revealing scopes (Local → App → Global) to minimise accidental coupling
• Deterministic merge & precedence so templates stay concise ({{ someKey}} just works with local override semantics)
• Event reactivity through ON_DATA_HUB_CHANGE so elements can react declaratively when relevant data changes
• A uniform contract consumed by the Dynamic Rendering Context so all dynamic elements read state the same way

Use it whenever you need temporary data sharing between actions or elements—especially for richer values you do NOT want in the page URL.

1. When To Use (Decision Guide)

Rule of thumb: Start as Local, promote to App only when two or more contents collaborate, promote to Global only if truly cross‑app.

2. Core Mental Model

Three maps exist simultaneously:

• Global Map (singleton for the session)
• App Map (namespaced by current appKey)
• Local Map (namespaced by contentId)

When something on the page runs, the system builds a usable "context" made from Global, then App, then Local data (Local beats App, App beats Global if the same key exists). So if selection exists in Local, that one shows; otherwise it falls back to App, then Global. You can still explicitly read each scope: local.selection, app.selection, global.selection.

Additional always‑present helper keys:

3. How To Set Values (Action Editor)

Chain Dynamic Actions:

Each Set action defines a Parameters Map (rows). For each row you specify: Target Key, Source Type, Value/Expression.

Supported Source Patterns (Common)

Merge Semantics (Per Key)

Tip: Replacing an object but keeping stale nested fields? First set the key to null, then set the new object.

4. Reading Values

1. Direct in app composer components: {{ selection.rowId }} or explicit {{ local.selection.rowId }}
2. Via Get actions inside an action chain when an intermediate action (e.g. API Invoke) needs the value.

5. Reactivity With ON_DATA_HUB_CHANGE

ON_DATA_HUB_CHANGE lets an element automatically fire an action chain whenever any Data Hub value changes (Local, App, or Global). Add it only where you need automatic reactions.

5.1 What Triggers It?

Whenever a Set/Remove/Clear action actually changes a value (not just writing the same thing again).

5.2 Payload Structure

Inside the chain you can directly use the same placeholders as in templates. All flattened keys are available (with Local taking precedence). You can still reach the exact scope using local.<key>, app.<key>, or global.<key>.

5.3 Typical Use Cases

• Auto refresh detail panel when selection changes elsewhere
• Trigger conditional API pre‑fetch when prerequisite key appears (e.g. rowDetails after selection set)
• Cascade enrichment: selection → fetch → store → label updates

5.4 Filtering Inside the Chain

Because the event fires for ANY change, always gate expensive logic:

1. Add a Condition action checking the key(s) you care about.
2. (Optional) Maintain a previous snapshot locally: store lastProcessedSelection and compare.

Example condition idea: Only continue if the row actually changed. You could store lastProcessedSelection locally and compare {{ selection.rowId !== (lastProcessedSelection?.rowId) }}; then update lastProcessedSelection at the end.

5.5 Performance Considerations

• Namespacing keys keeps unrelated changes from touching objects you depend on.
• Avoid putting everything in one huge object (split into smaller keys like selection, selectionMeta).

5.6 When NOT To Use The Event

• Display‑only: if a component just shows context values you usually do not need ON_DATA_HUB_CHANGE; the rendering system already re‑supplies updated context. Use the event only for side effects (API calls, further Set actions, navigation, dialogs, etc.).

6. Practical Recipes

6.1 Store a Table Selection (Local)

Row Click → Local Set (selection = JSON Interpolated: { "rowId":"{{clickedRow.id}}", "ts":"{{timestamp}}" })

6.2 Use Selection In Button API Call

Button Click chain:

1. Local Get (selection)
2. Check context change (selection)
3. API Invoke (body includes {{selection.rowId}})
4. Local Set (rowDetails = response)

6.3 Shared Filter Across Widgets

Input Change → App Set (activeFilter = user input). All boardlet reference activeFilter or app.activeFilter. Boardlet can also listen for On Data Hub Change

6.4 React To Data Changes

Add event ON_DATA_HUB_CHANGE to a panel element; first action checks if selection actually changed; next action fetches details and stores them.

6.5 DynamicLabel Examples

A. Show A Value Stored In Data Hub

1. A table row click sets Local key currentRow = { "id": "{{clickedRow.id}}", "name": "{{clickedRow.name}}" }.
2. In the label text field use: Selected: {{currentRow.name}}.
3. The label updates immediately after the Set action (no extra event needed).

Result: Label updates automatically after the Set action without needing ON_DATA_HUB_CHANGE.

B. Prevent Flicker With Progressive Loading

1. Set placeholder: Local Set currentRow = { "name": "Loading..." }.
2. Run API action.
3. On success Set currentRow again with real data.
4. Label swaps from placeholder to real content.

C. Access Scoped Values Explicitly

If both global.currentUser and Local currentUser exist: Welcome {{currentUser.name || global.currentUser.name}} ensures Local override but falls back gracefully.

6.6 Patterns For Other Components

All other dynamic components work the same: use {{ someKey }} (flattened), or explicitly {{ app.filterX }}, {{ global.tenant.id }}.

7. Naming & Collision Strategy

8. Cleaning / Resetting

• Provide a Clear Local Data On destroy event
• Navigation: optionally clear App keys via dedicated Clear action (if available) or set them to neutral defaults
• To purge multiple nested leftovers, replace parent object instead of merging

9. Troubleshooting Quick Table

10. Quick Reminders (No‑Code Friendly)

Performance (plain language): keep keys focused, split large objects, only enable ON_DATA_HUB_CHANGE where you truly need automatic follow‑up actions.