AdapTable State Guide
Summary
- AdapTable provides a powerful State-management architecture
- AdapTable State comprises 2 sets of Adaptable Objects and associated settings:
- Initial Adaptable State provided by developers at design-time
- changes to these objects (plus any new ones created) made by Users at run-time
- AdapTable provides full State persistence and retrieval mechanisms of AdapTable State
Important
- AdapTable State does not include AG Grid data; it deals only with the AdapTable UI and associated objects
- Likewise AdapTable does not have access to the clients' private data
Managing User State is one of the most valued pieces of functionality that AdapTable provides.
It allows developers to configure AdapTable with the objects their users needs.
It also provides a mechanism whereby these objects - and any subsequent additions, modifications and deletions - are automatically persisted and fetched as required on subsequent application re-starts.
Contents of AdapTable State
User State comprises 2 elements:
- state provided at design-time (using Initial Adaptable State) for initial use
- state created at run-time through user action (e.g. selecting a Layout, creating a Format Column etc.)
Find Out More
See Initial Adaptable State for extensive information on pre-populating AdapTable instances with initial User State
How AdapTable State Works
AdapTable State can best be seen as a 3 stage process, as follows:
At design-time developers will create Initial Adaptable State.
This is a JSON object that contains the items the AdapTable instance requires for initial use.
It consists of multiple sections - each relating to one Module in AdapTable.
Some of the contents of each section are collections of Adaptable Objects (e.g. Layouts) but can also be string properties (e.g name of the Current Layout).
When the application loads for the first time, the Initial Adaptable State is read into memory.
This Initial State is then stored as AdapTable State and is updated (and automatically persisted) with any user state that is created during that session.
It can be stored locally or remotely depending on your settings (see below for more information).
Subsequently, each time the application is launched, that persisted User State is retrieved and the particular AdapTable instance is pre-populated with it
This allows AdapTable users always to see the same state as was persisted on their previous visit.
This allows AdapTable users always to see the same state as was persisted on their previous visit.
Initial Adaptable State
Initial State is provided by developers to populate each new AdapTable instance for first use.
Caution
- As the name indicates, Initial Adaptable State is intended only for first-time use of the Application
- AdapTable State should be relied on to manage all subsequent state-related behaviour
This means that when end-users open the new application for the first time, they won't just see a clean AG Grid instance but, rather, one pre-loaded with multiple Searches, Styles, Edit Rules, Reports etc.
The Initial Adaptable State is then automatically saved into AdapTable State which is subsequently used during the Application's lifetime.
Hint
The useful Revision property allows developers to update Initial State after it has been initially loaded
Find Out More
See Initial Adaptable State for a full Guide to this topic
Redux
Internally AdapTable uses Redux to manage its state.
This provides a uni-directional store for all the objects used in the grid
Caution
If using Redux in your application, continue to maintain your own Store; merging the 2 Stores can cause complications
Persisting AdapTable State
AdapTable State is designed to be persisted allowing for a seamless user experience between sessions.
AdapTable State can be saved in 2 different ways:
- Local Storage - by default, AdapTable State is stored in the browser's local storage
- Remote Storage - accessible via a series of JavaScript functions available in State Options
Find Out More
See Persisting AdapTable State for detailed discussion about how to save state
Default AdapTable State
AdapTable State is, by design, almost entirely empty when the Application starts for the first time.
It is then populated by the supplied Initial Adaptable State.
However there are 4 default properties which AdapTable provides for convenience sake:
Note
All of these can be replaced by properties in Initial Adaptable State if necessary
| Module | Default Property Description |
|---|---|
| Dashboard | A SettingsPanel Button is provided in the ModuleButtons property |
| Quick Search | Quick Search Highlight Style (Black Text on Yellow Background) |
| Theme | Current Theme is set to "light" |
| Tool Panel | A SettingsPanel Button is provided in the ModuleButtons property |
Monitoring AdapTable State
The Adaptable State Changed Event allows developers and support to monitor all changes in the State.
It is fired every time that any Adaptable State changes.
Migrating AdapTable State
AdapTable will make changes to Adaptable State from time to time as requirements change.
Most of these changes are purely additive - typically the result of user enhancements requests.
However once a year AdapTable might introduce breaking changes to Adaptable State.
When this happens, AdapTable will migrate the State automatically, although developers can opt out from this and perform all State updates manually.
Find Out More
Learn more about Migrating AdapTable State and the different options available
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 your State in a remote location. There are simply too many different storage locations and mechanisms for us to provide connectors.