State

Mixin

A mixin that handles accessing, saving, and restoring an object's persistent state.

Using Stateful Components

Instances of classes that use this mixin (i.e., "stateful components") have a state property that provides read/write access to their persistable state in the form of a simple object. These state objects can be saved and restored under application control, e.g., using localStorage.

This approach can be streamlined using a StateProvider either by setting the default state provider or by using an instance-level stateProvider config.

When using a state provider, stateful components with a stateId or an id will automatically save (see saveState) and restore (see loadState) their state. This use of the id as a stateId can be disabled by assigning the stateful config to false. When using a stateId and a state provider, it is not necessary to call the loadState and saveState methods directly.

Simple vs Complex State

Some stateful components (e.g., panels) have state that can be described purely by their config properties. For these components, the stateful config can be used to control which config properties to include in their persistent state. For example:

 const mainPanel = new Panel({
     collapsible : true,
     stateId     : 'mainPanel',
     stateful    : ['collapsed']
 });

Other components have a complex state (e.g., GridState), and do not use the stateful config in this way. In all other ways, however, these components behave the same as their simple state counterparts.

Alter state information

For complex state components, the beforeStateSave event can be used to alter the state object:

const grid = new Grid({
   stateId   : 'grid',
   listeners : {
      beforeStateSave : ({ state }) => {
         // Removes state info for the store, like sorters and filters
         delete state.store;
      }
   }
}

Implementing Stateful Components

Implementors of stateful components have two main design points to consider:

• Getting and setting their persistent state object.
• Initiating calls to saveState when the object's persistent state changes.

Persistent State

For simple cases, the stateful config can be set to the list of config property names that should be saved:

 class MyStatefulComponent extends Base.mixin(State) {
     static configurable = {
         stateful : ['text', 'size']
     };
 }

While the stateful config supports an object form (where keys with truthy values are the config names), this form is typically reserved for configuring instances.

Classes can choose to implement the getState and applyState methods to enhance the state object with data not easily mapped to config properties. These method can call their super methods or fully replace them.

 class MyStatefulComponent extends Base.mixin(State) {
     getState() {
         return {
             text : this.text,
             size : this.size
         };
     }

     applyState(state) {
         this.text = state.text;
         this.size = state.size;
     }
 }

Saving Dates

A stateful property may be a Date property if the changeDate method of the class accepts an ISO 8601 formatted date. Dates are saved in state using ISO 8601 format: YYYY-MM-DDTHH:mm:ssZ

Saving State

When the persistent state of a stateful component changes, it must call saveState. This method schedules an update of the component's persistence state with the appropriate stateProvider. When a config property named in the stateful config changes, this call will be made automatically. This means that even if a component replaces getState and applyState, it can still be helpful to specify a value for the stateful config.

 class MyStatefulComponent extends Base.mixin(State) {
     static configurable = {
         stateful : ['text', 'size']
     };

     getState() { ... }
     applyState(state) { ... }
 }

Another way to ensure saveState is called when necessary is to use statefulEvents.

 class MyStatefulComponent extends Base.mixin(State) {
     static configurable = {
         statefulEvents : ['change', 'resize']
     };
 }

Useful configs and functions

See also

• StateProvider - Provider for automatic state storage