Upgrade to ExtJS 4.0.7 - Released 10/19/2011
[extjs.git] / docs / source / History.html
index 48d103e..62cc441 100644 (file)
-<html>\r
-<head>\r
-  <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />    \r
-  <title>The source code</title>\r
-    <link href="../resources/prettify/prettify.css" type="text/css" rel="stylesheet" />\r
-    <script type="text/javascript" src="../resources/prettify/prettify.js"></script>\r
-</head>\r
-<body  onload="prettyPrint();">\r
-    <pre class="prettyprint lang-js"><div id="cls-Ext.History"></div>/**\r
- * @class Ext.History\r
- * @extends Ext.util.Observable\r
- * History management component that allows you to register arbitrary tokens that signify application\r
- * history state on navigation actions.  You can then handle the history {@link #change} event in order\r
- * to reset your application UI to the appropriate state when the user navigates forward or backward through\r
- * the browser history stack.\r
- * @singleton\r
- */\r
-Ext.History = (function () {\r
-    var iframe, hiddenField;\r
-    var ready = false;\r
-    var currentToken;\r
-\r
-    function getHash() {\r
-        var href = top.location.href, i = href.indexOf("#");\r
-        return i >= 0 ? href.substr(i + 1) : null;\r
-    }\r
-\r
-    function doSave() {\r
-        hiddenField.value = currentToken;\r
-    }\r
-\r
-    function handleStateChange(token) {\r
-        currentToken = token;\r
-        Ext.History.fireEvent('change', token);\r
-    }\r
-\r
-    function updateIFrame (token) {\r
-        var html = ['<html><body><div id="state">',Ext.util.Format.htmlEncode(token),'</div></body></html>'].join('');\r
-        try {\r
-            var doc = iframe.contentWindow.document;\r
-            doc.open();\r
-            doc.write(html);\r
-            doc.close();\r
-            return true;\r
-        } catch (e) {\r
-            return false;\r
-        }\r
-    }\r
-\r
-    function checkIFrame() {\r
-        if (!iframe.contentWindow || !iframe.contentWindow.document) {\r
-            setTimeout(checkIFrame, 10);\r
-            return;\r
-        }\r
-\r
-        var doc = iframe.contentWindow.document;\r
-        var elem = doc.getElementById("state");\r
-        var token = elem ? elem.innerText : null;\r
-\r
-        var hash = getHash();\r
-\r
-        setInterval(function () {\r
-\r
-            doc = iframe.contentWindow.document;\r
-            elem = doc.getElementById("state");\r
-\r
-            var newtoken = elem ? elem.innerText : null;\r
-\r
-            var newHash = getHash();\r
-\r
-            if (newtoken !== token) {\r
-                token = newtoken;\r
-                handleStateChange(token);\r
-                top.location.hash = token;\r
-                hash = token;\r
-                doSave();\r
-            } else if (newHash !== hash) {\r
-                hash = newHash;\r
-                updateIFrame(newHash);\r
-            }\r
-\r
-        }, 50);\r
-\r
-        ready = true;\r
-\r
-        Ext.History.fireEvent('ready', Ext.History);\r
-    }\r
-\r
-    function startUp() {\r
-        currentToken = hiddenField.value ? hiddenField.value : getHash();\r
-\r
-        if (Ext.isIE) {\r
-            checkIFrame();\r
-        } else {\r
-            var hash = getHash();\r
-            setInterval(function () {\r
-                var newHash = getHash();\r
-                if (newHash !== hash) {\r
-                    hash = newHash;\r
-                    handleStateChange(hash);\r
-                    doSave();\r
-                }\r
-            }, 50);\r
-            ready = true;\r
-            Ext.History.fireEvent('ready', Ext.History);\r
-        }\r
-    }\r
-\r
-    return {\r
-        <div id="prop-Ext.History-fieldId"></div>/**\r
-         * The id of the hidden field required for storing the current history token.\r
-         * @type String\r
-         * @property\r
-         */\r
-        fieldId: 'x-history-field',\r
-        <div id="prop-Ext.History-iframeId"></div>/**\r
-         * The id of the iframe required by IE to manage the history stack.\r
-         * @type String\r
-         * @property\r
-         */\r
-        iframeId: 'x-history-frame',\r
-\r
-        events:{},\r
-\r
-        <div id="method-Ext.History-init"></div>/**\r
-         * Initialize the global History instance.\r
-         * @param {Boolean} onReady (optional) A callback function that will be called once the history\r
-         * component is fully initialized.\r
-         * @param {Object} scope (optional) The scope (<code>this</code> reference) in which the callback is executed. Defaults to the browser window.\r
-         */\r
-        init: function (onReady, scope) {\r
-            if(ready) {\r
-                Ext.callback(onReady, scope, [this]);\r
-                return;\r
-            }\r
-            if(!Ext.isReady){\r
-                Ext.onReady(function(){\r
-                    Ext.History.init(onReady, scope);\r
-                });\r
-                return;\r
-            }\r
-            hiddenField = Ext.getDom(Ext.History.fieldId);\r
-            if (Ext.isIE) {\r
-                iframe = Ext.getDom(Ext.History.iframeId);\r
-            }\r
-            this.addEvents(\r
-                <div id="event-Ext.History-ready"></div>/**\r
-                 * @event ready\r
-                 * Fires when the Ext.History singleton has been initialized and is ready for use.\r
-                 * @param {Ext.History} The Ext.History singleton.\r
-                 */\r
-                'ready',\r
-                <div id="event-Ext.History-change"></div>/**\r
-                 * @event change\r
-                 * Fires when navigation back or forwards within the local page's history occurs.\r
-                 * @param {String} token An identifier associated with the page state at that point in its history.\r
-                 */\r
-                'change'\r
-            );\r
-            if(onReady){\r
-                this.on('ready', onReady, scope, {single:true});\r
-            }\r
-            startUp();\r
-        },\r
-\r
-        <div id="method-Ext.History-add"></div>/**\r
-         * Add a new token to the history stack. This can be any arbitrary value, although it would\r
-         * commonly be the concatenation of a component id and another id marking the specifc history\r
-         * state of that component.  Example usage:\r
-         * <pre><code>\r
-// Handle tab changes on a TabPanel\r
-tabPanel.on('tabchange', function(tabPanel, tab){\r
-    Ext.History.add(tabPanel.id + ':' + tab.id);\r
-});\r
-</code></pre>\r
-         * @param {String} token The value that defines a particular application-specific history state\r
-         * @param {Boolean} preventDuplicates When true, if the passed token matches the current token\r
-         * it will not save a new history step. Set to false if the same state can be saved more than once\r
-         * at the same history stack location (defaults to true).\r
-         */\r
-        add: function (token, preventDup) {\r
-            if(preventDup !== false){\r
-                if(this.getToken() == token){\r
-                    return true;\r
-                }\r
-            }\r
-            if (Ext.isIE) {\r
-                return updateIFrame(token);\r
-            } else {\r
-                top.location.hash = token;\r
-                return true;\r
-            }\r
-        },\r
-\r
-        <div id="method-Ext.History-back"></div>/**\r
-         * Programmatically steps back one step in browser history (equivalent to the user pressing the Back button).\r
-         */\r
-        back: function(){\r
-            history.go(-1);\r
-        },\r
-\r
-        <div id="method-Ext.History-forward"></div>/**\r
-         * Programmatically steps forward one step in browser history (equivalent to the user pressing the Forward button).\r
-         */\r
-        forward: function(){\r
-            history.go(1);\r
-        },\r
-\r
-        <div id="method-Ext.History-getToken"></div>/**\r
-         * Retrieves the currently-active history token.\r
-         * @return {String} The token\r
-         */\r
-        getToken: function() {\r
-            return ready ? currentToken : getHash();\r
-        }\r
-    };\r
-})();\r
-Ext.apply(Ext.History, new Ext.util.Observable());</pre>    \r
-</body>\r
-</html>
\ No newline at end of file
+<!DOCTYPE html>
+<html>
+<head>
+  <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+  <title>The source code</title>
+  <link href="../resources/prettify/prettify.css" type="text/css" rel="stylesheet" />
+  <script type="text/javascript" src="../resources/prettify/prettify.js"></script>
+  <style type="text/css">
+    .highlight { display: block; background-color: #ddd; }
+  </style>
+  <script type="text/javascript">
+    function highlight() {
+      document.getElementById(location.hash.replace(/#/, "")).className = "highlight";
+    }
+  </script>
+</head>
+<body onload="prettyPrint(); highlight();">
+  <pre class="prettyprint lang-js"><span id='Ext-util-History'>/**
+</span> * @class Ext.util.History
+ *
+ * History management component that allows you to register arbitrary tokens that signify application
+ * history state on navigation actions.  You can then handle the history {@link #change} event in order
+ * to reset your application UI to the appropriate state when the user navigates forward or backward through
+ * the browser history stack.
+ *
+ * ## Initializing
+ * The {@link #init} method of the History object must be called before using History. This sets up the internal
+ * state and must be the first thing called before using History.
+ *
+ * ## Setup
+ * The History objects requires elements on the page to keep track of the browser history. For older versions of IE,
+ * an IFrame is required to do the tracking. For other browsers, a hidden field can be used. The history objects expects
+ * these to be on the page before the {@link #init} method is called. The following markup is suggested in order
+ * to support all browsers:
+ *
+ *     &lt;form id=&quot;history-form&quot; class=&quot;x-hide-display&quot;&gt;
+ *         &lt;input type=&quot;hidden&quot; id=&quot;x-history-field&quot; /&gt;
+ *         &lt;iframe id=&quot;x-history-frame&quot;&gt;&lt;/iframe&gt;
+ *     &lt;/form&gt;
+ *
+ * @singleton
+ */
+Ext.define('Ext.util.History', {
+    singleton: true,
+    alternateClassName: 'Ext.History',
+    mixins: {
+        observable: 'Ext.util.Observable'
+    },
+
+    constructor: function() {
+        var me = this;
+        me.oldIEMode = Ext.isIE6 || Ext.isIE7 || !Ext.isStrict &amp;&amp; Ext.isIE8;
+        me.iframe = null;
+        me.hiddenField = null;
+        me.ready = false;
+        me.currentToken = null;
+    },
+
+    getHash: function() {
+        var href = window.location.href,
+            i = href.indexOf(&quot;#&quot;);
+
+        return i &gt;= 0 ? href.substr(i + 1) : null;
+    },
+
+    doSave: function() {
+        this.hiddenField.value = this.currentToken;
+    },
+
+
+    handleStateChange: function(token) {
+        this.currentToken = token;
+        this.fireEvent('change', token);
+    },
+
+    updateIFrame: function(token) {
+        var html = '&lt;html&gt;&lt;body&gt;&lt;div id=&quot;state&quot;&gt;' +
+                    Ext.util.Format.htmlEncode(token) +
+                    '&lt;/div&gt;&lt;/body&gt;&lt;/html&gt;';
+
+        try {
+            var doc = this.iframe.contentWindow.document;
+            doc.open();
+            doc.write(html);
+            doc.close();
+            return true;
+        } catch (e) {
+            return false;
+        }
+    },
+
+    checkIFrame: function () {
+        var me = this,
+            contentWindow = me.iframe.contentWindow;
+
+        if (!contentWindow || !contentWindow.document) {
+            Ext.Function.defer(this.checkIFrame, 10, this);
+            return;
+        }
+
+        var doc = contentWindow.document,
+            elem = doc.getElementById(&quot;state&quot;),
+            oldToken = elem ? elem.innerText : null,
+            oldHash = me.getHash();
+
+        Ext.TaskManager.start({
+            run: function () {
+                var doc = contentWindow.document,
+                    elem = doc.getElementById(&quot;state&quot;),
+                    newToken = elem ? elem.innerText : null,
+                    newHash = me.getHash();
+
+                if (newToken !== oldToken) {
+                    oldToken = newToken;
+                    me.handleStateChange(newToken);
+                    window.top.location.hash = newToken;
+                    oldHash = newToken;
+                    me.doSave();
+                } else if (newHash !== oldHash) {
+                    oldHash = newHash;
+                    me.updateIFrame(newHash);
+                }
+            },
+            interval: 50,
+            scope: me
+        });
+        me.ready = true;
+        me.fireEvent('ready', me);
+    },
+
+    startUp: function () {
+        var me = this;
+
+        me.currentToken = me.hiddenField.value || this.getHash();
+
+        if (me.oldIEMode) {
+            me.checkIFrame();
+        } else {
+            var hash = me.getHash();
+            Ext.TaskManager.start({
+                run: function () {
+                    var newHash = me.getHash();
+                    if (newHash !== hash) {
+                        hash = newHash;
+                        me.handleStateChange(hash);
+                        me.doSave();
+                    }
+                },
+                interval: 50,
+                scope: me
+            });
+            me.ready = true;
+            me.fireEvent('ready', me);
+        }
+
+    },
+
+<span id='Ext-util-History-property-fieldId'>    /**
+</span>     * The id of the hidden field required for storing the current history token.
+     * @type String
+     * @property
+     */
+    fieldId: Ext.baseCSSPrefix + 'history-field',
+<span id='Ext-util-History-property-iframeId'>    /**
+</span>     * The id of the iframe required by IE to manage the history stack.
+     * @type String
+     * @property
+     */
+    iframeId: Ext.baseCSSPrefix + 'history-frame',
+
+<span id='Ext-util-History-method-init'>    /**
+</span>     * Initialize the global History instance.
+     * @param {Boolean} onReady (optional) A callback function that will be called once the history
+     * component is fully initialized.
+     * @param {Object} scope (optional) The scope (`this` reference) in which the callback is executed. Defaults to the browser window.
+     */
+    init: function (onReady, scope) {
+        var me = this;
+
+        if (me.ready) {
+            Ext.callback(onReady, scope, [me]);
+            return;
+        }
+
+        if (!Ext.isReady) {
+            Ext.onReady(function() {
+                me.init(onReady, scope);
+            });
+            return;
+        }
+
+        me.hiddenField = Ext.getDom(me.fieldId);
+
+        if (me.oldIEMode) {
+            me.iframe = Ext.getDom(me.iframeId);
+        }
+
+        me.addEvents(
+<span id='Ext-util-History-event-ready'>            /**
+</span>             * @event ready
+             * Fires when the Ext.util.History singleton has been initialized and is ready for use.
+             * @param {Ext.util.History} The Ext.util.History singleton.
+             */
+            'ready',
+<span id='Ext-util-History-event-change'>            /**
+</span>             * @event change
+             * Fires when navigation back or forwards within the local page's history occurs.
+             * @param {String} token An identifier associated with the page state at that point in its history.
+             */
+            'change'
+        );
+
+        if (onReady) {
+            me.on('ready', onReady, scope, {single: true});
+        }
+        me.startUp();
+    },
+
+<span id='Ext-util-History-method-add'>    /**
+</span>     * Add a new token to the history stack. This can be any arbitrary value, although it would
+     * commonly be the concatenation of a component id and another id marking the specific history
+     * state of that component. Example usage:
+     *
+     *     // Handle tab changes on a TabPanel
+     *     tabPanel.on('tabchange', function(tabPanel, tab){
+     *          Ext.History.add(tabPanel.id + ':' + tab.id);
+     *     });
+     *
+     * @param {String} token The value that defines a particular application-specific history state
+     * @param {Boolean} [preventDuplicates=true] When true, if the passed token matches the current token
+     * it will not save a new history step. Set to false if the same state can be saved more than once
+     * at the same history stack location.
+     */
+    add: function (token, preventDup) {
+        var me = this;
+
+        if (preventDup !== false) {
+            if (me.getToken() === token) {
+                return true;
+            }
+        }
+
+        if (me.oldIEMode) {
+            return me.updateIFrame(token);
+        } else {
+            window.top.location.hash = token;
+            return true;
+        }
+    },
+
+<span id='Ext-util-History-method-back'>    /**
+</span>     * Programmatically steps back one step in browser history (equivalent to the user pressing the Back button).
+     */
+    back: function() {
+        window.history.go(-1);
+    },
+
+<span id='Ext-util-History-method-forward'>    /**
+</span>     * Programmatically steps forward one step in browser history (equivalent to the user pressing the Forward button).
+     */
+    forward: function(){
+        window.history.go(1);
+    },
+
+<span id='Ext-util-History-method-getToken'>    /**
+</span>     * Retrieves the currently-active history token.
+     * @return {String} The token
+     */
+    getToken: function() {
+        return this.ready ? this.currentToken : this.getHash();
+    }
+});</pre>
+</body>
+</html>