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:
- Local Storage - by default, Adaptable State is stored in the browser's local storage using the unique adaptableId property provided in Adaptable Options.
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.
Config Server - the previous way of managing AdapTable state remotely - was removed in Version 7.
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 actually a simple wrapper around our Redux store with some additional error handling, logging and other features.
Listening to State Changes
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 Function 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 configuration stored?
By default its 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).
Do you provide data adapters to fetch / save configuration?
No we don't, you will need to provide the mechanism to store configuration in a remote location.
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 are able to provide this configuration as a JSON object or as a URL (to a .JSON file).
Can I provide different configuration 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