jssource/src_files/include/javascript/yui3/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: 3.0.0
   6 build: 1549
   7 */
   8 YUI.add('history', function(Y) {
   9
  10 /*global YUI */
  11
  12
  13 /**
  14  * The Browser History Utility provides the ability to use the back/forward
  15  * navigation buttons in a DHTML application. It also allows a DHTML
  16  * application to be bookmarked in a specific state.
  17  *
  18  * This utility requires the following static markup:
  19  *
  20  * &lt;iframe id="yui-history-iframe" src="path-to-real-asset-in-same-domain"&gt;&lt;/iframe&gt;
  21  * &lt;input id="yui-history-field" type="hidden"&gt;
  22  *
  23  * @module history
  24  */
  25
  26 /**
  27  * This class represents an instance of the browser history utility.
  28  * @class History
  29  * @constructor
  30  */
  31
  32         // Shortcuts, etc.
  33     var win = Y.config.win,
  34         doc = Y.config.doc,
  35
  36         encode = encodeURIComponent,
  37         decode = decodeURIComponent,
  38
  39         H, G,
  40
  41         // YUI Compressor helper...
  42         E_MISSING_OR_INVALID_ARG = 'Missing or invalid argument',
  43
  44         // Regular expression used to parse query strings and such.
  45         REGEXP = /([^=&]+)=([^&]*)/g,
  46
  47         // A few private variables...
  48         _useIFrame = false,
  49         _getHash,
  50
  51         /**
  52          * @event history:ready
  53          * @description Fires when the browser history utility is ready
  54          * @type Event.Custom
  55          */
  56         EV_HISTORY_READY = 'history:ready',
  57
  58         /**
  59          * @event history:globalStateChange
  60          * @description Fires when the global state of the page has changed (that is,
  61          *     when the state of at least one browser history module has changed)
  62          * @type Event.Custom
  63          */
  64         EV_HISTORY_GLOBAL_STATE_CHANGE = 'history:globalStateChange',
  65
  66         /**
  67          * @event history:moduleStateChange
  68          * @description Fires when the state of a history module object has changed
  69          * @type Event.Custom
  70          */
  71         EV_HISTORY_MODULE_STATE_CHANGE = 'history:moduleStateChange';
  72
  73
  74     if (!YUI.Env.history) {
  75
  76         YUI.Env.history = G = {
  77
  78             // Flag used to tell whether the history utility is ready to be used.
  79             ready: false,
  80
  81             // List of registered modules.
  82             _modules: [],
  83
  84             // INPUT field (with type="hidden" or type="text") or TEXTAREA.
  85             // This field keeps the value of the initial state, current state
  86             // the list of all states across pages within a single browser session.
  87             _stateField: null,
  88
  89             // Hidden IFrame used to store the browsing history on IE6/7.
  90             _historyIFrame: null
  91         };
  92
  93     }
  94
  95     /**
  96      * Returns the portion of the hash after the '#' symbol.
  97      * @method _getHash
  98      * @return {string} The hash portion of the document's location
  99      * @private
 100      */
 101     if (Y.UA.gecko) {
 102         // We branch at runtime for Gecko since window.location.hash in Gecko
 103         // returns a decoded string, and we want all encoding untouched.
 104         _getHash = function () {
 105             var m = /#(.*)$/.exec(win.location.href);
 106             return m && m[1] ? m[1] : '';
 107         };
 108     } else {
 109         _getHash = function () {
 110             return win.location.hash.substr(1);
 111         };
 112     }
 113
 114     /**
 115      * Stores the initial state and current state for all registered modules
 116      * in the (hidden) form field specified during initialization.
 117      * @method _storeStates
 118      * @private
 119      */
 120     function _storeStates() {
 121         var initialStates = [], currentStates = [];
 122
 123         Y.Object.each(G._modules, function (module, moduleId) {
 124             initialStates.push(moduleId + '=' + module.initialState);
 125             currentStates.push(moduleId + '=' + module.currentState);
 126         });
 127
 128         G._stateField.set('value', initialStates.join('&') + '|' + currentStates.join('&'));
 129     }
 130
 131     /**
 132      * Sets the new currentState attribute of all modules depending on the new fully
 133      * qualified state. Also notifies the modules which current state has changed.
 134      * @method _handleFQStateChange
 135      * @param {string} fqstate fully qualified state
 136      * @private
 137      */
 138     function _handleFQStateChange(fqstate) {
 139         var m, states = [], globalStateChanged = false;
 140
 141         if (fqstate) {
 142
 143             REGEXP.lastIndex = 0;
 144             while ((m = REGEXP.exec(fqstate))) {
 145                 states[m[1]] = m[2];
 146             }
 147
 148             Y.Object.each(G._modules, function (module, moduleId) {
 149                 var currentState = states[moduleId];
 150
 151                 if (!currentState || module.currentState !== currentState) {
 152                     module.currentState = currentState || module.initialState;
 153                     module.fire(EV_HISTORY_MODULE_STATE_CHANGE, decode(module.currentState));
 154                     globalStateChanged = true;
 155                 }
 156             });
 157
 158         } else {
 159
 160             Y.Object.each(G._modules, function (module, moduleId) {
 161                 if (module.currentState !== module.initialState) {
 162                     module.currentState = module.initialState;
 163                     module.fire(EV_HISTORY_MODULE_STATE_CHANGE, decode(module.currentState));
 164                     globalStateChanged = true;
 165                 }
 166             });
 167         }
 168
 169         if (globalStateChanged) {
 170             H.fire(EV_HISTORY_GLOBAL_STATE_CHANGE);
 171         }
 172     }
 173
 174     /**
 175      * Update the IFrame with our new state.
 176      * @method _updateIFrame
 177      * @private
 178      * @return {boolean} true if successful. false otherwise.
 179      */
 180     function _updateIFrame(fqstate) {
 181         var html, doc;
 182
 183         html = '<html><body>' + fqstate + '</body></html>';
 184
 185         try {
 186             doc = G._historyIFrame.get('contentWindow.document');
 187             // TODO: The Node API should expose these methods in the very near future...
 188             doc.invoke('open');
 189             doc.invoke('write', html, '', '', '', ''); // see bug #2447937
 190             doc.invoke('close');
 191             return true;
 192         } catch (e) {
 193             return false;
 194         }
 195     }
 196
 197     /**
 198      * Periodically checks whether our internal IFrame is ready to be used
 199      * @method _checkIframeLoaded
 200      * @private
 201      */
 202     function _checkIframeLoaded() {
 203         var elem, fqstate, hash;
 204
 205         if (!G._historyIFrame.get('contentWindow.document')) {
 206             // Check again in 10 msec...
 207             setTimeout(_checkIframeLoaded, 10);
 208             return;
 209         }
 210
 211         // Periodically check whether a navigate operation has been
 212         // requested on the main window. This will happen when
 213         // History.navigate has been called or after the user
 214         // has hit the back/forward button.
 215         elem = G._historyIFrame.get('contentWindow.document.body');
 216         // We must use innerText, and not innerHTML because our string contains
 217         // the "&" character (which would end up being escaped as "&amp;") and
 218         // the string comparison would fail...
 219         fqstate = elem ? elem.get('innerText') : null;
 220
 221         hash = _getHash();
 222
 223         setInterval(function () {
 224             var newfqstate, states, newHash;
 225
 226             elem = G._historyIFrame.get('contentWindow.document.body');
 227             // See my comment above about using innerText instead of innerHTML...
 228             newfqstate = elem ? elem.get('innerText') : null;
 229
 230             newHash = _getHash();
 231
 232             if (newfqstate !== fqstate) {
 233
 234                 fqstate = newfqstate;
 235                 _handleFQStateChange(fqstate);
 236
 237                 if (!fqstate) {
 238                     states = [];
 239                     Y.Object.each(G._modules, function (module, moduleId) {
 240                         states.push(moduleId + '=' + module.initialState);
 241                     });
 242                     newHash = states.join('&');
 243                 } else {
 244                     newHash = fqstate;
 245                 }
 246
 247                 // Allow the state to be bookmarked by setting the top window's
 248                 // URL fragment identifier. Note that here, we are on IE < 8
 249                 // which does not touch the browser history when changing the
 250                 // hash (unlike all the other browsers).
 251                 win.location.hash = hash = newHash;
 252
 253                 _storeStates();
 254
 255             } else if (newHash !== hash) {
 256
 257                 // The hash has changed. The user might have clicked on a link,
 258                 // or modified the URL directly, or opened the same application
 259                 // bookmarked in a specific state using a bookmark. However, we
 260                 // know the hash change was not caused by a hit on the back or
 261                 // forward buttons, or by a call to navigate() (because it would
 262                 // have been handled above) We must handle these cases, which is
 263                 // why we also need to keep track of hash changes on IE!
 264
 265                 // Note that IE6 has some major issues with this kind of user
 266                 // interaction (the history stack gets completely messed up)
 267                 // but it seems to work fine on IE7.
 268
 269                 hash = newHash;
 270
 271                 // Now, store a new history entry. The following will cause the
 272                 // code above to execute, doing all the dirty work for us...
 273                 _updateIFrame(newHash);
 274             }
 275
 276         }, 50);
 277
 278         G.ready = true;
 279         H.fire(EV_HISTORY_READY);
 280     }
 281
 282     /**
 283      * Finish up the initialization of the browser utility library.
 284      * @method _initialize
 285      * @private
 286      */
 287     function _initialize() {
 288         var m, parts, moduleId, module, initialState, currentState, hash;
 289
 290         // Decode the content of our storage field...
 291         parts = G._stateField.get('value').split('|');
 292
 293         if (parts.length > 1) {
 294
 295             REGEXP.lastIndex = 0;
 296             while ((m = REGEXP.exec(parts[0]))) {
 297                 moduleId = m[1];
 298                 initialState = m[2];
 299                 module = G._modules[moduleId];
 300                 if (module) {
 301                     module.initialState = initialState;
 302                 }
 303             }
 304
 305             REGEXP.lastIndex = 0;
 306             while ((m = REGEXP.exec(parts[1]))) {
 307                 moduleId = m[1];
 308                 currentState = m[2];
 309                 module = G._modules[moduleId];
 310                 if (module) {
 311                     module.currentState = currentState;
 312                 }
 313             }
 314         }
 315
 316         // IE8 in IE7 mode defines window.onhashchange, but never fires it...
 317         if (!Y.Lang.isUndefined(win.onhashchange) &&
 318             (Y.Lang.isUndefined(doc.documentMode) || doc.documentMode > 7)) {
 319
 320             // The HTML5 way of handling DHTML history...
 321             win.onhashchange = function () {
 322                 var hash = _getHash();
 323                 _handleFQStateChange(hash);
 324                 _storeStates();
 325             };
 326
 327             G.ready = true;
 328             H.fire(EV_HISTORY_READY);
 329
 330         } else if (_useIFrame) {
 331
 332             // IE < 8 or IE8 in quirks mode or IE7 standards mode
 333             _checkIframeLoaded();
 334
 335         } else {
 336
 337             // Periodically check whether a navigate operation has been
 338             // requested on the main window. This will happen when
 339             // History.navigate has been called, or after the user
 340             // has hit the back/forward button.
 341
 342             // On Gecko and Opera, we just need to watch the hash...
 343             hash = _getHash();
 344
 345             setInterval(function () {
 346                 var newHash = _getHash();
 347                 if (newHash !== hash) {
 348                     hash = newHash;
 349                     _handleFQStateChange(hash);
 350                     _storeStates();
 351                 }
 352             }, 50);
 353
 354             G.ready = true;
 355             H.fire(EV_HISTORY_READY);
 356         }
 357     }
 358
 359
 360     H = {
 361
 362         /**
 363          * Registers a new module.
 364          * @method register
 365          * @param {string} moduleId Non-empty string uniquely identifying the
 366          *     module you wish to register.
 367          * @param {string} initialState The initial state of the specified
 368          *     module corresponding to its earliest history entry.
 369          * @return {History.Module} The newly registered module
 370          */
 371         register: function (moduleId, initialState) {
 372             var module;
 373
 374             if (!Y.Lang.isString(moduleId) || Y.Lang.trim(moduleId) === '' || !Y.Lang.isString(initialState)) {
 375                 throw new Error(E_MISSING_OR_INVALID_ARG);
 376             }
 377
 378             moduleId = encode(moduleId);
 379             initialState = encode(initialState);
 380
 381             if (G._modules[moduleId]) {
 382                 // The module seems to have already been registered.
 383                 return;
 384             }
 385
 386             // Note: A module CANNOT be registered once the browser history
 387             // utility has been initialized. This is related to reading and
 388             // writing state values from/to the input field. Relaxing this
 389             // rule would potentially create situations rather complicated
 390             // to deal with.
 391             if (G.ready) {
 392                 return null;
 393             }
 394
 395             module = new H.Module(moduleId, initialState);
 396             G._modules[moduleId] = module;
 397             return module;
 398         },
 399
 400         /**
 401          * Initializes the Browser History Manager. Call this method
 402          * from a script block located right after the opening body tag.
 403          * @method initialize
 404          * @param {string|HTML Element} stateField <input type="hidden"> used
 405          *     to store application states. Must be in the static markup.
 406          * @param {string|HTML Element} historyIFrame IFrame used to store
 407          *     the history (only required for IE6/7)
 408          * @public
 409          */
 410         initialize: function (stateField, historyIFrame) {
 411             var tagName, type;
 412
 413             if (G.ready) {
 414                 // The browser history utility has already been initialized.
 415                 return true;
 416             }
 417
 418             stateField = Y.get(stateField);
 419             if (!stateField) {
 420                 throw new Error(E_MISSING_OR_INVALID_ARG);
 421             }
 422
 423             tagName = stateField.get('tagName').toUpperCase();
 424             type = stateField.get('type');
 425
 426             if (tagName !== 'TEXTAREA' && (tagName !== 'INPUT' || type !== 'hidden' && type !== 'text')) {
 427                 throw new Error(E_MISSING_OR_INVALID_ARG);
 428             }
 429
 430             // IE < 8 or IE8 in quirks mode or IE7 standards mode
 431             if (Y.UA.ie && (Y.Lang.isUndefined(doc.documentMode) || doc.documentMode < 8)) {
 432                 _useIFrame = true;
 433                 historyIFrame = Y.get(historyIFrame);
 434                 if (!historyIFrame || historyIFrame.get('tagName').toUpperCase() !== 'IFRAME') {
 435                     throw new Error(E_MISSING_OR_INVALID_ARG);
 436                 }
 437             }
 438
 439             if (Y.UA.opera && !Y.Lang.isUndefined(win.history.navigationMode)) {
 440                 // Disable Opera's fast back/forward navigation mode and put
 441                 // it in compatible mode. This makes anchor-based history
 442                 // navigation work after the page has been navigated away
 443                 // from and re-activated, at the cost of slowing down
 444                 // back/forward navigation to and from that page.
 445                 win.history.navigationMode = 'compatible';
 446             }
 447
 448             G._stateField = stateField;
 449             G._historyIFrame = historyIFrame;
 450
 451             Y.on('domready', _initialize);
 452             return true;
 453         },
 454
 455         /**
 456          * Stores a new entry in the browser history by changing the state of a registered module.
 457          * @method navigate
 458          * @param {string} module Non-empty string representing your module.
 459          * @param {string} state String representing the new state of the specified module.
 460          * @return {boolean} Indicates whether the new state was successfully added to the history.
 461          * @public
 462          */
 463         navigate: function (moduleId, state) {
 464             var states;
 465
 466             if (!Y.Lang.isString(moduleId) || !Y.Lang.isString(state)) {
 467                 throw new Error(E_MISSING_OR_INVALID_ARG);
 468             }
 469
 470             // The ncoding of module id and state takes place in mutiNavigate.
 471             states = {};
 472             states[moduleId] = state;
 473
 474             return H.multiNavigate(states);
 475         },
 476
 477         /**
 478          * Stores a new entry in the browser history by changing the state
 479          * of several registered modules in one atomic operation.
 480          * @method multiNavigate
 481          * @param {object} states Associative array of module-state pairs to set simultaneously.
 482          * @return {boolean} Indicates whether the new state was successfully added to the history.
 483          * @public
 484          */
 485         multiNavigate: function (states) {
 486             var newStates = [], fqstate, globalStateChanged = false;
 487
 488             if (!G.ready) {
 489                 return false;
 490             }
 491
 492             Y.Object.each(G._modules, function (module, moduleId) {
 493                 var state, decodedModuleId = decode(moduleId);
 494
 495                 if (!states.hasOwnProperty(decodedModuleId)) {
 496                     // The caller did not wish to modify the state of this
 497                     // module. We must however include it in fqstate!
 498                     state = module.currentState;
 499                 } else {
 500                     state = encode(states[decodedModuleId]);
 501                     if (state !== module.upcomingState) {
 502                         module.upcomingState = state;
 503                         globalStateChanged = true;
 504                     }
 505                 }
 506
 507                 newStates.push(moduleId + '=' + state);
 508             });
 509
 510             if (!globalStateChanged) {
 511                 // Nothing changed, so don't do anything.
 512                 return false;
 513             }
 514
 515             fqstate = newStates.join('&');
 516
 517             if (_useIFrame) {
 518                 return _updateIFrame(fqstate);
 519             } else {
 520                 win.location.hash = fqstate;
 521                 return true;
 522             }
 523         },
 524
 525         /**
 526          * Returns the current state of the specified module.
 527          * @method getCurrentState
 528          * @param {string} moduleId Non-empty string representing your module.
 529          * @return {string} The current state of the specified module.
 530          * @public
 531          */
 532         getCurrentState: function (moduleId) {
 533             var module;
 534
 535             if (!Y.Lang.isString(moduleId)) {
 536                 throw new Error(E_MISSING_OR_INVALID_ARG);
 537             }
 538
 539             if (!G.ready) {
 540                 return null;
 541             }
 542
 543             moduleId = encode(moduleId);
 544             module = G._modules[moduleId];
 545             if (!module) {
 546                 return null;
 547             }
 548
 549             return decode(module.currentState);
 550         },
 551
 552         /**
 553          * Returns the state of a module according to the URL fragment
 554          * identifier. This method is useful to initialize your modules
 555          * if your application was bookmarked from a particular state.
 556          * @method getBookmarkedState
 557          * @param {string} moduleId Non-empty string representing your module.
 558          * @return {string} The bookmarked state of the specified module.
 559          * @public
 560          */
 561         getBookmarkedState: function (moduleId) {
 562             var m, i, h;
 563
 564             if (!Y.Lang.isString(moduleId)) {
 565                 throw new Error(E_MISSING_OR_INVALID_ARG);
 566             }
 567
 568             moduleId = encode(moduleId);
 569
 570             // Use location.href instead of location.hash which is already
 571             // URL-decoded, which creates problems if the state value
 572             // contained special characters...
 573             h = win.location.href;
 574             i = h.indexOf('#');
 575
 576             if (i >= 0) {
 577                 h = h.substr(i + 1);
 578                 REGEXP.lastIndex = 0;
 579                 while ((m = REGEXP.exec(h))) {
 580                     if (m[1] === moduleId) {
 581                         return decode(m[2]);
 582                     }
 583                 }
 584             }
 585
 586             return null;
 587         },
 588
 589         /**
 590          * Returns the value of the specified query string parameter.
 591          * This method is not used internally by the Browser History Manager.
 592          * However, it is provided here as a helper since many applications
 593          * using the Browser History Manager will want to read the value of
 594          * url parameters to initialize themselves.
 595          * @method getQueryStringParameter
 596          * @param {string} paramName Name of the parameter we want to look up.
 597          * @param {string} queryString Optional URL to look at. If not specified,
 598          *     this method uses the URL in the address bar.
 599          * @return {string} The value of the specified parameter, or null.
 600          * @public
 601          */
 602         getQueryStringParameter: function (paramName, url) {
 603             var m, q, i;
 604
 605             url = url || win.location.href;
 606
 607             i = url.indexOf('?');
 608             q = i >= 0 ? url.substr(i + 1) : url;
 609
 610             // Remove the hash if any
 611             i = q.lastIndexOf('#');
 612             q = i >= 0 ? q.substr(0, i) : q;
 613
 614             REGEXP.lastIndex = 0;
 615             while ((m = REGEXP.exec(q))) {
 616                 if (m[1] === paramName) {
 617                     return decode(m[2]);
 618                 }
 619             }
 620
 621             return null;
 622         }
 623     };
 624
 625
 626     // Make Y.History an event target
 627     Y.mix(H, Y.Event.Target.prototype);
 628     Y.Event.Target.call(H);
 629
 630
 631     /**
 632      * This class represents a browser history module.
 633      * @class History.Module
 634      * @constructor
 635      * @param id {String} the module identifier
 636      * @param initialState {String} the module's initial state
 637      */
 638     H.Module = function (id, initialState) {
 639
 640         Y.Event.Target.call(this);
 641
 642         /**
 643          * The module identifier
 644          * @type String
 645          * @final
 646          */
 647         this.id = id;
 648
 649         /**
 650          * The module's initial state
 651          * @type String
 652          * @final
 653          */
 654         this.initialState = initialState;
 655
 656         /**
 657          * The module's current state
 658          * @type String
 659          * @final
 660          */
 661         this.currentState = initialState;
 662
 663         /**
 664          * The module's upcoming state. There can be a slight delay between the
 665          * time a state is changed, and the time a state change is detected.
 666          * This property allows us to not fire the module state changed event
 667          * multiple times, making client code simpler.
 668          * @type String
 669          * @private
 670          * @final
 671          */
 672         this.upcomingState = initialState;
 673     };
 674
 675     Y.mix(H.Module, Y.Event.Target, false, null, 1);
 676
 677     Y.History = H;
 678
 679
 680 }, '3.0.0' ,{skinnable:false, use:['event', 'node']});