include/javascript/yui/build/history/history.js

   1 /*
   2 Copyright (c) 2009, Yahoo! Inc. All rights reserved.
   3 Code licensed under the BSD License:
   4 http://developer.yahoo.net/yui/license.txt
   5 version: 2.8.0r4
   6 */
   7 /**
   8  * The Browser History Manager provides the ability to use the back/forward
   9  * navigation buttons in a DHTML application. It also allows a DHTML
  10  * application to be bookmarked in a specific state.
  11  *
  12  * This library requires the following static markup:
  13  *
  14  * &lt;iframe id="yui-history-iframe" src="path-to-real-asset-in-same-domain"&gt;&lt;/iframe&gt;
  15  * &lt;input id="yui-history-field" type="hidden"&gt;
  16  *
  17  * @module history
  18  * @requires yahoo,event
  19  * @namespace YAHOO.util
  20  * @title Browser History Manager
  21  */
  22
  23 /**
  24  * The History class provides the ability to use the back/forward navigation
  25  * buttons in a DHTML application. It also allows a DHTML application to
  26  * be bookmarked in a specific state.
  27  *
  28  * @class History
  29  * @constructor
  30  */
  31 YAHOO.util.History = (function () {
  32
  33     /**
  34      * Our hidden IFrame used to store the browsing history.
  35      *
  36      * @property _histFrame
  37      * @type HTMLIFrameElement
  38      * @default null
  39      * @private
  40      */
  41     var _histFrame = null;
  42
  43     /**
  44      * INPUT field (with type="hidden" or type="text") or TEXTAREA.
  45      * This field keeps the value of the initial state, current state
  46      * the list of all states across pages within a single browser session.
  47      *
  48      * @property _stateField
  49      * @type HTMLInputElement|HTMLTextAreaElement
  50      * @default null
  51      * @private
  52      */
  53     var _stateField = null;
  54
  55     /**
  56      * Flag used to tell whether YAHOO.util.History.initialize has been called.
  57      *
  58      * @property _initialized
  59      * @type boolean
  60      * @default false
  61      * @private
  62      */
  63     var _initialized = false;
  64
  65     /**
  66      * List of registered modules.
  67      *
  68      * @property _modules
  69      * @type array
  70      * @default []
  71      * @private
  72      */
  73     var _modules = [];
  74
  75     /**
  76      * List of fully qualified states. This is used only by Safari.
  77      *
  78      * @property _fqstates
  79      * @type array
  80      * @default []
  81      * @private
  82      */
  83     var _fqstates = [];
  84
  85     /**
  86      * location.hash is a bit buggy on Opera. I have seen instances where
  87      * navigating the history using the back/forward buttons, and hence
  88      * changing the URL, would not change location.hash. That's ok, the
  89      * implementation of an equivalent is trivial.
  90      *
  91      * @method _getHash
  92      * @return {string} The hash portion of the document's location
  93      * @private
  94      */
  95     function _getHash() {
  96         var i, href;
  97         href = top.location.href;
  98         i = href.indexOf("#");
  99         return i >= 0 ? href.substr(i + 1) : null;
 100     }
 101
 102     /**
 103      * Stores all the registered modules' initial state and current state.
 104      * On Safari, we also store all the fully qualified states visited by
 105      * the application within a single browser session. The storage takes
 106      * place in the form field specified during initialization.
 107      *
 108      * @method _storeStates
 109      * @private
 110      */
 111     function _storeStates() {
 112
 113         var moduleName, moduleObj, initialStates = [], currentStates = [];
 114
 115         for (moduleName in _modules) {
 116             if (YAHOO.lang.hasOwnProperty(_modules, moduleName)) {
 117                 moduleObj = _modules[moduleName];
 118                 initialStates.push(moduleName + "=" + moduleObj.initialState);
 119                 currentStates.push(moduleName + "=" + moduleObj.currentState);
 120             }
 121         }
 122
 123         _stateField.value = initialStates.join("&") + "|" + currentStates.join("&");
 124
 125         if (YAHOO.env.ua.webkit) {
 126             _stateField.value += "|" + _fqstates.join(",");
 127         }
 128     }
 129
 130     /**
 131      * Sets the new currentState attribute of all modules depending on the new
 132      * fully qualified state. Also notifies the modules which current state has
 133      * changed.
 134      *
 135      * @method _handleFQStateChange
 136      * @param {string} fqstate Fully qualified state
 137      * @private
 138      */
 139     function _handleFQStateChange(fqstate) {
 140
 141         var i, len, moduleName, moduleObj, modules, states, tokens, currentState;
 142
 143         if (!fqstate) {
 144             // Notifies all modules
 145             for (moduleName in _modules) {
 146                 if (YAHOO.lang.hasOwnProperty(_modules, moduleName)) {
 147                     moduleObj = _modules[moduleName];
 148                     moduleObj.currentState = moduleObj.initialState;
 149                     moduleObj.onStateChange(unescape(moduleObj.currentState));
 150                 }
 151             }
 152             return;
 153         }
 154
 155         modules = [];
 156         states = fqstate.split("&");
 157         for (i = 0, len = states.length; i < len; i++) {
 158             tokens = states[i].split("=");
 159             if (tokens.length === 2) {
 160                 moduleName = tokens[0];
 161                 currentState = tokens[1];
 162                 modules[moduleName] = currentState;
 163             }
 164         }
 165
 166         for (moduleName in _modules) {
 167             if (YAHOO.lang.hasOwnProperty(_modules, moduleName)) {
 168                 moduleObj = _modules[moduleName];
 169                 currentState = modules[moduleName];
 170                 if (!currentState || moduleObj.currentState !== currentState) {
 171                     moduleObj.currentState = currentState || moduleObj.initialState;
 172                     moduleObj.onStateChange(unescape(moduleObj.currentState));
 173                 }
 174             }
 175         }
 176     }
 177
 178     /**
 179      * Update the IFrame with our new state.
 180      *
 181      * @method _updateIFrame
 182      * @private
 183      * @return {boolean} true if successful. false otherwise.
 184      */
 185     function _updateIFrame (fqstate) {
 186
 187         var html, doc;
 188
 189         html = '<html><body><div id="state">' + fqstate + '</div></body></html>';
 190
 191         try {
 192             doc = _histFrame.contentWindow.document;
 193             doc.open();
 194             doc.write(html);
 195             doc.close();
 196             return true;
 197         } catch (e) {
 198             return false;
 199         }
 200     }
 201
 202     /**
 203      * Periodically checks whether our internal IFrame is ready to be used.
 204      *
 205      * @method _checkIframeLoaded
 206      * @private
 207      */
 208     function _checkIframeLoaded() {
 209
 210         var doc, elem, fqstate, hash;
 211
 212         if (!_histFrame.contentWindow || !_histFrame.contentWindow.document) {
 213             // Check again in 10 msec...
 214             setTimeout(_checkIframeLoaded, 10);
 215             return;
 216         }
 217
 218         // Start the thread that will have the responsibility to
 219         // periodically check whether a navigate operation has been
 220         // requested on the main window. This will happen when
 221         // YAHOO.util.History.navigate has been called or after
 222         // the user has hit the back/forward button.
 223
 224         doc = _histFrame.contentWindow.document;
 225         elem = doc.getElementById("state");
 226         // We must use innerText, and not innerHTML because our string contains
 227         // the "&" character (which would end up being escaped as "&amp;") and
 228         // the string comparison would fail...
 229         fqstate = elem ? elem.innerText : null;
 230
 231         hash = _getHash();
 232
 233         setInterval(function () {
 234
 235             var newfqstate, states, moduleName, moduleObj, newHash, historyLength;
 236
 237             doc = _histFrame.contentWindow.document;
 238             elem = doc.getElementById("state");
 239             // See my comment above about using innerText instead of innerHTML...
 240             newfqstate = elem ? elem.innerText : null;
 241
 242             newHash = _getHash();
 243
 244             if (newfqstate !== fqstate) {
 245
 246                 fqstate = newfqstate;
 247                 _handleFQStateChange(fqstate);
 248
 249                 if (!fqstate) {
 250                     states = [];
 251                     for (moduleName in _modules) {
 252                         if (YAHOO.lang.hasOwnProperty(_modules, moduleName)) {
 253                             moduleObj = _modules[moduleName];
 254                             states.push(moduleName + "=" + moduleObj.initialState);
 255                         }
 256                     }
 257                     newHash = states.join("&");
 258                 } else {
 259                     newHash = fqstate;
 260                 }
 261
 262                 // Allow the state to be bookmarked by setting the top window's
 263                 // URL fragment identifier. Note that here, we are on IE, and
 264                 // IE does not touch the browser history when setting the hash
 265                 // (unlike all the other browsers). I used to write:
 266                 //     top.location.replace( "#" + hash );
 267                 // but this had a side effect when the page was not the top frame.
 268                 top.location.hash = newHash;
 269                 hash = newHash;
 270
 271                 _storeStates();
 272
 273             } else if (newHash !== hash) {
 274
 275                 // The hash has changed. The user might have clicked on a link,
 276                 // or modified the URL directly, or opened the same application
 277                 // bookmarked in a specific state using a bookmark. However, we
 278                 // know the hash change was not caused by a hit on the back or
 279                 // forward buttons, or by a call to navigate() (because it would
 280                 // have been handled above) We must handle these cases, which is
 281                 // why we also need to keep track of hash changes on IE!
 282
 283                 // Note that IE6 has some major issues with this kind of user
 284                 // interaction (the history stack gets completely messed up)
 285                 // but it seems to work fine on IE7.
 286
 287                 hash = newHash;
 288
 289                 // Now, store a new history entry. The following will cause the
 290                 // code above to execute, doing all the dirty work for us...
 291                 _updateIFrame(newHash);
 292             }
 293
 294         }, 50);
 295
 296         _initialized = true;
 297         YAHOO.util.History.onLoadEvent.fire();
 298     }
 299
 300     /**
 301      * Finish up the initialization of the Browser History Manager.
 302      *
 303      * @method _initialize
 304      * @private
 305      */
 306     function _initialize() {
 307
 308         var i, len, parts, tokens, moduleName, moduleObj, initialStates, initialState, currentStates, currentState, counter, hash;
 309
 310         // Decode the content of our storage field...
 311         parts = _stateField.value.split("|");
 312
 313         if (parts.length > 1) {
 314
 315             initialStates = parts[0].split("&");
 316             for (i = 0, len = initialStates.length; i < len; i++) {
 317                 tokens = initialStates[i].split("=");
 318                 if (tokens.length === 2) {
 319                     moduleName = tokens[0];
 320                     initialState = tokens[1];
 321                     moduleObj = _modules[moduleName];
 322                     if (moduleObj) {
 323                         moduleObj.initialState = initialState;
 324                     }
 325                 }
 326             }
 327
 328             currentStates = parts[1].split("&");
 329             for (i = 0, len = currentStates.length; i < len; i++) {
 330                 tokens = currentStates[i].split("=");
 331                 if (tokens.length >= 2) {
 332                     moduleName = tokens[0];
 333                     currentState = tokens[1];
 334                     moduleObj = _modules[moduleName];
 335                     if (moduleObj) {
 336                         moduleObj.currentState = currentState;
 337                     }
 338                 }
 339             }
 340         }
 341
 342         if (parts.length > 2) {
 343             _fqstates = parts[2].split(",");
 344         }
 345
 346         if (YAHOO.env.ua.ie) {
 347
 348             if (typeof document.documentMode === "undefined" || document.documentMode < 8) {
 349
 350                 // IE < 8 or IE8 in quirks mode or IE7 standards mode
 351                 _checkIframeLoaded();
 352
 353             } else {
 354
 355                 // IE8 in IE8 standards mode
 356                 YAHOO.util.Event.on(top, "hashchange",
 357                     function () {
 358                         var hash = _getHash();
 359                         _handleFQStateChange(hash);
 360                         _storeStates();
 361                     });
 362
 363                 _initialized = true;
 364                 YAHOO.util.History.onLoadEvent.fire();
 365
 366             }
 367
 368         } else {
 369
 370             // Start the thread that will have the responsibility to
 371             // periodically check whether a navigate operation has been
 372             // requested on the main window. This will happen when
 373             // YAHOO.util.History.navigate has been called or after
 374             // the user has hit the back/forward button.
 375
 376             // On Safari 1.x and 2.0, the only way to catch a back/forward
 377             // operation is to watch history.length... We basically exploit
 378             // what I consider to be a bug (history.length is not supposed
 379             // to change when going back/forward in the history...) This is
 380             // why, in the following thread, we first compare the hash,
 381             // because the hash thing will be fixed in the next major
 382             // version of Safari. So even if they fix the history.length
 383             // bug, all this will still work!
 384             counter = history.length;
 385
 386             // On Gecko and Opera, we just need to watch the hash...
 387             hash = _getHash();
 388
 389             setInterval(function () {
 390
 391                 var state, newHash, newCounter;
 392
 393                 newHash = _getHash();
 394                 newCounter = history.length;
 395                 if (newHash !== hash) {
 396                     hash = newHash;
 397                     counter = newCounter;
 398                     _handleFQStateChange(hash);
 399                     _storeStates();
 400                 } else if (newCounter !== counter && YAHOO.env.ua.webkit) {
 401                     hash = newHash;
 402                     counter = newCounter;
 403                     state = _fqstates[counter - 1];
 404                     _handleFQStateChange(state);
 405                     _storeStates();
 406                 }
 407
 408             }, 50);
 409
 410             _initialized = true;
 411             YAHOO.util.History.onLoadEvent.fire();
 412         }
 413     }
 414
 415     return {
 416
 417         /**
 418          * Fired when the Browser History Manager is ready. If you subscribe to
 419          * this event after the Browser History Manager has been initialized,
 420          * it will not fire. Therefore, it is recommended to use the onReady
 421          * method instead.
 422          *
 423          * @event onLoadEvent
 424          * @see onReady
 425          */
 426         onLoadEvent: new YAHOO.util.CustomEvent("onLoad"),
 427
 428         /**
 429          * Executes the supplied callback when the Browser History Manager is
 430          * ready. This will execute immediately if called after the Browser
 431          * History Manager onLoad event has fired.
 432          *
 433          * @method onReady
 434          * @param {function} fn what to execute when the Browser History Manager is ready.
 435          * @param {object} obj an optional object to be passed back as a parameter to fn.
 436          * @param {boolean|object} overrideContext If true, the obj passed in becomes fn's execution scope.
 437          * @see onLoadEvent
 438          */
 439         onReady: function (fn, obj, overrideContext) {
 440
 441             if (_initialized) {
 442
 443                 setTimeout(function () {
 444                     var ctx = window;
 445                     if (overrideContext) {
 446                         if (overrideContext === true) {
 447                             ctx = obj;
 448                         } else {
 449                             ctx = overrideContext;
 450                         }
 451                     }
 452                     fn.call(ctx, "onLoad", [], obj);
 453                 }, 0);
 454
 455             } else {
 456
 457                 YAHOO.util.History.onLoadEvent.subscribe(fn, obj, overrideContext);
 458
 459             }
 460         },
 461
 462         /**
 463          * Registers a new module.
 464          *
 465          * @method register
 466          * @param {string} module Non-empty string uniquely identifying the
 467          *     module you wish to register.
 468          * @param {string} initialState The initial state of the specified
 469          *     module corresponding to its earliest history entry.
 470          * @param {function} onStateChange Callback called when the
 471          *     state of the specified module has changed.
 472          * @param {object} obj An arbitrary object that will be passed as a
 473          *     parameter to the handler.
 474          * @param {boolean} overrideContext If true, the obj passed in becomes the
 475          *     execution scope of the listener.
 476          */
 477         register: function (module, initialState, onStateChange, obj, overrideContext) {
 478
 479             var scope, wrappedFn;
 480
 481             if (typeof module !== "string" || YAHOO.lang.trim(module) === "" ||
 482                 typeof initialState !== "string" ||
 483                 typeof onStateChange !== "function") {
 484                 throw new Error("Missing or invalid argument");
 485             }
 486
 487             if (_modules[module]) {
 488                 // Here, we used to throw an exception. However, users have
 489                 // complained about this behavior, so we now just return.
 490                 return;
 491             }
 492
 493             // Note: A module CANNOT be registered after calling
 494             // YAHOO.util.History.initialize. Indeed, we set the initial state
 495             // of each registered module in YAHOO.util.History.initialize.
 496             // If you could register a module after initializing the Browser
 497             // History Manager, you would not read the correct state using
 498             // YAHOO.util.History.getCurrentState when coming back to the
 499             // page using the back button.
 500             if (_initialized) {
 501                 throw new Error("All modules must be registered before calling YAHOO.util.History.initialize");
 502             }
 503
 504             // Make sure the strings passed in do not contain our separators "," and "|"
 505             module = escape(module);
 506             initialState = escape(initialState);
 507
 508             // If the user chooses to override the scope, we use the
 509             // custom object passed in as the execution scope.
 510             scope = null;
 511             if (overrideContext === true) {
 512                 scope = obj;
 513             } else {
 514                 scope = overrideContext;
 515             }
 516
 517             wrappedFn = function (state) {
 518                 return onStateChange.call(scope, state, obj);
 519             };
 520
 521             _modules[module] = {
 522                 name: module,
 523                 initialState: initialState,
 524                 currentState: initialState,
 525                 onStateChange: wrappedFn
 526             };
 527         },
 528
 529         /**
 530          * Initializes the Browser History Manager. Call this method
 531          * from a script block located right after the opening body tag.
 532          *
 533          * @method initialize
 534          * @param {string|HTML Element} stateField <input type="hidden"> used
 535          *     to store application states. Must be in the static markup.
 536          * @param {string|HTML Element} histFrame IFrame used to store
 537          *     the history (only required on Internet Explorer)
 538          * @public
 539          */
 540         initialize: function (stateField, histFrame) {
 541
 542             if (_initialized) {
 543                 // The browser history manager has already been initialized.
 544                 return;
 545             }
 546
 547             if (YAHOO.env.ua.opera && typeof history.navigationMode !== "undefined") {
 548                 // Disable Opera's fast back/forward navigation mode and puts
 549                 // it in compatible mode. This makes anchor-based history
 550                 // navigation work after the page has been navigated away
 551                 // from and re-activated, at the cost of slowing down
 552                 // back/forward navigation to and from that page.
 553                 history.navigationMode = "compatible";
 554             }
 555
 556             if (typeof stateField === "string") {
 557                 stateField = document.getElementById(stateField);
 558             }
 559
 560             if (!stateField ||
 561                 stateField.tagName.toUpperCase() !== "TEXTAREA" &&
 562                 (stateField.tagName.toUpperCase() !== "INPUT" ||
 563                  stateField.type !== "hidden" &&
 564                  stateField.type !== "text")) {
 565                 throw new Error("Missing or invalid argument");
 566             }
 567
 568             _stateField = stateField;
 569
 570             // IE < 8 or IE8 in quirks mode or IE7 standards mode
 571             if (YAHOO.env.ua.ie && (typeof document.documentMode === "undefined" || document.documentMode < 8)) {
 572
 573                 if (typeof histFrame === "string") {
 574                     histFrame = document.getElementById(histFrame);
 575                 }
 576
 577                 if (!histFrame || histFrame.tagName.toUpperCase() !== "IFRAME") {
 578                     throw new Error("Missing or invalid argument");
 579                 }
 580
 581                 _histFrame = histFrame;
 582             }
 583
 584             // Note that the event utility MUST be included inline in the page.
 585             // If it gets loaded later (which you may want to do to improve the
 586             // loading speed of your site), the onDOMReady event never fires,
 587             // and the history library never gets fully initialized.
 588             YAHOO.util.Event.onDOMReady(_initialize);
 589         },
 590
 591         /**
 592          * Call this method when you want to store a new entry in the browser's history.
 593          *
 594          * @method navigate
 595          * @param {string} module Non-empty string representing your module.
 596          * @param {string} state String representing the new state of the specified module.
 597          * @return {boolean} Indicates whether the new state was successfully added to the history.
 598          * @public
 599          */
 600         navigate: function (module, state) {
 601
 602             var states;
 603
 604             if (typeof module !== "string" || typeof state !== "string") {
 605                 throw new Error("Missing or invalid argument");
 606             }
 607
 608             states = {};
 609             states[module] = state;
 610
 611             return YAHOO.util.History.multiNavigate(states);
 612         },
 613
 614         /**
 615          * Call this method when you want to store a new entry in the browser's history.
 616          *
 617          * @method multiNavigate
 618          * @param {object} states Associative array of module-state pairs to set simultaneously.
 619          * @return {boolean} Indicates whether the new state was successfully added to the history.
 620          * @public
 621          */
 622         multiNavigate: function (states) {
 623
 624             var currentStates, moduleName, moduleObj, currentState, fqstate;
 625
 626             if (typeof states !== "object") {
 627                 throw new Error("Missing or invalid argument");
 628             }
 629
 630             if (!_initialized) {
 631                 throw new Error("The Browser History Manager is not initialized");
 632             }
 633
 634             for (moduleName in states) {
 635                 if (!_modules[moduleName]) {
 636                     throw new Error("The following module has not been registered: " + moduleName);
 637                 }
 638             }
 639
 640             // Generate our new full state string mod1=xxx&mod2=yyy
 641             currentStates = [];
 642
 643             for (moduleName in _modules) {
 644                 if (YAHOO.lang.hasOwnProperty(_modules, moduleName)) {
 645                     moduleObj = _modules[moduleName];
 646                     if (YAHOO.lang.hasOwnProperty(states, moduleName)) {
 647                         currentState = states[unescape(moduleName)];
 648                     } else {
 649                         currentState = unescape(moduleObj.currentState);
 650                     }
 651
 652                     // Make sure the strings passed in do not contain our separators "," and "|"
 653                     moduleName = escape(moduleName);
 654                     currentState = escape(currentState);
 655
 656                     currentStates.push(moduleName + "=" + currentState);
 657                 }
 658             }
 659
 660             fqstate = currentStates.join("&");
 661
 662             if (YAHOO.env.ua.ie && (typeof document.documentMode === "undefined" || document.documentMode < 8)) {
 663
 664                 return _updateIFrame(fqstate);
 665
 666             } else {
 667
 668                 // Known bug: On Safari 1.x and 2.0, if you have tab browsing
 669                 // enabled, Safari will show an endless loading icon in the
 670                 // tab. This has apparently been fixed in recent WebKit builds.
 671                 // One work around found by Dav Glass is to submit a form that
 672                 // points to the same document. This indeed works on Safari 1.x
 673                 // and 2.0 but creates bigger problems on WebKit. So for now,
 674                 // we'll consider this an acceptable bug, and hope that Apple
 675                 // comes out with their next version of Safari very soon.
 676                 top.location.hash = fqstate;
 677                 if (YAHOO.env.ua.webkit) {
 678                     // The following two lines are only useful for Safari 1.x
 679                     // and 2.0. Recent nightly builds of WebKit do not require
 680                     // that, but unfortunately, it is not easy to differentiate
 681                     // between the two. Once Safari 2.0 departs the A-grade
 682                     // list, we can remove the following two lines...
 683                     _fqstates[history.length] = fqstate;
 684                     _storeStates();
 685                 }
 686
 687                 return true;
 688
 689             }
 690         },
 691
 692         /**
 693          * Returns the current state of the specified module.
 694          *
 695          * @method getCurrentState
 696          * @param {string} module Non-empty string representing your module.
 697          * @return {string} The current state of the specified module.
 698          * @public
 699          */
 700         getCurrentState: function (module) {
 701
 702             var moduleObj;
 703
 704             if (typeof module !== "string") {
 705                 throw new Error("Missing or invalid argument");
 706             }
 707
 708             if (!_initialized) {
 709                 throw new Error("The Browser History Manager is not initialized");
 710             }
 711
 712             moduleObj = _modules[module];
 713             if (!moduleObj) {
 714                 throw new Error("No such registered module: " + module);
 715             }
 716
 717             return unescape(moduleObj.currentState);
 718         },
 719
 720         /**
 721          * Returns the state of a module according to the URL fragment
 722          * identifier. This method is useful to initialize your modules
 723          * if your application was bookmarked from a particular state.
 724          *
 725          * @method getBookmarkedState
 726          * @param {string} module Non-empty string representing your module.
 727          * @return {string} The bookmarked state of the specified module.
 728          * @public
 729          */
 730         getBookmarkedState: function (module) {
 731
 732             var i, len, idx, hash, states, tokens, moduleName;
 733
 734             if (typeof module !== "string") {
 735                 throw new Error("Missing or invalid argument");
 736             }
 737
 738             // Use location.href instead of location.hash which is already
 739             // URL-decoded, which creates problems if the state value
 740             // contained special characters...
 741             idx = top.location.href.indexOf("#");
 742             if (idx >= 0) {
 743                 hash = top.location.href.substr(idx + 1);
 744                 states = hash.split("&");
 745                 for (i = 0, len = states.length; i < len; i++) {
 746                     tokens = states[i].split("=");
 747                     if (tokens.length === 2) {
 748                         moduleName = tokens[0];
 749                         if (moduleName === module) {
 750                             return unescape(tokens[1]);
 751                         }
 752                     }
 753                 }
 754             }
 755
 756             return null;
 757         },
 758
 759         /**
 760          * Returns the value of the specified query string parameter.
 761          * This method is not used internally by the Browser History Manager.
 762          * However, it is provided here as a helper since many applications
 763          * using the Browser History Manager will want to read the value of
 764          * url parameters to initialize themselves.
 765          *
 766          * @method getQueryStringParameter
 767          * @param {string} paramName Name of the parameter we want to look up.
 768          * @param {string} queryString Optional URL to look at. If not specified,
 769          *     this method uses the URL in the address bar.
 770          * @return {string} The value of the specified parameter, or null.
 771          * @public
 772          */
 773         getQueryStringParameter: function (paramName, url) {
 774
 775             var i, len, idx, queryString, params, tokens;
 776
 777             url = url || top.location.href;
 778
 779             idx = url.indexOf("?");
 780             queryString = idx >= 0 ? url.substr(idx + 1) : url;
 781
 782             // Remove the hash if any
 783             idx = queryString.lastIndexOf("#");
 784             queryString = idx >= 0 ? queryString.substr(0, idx) : queryString;
 785
 786             params = queryString.split("&");
 787
 788             for (i = 0, len = params.length; i < len; i++) {
 789                 tokens = params[i].split("=");
 790                 if (tokens.length >= 2) {
 791                     if (tokens[0] === paramName) {
 792                         return unescape(tokens[1]);
 793                     }
 794                 }
 795             }
 796
 797             return null;
 798         }
 799
 800     };
 801
 802 })();
 803 YAHOO.register("history", YAHOO.util.History, {version: "2.8.0r4", build: "2449"});