AdapTable State

This guide looks at how AdapTable manages User State at run-time.

important

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.

note

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.

tip

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:

  • Local Storage - by default, Adaptable State is stored in the browser's local storage using the unique adaptableId property provided in Adaptable Options.

    caution

    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.

State Options

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.

const adaptableOptions: AdaptableOptions = {
primaryKey: 'OrderId',
userName: 'Demo User',
adaptableId: 'State Functions Demo',
stateOptions: {
/**
* The loadState function is used to load the predefined config
* from a remote source - namely firebase in this example
*
* It returns a promise which is resolved when the
* Predefined Config is retrieved from firebase.
*/
loadState: () => {
return firebase
.database()
.ref(`predefinedconfig/${id}`)
.once('value')
.then(function(snapshot) {
const str = snapshot.val();
return str ? JSON.parse(str) : {};
});
},
/**
* The persistState function is called with the state that needs to be persisted.
* By default, state is persisted in localStorage, but this example
* illustrates how you can persist it to a remote datastore (e.g. Firebase)
*/
persistState: (state: Partial<AdaptableState>) => {
return firebase
.database()
.ref(`predefinedconfig/${id}`)
.set(JSON.stringify(state))
.then(() => Promise.resolve(true));
},
},
predefinedConfig: demoConfig,
vendorGrid: { ...gridOptions, modules: AllEnterpriseModules },
};

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.

note

The Adaptable Api is effectively a wrapper around our Redux store with some additional error handling, logging and other features.

Listening to State Changes

The best way to listen to changes in the Store is to subscribe to Adaptable State Changed Event in Event Api.

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

The easiest way to clear any Adaptable State added by a user is to provide a bespoke implementation for the clearState function in the State Options section of Adaptable Options.

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.

caution

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.

This is possible in AdapTable and pretty straightforward to do by leveraging the adaptableStateKey property of Adaptable Options and the setAdaptableStateKey method in Config Api.

tip

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.

FAQ

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?

Yes, it needs to be something that can be JSON stringified so it cannot be a JavaScript function.

More Information

Appendix: State Change Actions

NameDescription
ALERT_DEFINITION_ADDAn Alert Definition has been added
ALERT_DEFINITION_DELETEAn Alert Definition has been deleted
ALERT_DEFINITION_EDITAn Alert Definition has been edited
ALERT_READYAlert Module is ready
APPLICATION_DATA_ENTRY_ADDAn Application Data Entry has been added
APPLICATION_DATA_ENTRY_DELETEAn Application Data Entry has been deleted
APPLICATION_DATA_ENTRY_EDITAn Application Data Entry has been edited
BULK_UPDATE_APPLYBulk Update is being applied
BULK_UPDATE_COMPLETEBulk Update has been completed
BULK_UPDATE_READYBulk Update Module is ready
CALCULATED_COLUMN_ADDA Calculated Column has been added
CALCULATED_COLUMN_DELETEA Calculated Column has been deleted
CALCULATED_COLUMN_EDITA Calculated Column has been edited
CALCULATED_COLUMN_READYCalculated Column Module is ready
COLUMN_FILTER_ADDA Column Filter has been added
COLUMN_FILTER_CLEARA Column Filter has been cleared
COLUMN_FILTER_CLEAR_ALLAll Column Filters have been cleared
COLUMN_FILTER_EDITA Column Filter has been edited
COLUMN_FILTER_SETColumn Filters have been set
CONDITIONAL_STYLE_ADDA Conditional Style has been added
CONDITIONAL_STYLE_DELETEA Conditional Style has been deleted
CONDITIONAL_STYLE_EDITA Conditional Style has been edited
CONDITIONAL_STYLE_READYConditional Style Module is ready
CUSTOM_SORT_ADDA Custom Sort has been added
CUSTOM_SORT_DELETEA Custom Sort has been deleted
CUSTOM_SORT_EDITA Custom Sort has been edited
CUSTOM_SORT_READYCustom Sort Module is ready
DASHBOARD_ACTIVE_TAB_INDEX_CHANGEActive tab has changed
DASHBOARD_CLOSE_TOOLBARA Toolbar has been closed
DASHBOARD_CREATE_DEFAULT_TABA default Tab has been created
DASHBOARD_READYDashboard is ready
DASHBOARD_SET_FLOATING_POSITIONFloating position has changed
DASHBOARD_SET_IS_COLLAPSEDCollapsed Mode has changed
DASHBOARD_SET_IS_FLOATINGFloating Mode has changed
DASHBOARD_SET_IS_HIDDENVisibility has changed
DASHBOARD_SET_IS_INLINEInline Mode has changed
DASHBOARD_SET_MODULE_BUTTONSThe Module Buttons have been set in the Dashboard
DASHBOARD_SET_TABSNew Dashboard Tabs have been set
DASHBOARD_SET_TITLEDashboard Title has been set
DATA_SOURCE_ADDA Data Source has been added
DATA_SOURCE_DELETEA Data Source has been deleted
DATA_SOURCE_EDITA Data Source has been edited
DATA_SOURCE_READYData Source Module is ready
DATA_SOURCE_SELECTA Data Source has been selected
DESTINATION_SELECTA report Destination has been selected
EXPORT_APPLYExport has been applied
EXPORT_READYExport Module is ready
FILTER_FORM_HIDEThe Filter Form has been hidden
FILTER_READYFilter Module is ready
FLASHING_ALERT_DEFINITION_ADDA Flashing Alert Definition has been added
FLASHING_ALERT_DEFINITION_DELETEA Flashing Alert Definition has been deleted
FLASHING_ALERT_DEFINITION_EDITA Flashing Alert Definition has been edited
FORMAT_COLUMN_ADDA Format Column has been added
FORMAT_COLUMN_DELETEA Format Column has been deleted
FORMAT_COLUMN_EDITA Format Column has been edited
FORMAT_COLUMN_READYFormatColumn Module is ready
FREE_TEXT_COLUMN_ADDA Free Text Column has been added
FREE_TEXT_COLUMN_ADD_EDIT_STORED_VALUEA Free Text Column's stored values have changed
FREE_TEXT_COLUMN_DELETEA Free Text Column has been deleted
FREE_TEXT_COLUMN_EDITA Free Text Column has been edited
FREE_TEXT_COLUMN_READYFreeTextColumn Module is ready
GLUE42_LIVE_REPORT_CLEARA Glue42 live report has stopped
GLUE42_LIVE_REPORT_SETA Glue42 live report has started
GLUE42_LOGINLogged in to Glue42
GLUE42_SCHEDULE_ADDA Glue42 Schedule has been added
GLUE42_SCHEDULE_DELETEA Glue42 Schedule has been deleted
GLUE42_SCHEDULE_EDITA Glue42 Schedule has been edited
GLUE42_SEND_SNAPSHOTA snapshot report has been sent
GLUE42_SET_LOGIN_ERROR_MESSAGEError message set from failed login
GLUE42_SET_THROTTLE_TIMEThrottle time for live reports has been set
GLUE42_START_LIVE_DATALive data has been sent to Glue42
GLUE42_STOP_LIVE_DATALive data is not longer sent to Glue42
GRID_ADD_COLUMNA Column has been added to the Grid
GRID_ADD_COLUMNSColumns have been added to the Grid
GRID_CREATE_CELLS_SUMMARYCell Summary Information has been created
GRID_DATA_CHANGEDGrid data has changed but not as the result of user edit
GRID_DATA_EDITEDA cell has been edited by the user
GRID_EDIT_COLUMNA Column has been edited in the Grid
GRID_REFRESH_CELLSGrid cells have been refreshed
GRID_REMOVE_COLUMNA Column has been removed from the Grid
GRID_SET_CELLS_SUMMARYGrid Cell summary is set
GRID_SET_COLUMNSColumns have been set in the Grid
GRID_SET_MODULE_BUTTON_MENUITEMSModule Button menu items have been set
GRID_SET_MODULE_DROPDOWN_MENUITEMSModule Dropdown menu items have been set
GRID_SET_PIVOT_MODE_OFFGrid is taken out of pivot mode
GRID_SET_PIVOT_MODE_ONGrid is put in pivot mode
GRID_SET_SELECTED_CELLSCells have been selected in the Grid
GRID_SET_SELECTED_ROWSRows have been selected in the Grid
GRID_SET_SORTSorting has been in the Grid
GRID_SET_TREE_MODE_OFFGrid is taken out of tree mode
GRID_SET_TREE_MODE_ONGrid is put in tree mode
IPUSHPULL_ADD_PAGEA new ipushpull page has been added
IPUSHPULL_DOMAIN_PAGES_CLEARipushpull domain pages have been cleared
IPUSHPULL_DOMAIN_PAGES_SETipushpull domain pages have been set
IPUSHPULL_LIVE_REPORT_CLEARThe live report to ipuspull has been cleared
IPUSHPULL_LIVE_REPORT_SETA live report to ipuspull has been set
IPUSHPULL_LOGINLogged in to ipushpull
IPUSHPULL_LOGOUTLogged out from ipushpull
IPUSHPULL_REPORT_SELECTAn ipushpull report has been selected
IPUSHPULL_SCHEDULE_ADDAn ipushpull Schedule has been added
IPUSHPULL_SCHEDULE_DELETEAn ipushpull Schedule has been deleted
IPUSHPULL_SCHEDULE_EDITAn ipushpull Schedule has been edited
IPUSHPULL_SEND_SNAPSHOTA snapshot report has been sent
IPUSHPULL_SET_AVAILABLE_OFFipushpull has been made unavailable
IPUSHPULL_SET_AVAILABLE_ONipushpull has been made available
IPUSHPULL_SET_LOGIN_DETAILSLogin details to ipushpull have been set
IPUSHPULL_SET_LOGIN_ERROR_MESSAGEError message set from failed login
IPUSHPULL_SET_RUNNING_OFFipushpull is no longer running
IPUSHPULL_SET_RUNNING_ONipushpull is now running
IPUSHPULL_SET_THROTTLE_TIMEThrottle time for live reports has been set
IPUSHPULL_START_LIVE_DATALive data has been sent to ipushpull
IPUSHPULL_STOP_LIVE_DATALive data to ipushpull has been stopped
LAYOUT_ADDA Layout has been added
LAYOUT_DELETEA Layout has been deleted
LAYOUT_EDITA Layout has been edited
LAYOUT_READYLayout Module is ready
LAYOUT_SAVEA Layout has been (auto)saved
LAYOUT_SELECTA Layout has been selected
NAMED_QUERY_ADDA Named Query has been added
NAMED_QUERY_DELETEA Named Query has been deleted
NAMED_QUERY_EDITA Named Query has been edited
OPENFIN_LIVE_REPORT_CLEARAn OpenFin live report has stopped
OPENFIN_LIVE_REPORT_SETAn OpenFin live report has started
OPENFIN_SCHEDULE_ADDAn OpenFin Schedule has been added
OPENFIN_SCHEDULE_DELETEAn OpenFin Schedule has been deleted
OPENFIN_SCHEDULE_EDITAn OpenFin Schedule has been edited
OPENFIN_SET_AVAILABLE_OFFOpenFin is no longer available
OPENFIN_SET_AVAILABLE_ONOpenFin is now available
OPENFIN_SET_RUNNING_OFFOpenFin is no longer running
OPENFIN_SET_RUNNING_ONOpenFin is now running
OPENFIN_START_LIVE_DATALive data has been sent to OpenFin
OPENFIN_STOP_LIVE_DATALive data is not longer sent to OpenFin
PLUGINS_SET_PLUGIN_STATEPlugins have been instantiated
PLUS_MINUS_APPLYA Plus Minus Rule has been applied
PLUS_MINUS_READYPlusMinus Module is ready
PLUS_MINUS_RULE_ADDA Plus Minus Rule has been added
PLUS_MINUS_RULE_DELETEA Plus Minus Rule has been deleted
PLUS_MINUS_RULE_EDITA Plus Minus Rule has been edited
QUERY_READYQuery Module is ready
QUERY_RUNA Query has been run
QUICK_FILTER_BAR_HIDEQuick Filter Bar has been hidden
QUICK_FILTER_BAR_SHOWQuick Filter Bar has been made visible
QUICK_SEARCH_READYQuick Search Module is ready
QUICK_SEARCH_RUNRuns Quick Search
QUICK_SEARCH_SET_STYLESets Quick Search style
REMINDER_SCHEDULE_ADDA Reminder Schedule has been added
REMINDER_SCHEDULE_DELETEA Reminder Schedule has been deleted
REMINDER_SCHEDULE_EDITA Reminder Schedule has been edited
REPORT_ADDA Report has been added
REPORT_DELETEA Report has been deleted
REPORT_EDITA Report has been edited
REPORT_SCHEDULE_ADDA Report Schedule has been added
REPORT_SCHEDULE_DELETEA Report Schedule has been deleted
REPORT_SCHEDULE_EDITA Report Schedule has been edited
REPORT_SELECTA Report has been selected
SCHEDULE_JOB_RUNRuns a Scheduled job
SCHEDULE_READYSchedule Module is ready
SET_GLUE42_AVAILABLE_OFFGlue43 is no longer available
SET_GLUE42_AVAILABLE_ONGlue43 is now available
SET_GLUE42_RUNNING_OFFGlue43 is no longer running
SET_GLUE42_RUNNING_ONGlue43 is now running
SHORTCUT_ADDA Shortcut has been added
SHORTCUT_DELETEA Shortcut has been deleted
SHORTCUT_EDITA Shortcut has been edited
SHORTCUT_READYShortcut Module is ready
SMART_EDIT_APPLYSmart Editis being applied
SMART_EDIT_COMPLETESmart Edit has been completed
SMART_EDIT_READYSmartEdit Module is ready
SPARKLINE_COLUMNS_ADDA Sparkline Column has been added
SPARKLINE_COLUMNS_DELETEA Sparkline Column has been deleted
SPARKLINE_COLUMNS_EDITA Sparkline Column has been edited
SPARKLINE_COLUMNS_SETSparkline Columns have been set
SYSTEM_STATUS_MESSAGE_SETA System Status Message is set
SYSTEM_STATUS_READYSystemStatus Module is ready
THEME_READYTheme Module is ready
THEME_SELECTA theme has been selected
THEME_SET_SYSTEM_THEMESSystem Themes have been set
THEME_SET_USER_THEMESUser Themes have been set
TOOLPANEL_HIDE_TOOLPANELA Tool Panel has been hidden
TOOLPANEL_READYToolPanel Module is ready
TOOLPANEL_SET_MODULE_BUTTONSModule Buttons have set in Tool Panel header
TOOLPANEL_SET_TOOLPANELSTool Panels have been set in Adaptable Tool Panel
TOOLPANEL_SHOW_TOOLPANELA Tool Panel has been made visible
UI_CHECKBOX_COLUMN_ADDA Checkbox Column has been added
UI_CHECKBOX_COLUMN_DELETEA Checkbox Column has been deleted