This guide looks at how AdapTable manages User State at run-time.
See Predefined Config for extensive information on how to pre-populate a new AdapTable instance with initial User State at design-time.
Managing User State is one of the most valued pieces of functionality that AdapTable provides.
User State includes state provided at design-time (through Predefined Config) and that created at run-time through user action (e.g. selecting a Layout, creating a Column Filter etc.)
AdapTable automatically saves User State as it changes - meaning that the next time the Application is reloaded, the user sees the same state as on the previous visit.
Internally AdapTable uses Redux to manage its state - this provides a unidirectional store for all the objects used in the grid. This means that if you are also using Redux in your own application, then you should continue to use your own Store and not merge the 2 Stores.
Adaptable State Storage Options
There are 2 modes of storage available in AdapTable:
If using Local Storage, all user state will be lost each time the user clear's the browser cache and will not be available when switching computer.
Remote Storage - Adaptable state will be persisted to, and retrieved from, a remote location which you manage via State Options functions.
AdapTable provides 4 function hooks to enable users to provide their own implementations / functionality when state is being managed.
This allows you to provide your own hydration or rehydration functionality or to enrich the State when its being loaded with your own items (e.g. entitlements).
The 4 functions you can provide your own implementations for are:
loadState: Allows the customization of state loading.
applyState: Allows hooking into AdaptableState hydration
saveState: Allows the customization of the state that is going to be persisted
persistState: Allows the customization of state persistence
See more at State Options.
Accessing Adaptable State
Developers have full, run-time access to the Adaptable State Store is via the Adaptable Api.
Among many other advantages, the Adaptable Api provides full, programmatic, read / write access to all Adaptable State objects in a 'clean' and safe way.
The Adaptable Api is effectively a wrapper around our Redux store with some additional error handling, logging and other features.
Listening to State Changes
This event fires whenever anything in the State changes; it provides the Action that caused the change (with full details) as well as before and after copies of Adaptable State.
See State Changed Actions Appendix for a full list of State Changed Actions.
Clearing Adaptable State
Bespoke Items in Adaptable State
Bespoke data can be stored in AdapTable State via the
AdaptableEntries property of Application State.
This provides an array of key / value pairs which AdapTable will persist with the rest of the state.
Multiple 'Views' (or State sections)
Advanced Users of AdapTable often ask how they can create multiple 'Views' - ie. different, separate, named collections of Adaptable State - and switch between them at run-time.
A View in this scenario is not the same as a Layout as that stores Column information only, while a 'View' can contain multiple different sections of Predefined Config.
The Multiple Views demo provides one possible example for how to do this.
Retrieving State at run-time
The Config Api section of Adaptable Api contains many methods for retrieiving and managing Adaptable State.
Additionally the State Management Module contains a button to clear current User State and a series of helper methods to export State, User State or Predefined Config to various destinations.
Where is Adaptable State stored?
By default it is stored in the local browser cache. However you can use the State Options functions to choose to save your state in any location that you specify (as well as to enrich it en route).
Do you provide data adapters to fetch / save Adaptable State?
No we don't, you will need to provide the mechanism to store configuration in a remote location.
There are simply too many different storage locations and mechnisms for it to make sense for us to provide connectors.
Can I preconfigure my AdapTable instance?
Yes you can. You are able to build your own Adaptable Objects which are stored as Predefined Config. You then provide this configuration as a JSON object or as a URL (to a .JSON file) in Adaptable Options.
Can I provide different Predefined Config per user?
Yes, that is possible and expected. AdapTable allows you provide highly configurable and personalised instances.
Can we store our own data in the AdapTable State / Predefined Config?
Yes you can. Use the
AdaptableEntries property of Application State.
This provides an array of key / value pairs which you can use to store your own bespoke data and AdapTable will persist it with the rest of the state.
Is there a restriction on what we can store in AdapTable Entries?
- AdapTable State Demos contains a number of state-related demos
Appendix: State Change Actions
|ALERT_DEFINITION_ADD||An Alert Definition has been added|
|ALERT_DEFINITION_DELETE||An Alert Definition has been deleted|
|ALERT_DEFINITION_EDIT||An Alert Definition has been edited|
|ALERT_READY||Alert Module is ready|
|APPLICATION_DATA_ENTRY_ADD||An Application Data Entry has been added|
|APPLICATION_DATA_ENTRY_DELETE||An Application Data Entry has been deleted|
|APPLICATION_DATA_ENTRY_EDIT||An Application Data Entry has been edited|
|BULK_UPDATE_APPLY||Bulk Update is being applied|
|BULK_UPDATE_COMPLETE||Bulk Update has been completed|
|BULK_UPDATE_READY||Bulk Update Module is ready|
|CALCULATED_COLUMN_ADD||A Calculated Column has been added|
|CALCULATED_COLUMN_DELETE||A Calculated Column has been deleted|
|CALCULATED_COLUMN_EDIT||A Calculated Column has been edited|
|CALCULATED_COLUMN_READY||Calculated Column Module is ready|
|COLUMN_FILTER_ADD||A Column Filter has been added|
|COLUMN_FILTER_CLEAR||A Column Filter has been cleared|
|COLUMN_FILTER_CLEAR_ALL||All Column Filters have been cleared|
|COLUMN_FILTER_EDIT||A Column Filter has been edited|
|COLUMN_FILTER_SET||Column Filters have been set|
|CONDITIONAL_STYLE_ADD||A Conditional Style has been added|
|CONDITIONAL_STYLE_DELETE||A Conditional Style has been deleted|
|CONDITIONAL_STYLE_EDIT||A Conditional Style has been edited|
|CONDITIONAL_STYLE_READY||Conditional Style Module is ready|
|CUSTOM_SORT_ADD||A Custom Sort has been added|
|CUSTOM_SORT_DELETE||A Custom Sort has been deleted|
|CUSTOM_SORT_EDIT||A Custom Sort has been edited|
|CUSTOM_SORT_READY||Custom Sort Module is ready|
|DASHBOARD_ACTIVE_TAB_INDEX_CHANGE||Active tab has changed|
|DASHBOARD_CLOSE_TOOLBAR||A Toolbar has been closed|
|DASHBOARD_CREATE_DEFAULT_TAB||A default Tab has been created|
|DASHBOARD_READY||Dashboard is ready|
|DASHBOARD_SET_FLOATING_POSITION||Floating position has changed|
|DASHBOARD_SET_IS_COLLAPSED||Collapsed Mode has changed|
|DASHBOARD_SET_IS_FLOATING||Floating Mode has changed|
|DASHBOARD_SET_IS_HIDDEN||Visibility has changed|
|DASHBOARD_SET_IS_INLINE||Inline Mode has changed|
|DASHBOARD_SET_MODULE_BUTTONS||The Module Buttons have been set in the Dashboard|
|DASHBOARD_SET_TABS||New Dashboard Tabs have been set|
|DASHBOARD_SET_TITLE||Dashboard Title has been set|
|DATA_SOURCE_ADD||A Data Source has been added|
|DATA_SOURCE_DELETE||A Data Source has been deleted|
|DATA_SOURCE_EDIT||A Data Source has been edited|
|DATA_SOURCE_READY||Data Source Module is ready|
|DATA_SOURCE_SELECT||A Data Source has been selected|
|DESTINATION_SELECT||A report Destination has been selected|
|EXPORT_APPLY||Export has been applied|
|EXPORT_READY||Export Module is ready|
|FILTER_FORM_HIDE||The Filter Form has been hidden|
|FILTER_READY||Filter Module is ready|
|FLASHING_ALERT_DEFINITION_ADD||A Flashing Alert Definition has been added|
|FLASHING_ALERT_DEFINITION_DELETE||A Flashing Alert Definition has been deleted|
|FLASHING_ALERT_DEFINITION_EDIT||A Flashing Alert Definition has been edited|
|FORMAT_COLUMN_ADD||A Format Column has been added|
|FORMAT_COLUMN_DELETE||A Format Column has been deleted|
|FORMAT_COLUMN_EDIT||A Format Column has been edited|
|FORMAT_COLUMN_READY||FormatColumn Module is ready|
|FREE_TEXT_COLUMN_ADD||A Free Text Column has been added|
|FREE_TEXT_COLUMN_ADD_EDIT_STORED_VALUE||A Free Text Column's stored values have changed|
|FREE_TEXT_COLUMN_DELETE||A Free Text Column has been deleted|
|FREE_TEXT_COLUMN_EDIT||A Free Text Column has been edited|
|FREE_TEXT_COLUMN_READY||FreeTextColumn Module is ready|
|GLUE42_LIVE_REPORT_CLEAR||A Glue42 live report has stopped|
|GLUE42_LIVE_REPORT_SET||A Glue42 live report has started|
|GLUE42_LOGIN||Logged in to Glue42|
|GLUE42_SCHEDULE_ADD||A Glue42 Schedule has been added|
|GLUE42_SCHEDULE_DELETE||A Glue42 Schedule has been deleted|
|GLUE42_SCHEDULE_EDIT||A Glue42 Schedule has been edited|
|GLUE42_SEND_SNAPSHOT||A snapshot report has been sent|
|GLUE42_SET_LOGIN_ERROR_MESSAGE||Error message set from failed login|
|GLUE42_SET_THROTTLE_TIME||Throttle time for live reports has been set|
|GLUE42_START_LIVE_DATA||Live data has been sent to Glue42|
|GLUE42_STOP_LIVE_DATA||Live data is not longer sent to Glue42|
|GRID_ADD_COLUMN||A Column has been added to the Grid|
|GRID_ADD_COLUMNS||Columns have been added to the Grid|
|GRID_CREATE_CELLS_SUMMARY||Cell Summary Information has been created|
|GRID_DATA_CHANGED||Grid data has changed but not as the result of user edit|
|GRID_DATA_EDITED||A cell has been edited by the user|
|GRID_EDIT_COLUMN||A Column has been edited in the Grid|
|GRID_REFRESH_CELLS||Grid cells have been refreshed|
|GRID_REMOVE_COLUMN||A Column has been removed from the Grid|
|GRID_SET_CELLS_SUMMARY||Grid Cell summary is set|
|GRID_SET_COLUMNS||Columns have been set in the Grid|
|GRID_SET_MODULE_BUTTON_MENUITEMS||Module Button menu items have been set|
|GRID_SET_MODULE_DROPDOWN_MENUITEMS||Module Dropdown menu items have been set|
|GRID_SET_PIVOT_MODE_OFF||Grid is taken out of pivot mode|
|GRID_SET_PIVOT_MODE_ON||Grid is put in pivot mode|
|GRID_SET_SELECTED_CELLS||Cells have been selected in the Grid|
|GRID_SET_SELECTED_ROWS||Rows have been selected in the Grid|
|GRID_SET_SORT||Sorting has been in the Grid|
|GRID_SET_TREE_MODE_OFF||Grid is taken out of tree mode|
|GRID_SET_TREE_MODE_ON||Grid is put in tree mode|
|IPUSHPULL_ADD_PAGE||A new ipushpull page has been added|
|IPUSHPULL_DOMAIN_PAGES_CLEAR||ipushpull domain pages have been cleared|
|IPUSHPULL_DOMAIN_PAGES_SET||ipushpull domain pages have been set|
|IPUSHPULL_LIVE_REPORT_CLEAR||The live report to ipuspull has been cleared|
|IPUSHPULL_LIVE_REPORT_SET||A live report to ipuspull has been set|
|IPUSHPULL_LOGIN||Logged in to ipushpull|
|IPUSHPULL_LOGOUT||Logged out from ipushpull|
|IPUSHPULL_REPORT_SELECT||An ipushpull report has been selected|
|IPUSHPULL_SCHEDULE_ADD||An ipushpull Schedule has been added|
|IPUSHPULL_SCHEDULE_DELETE||An ipushpull Schedule has been deleted|
|IPUSHPULL_SCHEDULE_EDIT||An ipushpull Schedule has been edited|
|IPUSHPULL_SEND_SNAPSHOT||A snapshot report has been sent|
|IPUSHPULL_SET_AVAILABLE_OFF||ipushpull has been made unavailable|
|IPUSHPULL_SET_AVAILABLE_ON||ipushpull has been made available|
|IPUSHPULL_SET_LOGIN_DETAILS||Login details to ipushpull have been set|
|IPUSHPULL_SET_LOGIN_ERROR_MESSAGE||Error message set from failed login|
|IPUSHPULL_SET_RUNNING_OFF||ipushpull is no longer running|
|IPUSHPULL_SET_RUNNING_ON||ipushpull is now running|
|IPUSHPULL_SET_THROTTLE_TIME||Throttle time for live reports has been set|
|IPUSHPULL_START_LIVE_DATA||Live data has been sent to ipushpull|
|IPUSHPULL_STOP_LIVE_DATA||Live data to ipushpull has been stopped|
|LAYOUT_ADD||A Layout has been added|
|LAYOUT_DELETE||A Layout has been deleted|
|LAYOUT_EDIT||A Layout has been edited|
|LAYOUT_READY||Layout Module is ready|
|LAYOUT_SAVE||A Layout has been (auto)saved|
|LAYOUT_SELECT||A Layout has been selected|
|NAMED_QUERY_ADD||A Named Query has been added|
|NAMED_QUERY_DELETE||A Named Query has been deleted|
|NAMED_QUERY_EDIT||A Named Query has been edited|
|OPENFIN_LIVE_REPORT_CLEAR||An OpenFin live report has stopped|
|OPENFIN_LIVE_REPORT_SET||An OpenFin live report has started|
|OPENFIN_SCHEDULE_ADD||An OpenFin Schedule has been added|
|OPENFIN_SCHEDULE_DELETE||An OpenFin Schedule has been deleted|
|OPENFIN_SCHEDULE_EDIT||An OpenFin Schedule has been edited|
|OPENFIN_SET_AVAILABLE_OFF||OpenFin is no longer available|
|OPENFIN_SET_AVAILABLE_ON||OpenFin is now available|
|OPENFIN_SET_RUNNING_OFF||OpenFin is no longer running|
|OPENFIN_SET_RUNNING_ON||OpenFin is now running|
|OPENFIN_START_LIVE_DATA||Live data has been sent to OpenFin|
|OPENFIN_STOP_LIVE_DATA||Live data is not longer sent to OpenFin|
|PLUGINS_SET_PLUGIN_STATE||Plugins have been instantiated|
|PLUS_MINUS_APPLY||A Plus Minus Rule has been applied|
|PLUS_MINUS_READY||PlusMinus Module is ready|
|PLUS_MINUS_RULE_ADD||A Plus Minus Rule has been added|
|PLUS_MINUS_RULE_DELETE||A Plus Minus Rule has been deleted|
|PLUS_MINUS_RULE_EDIT||A Plus Minus Rule has been edited|
|QUERY_READY||Query Module is ready|
|QUERY_RUN||A Query has been run|
|QUICK_FILTER_BAR_HIDE||Quick Filter Bar has been hidden|
|QUICK_FILTER_BAR_SHOW||Quick Filter Bar has been made visible|
|QUICK_SEARCH_READY||Quick Search Module is ready|
|QUICK_SEARCH_RUN||Runs Quick Search|
|QUICK_SEARCH_SET_STYLE||Sets Quick Search style|
|REMINDER_SCHEDULE_ADD||A Reminder Schedule has been added|
|REMINDER_SCHEDULE_DELETE||A Reminder Schedule has been deleted|
|REMINDER_SCHEDULE_EDIT||A Reminder Schedule has been edited|
|REPORT_ADD||A Report has been added|
|REPORT_DELETE||A Report has been deleted|
|REPORT_EDIT||A Report has been edited|
|REPORT_SCHEDULE_ADD||A Report Schedule has been added|
|REPORT_SCHEDULE_DELETE||A Report Schedule has been deleted|
|REPORT_SCHEDULE_EDIT||A Report Schedule has been edited|
|REPORT_SELECT||A Report has been selected|
|SCHEDULE_JOB_RUN||Runs a Scheduled job|
|SCHEDULE_READY||Schedule Module is ready|
|SET_GLUE42_AVAILABLE_OFF||Glue43 is no longer available|
|SET_GLUE42_AVAILABLE_ON||Glue43 is now available|
|SET_GLUE42_RUNNING_OFF||Glue43 is no longer running|
|SET_GLUE42_RUNNING_ON||Glue43 is now running|
|SHORTCUT_ADD||A Shortcut has been added|
|SHORTCUT_DELETE||A Shortcut has been deleted|
|SHORTCUT_EDIT||A Shortcut has been edited|
|SHORTCUT_READY||Shortcut Module is ready|
|SMART_EDIT_APPLY||Smart Editis being applied|
|SMART_EDIT_COMPLETE||Smart Edit has been completed|
|SMART_EDIT_READY||SmartEdit Module is ready|
|SPARKLINE_COLUMNS_ADD||A Sparkline Column has been added|
|SPARKLINE_COLUMNS_DELETE||A Sparkline Column has been deleted|
|SPARKLINE_COLUMNS_EDIT||A Sparkline Column has been edited|
|SPARKLINE_COLUMNS_SET||Sparkline Columns have been set|
|SYSTEM_STATUS_MESSAGE_SET||A System Status Message is set|
|SYSTEM_STATUS_READY||SystemStatus Module is ready|
|THEME_READY||Theme Module is ready|
|THEME_SELECT||A theme has been selected|
|THEME_SET_SYSTEM_THEMES||System Themes have been set|
|THEME_SET_USER_THEMES||User Themes have been set|
|TOOLPANEL_HIDE_TOOLPANEL||A Tool Panel has been hidden|
|TOOLPANEL_READY||ToolPanel Module is ready|
|TOOLPANEL_SET_MODULE_BUTTONS||Module Buttons have set in Tool Panel header|
|TOOLPANEL_SET_TOOLPANELS||Tool Panels have been set in Adaptable Tool Panel|
|TOOLPANEL_SHOW_TOOLPANEL||A Tool Panel has been made visible|
|UI_CHECKBOX_COLUMN_ADD||A Checkbox Column has been added|
|UI_CHECKBOX_COLUMN_DELETE||A Checkbox Column has been deleted|