Upgrade to ExtJS 4.0.0 - Released 04/26/2011
[extjs.git] / docs / source / History.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-util.History'>/**
2 </span> * @class Ext.util.History
3  * History management component that allows you to register arbitrary tokens that signify application
4  * history state on navigation actions.  You can then handle the history {@link #change} event in order
5  * to reset your application UI to the appropriate state when the user navigates forward or backward through
6  * the browser history stack.
7  * @singleton
8  */
9 Ext.define('Ext.util.History', {
10     singleton: true,
11     alternateClassName: 'Ext.History',
12     mixins: {
13         observable: 'Ext.util.Observable'
14     },
15     
16     constructor: function() {
17         var me = this;
18         me.oldIEMode = Ext.isIE6 || Ext.isIE7 || !Ext.isStrict &amp;&amp; Ext.isIE8;
19         me.iframe = null;
20         me.hiddenField = null;
21         me.ready = false;
22         me.currentToken = null;
23     },
24     
25     getHash: function() {
26         var href = window.location.href,
27             i = href.indexOf(&quot;#&quot;);
28             
29         return i &gt;= 0 ? href.substr(i + 1) : null;
30     },
31
32     doSave: function() {
33         this.hiddenField.value = this.currentToken;
34     },
35     
36
37     handleStateChange: function(token) {
38         this.currentToken = token;
39         this.fireEvent('change', token);
40     },
41
42     updateIFrame: function(token) {
43         var html = '&lt;html&gt;&lt;body&gt;&lt;div id=&quot;state&quot;&gt;' + 
44                     Ext.util.Format.htmlEncode(token) + 
45                     '&lt;/div&gt;&lt;/body&gt;&lt;/html&gt;';
46
47         try {
48             var doc = this.iframe.contentWindow.document;
49             doc.open();
50             doc.write(html);
51             doc.close();
52             return true;
53         } catch (e) {
54             return false;
55         }
56     },
57
58     checkIFrame: function () {
59         var me = this,
60             contentWindow = me.iframe.contentWindow;
61             
62         if (!contentWindow || !contentWindow.document) {
63             Ext.Function.defer(this.checkIFrame, 10, this);
64             return;
65         }
66        
67         var doc = contentWindow.document,
68             elem = doc.getElementById(&quot;state&quot;),
69             oldToken = elem ? elem.innerText : null,
70             oldHash = me.getHash();
71            
72         Ext.TaskManager.start({
73             run: function () {
74                 var doc = contentWindow.document,
75                     elem = doc.getElementById(&quot;state&quot;),
76                     newToken = elem ? elem.innerText : null,
77                     newHash = me.getHash();
78
79                 if (newToken !== oldToken) {
80                     oldToken = newToken;
81                     me.handleStateChange(newToken);
82                     window.top.location.hash = newToken;
83                     oldHash = newToken;
84                     me.doSave();
85                 } else if (newHash !== oldHash) {
86                     oldHash = newHash;
87                     me.updateIFrame(newHash);
88                 }
89             }, 
90             interval: 50,
91             scope: me
92         });
93         me.ready = true;
94         me.fireEvent('ready', me);            
95     },
96
97     startUp: function () {
98         var me = this;
99         
100         me.currentToken = me.hiddenField.value || this.getHash();
101
102         if (me.oldIEMode) {
103             me.checkIFrame();
104         } else {
105             var hash = me.getHash();
106             Ext.TaskManager.start({
107                 run: function () {
108                     var newHash = me.getHash();
109                     if (newHash !== hash) {
110                         hash = newHash;
111                         me.handleStateChange(hash);
112                         me.doSave();
113                     }
114                 },
115                 interval: 50,
116                 scope: me
117             });
118             me.ready = true;
119             me.fireEvent('ready', me);
120         }
121         
122     },
123
124 <span id='Ext-util.History-property-fieldId'>    /**
125 </span>     * The id of the hidden field required for storing the current history token.
126      * @type String
127      * @property
128      */
129     fieldId: Ext.baseCSSPrefix + 'history-field',
130 <span id='Ext-util.History-property-iframeId'>    /**
131 </span>     * The id of the iframe required by IE to manage the history stack.
132      * @type String
133      * @property
134      */
135     iframeId: Ext.baseCSSPrefix + 'history-frame',
136
137 <span id='Ext-util.History-method-init'>    /**
138 </span>     * Initialize the global History instance.
139      * @param {Boolean} onReady (optional) A callback function that will be called once the history
140      * component is fully initialized.
141      * @param {Object} scope (optional) The scope (&lt;code&gt;this&lt;/code&gt; reference) in which the callback is executed. Defaults to the browser window.
142      */
143     init: function (onReady, scope) {
144         var me = this;
145         
146         if (me.ready) {
147             Ext.callback(onReady, scope, [me]);
148             return;
149         }
150         
151         if (!Ext.isReady) {
152             Ext.onReady(function() {
153                 me.init(onReady, scope);
154             });
155             return;
156         }
157         
158         me.hiddenField = Ext.getDom(me.fieldId);
159         
160         if (me.oldIEMode) {
161             me.iframe = Ext.getDom(me.iframeId);
162         }
163         
164         me.addEvents(
165 <span id='Ext-util.History-event-ready'>            /**
166 </span>             * @event ready
167              * Fires when the Ext.util.History singleton has been initialized and is ready for use.
168              * @param {Ext.util.History} The Ext.util.History singleton.
169              */
170             'ready',
171 <span id='Ext-util.History-event-change'>            /**
172 </span>             * @event change
173              * Fires when navigation back or forwards within the local page's history occurs.
174              * @param {String} token An identifier associated with the page state at that point in its history.
175              */
176             'change'
177         );
178         
179         if (onReady) {
180             me.on('ready', onReady, scope, {single: true});
181         }
182         me.startUp();
183     },
184
185 <span id='Ext-util.History-method-add'>    /**
186 </span>     * Add a new token to the history stack. This can be any arbitrary value, although it would
187      * commonly be the concatenation of a component id and another id marking the specifc history
188      * state of that component.  Example usage:
189      * &lt;pre&gt;&lt;code&gt;
190 // Handle tab changes on a TabPanel
191 tabPanel.on('tabchange', function(tabPanel, tab){
192 Ext.History.add(tabPanel.id + ':' + tab.id);
193 });
194 &lt;/code&gt;&lt;/pre&gt;
195      * @param {String} token The value that defines a particular application-specific history state
196      * @param {Boolean} preventDuplicates When true, if the passed token matches the current token
197      * it will not save a new history step. Set to false if the same state can be saved more than once
198      * at the same history stack location (defaults to true).
199      */
200     add: function (token, preventDup) {
201         var me = this;
202         
203         if (preventDup !== false) {
204             if (me.getToken() === token) {
205                 return true;
206             }
207         }
208         
209         if (me.oldIEMode) {
210             return me.updateIFrame(token);
211         } else {
212             window.top.location.hash = token;
213             return true;
214         }
215     },
216
217 <span id='Ext-util.History-method-back'>    /**
218 </span>     * Programmatically steps back one step in browser history (equivalent to the user pressing the Back button).
219      */
220     back: function() {
221         window.history.go(-1);
222     },
223
224 <span id='Ext-util.History-method-forward'>    /**
225 </span>     * Programmatically steps forward one step in browser history (equivalent to the user pressing the Forward button).
226      */
227     forward: function(){
228         window.history.go(1);
229     },
230
231 <span id='Ext-util.History-method-getToken'>    /**
232 </span>     * Retrieves the currently-active history token.
233      * @return {String} The token
234      */
235     getToken: function() {
236         return this.ready ? this.currentToken : this.getHash();
237     }
238 });</pre></pre></body></html>