Adaptable State Technical Reference
State Options
StateOptions
Options related to Adaptable State hydration / dehydration; allows users to intercept state persistence and loading with custom functionality
All functions deal with AdaptablePersistentState - the persisted subset of AdaptableState.
Transient sections (Internal, Popup, Comment, Plugins) are never passed to, nor expected from, these functions.
Hydration flow: loadState() - (merge with initialState) - applyState()
Dehydration flow: saveState() - persistState()
To store Adaptable State in a custom format (e.g. wrapped in an envelope, compressed, encrypted) do the wrapping in persistState() and the unwrapping in loadState() - these are the only functions which own the storage format.
saveState() and applyState() always operate on Adaptable State, as loadState()'s result is merged with initialState section by section before applyState() is called.
Transforms state before applying it to the application. Called after loadState() (and after merging with initialState) but before the state is used.
boolean
Automatically migrate State from previous AdapTable version to current one
true
Allows clearing of remote Adaptable State. Only invoked during StateApi.reloadInitialState() operations.
undefined
number
Delay (in ms) to debounce saveState / persistState calls enabling grouping multiple sequential calls in single one (e.g. elevator doors)
Defaults to: 400. Also, the wait will be max 1000ms, at which point the save/persist calls will happen anyway.
400
Retrieves saved Adaptable State from storage or external source
Handles the actual storage of state to localStorage, server, etc. Called after saveState() to store the prepared state.
Transforms state before saving to storage. Called before persistState().
State API
StateApi
Adaptable State: the initial state, the full state, the persisted user state, and each module's section.
Promise<void>
Merges Initial State into the current user state (Revision / Override / KeepUserDefined),
without clearing persistence. Same merge as startup, applied at runtime.
When newInitialState is provided it also updates AdaptableOptions.initialState.
Omitting it re-applies the current Initial State onto current user state.
void
Copies all Adaptable state to clipboard
void
Copies User State sections of Adaptable State to clipboard
void
Sent by each Module when it is Ready
Gets filter-related sections of Adaptable State
Gets sort-related sections of Adaptable State
Returns Alert section of Adaptable State
Retrieves ALL state which is currently stored by Adaptable (both persistent and transient/internal)
Returns Application section of Adaptable State
Returns Calculated Column section of Adaptable State
Returns Charting section of Adaptable State
Returns Custom Sort section of Adaptable State
Returns Dashboard section of Adaptable State
string
Retrieves a brief description of an AdapTable Module
Returns Export section of Adaptable State
Returns Flashing Cell section of Adaptable State
Returns Format Column section of Adaptable State
Returns FreeText Column section of Adaptable State
string
Retrieves the help page for an AdapTable Module
InitialState | any
Returns the Initial Adaptable State
Returns Layout section of Adaptable State
Returns Query section of Adaptable State
Returns Note section of Adaptable State
Retrieves the persistent state in Adaptable, i.e. state that is passed to the StateOptions.persistState() function.
Returns Plus Minus section of Adaptable State
Returns Quick Search section of Adaptable State
Returns Shortcut section of Adaptable State
Returns StatusBar section of Adaptable State
Returns StyledColumn section of Adaptable State
Returns Theme section of Adaptable State
Returns Tool Panel section of Adaptable State
BaseState | string
Returns given section of Adaptable State (as JSON or object)
void
Adds '1' to current revision number of State element
Promise<void>
Loads supplied user state, replacing (NOT merging) existing User(persisted) State.
Promise<AdaptablePersistentState>
Persists the current Adaptable State to storage.
This method first calls StateOption.saveState() to prepare the state
and then StateOptions.persistState() to save it to the configured storage.
Promise<void>
Reloads existing (or supplied) Initial State; clears persistent state by calling StateOptions.clearState
Promise<void>
Re-runs the startup merge using persisted user state from StateOptions.loadState
and the current AdaptableOptions.initialState. Does not clear persistence.
Use when remote/local storage may have changed (or Initial State in options was updated)
and you want to re-sync without a full wipe (reloadInitialState).
Unsaved in-memory-only changes are discarded in favour of what loadState returns.
Promise<void>
Changes key used for persisting AdaptableState into localStorage; optionally provides an initialState to load
Application State
Application section of AdapTable State stores custom data as a collection of ApplicationDataEntries:
ApplicationState
Application section of Adaptable State, including Initial State.
A place to store your own key/value data with the rest of AdapTable State. There is no Application UI. Each Value must be stringifiable, because the section is persisted.
Array of Key / Value pairs enabling custom data to be stored in Adaptable State.
ApplicationDataEntry
Each ApplicationDataEntry is a key / value pair:
ApplicationDataEntry
Simple Key / Value pair object used to store custom - stringifiable - data in Adaptable State.
Application API
ApplicationApi
Provides run-time access to the Application Module
Adds new Application Data Entry
void
Creates new Application Data Entry with given Key and Value
Deletes given Application Data Entry
Edits given Application Data Entry
Every key/value entry in Application State.
Gets Application Data Entry with given value
ApplicationDataEntry | undefined
Gets Application Data Entry with given key
The Application section of Adaptable State.
Find Out More
See Customising AdapTable State for how Application State is supplied and persisted
Initial State
Initial State is the Adaptable State provided at design time for first-time use.
The full definition of the object is:
InitialState
Initial Adaptable State which is populated at design-time and used to create Adaptable State; must include at least one Layout (unless autoCreateLayout is set)
Collection of AlertDefinitions which will fire Alerts when the rule is met
Empty state section (only populated at Design Time) available for User to store their own data with the rest of AdapTable state.
Collection of CalculatedColumn objects that will display a value based on other cells in the row (using a Calculated Column Expression)
Saved charts. AG Grid charts are ChartDefinitions (Name and Model). Application charts are ExternalChartDefinitions (Name and Data).
Collection of Custom Sort objects to allow some columns to be sorted in non-standard (e.g. non alphabetical) ways
Large series of properties to give users full control over the look and feel of the Dashboard - the section above the grid with toolbars and buttons
Collection of Report objects, together with name of the Current Report, as part of AdapTable export Module
Flashing Cell definitions. Each one names a column scope and a boolean rule, and flashes a cell, a row, or an aggregated cell.
Format Columns. Each one colours cells, changes how values are displayed, or both, for a column scope. Omit Rule to apply it on every row.
Collection of FreeText objects that define user-owned columns whose cell values are stored in Adaptable State (not the grid DataSource). Use for editable per-row fields such as ops notes, flags, or codes — distinct from cell-level Notes and Comments.
Collection of Layouts to name (and manage) sets of column visibility, order, grouping, sorts, aggregations, filters etc.
Required unless layoutOptions.autoCreateLayout is set.
Named Queries other expressions can call with QUERY('Name'). A boolean query can be a Grid Filter or an Alert rule.
Plus Minus module: nudge rules. Optional IncrementKey / DecrementKey on each nudge
accept either a single key or a keyboard shortcut combination (e.g. shift+Enter); when
omitted, AdaptableOptions.plusMinusOptions applies, then + / -.
Quick Search text restored at startup, and the styles used to highlight matches.
Collection of Shortcut objects to aid data entry and prevent 'fat finger' issues
Status bars. Each Key matches an AG Grid statusPanels entry whose component is AdaptableStatusPanel.
Styled Columns. Each entry draws one column with a single visual style.
Active theme (light, dark or os) and which shipped themes are offered.
Sets order & visibility of Tool Panel controls in AdapTable ToolPanel (on right of grid)
Controls the visibility of AdapTable UI elements (Dashboard, Tool Panel, Status Bar, Menus etc.)
Every item in the object, inherits from BaseState which contains just one property:
BaseState
Base of every AdapTable State section.
Revision is how a newer Initial State updates one section without touching the others.
number | { Key: number; UpdateStrategy: 'Override' | 'KeepUserDefined'; }
Version of this section.
A number, or { Key, UpdateStrategy }. AdapTable compares Key (or the number) with the Revision already persisted for this section. When the Initial State key is higher, the section is updated:
- Override (the default) replaces the persisted section with the Initial State section.
- KeepUserDefined applies the Initial State section, then appends objects the user added (their Source is not InitialState) back onto each array.
AdapTable State Events
AdapTable provides 3 State-related Events:
BeforeAdaptableStateChange— fired before something changes in AdapTable StateAdaptableStateChanged— fired after anything changes in AdapTable StateAdaptableStateReloaded— fired whenever the State reloads
Find Out More
See Listening to Adaptable State for full details
Adaptable State Changed
The full definition of the AdaptableStateChangedInfo object is:
AdaptableStateChangedInfo
Payload of the AdaptableStateChanged event.
Fires after each Adaptable State change once the grid is ready. Loading or initialising state does not fire it; that is AdaptableStateReloaded.
Extends , so adaptableApi is included.
Redux.Action
Redux action that was applied.
string
Redux action type that was applied (action.type).
Full Adaptable State after the action.
Full Adaptable State before the action.
Custom application Context provided in AdaptableOptions.adaptableContext
Before Adaptable State Change
The full definition of the BeforeAdaptableStateChangeInfo object is:
BeforeAdaptableStateChangeInfo
Payload of the BeforeAdaptableStateChange event.
Fired synchronously, before the reducer runs, once the grid is ready.
Extends , so adaptableApi is included.
Redux.Action
The Redux Action that is about to be invoked
string
Redux action type about to be applied (action.type).
Current Adaptable State (before the Action is applied)
Custom application Context provided in AdaptableOptions.adaptableContext
Adaptable State Reloaded
The full definition of the AdaptableStateReloadedInfo object is:
AdaptableStateReloadedInfo
Payload of the AdaptableStateReloaded event.
Fires after persisted state has been loaded and applied. The load and init actions themselves do not emit AdaptableStateChanged.
Extends , so adaptableApi is included.
Persisted Adaptable State after the reload.
Persisted Adaptable State before the reload.
Custom application Context provided in AdaptableOptions.adaptableContext
Base Event Info
The Event Info objects extend BaseContext:
BaseContext
Base class for all AdapTable callbacks and Events
Adaptable Api object
Custom application Context provided in AdaptableOptions.adaptableContext
string
Id of current AdapTable instance
string
Current Adaptable State Key
Date
Time on user's computer
string
Name of Current User
Event Subscription
Subscribing to the Events is done the same as with all Adaptable Events:
api.eventApi.on(
'BeforeAdaptableStateChange',
(eventInfo: BeforeAdaptableStateChangeInfo) => {
// do something with the info
}
);
api.eventApi.on(
'AdaptableStateChanged',
(eventInfo: AdaptableStateChangedInfo) => {
// do something with the info
}
);
api.eventApi.on(
'AdaptableStateReloaded',
(eventInfo: AdaptableStateReloadedInfo) => {
// do something with the info
}
);