StateProvider

Instances of this class are used to manage data storage for objects that use the State mixin, i.e. stateful components. When such components change their stateful properties, they notify the associated stateProvider, which will save the changes after a short delay (to allow multiple changes to coalesce into a single save operation).

There are two (2) built-in types of storage supported by StateProvider:

local : Stores data in the browser's localStorage. Because of this, all StateProvider instances share their state data if they have the same prefix.
memory : Stores data in the provider's memory. Each instance has its own storage. This is typically used when the state data is saved to a backend server.

Using `local` Storage

The global StateProvider is typically to use localStorage for the page or application like so:

 StateProvider.setup('local');

With this provider in place, all stateful components will save their state to this provider by default.

This is the most typical, and recommended, strategy for proving data to stateful components. This approach allows various widgets on the page to simply declare their stateId to participate in the saving and restoring of application state.

Because this storage type uses localStorage, the StateProvider applies a string prefix to isolate its data from other users of localStorage. The default prefix is 'bryntum-state:', but this can be configured to a different value. This could be desired, for example, to isolate state data from multiple pages or for version changes.

 StateProvider.setup({
     storage : 'local',
     prefix  : 'myApp-v1:'
 });

Using `memory` Storage

In some applications it may be desirable to save state to a server and restore it on other devices for the user. Because state data is consumed synchronously, and server I/O is asynchronous, the StateProvider can be configured to use 'memory' storage and the actual state data can be loaded/saved by the application.

Two factors are important to consider before deciding to save application state on the server (beyond the async adaptation):

State properties are often more of a reflection of the user's device than they are application preferences and, therefore, may not apply well on other devices.
Potentially undesired application state will not be cleared by clearing local browser user data (a common troubleshooting strategy) and will follow the user to other browsers (another common troubleshooting technique).

The use this type of storage, the global StateProvider is configured like so:

StateProvider.setup('memory');

In this scenario, application code would download the user's state and use data to populate the StateProvider.instance. In this case, the save event is used to save the data back to the server when it changes.

See state demo for a usage example.

Configs

Common

listenersEvents

Other

prefix: String= bryntum-state:

The key prefix applied when using the 'local' storage type.

storage: local | memory | StateStorage= localAlso a property

One of the following storage types:

local : Stores data in the browser's localStorage using the prefix.
memory : Stores data in the provider's memory.

catchEventHandlerExceptionsEvents

Misc

bubbleEventsEvents

callOnFunctionsEvents

Properties

Other

data: Object

On read, this property returns all state data stored in the provider. On write, this property adds all the given values to the state provider's data. To replace the data, call clear before assigning this property. This is used to bulk populate this StateProvider with data for stateful components.

instance: StateProviderstatic

The default stateProvider for stateful objects.

storage: StateStorageAlso a config

Storage instance

catchEventHandlerExceptionsEvents

Class hierarchy

isEventsEvents

Misc

callOnFunctionsEvents

Functions

clear

Clears all state date

Returns: StateProvider -

this instance

getValue

Returns the stored state given its key.

Parameter	Type	Description
`key`	String	The identifier of the state to return.

Returns: Object

setupstatic

Initializes the default StateProvider instance for the page. This method can be passed an instance or one of the following type aliases:

'local' : use localStorage to store application state (most common)
'memory' : holds application state in the StateProvider instance (used when state is saved to a server)

Once the StateProvider is initialized, components that use State and assign components a stateId will use this default provider to automatically save and restore their state.

Parameter	Type	Description
`inst`	local \| memory \| StateProvider	The state provider storage type ('local' or 'memory') or the `StateProvider` instance.

Returns: StateProvider

setValue

Stores the given state value under the specified key.

Parameter	Type	Description
`key`	String	The identifier of the state value.
`value`	Object	The state value to set.

Returns: StateProvider -

this instance

addListenerEvents

hasListenerEvents

onEvents

relayAllEvents

removeAllListenersEvents

removeListenerEvents

resumeEventsEvents

suspendEventsEvents

triggerEvents

unEvents

Events

remove

Triggered after an item is removed from the state provider.

// Adding a listener using the "on" method
stateProvider.on('remove', ({ source, key, was }) => {

});

Parameter	Type	Description
`source`	StateProvider	The source of the event
`key`	String	The name of the removed item.
`was`	*	The value of the removed item.

save

Triggered after one or more stateful objects save their state to the state provider. This event can be used to save state to a backend server.

For example, to save the page's state object as a single object on the server:

 StateProvider.instance.on({
     save() {
         const data = StateProvider.instance.data;
         // Save "data" to server
     }
 });

Or, to save individual stateful components to the server:

 StateProvider.instance.on({
     save({ stateIds }) {
         for (const stateId of stateIds) {
             const data = StateProvider.instance.getValue(stateId);

             if (data == null) {
                 // Remove "stateId" from the server
             }
             else {
                 // Save new "data" for "stateId" to the server
             }
         }
     }
 });

Multi-page applications should probably include a page identifier in addition to the stateId to prevent state from one page affecting other pages. If there are common components across all (or many) pages, the stateId values would need to be assigned with all pages in mind.

// Adding a listener using the "on" method
stateProvider.on('save', ({ source, stateIds, saved }) => {

});

Parameter	Type	Description
`source`	StateProvider	The source of the event
`stateIds`	String[]	An array of `stateId` values that were saved to the state provider.
`saved`	State[]	An array of stateful objects saved just saved to state provider storage, in the same order as the `stateIds` array.

set

Triggered after an item is stored to the state provider.

// Adding a listener using the "on" method
stateProvider.on('set', ({ source, key, value, was }) => {

});

Parameter	Type	Description
`source`	StateProvider	The source of the event
`key`	String	The name of the stored item.
`value`	*	The value of the stored item.
`was`	*	The previous value of the stored item.

beforeDestroyEvents

catchAllEvents

destroyEvents

Event handlers

onRemove

Called after an item is removed from the state provider.

new StateProvider({
    onRemove({ source, key, was }) {

    }
});

Parameter	Type	Description
`source`	StateProvider	The source of the event
`key`	String	The name of the removed item.
`was`	*	The value of the removed item.

onSave

Called after one or more stateful objects save their state to the state provider. This event can be used to save state to a backend server.

For example, to save the page's state object as a single object on the server:

 StateProvider.instance.on({
     save() {
         const data = StateProvider.instance.data;
         // Save "data" to server
     }
 });

Or, to save individual stateful components to the server:

 StateProvider.instance.on({
     save({ stateIds }) {
         for (const stateId of stateIds) {
             const data = StateProvider.instance.getValue(stateId);

             if (data == null) {
                 // Remove "stateId" from the server
             }
             else {
                 // Save new "data" for "stateId" to the server
             }
         }
     }
 });

new StateProvider({
    onSave({ source, stateIds, saved }) {

    }
});

Parameter	Type	Description
`source`	StateProvider	The source of the event
`stateIds`	String[]	An array of `stateId` values that were saved to the state provider.
`saved`	State[]	An array of stateful objects saved just saved to state provider storage, in the same order as the `stateIds` array.

onSet

Called after an item is stored to the state provider.

new StateProvider({
    onSet({ source, key, value, was }) {

    }
});

Parameter	Type	Description
`source`	StateProvider	The source of the event
`key`	String	The name of the stored item.
`value`	*	The value of the stored item.
`was`	*	The previous value of the stored item.