Upgrade to ExtJS 3.1.0 - Released 12/16/2009
[extjs.git] / docs / source / History.html
index 8a42ef1..99630ec 100644 (file)
@@ -1,5 +1,6 @@
 <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
  * @singleton\r
  */\r
 Ext.History = (function () {\r
-    var iframe, hiddenField;\r
-    var ready = false;\r
-    var currentToken;\r
+    var iframe, hiddenField,\r
+        ready = false,\r
+        currentToken,\r
+        ignoreNext = false;\r
 \r
     function getHash() {\r
         var href = top.location.href, i = href.indexOf("#");\r
@@ -30,11 +32,14 @@ Ext.History = (function () {
 \r
     function handleStateChange(token) {\r
         currentToken = token;\r
-        Ext.History.fireEvent('change', token);\r
+        if(!(token == ignoreNext)){\r
+            Ext.History.fireEvent('change', token);\r
+        }\r
+        ignoreNext = false;\r
     }\r
 \r
     function updateIFrame (token) {\r
-        var html = ['<html><body><div id="state">',token,'</div></body></html>'].join('');\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
@@ -52,20 +57,18 @@ Ext.History = (function () {
             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
+        var doc = iframe.contentWindow.document,\r
+            elem = doc.getElementById("state"),\r
+            token = elem ? elem.innerText : null,\r
+            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
+            var newtoken = elem ? elem.innerText : null,\r
+                newHash = getHash();\r
 \r
             if (newtoken !== token) {\r
                 token = newtoken;\r
@@ -118,14 +121,14 @@ Ext.History = (function () {
          * @property\r
          */\r
         iframeId: 'x-history-frame',\r
-        \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
+         * @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
@@ -142,7 +145,20 @@ Ext.History = (function () {
             if (Ext.isIE) {\r
                 iframe = Ext.getDom(Ext.History.iframeId);\r
             }\r
-            this.addEvents('ready', 'change');\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
@@ -164,12 +180,15 @@ tabPanel.on('tabchange', function(tabPanel, tab){
          * 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
+        add: function (token, preventDup, suppressEvent) {\r
             if(preventDup !== false){\r
                 if(this.getToken() == token){\r
                     return true;\r
                 }\r
             }\r
+            if(suppressEvent){\r
+                ignoreNext = token;\r
+            }\r
             if (Ext.isIE) {\r
                 return updateIFrame(token);\r
             } else {\r