Adaptable State Technical Reference
Summary
- State API is designed to help support to manage AdapTable State at run-time
State Options
| Property | Description | Default |
|---|---|---|
| applyState | Transforms state before applying it to the application. Called after loadState() but before the state is used. | |
| autoMigrateState | Automatically migrate State from previous AdapTable version to current one | true |
| clearState | Allows clearing of remote Adaptable State. Only invoked during StateApi.reloadInitialState() operations. | undefined |
| debounceStateDelay | Delay (in ms) to debounce saveState / persistState calls enabling grouping multiple sequential calls in single one (e.g. elevator doors) | 400 |
| loadState | Retrieves saved Adaptable State from storage or external source | |
| persistState | Handles the actual storage of state to localStorage, server, etc. Called after saveState() to store the prepared state. | |
| saveState | 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 | Description |
|---|---|
| copyAllStateToClipboard() | Copies all Adaptable state to clipboard |
| copyUserStateToClipboard() | Copies User State sections of Adaptable State to clipboard |
| dispatchStateReadyAction(module) | Sent by each Module when it is Ready |
| getAdaptableFilterState() | Gets filter-related sections of Adaptable State |
| getAdaptableSortState() | Gets sort-related sections of Adaptable State |
| getAlertState(returnJson) | Returns Alert section of Adaptable State |
| getAllState() | Retrieves ALL state which is currently stored by Adaptable (both persistent and transient/internal) |
| getApplicationState(returnJson) | Returns Application section of Adaptable State |
| getCalculatedColumnState(returnJson) | Returns Calculated Column section of Adaptable State |
| getChartingState(returnJson) | Returns Charting section of Adaptable State |
| getCustomSortState(returnJson) | Returns Custom Sort section of Adaptable State |
| getDashboardState(returnJson) | Returns Dashboard section of Adaptable State |
| getDescriptionForModule(adaptableModule) | Retrieves a brief description of an AdapTable Module |
| getExportState(returnJson) | Returns Export section of Adaptable State |
| getFlashingCellState(returnJson) | Returns Flashing Cell section of Adaptable State |
| getFormatColumnState(returnJson) | Returns Format Column section of Adaptable State |
| getFreeTextColumnState(returnJson) | Returns FreeText Column section of Adaptable State |
| getHelpPageForModule(adaptableModule) | Retrieves the help page for an AdapTable Module |
| getInitialState() | Returns the Initial Adaptable State |
| getLayoutState(returnJson) | Returns Layout section of Adaptable State |
| getNamedQueryState(returnJson) | Returns Query section of Adaptable State |
| getNoteState(returnJson) | Returns Note section of Adaptable State |
| getPersistentState() | Retrieves the persistent state in Adaptable, i.e. state that is passed to the StateOptions.persistState() function. |
| getPlusMinusState(returnJson) | Returns Plus Minus section of Adaptable State |
| getQuickSearchState(returnJson) | Returns Quick Search section of Adaptable State |
| getScheduleState(returnJson) | Returns Schedule section of Adaptable State |
| getShortcutState(returnJson) | Returns Shortcut section of Adaptable State |
| getStatusBarState(returnJson) | Returns StatusBar section of Adaptable State |
| getStyledColumnState(returnJson) | Returns StyledColumn section of Adaptable State |
| getThemeState(returnJson) | Returns Theme section of Adaptable State |
| getToolPanelState(returnJson) | Returns Tool Panel section of Adaptable State |
| getUserStateByStateKey(stateKey, returnJson) | Returns given section of Adaptable State (as JSON or object) |
| incrementUserStateRevision(stateKey) | Adds '1' to current revision number of State element |
| loadUserState(state) | Loads supplied user state, replacing (NOT merging) existing User(persisted) State. |
| persistAdaptableState() | Persists the current Adaptable State to storage. |
| reloadInitialState(newInitialState) | Reloads existing (or supplied) Initial State; clears persistent state by calling StateOptions.clearState |
| setAdaptableStateKey(adaptableStateKey, config) | 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 | Description |
|---|---|
| Alert | Collection of AlertDefinitions which will fire Alerts when the rule is met |
| Application | Empty state section (only populated at Design Time) available for User to store their own data with the rest of AdapTable state. |
| CalculatedColumn | Collection of CalculatedColumn objects that will display a value based on other cells in the row (using a Calculated Column Expression) |
| Charting | Named Charts (wrapping Chart models) |
| CustomSort | Collection of Custom Sort objects to allow some columns to be sorted in non-standard (e.g. non alphabetical) ways |
| Dashboard | 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 | Collection of Report objects, together with name of the Current Report, as part of AdapTable export Module |
| FlashingCell | Definitions of which cells flash in response to data changes |
| FormatColumn | Collection of FormatColumn objects that will style an entire column either fully or using a Condition |
| FreeTextColumn | 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 | Collection of Layouts to name (and manage) sets of column visibility, order, grouping, sorts, aggregations, filters etc. |
| NamedQuery | Named Queries available for use across multiple AdapTable Modules; and CurrentQuery - an Expression to run at start-up |
| Note | Collection of personal Notes that are edited at Cell level |
| PlusMinus | Collection of PlusMinus rule objects to stipulate what happens when the user clicks '+' or '-' in a numeric cell |
| QuickSearch | Configues how Quick Search will run i.e. how and whether to highlight matching cells and to filter out non-matching rows |
| Schedule | Collection of Schedule objects |
| Shortcut | Collection of Shortcut objects to aid data entry and prevent 'fat finger' issues |
| StatusBar | Configures the Adaptable Status Bar |
| StyledColumn | Collection of Special Column Styles |
| Theme | Specifies current Theme and lists User and System themes available for selection |
| ToolPanel | Sets order & visibility of Tool Panel controls in AdapTable ToolPanel (on right of grid) |
| UserInterface | 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 | Description |
|---|---|
| Revision | Version number of the Item - allows developers to update one section in Initial Adaptable State while keeping others unchanged |
AdapTable State Events
AdapTable provides 2 State-related Events:
AdaptableStateChanged- fired when 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:
| Property | Description |
|---|---|
| action | The Redux Action that was invoked |
| actionName | Name of the Action |
| newState | Adaptable State after the Action |
| oldState | Adaptable State before the Action |
| adaptableContext | Custom application Context provided in AdaptableOptions.adaptableContext |
Adaptable State Reloaded
The full definition of the AdaptableStateReloadedInfo object is:
| Property | Description |
|---|---|
| newState | Adaptable State after the reload |
| oldState | Adaptable State before the reload |
| adaptableContext | Custom application Context provided in AdaptableOptions.adaptableContext |
Base Event Info
Both EventInfo objects from BaseContext defined as follow:
| Property | Description |
|---|---|
| adaptableApi | Adaptable Api object |
| adaptableContext | Custom application Context provided in AdaptableOptions.adaptableContext |
| adaptableId | Id of current AdapTable instance |
| adaptableStateKey | Current Adaptable State Key |
| clientTimestamp | Time on user's computer |
| userName | 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
});