Upgrade to ExtJS 3.3.0 - Released 10/06/2010
[extjs.git] / docs / source / History.html
index 8a42ef1..7bd6ad1 100644 (file)
-<html>\r
-<head>\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">',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 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
-        <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>
+<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>
+</head>
+<body  onload="prettyPrint();">
+    <pre class="prettyprint lang-js">/*!
+ * Ext JS Library 3.3.0
+ * Copyright(c) 2006-2010 Ext JS, Inc.
+ * licensing@extjs.com
+ * http://www.extjs.com/license
+ */
+<div id="cls-Ext.History"></div>/**
+ * @class Ext.History
+ * @extends Ext.util.Observable
+ * 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.
+ * @singleton
+ */
+Ext.History = (function () {
+    var iframe, hiddenField;
+    var ready = false;
+    var currentToken;
+
+    function getHash() {
+        var href = location.href, i = href.indexOf("#");
+        return i >= 0 ? href.substr(i + 1) : null;
+    }
+
+    function doSave() {
+        hiddenField.value = currentToken;
+    }
+
+    function handleStateChange(token) {
+        currentToken = token;
+        Ext.History.fireEvent('change', token);
+    }
+
+    function updateIFrame (token) {
+        var html = ['<html><body><div id="state">',Ext.util.Format.htmlEncode(token),'</div></body></html>'].join('');
+        try {
+            var doc = iframe.contentWindow.document;
+            doc.open();
+            doc.write(html);
+            doc.close();
+            return true;
+        } catch (e) {
+            return false;
+        }
+    }
+
+    function checkIFrame() {
+        if (!iframe.contentWindow || !iframe.contentWindow.document) {
+            setTimeout(checkIFrame, 10);
+            return;
+        }
+
+        var doc = iframe.contentWindow.document;
+        var elem = doc.getElementById("state");
+        var token = elem ? elem.innerText : null;
+
+        var hash = getHash();
+
+        setInterval(function () {
+
+            doc = iframe.contentWindow.document;
+            elem = doc.getElementById("state");
+
+            var newtoken = elem ? elem.innerText : null;
+
+            var newHash = getHash();
+
+            if (newtoken !== token) {
+                token = newtoken;
+                handleStateChange(token);
+                top.location.hash = token;
+                hash = token;
+                doSave();
+            } else if (newHash !== hash) {
+                hash = newHash;
+                updateIFrame(newHash);
+            }
+
+        }, 50);
+
+        ready = true;
+
+        Ext.History.fireEvent('ready', Ext.History);
+    }
+
+    function startUp() {
+        currentToken = hiddenField.value ? hiddenField.value : getHash();
+
+        if (Ext.isIE) {
+            checkIFrame();
+        } else {
+            var hash = getHash();
+            setInterval(function () {
+                var newHash = getHash();
+                if (newHash !== hash) {
+                    hash = newHash;
+                    handleStateChange(hash);
+                    doSave();
+                }
+            }, 50);
+            ready = true;
+            Ext.History.fireEvent('ready', Ext.History);
+        }
+    }
+
+    return {
+        <div id="prop-Ext.History-fieldId"></div>/**
+         * The id of the hidden field required for storing the current history token.
+         * @type String
+         * @property
+         */
+        fieldId: 'x-history-field',
+        <div id="prop-Ext.History-iframeId"></div>/**
+         * The id of the iframe required by IE to manage the history stack.
+         * @type String
+         * @property
+         */
+        iframeId: 'x-history-frame',
+
+        events:{},
+
+        <div id="method-Ext.History-init"></div>/**
+         * 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 (<code>this</code> reference) in which the callback is executed. Defaults to the browser window.
+         */
+        init: function (onReady, scope) {
+            if(ready) {
+                Ext.callback(onReady, scope, [this]);
+                return;
+            }
+            if(!Ext.isReady){
+                Ext.onReady(function(){
+                    Ext.History.init(onReady, scope);
+                });
+                return;
+            }
+            hiddenField = Ext.getDom(Ext.History.fieldId);
+            if (Ext.isIE) {
+                iframe = Ext.getDom(Ext.History.iframeId);
+            }
+            this.addEvents(
+                <div id="event-Ext.History-ready"></div>/**
+                 * @event ready
+                 * Fires when the Ext.History singleton has been initialized and is ready for use.
+                 * @param {Ext.History} The Ext.History singleton.
+                 */
+                'ready',
+                <div id="event-Ext.History-change"></div>/**
+                 * @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){
+                this.on('ready', onReady, scope, {single:true});
+            }
+            startUp();
+        },
+
+        <div id="method-Ext.History-add"></div>/**
+         * 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 specifc history
+         * state of that component.  Example usage:
+         * <pre><code>
+// Handle tab changes on a TabPanel
+tabPanel.on('tabchange', function(tabPanel, tab){
+    Ext.History.add(tabPanel.id + ':' + tab.id);
+});
+</code></pre>
+         * @param {String} token The value that defines a particular application-specific history state
+         * @param {Boolean} preventDuplicates 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 (defaults to true).
+         */
+        add: function (token, preventDup) {
+            if(preventDup !== false){
+                if(this.getToken() == token){
+                    return true;
+                }
+            }
+            if (Ext.isIE) {
+                return updateIFrame(token);
+            } else {
+                top.location.hash = token;
+                return true;
+            }
+        },
+
+        <div id="method-Ext.History-back"></div>/**
+         * Programmatically steps back one step in browser history (equivalent to the user pressing the Back button).
+         */
+        back: function(){
+            history.go(-1);
+        },
+
+        <div id="method-Ext.History-forward"></div>/**
+         * Programmatically steps forward one step in browser history (equivalent to the user pressing the Forward button).
+         */
+        forward: function(){
+            history.go(1);
+        },
+
+        <div id="method-Ext.History-getToken"></div>/**
+         * Retrieves the currently-active history token.
+         * @return {String} The token
+         */
+        getToken: function() {
+            return ready ? currentToken : getHash();
+        }
+    };
+})();
+Ext.apply(Ext.History, new Ext.util.Observable());</pre>    
+</body>
 </html>
\ No newline at end of file