lib/yuilib/3.13.0/history-hash/history-hash-debug.js

   1 /*
   2 YUI 3.13.0 (build 508226d)
   3 Copyright 2013 Yahoo! Inc. All rights reserved.
   4 Licensed under the BSD License.
   5 http://yuilibrary.com/license/
   6 */
   7
   8 YUI.add('history-hash', function (Y, NAME) {
   9
  10 /**
  11  * Provides browser history management backed by
  12  * <code>window.location.hash</code>, as well as convenience methods for working
  13  * with the location hash and a synthetic <code>hashchange</code> event that
  14  * normalizes differences across browsers.
  15  *
  16  * @module history
  17  * @submodule history-hash
  18  * @since 3.2.0
  19  * @class HistoryHash
  20  * @extends HistoryBase
  21  * @constructor
  22  * @param {Object} config (optional) Configuration object. See the HistoryBase
  23  *   documentation for details.
  24  */
  25
  26 var HistoryBase = Y.HistoryBase,
  27     Lang        = Y.Lang,
  28     YArray      = Y.Array,
  29     YObject     = Y.Object,
  30     GlobalEnv   = YUI.namespace('Env.HistoryHash'),
  31
  32     SRC_HASH    = 'hash',
  33
  34     hashNotifiers,
  35     oldHash,
  36     oldUrl,
  37     win             = Y.config.win,
  38     useHistoryHTML5 = Y.config.useHistoryHTML5;
  39
  40 function HistoryHash() {
  41     HistoryHash.superclass.constructor.apply(this, arguments);
  42 }
  43
  44 Y.extend(HistoryHash, HistoryBase, {
  45     // -- Initialization -------------------------------------------------------
  46     _init: function (config) {
  47         var bookmarkedState = HistoryHash.parseHash();
  48
  49         // If an initialState was provided, merge the bookmarked state into it
  50         // (the bookmarked state wins).
  51         config = config || {};
  52
  53         this._initialState = config.initialState ?
  54                 Y.merge(config.initialState, bookmarkedState) : bookmarkedState;
  55
  56         // Subscribe to the synthetic hashchange event (defined below) to handle
  57         // changes.
  58         Y.after('hashchange', Y.bind(this._afterHashChange, this), win);
  59
  60         HistoryHash.superclass._init.apply(this, arguments);
  61     },
  62
  63     // -- Protected Methods ----------------------------------------------------
  64     _change: function (src, state, options) {
  65         // Stringify all values to ensure that comparisons don't fail after
  66         // they're coerced to strings in the location hash.
  67         YObject.each(state, function (value, key) {
  68             if (Lang.isValue(value)) {
  69                 state[key] = value.toString();
  70             }
  71         });
  72
  73         return HistoryHash.superclass._change.call(this, src, state, options);
  74     },
  75
  76     _storeState: function (src, newState) {
  77         var decode  = HistoryHash.decode,
  78             newHash = HistoryHash.createHash(newState);
  79
  80         HistoryHash.superclass._storeState.apply(this, arguments);
  81
  82         // Update the location hash with the changes, but only if the new hash
  83         // actually differs from the current hash (this avoids creating multiple
  84         // history entries for a single state).
  85         //
  86         // We always compare decoded hashes, since it's possible that the hash
  87         // could be set incorrectly to a non-encoded value outside of
  88         // HistoryHash.
  89         if (src !== SRC_HASH && decode(HistoryHash.getHash()) !== decode(newHash)) {
  90             HistoryHash[src === HistoryBase.SRC_REPLACE ? 'replaceHash' : 'setHash'](newHash);
  91         }
  92     },
  93
  94     // -- Protected Event Handlers ---------------------------------------------
  95
  96     /**
  97      * Handler for hashchange events.
  98      *
  99      * @method _afterHashChange
 100      * @param {Event} e
 101      * @protected
 102      */
 103     _afterHashChange: function (e) {
 104         this._resolveChanges(SRC_HASH, HistoryHash.parseHash(e.newHash), {});
 105     }
 106 }, {
 107     // -- Public Static Properties ---------------------------------------------
 108     NAME: 'historyHash',
 109
 110     /**
 111      * Constant used to identify state changes originating from
 112      * <code>hashchange</code> events.
 113      *
 114      * @property SRC_HASH
 115      * @type String
 116      * @static
 117      * @final
 118      */
 119     SRC_HASH: SRC_HASH,
 120
 121     /**
 122      * <p>
 123      * Prefix to prepend when setting the hash fragment. For example, if the
 124      * prefix is <code>!</code> and the hash fragment is set to
 125      * <code>#foo=bar&baz=quux</code>, the final hash fragment in the URL will
 126      * become <code>#!foo=bar&baz=quux</code>. This can be used to help make an
 127      * Ajax application crawlable in accordance with Google's guidelines at
 128      * <a href="http://code.google.com/web/ajaxcrawling/">http://code.google.com/web/ajaxcrawling/</a>.
 129      * </p>
 130      *
 131      * <p>
 132      * Note that this prefix applies to all HistoryHash instances. It's not
 133      * possible for individual instances to use their own prefixes since they
 134      * all operate on the same URL.
 135      * </p>
 136      *
 137      * @property hashPrefix
 138      * @type String
 139      * @default ''
 140      * @static
 141      */
 142     hashPrefix: '',
 143
 144     // -- Protected Static Properties ------------------------------------------
 145
 146     /**
 147      * Regular expression used to parse location hash/query strings.
 148      *
 149      * @property _REGEX_HASH
 150      * @type RegExp
 151      * @protected
 152      * @static
 153      * @final
 154      */
 155     _REGEX_HASH: /([^\?#&=]+)=?([^&=]*)/g,
 156
 157     // -- Public Static Methods ------------------------------------------------
 158
 159     /**
 160      * Creates a location hash string from the specified object of key/value
 161      * pairs.
 162      *
 163      * @method createHash
 164      * @param {Object} params object of key/value parameter pairs
 165      * @return {String} location hash string
 166      * @static
 167      */
 168     createHash: function (params) {
 169         var encode = HistoryHash.encode,
 170             hash   = [];
 171
 172         YObject.each(params, function (value, key) {
 173             if (Lang.isValue(value)) {
 174                 hash.push(encode(key) + '=' + encode(value));
 175             }
 176         });
 177
 178         return hash.join('&');
 179     },
 180
 181     /**
 182      * Wrapper around <code>decodeURIComponent()</code> that also converts +
 183      * chars into spaces.
 184      *
 185      * @method decode
 186      * @param {String} string string to decode
 187      * @return {String} decoded string
 188      * @static
 189      */
 190     decode: function (string) {
 191         return decodeURIComponent(string.replace(/\+/g, ' '));
 192     },
 193
 194     /**
 195      * Wrapper around <code>encodeURIComponent()</code> that converts spaces to
 196      * + chars.
 197      *
 198      * @method encode
 199      * @param {String} string string to encode
 200      * @return {String} encoded string
 201      * @static
 202      */
 203     encode: function (string) {
 204         return encodeURIComponent(string).replace(/%20/g, '+');
 205     },
 206
 207     /**
 208      * Gets the raw (not decoded) current location hash, minus the preceding '#'
 209      * character and the hashPrefix (if one is set).
 210      *
 211      * @method getHash
 212      * @return {String} current location hash
 213      * @static
 214      */
 215     getHash: (Y.UA.gecko ? function () {
 216         // Gecko's window.location.hash returns a decoded string and we want all
 217         // encoding untouched, so we need to get the hash value from
 218         // window.location.href instead. We have to use UA sniffing rather than
 219         // feature detection, since the only way to detect this would be to
 220         // actually change the hash.
 221         var location = Y.getLocation(),
 222             matches  = /#(.*)$/.exec(location.href),
 223             hash     = matches && matches[1] || '',
 224             prefix   = HistoryHash.hashPrefix;
 225
 226         return prefix && hash.indexOf(prefix) === 0 ?
 227                     hash.replace(prefix, '') : hash;
 228     } : function () {
 229         var location = Y.getLocation(),
 230             hash     = location.hash.substring(1),
 231             prefix   = HistoryHash.hashPrefix;
 232
 233         // Slight code duplication here, but execution speed is of the essence
 234         // since getHash() is called every 50ms to poll for changes in browsers
 235         // that don't support native onhashchange. An additional function call
 236         // would add unnecessary overhead.
 237         return prefix && hash.indexOf(prefix) === 0 ?
 238                     hash.replace(prefix, '') : hash;
 239     }),
 240
 241     /**
 242      * Gets the current bookmarkable URL.
 243      *
 244      * @method getUrl
 245      * @return {String} current bookmarkable URL
 246      * @static
 247      */
 248     getUrl: function () {
 249         return location.href;
 250     },
 251
 252     /**
 253      * Parses a location hash string into an object of key/value parameter
 254      * pairs. If <i>hash</i> is not specified, the current location hash will
 255      * be used.
 256      *
 257      * @method parseHash
 258      * @param {String} hash (optional) location hash string
 259      * @return {Object} object of parsed key/value parameter pairs
 260      * @static
 261      */
 262     parseHash: function (hash) {
 263         var decode = HistoryHash.decode,
 264             i,
 265             len,
 266             match,
 267             matches,
 268             param,
 269             params = {},
 270             prefix = HistoryHash.hashPrefix,
 271             prefixIndex;
 272
 273         hash = Lang.isValue(hash) ? hash : HistoryHash.getHash();
 274
 275         if (prefix) {
 276             prefixIndex = hash.indexOf(prefix);
 277
 278             if (prefixIndex === 0 || (prefixIndex === 1 && hash.charAt(0) === '#')) {
 279                 hash = hash.replace(prefix, '');
 280             }
 281         }
 282
 283         matches = hash.match(HistoryHash._REGEX_HASH) || [];
 284
 285         for (i = 0, len = matches.length; i < len; ++i) {
 286             match = matches[i];
 287
 288             param = match.split('=');
 289
 290             if (param.length > 1) {
 291                 params[decode(param[0])] = decode(param[1]);
 292             } else {
 293                 params[decode(match)] = '';
 294             }
 295         }
 296
 297         return params;
 298     },
 299
 300     /**
 301      * Replaces the browser's current location hash with the specified hash
 302      * and removes all forward navigation states, without creating a new browser
 303      * history entry. Automatically prepends the <code>hashPrefix</code> if one
 304      * is set.
 305      *
 306      * @method replaceHash
 307      * @param {String} hash new location hash
 308      * @static
 309      */
 310     replaceHash: function (hash) {
 311         var location = Y.getLocation(),
 312             base     = location.href.replace(/#.*$/, '');
 313
 314         if (hash.charAt(0) === '#') {
 315             hash = hash.substring(1);
 316         }
 317
 318         location.replace(base + '#' + (HistoryHash.hashPrefix || '') + hash);
 319     },
 320
 321     /**
 322      * Sets the browser's location hash to the specified string. Automatically
 323      * prepends the <code>hashPrefix</code> if one is set.
 324      *
 325      * @method setHash
 326      * @param {String} hash new location hash
 327      * @static
 328      */
 329     setHash: function (hash) {
 330         var location = Y.getLocation();
 331
 332         if (hash.charAt(0) === '#') {
 333             hash = hash.substring(1);
 334         }
 335
 336         location.hash = (HistoryHash.hashPrefix || '') + hash;
 337     }
 338 });
 339
 340 // -- Synthetic hashchange Event -----------------------------------------------
 341
 342 // TODO: YUIDoc currently doesn't provide a good way to document synthetic DOM
 343 // events. For now, we're just documenting the hashchange event on the YUI
 344 // object, which is about the best we can do until enhancements are made to
 345 // YUIDoc.
 346
 347 /**
 348 Synthetic <code>window.onhashchange</code> event that normalizes differences
 349 across browsers and provides support for browsers that don't natively support
 350 <code>onhashchange</code>.
 351
 352 This event is provided by the <code>history-hash</code> module.
 353
 354 @example
 355
 356     YUI().use('history-hash', function (Y) {
 357       Y.on('hashchange', function (e) {
 358         // Handle hashchange events on the current window.
 359       }, Y.config.win);
 360     });
 361
 362 @event hashchange
 363 @param {EventFacade} e Event facade with the following additional
 364   properties:
 365
 366 <dl>
 367   <dt>oldHash</dt>
 368   <dd>
 369     Previous hash fragment value before the change.
 370   </dd>
 371
 372   <dt>oldUrl</dt>
 373   <dd>
 374     Previous URL (including the hash fragment) before the change.
 375   </dd>
 376
 377   <dt>newHash</dt>
 378   <dd>
 379     New hash fragment value after the change.
 380   </dd>
 381
 382   <dt>newUrl</dt>
 383   <dd>
 384     New URL (including the hash fragment) after the change.
 385   </dd>
 386 </dl>
 387 @for YUI
 388 @since 3.2.0
 389 **/
 390
 391 hashNotifiers = GlobalEnv._notifiers;
 392
 393 if (!hashNotifiers) {
 394     hashNotifiers = GlobalEnv._notifiers = [];
 395 }
 396
 397 Y.Event.define('hashchange', {
 398     on: function (node, subscriber, notifier) {
 399         // Ignore this subscription if the node is anything other than the
 400         // window or document body, since those are the only elements that
 401         // should support the hashchange event. Note that the body could also be
 402         // a frameset, but that's okay since framesets support hashchange too.
 403         if (node.compareTo(win) || node.compareTo(Y.config.doc.body)) {
 404             hashNotifiers.push(notifier);
 405         }
 406     },
 407
 408     detach: function (node, subscriber, notifier) {
 409         var index = YArray.indexOf(hashNotifiers, notifier);
 410
 411         if (index !== -1) {
 412             hashNotifiers.splice(index, 1);
 413         }
 414     }
 415 });
 416
 417 oldHash = HistoryHash.getHash();
 418 oldUrl  = HistoryHash.getUrl();
 419
 420 if (HistoryBase.nativeHashChange) {
 421     // Wrap the browser's native hashchange event if there's not already a
 422     // global listener.
 423     if (!GlobalEnv._hashHandle) {
 424         GlobalEnv._hashHandle = Y.Event.attach('hashchange', function (e) {
 425             var newHash = HistoryHash.getHash(),
 426                 newUrl  = HistoryHash.getUrl();
 427
 428             // Iterate over a copy of the hashNotifiers array since a subscriber
 429             // could detach during iteration and cause the array to be re-indexed.
 430             YArray.each(hashNotifiers.concat(), function (notifier) {
 431                 notifier.fire({
 432                     _event : e,
 433                     oldHash: oldHash,
 434                     oldUrl : oldUrl,
 435                     newHash: newHash,
 436                     newUrl : newUrl
 437                 });
 438             });
 439
 440             oldHash = newHash;
 441             oldUrl  = newUrl;
 442         }, win);
 443     }
 444 } else {
 445     // Begin polling for location hash changes if there's not already a global
 446     // poll running.
 447     if (!GlobalEnv._hashPoll) {
 448         GlobalEnv._hashPoll = Y.later(50, null, function () {
 449             var newHash = HistoryHash.getHash(),
 450                 facade, newUrl;
 451
 452             if (oldHash !== newHash) {
 453                 newUrl = HistoryHash.getUrl();
 454
 455                 facade = {
 456                     oldHash: oldHash,
 457                     oldUrl : oldUrl,
 458                     newHash: newHash,
 459                     newUrl : newUrl
 460                 };
 461
 462                 oldHash = newHash;
 463                 oldUrl  = newUrl;
 464
 465                 YArray.each(hashNotifiers.concat(), function (notifier) {
 466                     notifier.fire(facade);
 467                 });
 468             }
 469         }, null, true);
 470     }
 471 }
 472
 473 Y.HistoryHash = HistoryHash;
 474
 475 // HistoryHash will never win over HistoryHTML5 unless useHistoryHTML5 is false.
 476 if (useHistoryHTML5 === false || (!Y.History && useHistoryHTML5 !== true &&
 477         (!HistoryBase.html5 || !Y.HistoryHTML5))) {
 478     Y.History = HistoryHash;
 479 }
 480
 481
 482 }, '3.13.0', {"requires": ["event-synthetic", "history-base", "yui-later"]});