State Options

State Options contain a series of useful JavaScript function hooks which allow developers to control the management of Adaptable State.

Managing State

The 4 functions devoted to AdapTable State hydration and dehydration.

They enable users to intercept state persistence and state loading with custom functionality.

important

By default, AdaptableState is persisted in the local storage of the user browser, under the adaptableId key

The various state-management functions provided here allow you to change this default behaviour, and also to add custom properties in the persisted state.

note

Since Version 7 this is the only way to manage remote storage as the previous implementation, Config Server, was removed.

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

Adaptable State flow

The Adaptable State flow is as follows:

  1. User Loads Page --> loadState() state1 -> applyState(state1)
  2. state2 ---- ADAPTABLE NOW READY WITH STATE (state2)
  3. User Updates State ------ saveState(state3):
  4. state4 -> persistState(state4)

persistState

Allows the customization of state persistence.

important

By default, state is stringified using JSON.stringify and persisted into the localStorage, at the key denoted by adaptableId.

This function can be used to change this behavior, throttle state persistence, etc.

If defined, most likely it should be used in conjunction with loadState, which is the other side of the persistence mechanism.

The persistence (dehydration) flow is the following: saveState -> persistState.

tip

If you want to add other properties on the state that is going to be persisted, use saveState.

Whatever that returns is then passed to persistState.

Default implementation

Stringifies the state and puts it into the localStorage using the adaptableId key

loadState

Allows the customization of state loading.

important

By default, AdapTable will read the state that was persisted from localStorage (at the adaptableId key) and returns it.

If this function is defined, most likely it will be used in conjunction with persistState, which is the other side of the persistence mechanism.

tip

For example, loadState can be used to load Adaptable State from the browser window object or from a remote location altogether.

The hydration flow is the following: loadState -> applyState

So whatever loadState returns, is passed to applyState.

Default implementation

For local predefinedConfig, it reads the state from localStorage<adaptableId> and parses it as a JavaScript object, which is returned.

saveState

Allows the customization of the state that is going to be persisted.

tip

If you simply want to add other properties to the state, before persistence, use this function

adaptableOptions = {
stateOptions: {
saveState: (state) => {
return {
...state,
userSettings: {
language: 'de'
}
}
}
}
}

In this case, you might find it useful to also define applyState which hooks into state hydration, and gives you access to the persisted custom properties, so you can use them later in the app.

note

If you also want to modify the persistence behavior, you have to implement the persistState as well.

The persistence (dehydration) flow is the following: saveState -> persistState

important

You have to make sure that the returned object is serializable with JSON.stringify - in case that it's not, you could define persistState to do a custom serialization of the object.

caution

This function should be a synchronous function.

Default implementation

(state) => state

applyState

Allows hooking into Adaptable State hydration.

important

This function determines what state is (re)applied in AdapTable when AdapTable is initialized.

This is useful when saveState was specified and added new custom properties, which will again be accessible into the applyState function.

tip

If you used saveState to add custom app-specific properties on the top-level object you returned, it's a good practice to clear these properties and just return Adaptable State from this function.

adaptableOptions = {
stateOptions: {
saveState: (state) => {
return {
...state,
userSettings: {
language: 'de'
}
}
},
applyState: (state) => {
const { userSettings, ...adaptableState } = state
// do something with userSettings here
return adaptableState
}
}
}

The hydration flow is the following: loadState -> applyState

So whatever loadState returns, is passed to this function.

caution

This function should be a synchronous function.

Default implementation

(state) => state

Clearing State

The clearState function enables Remote State to be cleared.

It is called by AdapTable whenever User State is cleared (so that State will return to whatever is in the initial Predefined Config)

note

One instance is the reloadPredefinedConfig function in Config Api which will call this function if an implementation has been provided

State Options Properties

PropertyDescriptionDefault
applyStateAllows hooking into AdaptableState hydration
clearStateAllows clearing of remote state.
debounceStateDelayDelay (in ms) to debounce saveState/persistState calls enabling grouping multiple sequential calls in single one (e.g. elevator doors)400
loadStateAllows the customization of state loading.
persistStateAllows the customization of state persistence.
saveStateAllows the customization of the state that is going to be persisted

More Information