docs/source/Stateful.html

   1 <!DOCTYPE html>
   2 <html>
   3 <head>
   4   <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
   5   <title>The source code</title>
   6   <link href="../resources/prettify/prettify.css" type="text/css" rel="stylesheet" />
   7   <script type="text/javascript" src="../resources/prettify/prettify.js"></script>
   8   <style type="text/css">
   9     .highlight { display: block; background-color: #ddd; }
  10   </style>
  11   <script type="text/javascript">
  12     function highlight() {
  13       document.getElementById(location.hash.replace(/#/, "")).className = "highlight";
  14     }
  15   </script>
  16 </head>
  17 <body onload="prettyPrint(); highlight();">
  18   <pre class="prettyprint lang-js"><span id='Ext-state-Stateful'>/**
  19 </span> * @class Ext.state.Stateful
  20  * A mixin for being able to save the state of an object to an underlying
  21  * {@link Ext.state.Provider}.
  22  */
  23 Ext.define('Ext.state.Stateful', {
  24
  25     /* Begin Definitions */
  26
  27    mixins: {
  28         observable: 'Ext.util.Observable'
  29     },
  30
  31     requires: ['Ext.state.Manager'],
  32
  33     /* End Definitions */
  34
  35 <span id='Ext-state-Stateful-cfg-stateful'>    /**
  36 </span>     * @cfg {Boolean} stateful
  37      * &lt;p&gt;A flag which causes the object to attempt to restore the state of
  38      * internal properties from a saved state on startup. The object must have
  39      * a &lt;code&gt;{@link #stateId}&lt;/code&gt; for state to be managed.
  40      * Auto-generated ids are not guaranteed to be stable across page loads and
  41      * cannot be relied upon to save and restore the same state for a object.&lt;p&gt;
  42      * &lt;p&gt;For state saving to work, the state manager's provider must have been
  43      * set to an implementation of {@link Ext.state.Provider} which overrides the
  44      * {@link Ext.state.Provider#set set} and {@link Ext.state.Provider#get get}
  45      * methods to save and recall name/value pairs. A built-in implementation,
  46      * {@link Ext.state.CookieProvider} is available.&lt;/p&gt;
  47      * &lt;p&gt;To set the state provider for the current page:&lt;/p&gt;
  48      * &lt;pre&gt;&lt;code&gt;
  49 Ext.state.Manager.setProvider(new Ext.state.CookieProvider({
  50     expires: new Date(new Date().getTime()+(1000*60*60*24*7)), //7 days from now
  51 }));
  52      * &lt;/code&gt;&lt;/pre&gt;
  53      * &lt;p&gt;A stateful object attempts to save state when one of the events
  54      * listed in the &lt;code&gt;{@link #stateEvents}&lt;/code&gt; configuration fires.&lt;/p&gt;
  55      * &lt;p&gt;To save state, a stateful object first serializes its state by
  56      * calling &lt;b&gt;&lt;code&gt;{@link #getState}&lt;/code&gt;&lt;/b&gt;. By default, this function does
  57      * nothing. The developer must provide an implementation which returns an
  58      * object hash which represents the restorable state of the object.&lt;/p&gt;
  59      * &lt;p&gt;The value yielded by getState is passed to {@link Ext.state.Manager#set}
  60      * which uses the configured {@link Ext.state.Provider} to save the object
  61      * keyed by the &lt;code&gt;{@link #stateId}&lt;/code&gt;.&lt;/p&gt;
  62      * &lt;p&gt;During construction, a stateful object attempts to &lt;i&gt;restore&lt;/i&gt;
  63      * its state by calling {@link Ext.state.Manager#get} passing the
  64      * &lt;code&gt;{@link #stateId}&lt;/code&gt;&lt;/p&gt;
  65      * &lt;p&gt;The resulting object is passed to &lt;b&gt;&lt;code&gt;{@link #applyState}&lt;/code&gt;&lt;/b&gt;.
  66      * The default implementation of &lt;code&gt;{@link #applyState}&lt;/code&gt; simply copies
  67      * properties into the object, but a developer may override this to support
  68      * more behaviour.&lt;/p&gt;
  69      * &lt;p&gt;You can perform extra processing on state save and restore by attaching
  70      * handlers to the {@link #beforestaterestore}, {@link #staterestore},
  71      * {@link #beforestatesave} and {@link #statesave} events.&lt;/p&gt;
  72      */
  73     stateful: true,
  74
  75 <span id='Ext-state-Stateful-cfg-stateId'>    /**
  76 </span>     * @cfg {String} stateId
  77      * The unique id for this object to use for state management purposes.
  78      * &lt;p&gt;See {@link #stateful} for an explanation of saving and restoring state.&lt;/p&gt;
  79      */
  80
  81 <span id='Ext-state-Stateful-cfg-stateEvents'>    /**
  82 </span>     * @cfg {String[]} stateEvents
  83      * &lt;p&gt;An array of events that, when fired, should trigger this object to
  84      * save its state. Defaults to none. &lt;code&gt;stateEvents&lt;/code&gt; may be any type
  85      * of event supported by this object, including browser or custom events
  86      * (e.g., &lt;tt&gt;['click', 'customerchange']&lt;/tt&gt;).&lt;/p&gt;
  87      * &lt;p&gt;See &lt;code&gt;{@link #stateful}&lt;/code&gt; for an explanation of saving and
  88      * restoring object state.&lt;/p&gt;
  89      */
  90
  91 <span id='Ext-state-Stateful-cfg-saveDelay'>    /**
  92 </span>     * @cfg {Number} saveDelay
  93      * A buffer to be applied if many state events are fired within a short period.
  94      */
  95     saveDelay: 100,
  96
  97     autoGenIdRe: /^((\w+-)|(ext-comp-))\d{4,}$/i,
  98
  99     constructor: function(config) {
 100         var me = this;
 101
 102         config = config || {};
 103         if (Ext.isDefined(config.stateful)) {
 104             me.stateful = config.stateful;
 105         }
 106         if (Ext.isDefined(config.saveDelay)) {
 107             me.saveDelay = config.saveDelay;
 108         }
 109         me.stateId = me.stateId || config.stateId;
 110
 111         if (!me.stateEvents) {
 112             me.stateEvents = [];
 113         }
 114         if (config.stateEvents) {
 115             me.stateEvents.concat(config.stateEvents);
 116         }
 117         this.addEvents(
 118 <span id='Ext-state-Stateful-event-beforestaterestore'>            /**
 119 </span>             * @event beforestaterestore
 120              * Fires before the state of the object is restored. Return false from an event handler to stop the restore.
 121              * @param {Ext.state.Stateful} this
 122              * @param {Object} state The hash of state values returned from the StateProvider. If this
 123              * event is not vetoed, then the state object is passed to &lt;b&gt;&lt;tt&gt;applyState&lt;/tt&gt;&lt;/b&gt;. By default,
 124              * that simply copies property values into this object. The method maybe overriden to
 125              * provide custom state restoration.
 126              */
 127             'beforestaterestore',
 128
 129 <span id='Ext-state-Stateful-event-staterestore'>            /**
 130 </span>             * @event staterestore
 131              * Fires after the state of the object is restored.
 132              * @param {Ext.state.Stateful} this
 133              * @param {Object} state The hash of state values returned from the StateProvider. This is passed
 134              * to &lt;b&gt;&lt;tt&gt;applyState&lt;/tt&gt;&lt;/b&gt;. By default, that simply copies property values into this
 135              * object. The method maybe overriden to provide custom state restoration.
 136              */
 137             'staterestore',
 138
 139 <span id='Ext-state-Stateful-event-beforestatesave'>            /**
 140 </span>             * @event beforestatesave
 141              * Fires before the state of the object is saved to the configured state provider. Return false to stop the save.
 142              * @param {Ext.state.Stateful} this
 143              * @param {Object} state The hash of state values. This is determined by calling
 144              * &lt;b&gt;&lt;tt&gt;getState()&lt;/tt&gt;&lt;/b&gt; on the object. This method must be provided by the
 145              * developer to return whetever representation of state is required, by default, Ext.state.Stateful
 146              * has a null implementation.
 147              */
 148             'beforestatesave',
 149
 150 <span id='Ext-state-Stateful-event-statesave'>            /**
 151 </span>             * @event statesave
 152              * Fires after the state of the object is saved to the configured state provider.
 153              * @param {Ext.state.Stateful} this
 154              * @param {Object} state The hash of state values. This is determined by calling
 155              * &lt;b&gt;&lt;tt&gt;getState()&lt;/tt&gt;&lt;/b&gt; on the object. This method must be provided by the
 156              * developer to return whetever representation of state is required, by default, Ext.state.Stateful
 157              * has a null implementation.
 158              */
 159             'statesave'
 160         );
 161         me.mixins.observable.constructor.call(me);
 162         if (me.stateful !== false) {
 163             me.initStateEvents();
 164             me.initState();
 165         }
 166     },
 167
 168 <span id='Ext-state-Stateful-method-initStateEvents'>    /**
 169 </span>     * Initializes any state events for this object.
 170      * @private
 171      */
 172     initStateEvents: function() {
 173         this.addStateEvents(this.stateEvents);
 174     },
 175
 176 <span id='Ext-state-Stateful-method-addStateEvents'>    /**
 177 </span>     * Add events that will trigger the state to be saved.
 178      * @param {String/String[]} events The event name or an array of event names.
 179      */
 180     addStateEvents: function(events){
 181         if (!Ext.isArray(events)) {
 182             events = [events];
 183         }
 184
 185         var me = this,
 186             i = 0,
 187             len = events.length;
 188
 189         for (; i &lt; len; ++i) {
 190             me.on(events[i], me.onStateChange, me);
 191         }
 192     },
 193
 194 <span id='Ext-state-Stateful-method-onStateChange'>    /**
 195 </span>     * This method is called when any of the {@link #stateEvents} are fired.
 196      * @private
 197      */
 198     onStateChange: function(){
 199         var me = this,
 200             delay = me.saveDelay;
 201
 202         if (delay &gt; 0) {
 203             if (!me.stateTask) {
 204                 me.stateTask = Ext.create('Ext.util.DelayedTask', me.saveState, me);
 205             }
 206             me.stateTask.delay(me.saveDelay);
 207         } else {
 208             me.saveState();
 209         }
 210     },
 211
 212 <span id='Ext-state-Stateful-method-saveState'>    /**
 213 </span>     * Saves the state of the object to the persistence store.
 214      * @private
 215      */
 216     saveState: function() {
 217         var me = this,
 218             id,
 219             state;
 220
 221         if (me.stateful !== false) {
 222             id = me.getStateId();
 223             if (id) {
 224                 state = me.getState();
 225                 if (me.fireEvent('beforestatesave', me, state) !== false) {
 226                     Ext.state.Manager.set(id, state);
 227                     me.fireEvent('statesave', me, state);
 228                 }
 229             }
 230         }
 231     },
 232
 233 <span id='Ext-state-Stateful-method-getState'>    /**
 234 </span>     * Gets the current state of the object. By default this function returns null,
 235      * it should be overridden in subclasses to implement methods for getting the state.
 236      * @return {Object} The current state
 237      */
 238     getState: function(){
 239         return null;
 240     },
 241
 242 <span id='Ext-state-Stateful-method-applyState'>    /**
 243 </span>     * Applies the state to the object. This should be overridden in subclasses to do
 244      * more complex state operations. By default it applies the state properties onto
 245      * the current object.
 246      * @param {Object} state The state
 247      */
 248     applyState: function(state) {
 249         if (state) {
 250             Ext.apply(this, state);
 251         }
 252     },
 253
 254 <span id='Ext-state-Stateful-method-getStateId'>    /**
 255 </span>     * Gets the state id for this object.
 256      * @return {String} The state id, null if not found.
 257      */
 258     getStateId: function() {
 259         var me = this,
 260             id = me.stateId;
 261
 262         if (!id) {
 263             id = me.autoGenIdRe.test(String(me.id)) ? null : me.id;
 264         }
 265         return id;
 266     },
 267
 268 <span id='Ext-state-Stateful-method-initState'>    /**
 269 </span>     * Initializes the state of the object upon construction.
 270      * @private
 271      */
 272     initState: function(){
 273         var me = this,
 274             id = me.getStateId(),
 275             state;
 276
 277         if (me.stateful !== false) {
 278             if (id) {
 279                 state = Ext.state.Manager.get(id);
 280                 if (state) {
 281                     state = Ext.apply({}, state);
 282                     if (me.fireEvent('beforestaterestore', me, state) !== false) {
 283                         me.applyState(state);
 284                         me.fireEvent('staterestore', me, state);
 285                     }
 286                 }
 287             }
 288         }
 289     },
 290
 291 <span id='Ext-state-Stateful-method-savePropToState'>    /**
 292 </span>     * Conditionally saves a single property from this object to the given state object.
 293      * The idea is to only save state which has changed from the initial state so that
 294      * current software settings do not override future software settings. Only those
 295      * values that are user-changed state should be saved.
 296      *
 297      * @param {String} propName The name of the property to save.
 298      * @param {Object} state The state object in to which to save the property.
 299      * @param {String} stateName (optional) The name to use for the property in state.
 300      * @return {Boolean} True if the property was saved, false if not.
 301      */
 302     savePropToState: function (propName, state, stateName) {
 303         var me = this,
 304             value = me[propName],
 305             config = me.initialConfig;
 306
 307         if (me.hasOwnProperty(propName)) {
 308             if (!config || config[propName] !== value) {
 309                 if (state) {
 310                     state[stateName || propName] = value;
 311                 }
 312                 return true;
 313             }
 314         }
 315         return false;
 316     },
 317
 318     savePropsToState: function (propNames, state) {
 319         var me = this;
 320         Ext.each(propNames, function (propName) {
 321             me.savePropToState(propName, state);
 322         });
 323         return state;
 324     },
 325
 326 <span id='Ext-state-Stateful-method-destroy'>    /**
 327 </span>     * Destroys this stateful object.
 328      */
 329     destroy: function(){
 330         var task = this.stateTask;
 331         if (task) {
 332             task.cancel();
 333         }
 334         this.clearListeners();
 335
 336     }
 337
 338 });
 339 </pre>
 340 </body>
 341 </html>