Adaptable State Technical Reference

Summary

State API is designed to help support to manage AdapTable State at run-time

State Options

Property	Type	Description	Default
applyState	`AdaptableApplyStateFunction`	Transforms state before applying it to the application. Called after `loadState()` but before the state is used.
autoMigrateState	`boolean`	Automatically migrate State from previous AdapTable version to current one	true
clearState	`AdaptableClearStateFunction`	Allows clearing of remote Adaptable State. Only invoked during `StateApi.reloadInitialState()` operations.	undefined
debounceStateDelay	`number`	Delay (in ms) to debounce `saveState` / `persistState` calls enabling grouping multiple sequential calls in single one (e.g. elevator doors)	400
loadState	`AdaptableLoadStateFunction`	Retrieves saved Adaptable State from storage or external source
persistState	`AdaptablePersistStateFunction`	Handles the actual storage of state to localStorage, server, etc. Called after `saveState()` to store the prepared state.
saveState	`AdaptableSaveStateFunction`	Transforms state before saving to storage. Called before `persistState()`.

State API

The Adaptable API provides an easy way to access all Adaptable State at runtime.

Nearly every class includes functions to allow developers to retrieve particular, relevant, portions of the State.

But the State API class is particularly useful, containing many functions to manage access to AdapTable State:

Method	Returns	Description
copyAllStateToClipboard()	`void`	Copies all Adaptable state to clipboard
copyUserStateToClipboard()	`void`	Copies User State sections of Adaptable State to clipboard
dispatchStateReadyAction(module)	`void`	Sent by each Module when it is Ready
getAdaptableFilterState()	`AdaptableFilterState`	Gets filter-related sections of Adaptable State
getAdaptableSortState()	`AdaptableSortState`	Gets sort-related sections of Adaptable State
getAlertState(returnJson)	`AlertState`	Returns Alert section of Adaptable State
getAllState()	`AdaptableState`	Retrieves ALL state which is currently stored by Adaptable (both persistent and transient/internal)
getApplicationState(returnJson)	`ApplicationState`	Returns Application section of Adaptable State
getCalculatedColumnState(returnJson)	`CalculatedColumnState`	Returns Calculated Column section of Adaptable State
getChartingState(returnJson)	`ChartingState`	Returns Charting section of Adaptable State
getCustomSortState(returnJson)	`CustomSortState`	Returns Custom Sort section of Adaptable State
getDashboardState(returnJson)	`DashboardState`	Returns Dashboard section of Adaptable State
getDescriptionForModule(adaptableModule)	`string`	Retrieves a brief description of an AdapTable Module
getExportState(returnJson)	`ExportState`	Returns Export section of Adaptable State
getFlashingCellState(returnJson)	`FlashingCellState`	Returns Flashing Cell section of Adaptable State
getFormatColumnState(returnJson)	`FormatColumnState`	Returns Format Column section of Adaptable State
getFreeTextColumnState(returnJson)	`FreeTextColumnState`	Returns FreeText Column section of Adaptable State
getHelpPageForModule(adaptableModule)	`string`	Retrieves the help page for an AdapTable Module
getInitialState()	`InitialState` `\| any`	Returns the Initial Adaptable State
getLayoutState(returnJson)	`LayoutState`	Returns Layout section of Adaptable State
getNamedQueryState(returnJson)	`NamedQueryState`	Returns Query section of Adaptable State
getNoteState(returnJson)	`NoteState`	Returns Note section of Adaptable State
getPersistentState()	`AdaptablePersistentState`	Retrieves the persistent state in Adaptable, i.e. state that is passed to the `StateOptions.persistState()` function.
getPlusMinusState(returnJson)	`PlusMinusState`	Returns Plus Minus section of Adaptable State
getQuickSearchState(returnJson)	`QuickSearchState`	Returns Quick Search section of Adaptable State
getShortcutState(returnJson)	`ShortcutState`	Returns Shortcut section of Adaptable State
getStatusBarState(returnJson)	`StatusBarState`	Returns StatusBar section of Adaptable State
getStyledColumnState(returnJson)	`StyledColumnState`	Returns StyledColumn section of Adaptable State
getThemeState(returnJson)	`ThemeState`	Returns Theme section of Adaptable State
getToolPanelState(returnJson)	`ToolPanelState`	Returns Tool Panel section of Adaptable State
getUserStateByStateKey(stateKey, returnJson)	`BaseState` `\| string`	Returns given section of Adaptable State (as JSON or object)
incrementUserStateRevision(stateKey)	`void`	Adds '1' to current revision number of State element
loadUserState(state)	`void`	Loads supplied user state, replacing (NOT merging) existing User(persisted) State.
persistAdaptableState()	`Promise<AdaptableState>`	Persists the current Adaptable State to storage.
reloadInitialState(newInitialState)	`Promise<void>`	Reloads existing (or supplied) Initial State; clears persistent state by calling `StateOptions.clearState`
setAdaptableStateKey(adaptableStateKey, config)	`Promise<void>`	Changes key used for persisting AdaptableState into localStorage; optionally provides an initialState to load

Initial State

Inital State is the Adaptable State provided at design time for first-time use.

The full definition of the object is:

Property	Type	Description
Alert	`AlertState`	Collection of `AlertDefinitions` which will fire Alerts when the rule is met
Application	`ApplicationState`	Empty state section (only populated at Design Time) available for User to store their own data with the rest of AdapTable state.
CalculatedColumn	`CalculatedColumnState`	Collection of CalculatedColumn objects that will display a value based on other cells in the row (using a Calculated Column Expression)
Charting	`ChartingState`	Named Charts (wrapping Chart models)
CustomSort	`CustomSortState`	Collection of Custom Sort objects to allow some columns to be sorted in non-standard (e.g. non alphabetical) ways
Dashboard	`DashboardState`	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
Export	`ExportState`	Collection of Report objects, together with name of the Current Report, as part of AdapTable export Module
FlashingCell	`FlashingCellState`	Definitions of which cells flash in response to data changes
FormatColumn	`FormatColumnState`	Collection of FormatColumn objects that will style an entire column either fully or using a Condition
FreeTextColumn	`FreeTextColumnState`	Collection of FreeText objects so users can make their own notes in bespoke columns that will get stored with their state (and not with the DataSource). Useful if needing a 'Comments' column.
Layout	`LayoutState`	Collection of Layouts to name (and manage) sets of column visibility, order, grouping, sorts, aggregations, filters etc.
NamedQuery	`NamedQueryState`	Named Queries available for use across multiple AdapTable Modules
Note	`NoteState`	Collection of personal Notes that are edited at Cell level
PlusMinus	`PlusMinusState`	Plus Minus module: nudge rules. Optional `IncrementKey` / `DecrementKey` on each nudge use `KeyboardEvent.key`; when omitted, `AdaptableOptions.plusMinusOptions` applies, then `+` / `-`.
QuickSearch	`QuickSearchState`	Configues how Quick Search will run i.e. how and whether to highlight matching cells and to filter out non-matching rows
Shortcut	`ShortcutState`	Collection of Shortcut objects to aid data entry and prevent 'fat finger' issues
StatusBar	`StatusBarState`	Configures the Adaptable Status Bar
StyledColumn	`StyledColumnState`	Collection of Special Column Styles
Theme	`ThemeState`	Specifies current Theme and lists User and System themes available for selection
ToolPanel	`ToolPanelState`	Sets order & visibility of Tool Panel controls in AdapTable ToolPanel (on right of grid)
UserInterface	`UserInterfaceState`	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:

Property	Type	Description
Revision	`number \| \{ Key: number; UpdateStrategy: 'Override' \| 'KeepUserDefined'; \}`	Version number of the Item - allows developers to update one section in Initial Adaptable State while keeping others unchanged

AdapTable State Events

AdapTable provides 3 State-related Events:

BeforeAdaptableStateChanges - fired before something changes in AdapTable State
AdaptableStateChanged - fired after anything changes in AdapTable State
AdaptableStateReloaded - 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:

Property	Type	Description
action	`Redux.Action`	The Redux Action that was invoked
actionName	`string`	Name of the Action
newState	`AdaptableState`	Adaptable State after the Action
oldState	`AdaptableState`	Adaptable State before the Action
adaptableContext	`any`	Custom application Context provided in `AdaptableOptions.adaptableContext`

Before Adaptable State Changes

The full definition of the BeforeAdaptableStateChangeInfo object is:

Property	Type	Description
action	`Redux.Action`	The Redux Action that is about to be invoked
actionName	`string`	Name of the Action about to be performed
state	`AdaptableState`	Current Adaptable State (before the Action is applied)
adaptableContext	`any`	Custom application Context provided in `AdaptableOptions.adaptableContext`

Adaptable State Reloaded

The full definition of the AdaptableStateReloadedInfo object is:

Property	Type	Description
newState	`AdaptablePersistentState`	Adaptable State after the reload
oldState	`AdaptablePersistentState`	Adaptable State before the reload
adaptableContext	`any`	Custom application Context provided in `AdaptableOptions.adaptableContext`

Base Event Info

Both EventInfo objects from BaseContext defined as follow:

Property	Type	Description
adaptableApi	`AdaptableApi`	Adaptable Api object
adaptableContext	`any`	Custom application Context provided in `AdaptableOptions.adaptableContext`
adaptableId	`string`	Id of current AdapTable instance
adaptableStateKey	`string`	Current Adaptable State Key
clientTimestamp	`Date`	Time on user's computer
userName	`string`	Name of Current User

Event Subscription

Subscribing to the Events is done the same as with all Adaptable Events:

api.eventApi.on(
  'AdaptableStateChanged',
  (eventInfo: AdaptableStateChangedInfo) => {
    // do something with the info
  }
);
api.eventApi.on(
  'AdaptableStateReloaded',
  (eventInfo: AdaptableStateReloadedInfo) => {
    // do something with the info
  }
);

PreviousMigrating AdapTable State NextPermissions