Persisted state
Use this page to turn a product requirement into a storage decision. First decide what users must be able to restore. Then wire the public state object that owns that information. The Backend integration guide separately explains how to store the selected objects.
Choose what users can restore
| Product requirement | Public state | What the integrator must decide | Guide |
|---|---|---|---|
| Reopen one named chart workspace and reapply saved content to its mounted charts | ChartLayout | Give the chart layout and each mounted chart a stable id; choose whether drawings travel inside it | Chart workspace layouts |
| Reopen a composed terminal with the same panels, tabs, groups, sizes, and widget parameters | WidgetLayoutState | Give the widget panel arrangement a stable identity and keep its lifecycle independent from chart layouts | Widget panel arrangements |
| Share, version, or update drawings independently from a chart layout | DrawingState | Use separate drawing storage and define the sharing bucket | Drawing storage |
| Let users apply a reusable chart, indicator, or drawing preset elsewhere | ChartTemplate | Enable only the template kinds the product exposes | Templates |
| Keep preferences when users switch chart layouts | UserSettingsState | Define which values are per user or workspace instead of chart-layout-specific | User settings |
| Resume one chart's replay cursor, status, and speed | ReplayState | Define the chart context whose replay session should return | Replay state |
Do not persist an object merely because the SDK exposes it. If the product does not promise that result after a reload, leave that storage capability out.
Keep independent lifecycles independent
A composed Trading Terminal commonly needs both ChartLayout and
WidgetLayoutState: the chart layout restores chart content, while the widget
panel arrangement restores the product shell around it. Saving, replacing, or
deleting one must not imply the same operation for the other.
Drawings are embedded in a chart layout by default. Use DrawingState only
when drawings need separate sharing, revision, deletion, or synchronization
behavior. A template is reusable input; it is not the identity of the chart
workspace to which it is applied. User settings survive chart-layout changes
and therefore do not belong in ChartLayout.metadata.
Keep live authorities out of persisted state
| Information | Correct owner | Why it is separate |
|---|---|---|
| Keyboard shortcuts | HotkeyStorageAdapter | Key bindings have their own user scope and sharing lifecycle |
| Alerts | AlertProvider | Alerts are active backend jobs, not passive chart JSON |
| Image drawing files | ChartImageStorageAdapter | Binary assets are uploaded separately from chart-layout, drawing, or template JSON |
| Market data and trading state | Datafeed and broker backends | These systems remain the live authorities for prices, orders, positions, and accounts |
chart.getState() may expose a broader runtime snapshot than any one public
storage object. Do not persist that snapshot as a substitute for the storage
contracts above.
Next steps
- Chart workspace layouts — define the chart-workspace state users can restore.
- Widget panel arrangements — define the panel state users can restore.
- Drawing storage — decide whether drawings stay embedded or have an independent lifecycle.
- Backend integration — implement storage after choosing the required state objects.