Upgrade to ExtJS 3.0.0 - Released 07/06/2009
[extjs.git] / src / util / History.js
diff --git a/src/util/History.js b/src/util/History.js
new file mode 100644 (file)
index 0000000..b50f8f5
--- /dev/null
@@ -0,0 +1,203 @@
+/*!
+ * Ext JS Library 3.0.0
+ * Copyright(c) 2006-2009 Ext JS, LLC
+ * licensing@extjs.com
+ * http://www.extjs.com/license
+ */
+/**\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">',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
+        /**\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
+        /**\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
+        /**\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 callback scope\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('ready', 'change');\r
+            if(onReady){\r
+                this.on('ready', onReady, scope, {single:true});\r
+            }\r
+            startUp();\r
+        },\r
+\r
+        /**\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
+        /**\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
+        /**\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
+        /**\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());
\ No newline at end of file