extjs/classic/classic/src/state/Stateful.js

   1 /**
   2  * @class Ext.state.Stateful
   3  * A mixin for being able to save the state of an object to an underlying
   4  * {@link Ext.state.Provider}.
   5  */
   6 Ext.define('Ext.state.Stateful', {
   7     mixinId: 'state',
   8
   9     requires: [
  10         'Ext.state.Manager',
  11         'Ext.util.TaskRunner'
  12     ],
  13
  14     /**
  15      * @cfg {Boolean} stateful
  16      * A flag which causes the object to attempt to restore the state of
  17      * internal properties from a saved state on startup. The object must have
  18      * a {@link #stateId} for state to be managed.
  19      *
  20      * Auto-generated ids are not guaranteed to be stable across page loads and
  21      * cannot be relied upon to save and restore the same state for a object.
  22      *
  23      * For state saving to work, the state manager's provider must have been
  24      * set to an implementation of {@link Ext.state.Provider} which overrides the
  25      * {@link Ext.state.Provider#set set} and {@link Ext.state.Provider#get get}
  26      * methods to save and recall name/value pairs. A built-in implementation,
  27      * {@link Ext.state.CookieProvider} is available.
  28      *
  29      * To set the state provider for the current page:
  30      *
  31      *    Ext.state.Manager.setProvider(new Ext.state.CookieProvider({
  32      *        expires: new Date(new Date().getTime()+(1000*60*60*24*7)), //7 days from now
  33      *    }));
  34      *
  35      * A stateful object attempts to save state when one of the events
  36      * listed in the {@link #stateEvents} configuration fires.
  37      *
  38      * To save state, a stateful object first serializes its state by
  39      * calling *{@link #getState}*.
  40      *
  41      * The Component base class implements {@link #getState} to save its width and height within the state
  42      * only if they were initially configured, and have changed from the configured value.
  43      *
  44      * The Panel class saves its collapsed state in addition to that.
  45      *
  46      * The Grid class saves its column state and store state (sorters and filters and grouper) in addition to its superclass state.
  47      *
  48      * If there is more application state to be save, the developer must provide an implementation which
  49      * first calls the superclass method to inherit the above behaviour, and then injects new properties
  50      * into the returned object.
  51      *
  52      * The value yielded by getState is passed to {@link Ext.state.Manager#set}
  53      * which uses the configured {@link Ext.state.Provider} to save the object
  54      * keyed by the {@link #stateId}.
  55      *
  56      * During construction, a stateful object attempts to *restore* its state by calling
  57      * {@link Ext.state.Manager#get} passing the {@link #stateId}
  58      *
  59      * The resulting object is passed to {@link #applyState}*. The default implementation of
  60      * {@link #applyState} simply copies properties into the object, but a developer may
  61      * override this to support restoration of more complex application state.
  62      *
  63      * You can perform extra processing on state save and restore by attaching
  64      * handlers to the {@link #beforestaterestore}, {@link #staterestore},
  65      * {@link #beforestatesave} and {@link #statesave} events.
  66      */
  67     stateful: false,
  68
  69     /**
  70      * @cfg {String} stateId
  71      * The unique id for this object to use for state management purposes.
  72      *
  73      * See {@link #stateful} for an explanation of saving and restoring state.
  74      */
  75
  76     /**
  77      * @cfg {String[]} stateEvents
  78      * An array of events that, when fired, should trigger this object to
  79      * save its state. Defaults to none. `stateEvents` may be any type
  80      * of event supported by this object, including browser or custom events
  81      * (e.g., `['click', 'customerchange']`).
  82      *
  83      * See `{@link #stateful}` for an explanation of saving and
  84      * restoring object state.
  85      */
  86
  87     /**
  88      * @cfg {Number} saveDelay
  89      * A buffer to be applied if many state events are fired within a short period.
  90      */
  91     saveDelay: 100,
  92
  93     /**
  94      * @event beforestaterestore
  95      * Fires before the state of the object is restored. Return false from an event handler to stop the restore.
  96      * @param {Ext.state.Stateful} this
  97      * @param {Object} state The hash of state values returned from the StateProvider. If this
  98      * event is not vetoed, then the state object is passed to *`applyState`*. By default,
  99      * that simply copies property values into this object. The method maybe overriden to
 100      * provide custom state restoration.
 101      */
 102
 103     /**
 104      * @event staterestore
 105      * Fires after the state of the object is restored.
 106      * @param {Ext.state.Stateful} this
 107      * @param {Object} state The hash of state values returned from the StateProvider. This is passed
 108      * to *`applyState`*. By default, that simply copies property values into this
 109      * object. The method maybe overridden to provide custom state restoration.
 110      */
 111
 112     /**
 113      * @event beforestatesave
 114      * Fires before the state of the object is saved to the configured state provider. Return false to stop the save.
 115      * @param {Ext.state.Stateful} this
 116      * @param {Object} state The hash of state values. This is determined by calling
 117      * *`getState()`* on the object. This method must be provided by the
 118      * developer to return whatever representation of state is required, by default, Ext.state.Stateful
 119      * has a null implementation.
 120      */
 121
 122     /**
 123      * @event statesave
 124      * Fires after the state of the object is saved to the configured state provider.
 125      * @param {Ext.state.Stateful} this
 126      * @param {Object} state The hash of state values. This is determined by calling
 127      * *`getState()`* on the object. This method must be provided by the
 128      * developer to return whatever representation of state is required, by default, Ext.state.Stateful
 129      * has a null implementation.
 130      */
 131
 132     constructor: function() {
 133         var me = this;
 134
 135         if (!me.stateEvents) {
 136             me.stateEvents = [];
 137         }
 138
 139         if (me.stateful !== false) {
 140             me.addStateEvents(me.stateEvents);
 141             me.initState();
 142         }
 143     },
 144
 145     /**
 146      * Add events that will trigger the state to be saved. If the first argument is an
 147      * array, each element of that array is the name of a state event. Otherwise, each
 148      * argument passed to this method is the name of a state event.
 149      *
 150      * @param {String/String[]} events The event name or an array of event names.
 151      */
 152     addStateEvents: function (events) {
 153         var me = this,
 154             i, event, stateEventsByName,
 155             eventArray;
 156
 157         if (me.stateful && me.getStateId()) {
 158             eventArray =  (typeof events === 'string') ? arguments : events;
 159
 160             stateEventsByName = me.stateEventsByName || (me.stateEventsByName = {});
 161
 162             for (i = eventArray.length; i--; ) {
 163                 event = eventArray[i];
 164
 165                 if (event && !stateEventsByName[event]) {
 166                     stateEventsByName[event] = 1;
 167                     me.on(event, me.onStateChange, me);
 168                 }
 169             }
 170         }
 171     },
 172
 173     /**
 174      * This method is called when any of the {@link #stateEvents} are fired.
 175      * @private
 176      */
 177     onStateChange: function(){
 178         var me = this,
 179             delay = me.saveDelay,
 180             statics, runner;
 181
 182         if (!me.stateful) {
 183             return;
 184         }
 185
 186         if (delay) {
 187             if (!me.stateTask) {
 188                 statics = Ext.state.Stateful;
 189                 runner = statics.runner || (statics.runner = new Ext.util.TaskRunner());
 190
 191                 me.stateTask = runner.newTask({
 192                     run: me.saveState,
 193                     scope: me,
 194                     interval: delay,
 195                     repeat: 1,
 196                     fireIdleEvent: false
 197                 });
 198             }
 199
 200             me.stateTask.start();
 201         } else {
 202             me.saveState();
 203         }
 204     },
 205
 206     /**
 207      * Saves the state of the object to the persistence store.
 208      */
 209     saveState: function() {
 210         var me = this,
 211             id = me.stateful && me.getStateId(),
 212             hasListeners = me.hasListeners,
 213             plugins,
 214             plugin,
 215             i, len,
 216             state,
 217             pluginState;
 218
 219         if (id) {
 220             state = me.getState() || {};    //pass along for custom interactions
 221
 222             /*
 223              * Gather state from those plugins that implement a getState method
 224              */
 225             plugins = me.getPlugins() || [];
 226             for (i = 0, len = plugins.length; i < len; i++) {
 227                 plugin = plugins[i];
 228                 if (plugin && plugin.getState) {
 229                     pluginState = plugin.getState(state);
 230                     if (pluginState && !state[plugin.ptype]) {  //first duplicate plugin wins
 231                         state[plugin.ptype] = pluginState;
 232                     }
 233                 }
 234             }
 235
 236             if (!hasListeners.beforestatesave || me.fireEvent('beforestatesave', me, state) !== false) {
 237                 Ext.state.Manager.set(id, state);
 238                 if (hasListeners.statesave) {
 239                     me.fireEvent('statesave', me, state);
 240                 }
 241             }
 242         }
 243     },
 244
 245     /**
 246      * Gets the current state of the object. By default this function returns null,
 247      * it should be overridden in subclasses to implement methods for getting the state.
 248      * @return {Object} The current state
 249      */
 250     getState: function(){
 251         return null;
 252     },
 253
 254     /**
 255      * Applies the state to the object. This should be overridden in subclasses to do
 256      * more complex state operations. By default it applies the state properties onto
 257      * the current object.
 258      * @param {Object} state The state
 259      */
 260     applyState: function(state) {
 261         if (state) {
 262             Ext.apply(this, state);
 263         }
 264     },
 265
 266     /**
 267      * Gets the state id for this object.
 268      * @return {String} The 'stateId' or the implicit 'id' specified by component configuration.
 269      * @private
 270      */
 271     getStateId: function() {
 272         var me = this;
 273         return me.stateId || (me.autoGenId ? null : me.id);
 274     },
 275
 276     /**
 277      * Initializes the state of the object upon construction.
 278      * @private
 279      */
 280     initState: function(){
 281         var me = this,
 282             id = me.stateful && me.getStateId(),
 283             hasListeners = me.hasListeners,
 284             state,
 285             combinedState,
 286             i, len,
 287             plugins,
 288             plugin,
 289             pluginType;
 290
 291         if (id) {
 292             combinedState = Ext.state.Manager.get(id);
 293             if (combinedState) {
 294                 state = Ext.apply({}, combinedState);
 295                 if (!hasListeners.beforestaterestore || me.fireEvent('beforestaterestore', me, combinedState) !== false) {
 296
 297                     //Notify all plugins FIRST (if interested) in new state
 298                     plugins = me.getPlugins() || [];
 299                     for (i = 0, len = plugins.length; i < len; i++) {
 300                         plugin = plugins[i];
 301                         if (plugin) {
 302                             pluginType = plugin.ptype;
 303                             if (plugin.applyState) {
 304                                 plugin.applyState(state[pluginType], combinedState);
 305                             }
 306                             delete state[pluginType];  //clean to prevent unwanted props on the component in final phase
 307                         }
 308                     }
 309
 310                     me.applyState(state);
 311                     if (hasListeners.staterestore) {
 312                         me.fireEvent('staterestore', me, combinedState);
 313                     }
 314                 }
 315             }
 316         }
 317     },
 318
 319     /**
 320      * Conditionally saves a single property from this object to the given state object.
 321      * The idea is to only save state which has changed from the initial state so that
 322      * current software settings do not override future software settings. Only those
 323      * values that are user-changed state should be saved.
 324      *
 325      * @param {String} propName The name of the property to save.
 326      * @param {Object} state The state object in to which to save the property.
 327      * @param {String} stateName (optional) The name to use for the property in state.
 328      * @return {Boolean} True if the property was saved, false if not.
 329      */
 330     savePropToState: function (propName, state, stateName) {
 331         var me = this,
 332             value = me[propName],
 333             config = me.initialConfig;
 334
 335         if (me.hasOwnProperty(propName)) {
 336             if (!config || config[propName] !== value) {
 337                 if (state) {
 338                     state[stateName || propName] = value;
 339                 }
 340                 return true;
 341             }
 342         }
 343         return false;
 344     },
 345
 346     /**
 347      * Gathers additional named properties of the instance and adds their current values
 348      * to the passed state object.
 349      * @param {String/String[]} propNames The name (or array of names) of the property to save.
 350      * @param {Object} state The state object in to which to save the property values.
 351      * @return {Object} state
 352      */
 353     savePropsToState: function (propNames, state) {
 354         var me = this,
 355             i, n;
 356
 357         if (typeof propNames === 'string') {
 358             me.savePropToState(propNames, state);
 359         } else {
 360             for (i = 0, n = propNames.length; i < n; ++i) {
 361                 me.savePropToState(propNames[i], state);
 362             }
 363         }
 364
 365         return state;
 366     },
 367
 368     /**
 369      * Destroys this stateful object.
 370      */
 371     destroy: function(){
 372         var me = this,
 373             task = me.stateTask;
 374
 375         if (task) {
 376             task.destroy();
 377             me.stateTask = null;
 378         }
 379
 380         me.clearListeners();
 381     }
 382 });