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