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

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