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.

note

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.

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 actually a simple wrapper around our Redux store with some additional error handling, logging and other features.

Listening to State Changes

The recommended way to listen to changes in the Store is by subscribing to the AuditStateChanged audit event in the AuditEventApi section of Adaptable Api.

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 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.

FAQs

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?

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

More Information