docs/source/Stateful.html

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