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.

Useful configs, properties and functions

Config / Property / Function	Description
setup	Create and set the global state provider
instance	The global default state provider
storage	Storage type: `'local'` or `'memory'`
prefix	Key prefix for localStorage isolation
data	Read/write all stored state data

Configs

Configs are options you supply in a configuration object when creating an instance of this class

prefix : Stringbryntum-state:

The key prefix applied when using the 'local'storage type.
storage : 'local'/'memory'/StateStoragelocal
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.
Has a corresponding runtime storage property.

Properties

Properties are getters/setters or publicly accessible variables on this class

instance : StateProvider

static

The default stateProvider for stateful objects.

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.
storage : StateStorage

Storage instance

Has a corresponding storage config.

Functions

Functions are methods available for calling on the class

setup( inst )
: StateProvider

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

clear( )
: StateProvider

Clears all state date
getValue( key )
: Object

Returns the stored state given its key.
saveStateful( stateful, options )

internal

This method is called to schedule saving the given stateful object.
setValue( key, value )
: StateProvider

Stores the given state value under the specified key.
writeStatefuls( )

private

A delayable method that flushes pending stateful objects.

Events

Events are triggered for certain actions in this class and can be listened for to react to those actions in your code

remove

Triggered after an item is removed from the state provider.
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.
set

Triggered after an item is stored to the state provider.

Event handlers

Event handlers are callbacks called as a result of certain actions in this class

onRemove

Called after an item is removed from the state provider.
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
             }
         }
     }
 });
```
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.
onSet

Called after an item is stored to the state provider.

Source path

Core/state/StateProvider.js

Inheritance tree1

StateProvider

Mixins1

Events

StateProvider

Using `local` Storage

Using `memory` Storage

Useful configs, properties and functions

See also

Configs

Properties

Functions

Events

Event handlers

Source path

Inheritance tree1

Mixins1

Contents

StateProvider

Using local Storage

Using memory Storage

Useful configs, properties and functions

See also

Configs

Properties

Functions

Events

Event handlers

Source path

Inheritance tree1

Mixins1

Contents

Using `local` Storage

Using `memory` Storage