Upgrade to ExtJS 4.0.7 - Released 10/19/2011
[extjs.git] / 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>