Upgrade to ExtJS 4.0.7 - Released 10/19/2011
[extjs.git] / docs / source / History.html
index 56e847b..62cc441 100644 (file)
@@ -3,8 +3,8 @@
 <head>
   <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
   <title>The source code</title>
-  <link href="../prettify/prettify.css" type="text/css" rel="stylesheet" />
-  <script type="text/javascript" src="../prettify/prettify.js"></script>
+  <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>
 <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;
-
- * @markdown
+ *
+ * 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', {
@@ -47,7 +46,7 @@ Ext.define('Ext.util.History', {
     mixins: {
         observable: 'Ext.util.Observable'
     },
-    
+
     constructor: function() {
         var me = this;
         me.oldIEMode = Ext.isIE6 || Ext.isIE7 || !Ext.isStrict &amp;&amp; Ext.isIE8;
@@ -56,18 +55,18 @@ Ext.define('Ext.util.History', {
         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;
@@ -75,8 +74,8 @@ Ext.define('Ext.util.History', {
     },
 
     updateIFrame: function(token) {
-        var html = '&lt;html&gt;&lt;body&gt;&lt;div id=&quot;state&quot;&gt;' + 
-                    Ext.util.Format.htmlEncode(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 {
@@ -93,17 +92,17 @@ Ext.define('Ext.util.History', {
     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,
@@ -121,17 +120,17 @@ Ext.define('Ext.util.History', {
                     oldHash = newHash;
                     me.updateIFrame(newHash);
                 }
-            }, 
+            },
             interval: 50,
             scope: me
         });
         me.ready = true;
-        me.fireEvent('ready', me);            
+        me.fireEvent('ready', me);
     },
 
     startUp: function () {
         var me = this;
-        
+
         me.currentToken = me.hiddenField.value || this.getHash();
 
         if (me.oldIEMode) {
@@ -153,7 +152,7 @@ Ext.define('Ext.util.History', {
             me.ready = true;
             me.fireEvent('ready', me);
         }
-        
+
     },
 
 <span id='Ext-util-History-property-fieldId'>    /**
@@ -173,29 +172,29 @@ Ext.define('Ext.util.History', {
 </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 (&lt;code&gt;this&lt;/code&gt; reference) in which the callback is executed. Defaults to the browser window.
+     * @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
@@ -210,7 +209,7 @@ Ext.define('Ext.util.History', {
              */
             'change'
         );
-        
+
         if (onReady) {
             me.on('ready', onReady, scope, {single: true});
         }
@@ -219,28 +218,28 @@ Ext.define('Ext.util.History', {
 
 <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 specifc history
-     * state of that component.  Example usage:
-     * &lt;pre&gt;&lt;code&gt;
-// Handle tab changes on a TabPanel
-tabPanel.on('tabchange', function(tabPanel, tab){
-Ext.History.add(tabPanel.id + ':' + tab.id);
-});
-&lt;/code&gt;&lt;/pre&gt;
+     * 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 When true, if the passed token matches the current token
+     * @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 (defaults to true).
+     * 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 {