2
Copyright (c) 2010, Yahoo! Inc. All rights reserved.
3
Code licensed under the BSD License:
4
http://developer.yahoo.com/yui/license.html
8
YUI.add('history-hash', function(Y) {
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.
17
* @submodule history-hash
20
* @extends HistoryBase
22
* @param {Object} config (optional) Configuration object. See the HistoryBase
23
* documentation for details.
26
var HistoryBase = Y.HistoryBase,
29
GlobalEnv = YUI.namespace('Env.HistoryHash'),
37
location = win.location,
38
useHistoryHTML5 = Y.config.useHistoryHTML5;
40
function HistoryHash() {
41
HistoryHash.superclass.constructor.apply(this, arguments);
44
Y.extend(HistoryHash, HistoryBase, {
45
// -- Initialization -------------------------------------------------------
46
_init: function (config) {
47
var bookmarkedState = HistoryHash.parseHash();
49
// If an initialState was provided, merge the bookmarked state into it
50
// (the bookmarked state wins).
51
config = config || {};
53
this._initialState = config.initialState ?
54
Y.merge(config.initialState, bookmarkedState) : bookmarkedState;
56
// Subscribe to the synthetic hashchange event (defined below) to handle
58
Y.after('hashchange', Y.bind(this._afterHashChange, this), win);
60
HistoryHash.superclass._init.apply(this, arguments);
63
// -- Protected Methods ----------------------------------------------------
64
_storeState: function (src, newState) {
65
var newHash = HistoryHash.createHash(newState);
67
HistoryHash.superclass._storeState.apply(this, arguments);
69
// Update the location hash with the changes, but only if the new hash
70
// actually differs from the current hash (this avoids creating multiple
71
// history entries for a single state).
72
if (HistoryHash.getHash() !== newHash) {
73
HistoryHash[src === HistoryBase.SRC_REPLACE ? 'replaceHash' : 'setHash'](newHash);
77
// -- Protected Event Handlers ---------------------------------------------
80
* Handler for hashchange events.
82
* @method _afterHashChange
86
_afterHashChange: function (e) {
87
this._resolveChanges(SRC_HASH, HistoryHash.parseHash(e.newHash), {});
90
// -- Public Static Properties ---------------------------------------------
94
* Constant used to identify state changes originating from
95
* <code>hashchange</code> events.
106
* Prefix to prepend when setting the hash fragment. For example, if the
107
* prefix is <code>!</code> and the hash fragment is set to
108
* <code>#foo=bar&baz=quux</code>, the final hash fragment in the URL will
109
* become <code>#!foo=bar&baz=quux</code>. This can be used to help make an
110
* Ajax application crawlable in accordance with Google's guidelines at
111
* <a href="http://code.google.com/web/ajaxcrawling/">http://code.google.com/web/ajaxcrawling/</a>.
115
* Note that this prefix applies to all HistoryHash instances. It's not
116
* possible for individual instances to use their own prefixes since they
117
* all operate on the same URL.
120
* @property hashPrefix
127
// -- Protected Static Properties ------------------------------------------
130
* Regular expression used to parse location hash/query strings.
132
* @property _REGEX_HASH
138
_REGEX_HASH: /([^\?#&]+)=([^&]+)/g,
140
// -- Public Static Methods ------------------------------------------------
143
* Creates a location hash string from the specified object of key/value
147
* @param {Object} params object of key/value parameter pairs
148
* @return {String} location hash string
151
createHash: function (params) {
152
var encode = HistoryHash.encode,
155
Y.Object.each(params, function (value, key) {
156
if (Lang.isValue(value)) {
157
hash.push(encode(key) + '=' + encode(value));
161
return hash.join('&');
165
* Wrapper around <code>decodeURIComponent()</code> that also converts +
169
* @param {String} string string to decode
170
* @return {String} decoded string
173
decode: function (string) {
174
return decodeURIComponent(string.replace(/\+/g, ' '));
178
* Wrapper around <code>encodeURIComponent()</code> that converts spaces to
182
* @param {String} string string to encode
183
* @return {String} encoded string
186
encode: function (string) {
187
return encodeURIComponent(string).replace(/%20/g, '+');
191
* Gets the raw (not decoded) current location hash, minus the preceding '#'
192
* character and the hashPrefix (if one is set).
195
* @return {String} current location hash
198
getHash: (Y.UA.gecko ? function () {
199
// Gecko's window.location.hash returns a decoded string and we want all
200
// encoding untouched, so we need to get the hash value from
201
// window.location.href instead. We have to use UA sniffing rather than
202
// feature detection, since the only way to detect this would be to
203
// actually change the hash.
204
var matches = /#(.*)$/.exec(location.href),
205
hash = matches && matches[1] || '',
206
prefix = HistoryHash.hashPrefix;
208
return prefix && hash.indexOf(prefix) === 0 ?
209
hash.replace(prefix, '') : hash;
211
var hash = location.hash.substr(1),
212
prefix = HistoryHash.hashPrefix;
214
// Slight code duplication here, but execution speed is of the essence
215
// since getHash() is called every 50ms to poll for changes in browsers
216
// that don't support native onhashchange. An additional function call
217
// would add unnecessary overhead.
218
return prefix && hash.indexOf(prefix) === 0 ?
219
hash.replace(prefix, '') : hash;
223
* Gets the current bookmarkable URL.
226
* @return {String} current bookmarkable URL
229
getUrl: function () {
230
return location.href;
234
* Parses a location hash string into an object of key/value parameter
235
* pairs. If <i>hash</i> is not specified, the current location hash will
239
* @param {String} hash (optional) location hash string
240
* @return {Object} object of parsed key/value parameter pairs
243
parseHash: function (hash) {
244
var decode = HistoryHash.decode,
250
prefix = HistoryHash.hashPrefix,
253
hash = Lang.isValue(hash) ? hash : HistoryHash.getHash();
256
prefixIndex = hash.indexOf(prefix);
258
if (prefixIndex === 0 || (prefixIndex === 1 && hash.charAt(0) === '#')) {
259
hash = hash.replace(prefix, '');
263
matches = hash.match(HistoryHash._REGEX_HASH) || [];
265
for (i = 0, len = matches.length; i < len; ++i) {
266
param = matches[i].split('=');
267
params[decode(param[0])] = decode(param[1]);
274
* Replaces the browser's current location hash with the specified hash
275
* and removes all forward navigation states, without creating a new browser
276
* history entry. Automatically prepends the <code>hashPrefix</code> if one
279
* @method replaceHash
280
* @param {String} hash new location hash
283
replaceHash: function (hash) {
284
if (hash.charAt(0) === '#') {
285
hash = hash.substr(1);
288
location.replace('#' + (HistoryHash.hashPrefix || '') + hash);
292
* Sets the browser's location hash to the specified string. Automatically
293
* prepends the <code>hashPrefix</code> if one is set.
296
* @param {String} hash new location hash
299
setHash: function (hash) {
300
if (hash.charAt(0) === '#') {
301
hash = hash.substr(1);
304
location.hash = (HistoryHash.hashPrefix || '') + hash;
308
// -- Synthetic hashchange Event -----------------------------------------------
310
// TODO: YUIDoc currently doesn't provide a good way to document synthetic DOM
311
// events. For now, we're just documenting the hashchange event on the YUI
312
// object, which is about the best we can do until enhancements are made to
317
* Synthetic <code>window.onhashchange</code> event that normalizes differences
318
* across browsers and provides support for browsers that don't natively support
319
* <code>onhashchange</code>.
323
* This event is provided by the <code>history-hash</code> module.
327
* <strong>Usage example:</strong>
331
* YUI().use('history-hash', function (Y) {
332
* Y.on('hashchange', function (e) {
333
* // Handle hashchange events on the current window.
334
* }, Y.config.win);
339
* @param {EventFacade} e Event facade with the following additional
345
* Previous hash fragment value before the change.
350
* Previous URL (including the hash fragment) before the change.
355
* New hash fragment value after the change.
360
* New URL (including the hash fragment) after the change.
367
hashNotifiers = GlobalEnv._notifiers;
369
if (!hashNotifiers) {
370
hashNotifiers = GlobalEnv._notifiers = [];
373
Y.Event.define('hashchange', {
374
on: function (node, subscriber, notifier) {
375
// Ignore this subscription if the node is anything other than the
376
// window or document body, since those are the only elements that
377
// should support the hashchange event. Note that the body could also be
378
// a frameset, but that's okay since framesets support hashchange too.
379
if (node.compareTo(win) || node.compareTo(Y.config.doc.body)) {
380
hashNotifiers.push(notifier);
384
detach: function (node, subscriber, notifier) {
385
var index = YArray.indexOf(hashNotifiers, notifier);
388
hashNotifiers.splice(index, 1);
393
oldHash = HistoryHash.getHash();
394
oldUrl = HistoryHash.getUrl();
396
if (HistoryBase.nativeHashChange) {
397
// Wrap the browser's native hashchange event.
398
Y.Event.attach('hashchange', function (e) {
399
var newHash = HistoryHash.getHash(),
400
newUrl = HistoryHash.getUrl();
402
// Iterate over a copy of the hashNotifiers array since a subscriber
403
// could detach during iteration and cause the array to be re-indexed.
404
YArray.each(hashNotifiers.concat(), function (notifier) {
418
// Begin polling for location hash changes if there's not already a global
420
if (!GlobalEnv._hashPoll) {
421
if (Y.UA.webkit && !Y.UA.chrome &&
422
navigator.vendor.indexOf('Apple') !== -1) {
423
// Attach a noop unload handler to disable Safari's back/forward
424
// cache. This works around a nasty Safari bug when the back button
425
// is used to return from a page on another domain, but results in
426
// slightly worse performance. This bug is not present in Chrome.
428
// Unfortunately a UA sniff is unavoidable here, but the
429
// consequences of a false positive are minor.
431
// Current as of Safari 5.0 (6533.16).
432
// See: https://bugs.webkit.org/show_bug.cgi?id=34679
433
Y.on('unload', function () {}, win);
436
GlobalEnv._hashPoll = Y.later(50, null, function () {
437
var newHash = HistoryHash.getHash(),
440
if (oldHash !== newHash) {
441
newUrl = HistoryHash.getUrl();
443
YArray.each(hashNotifiers, function (notifier) {
459
Y.HistoryHash = HistoryHash;
461
// HistoryHash will never win over HistoryHTML5 unless useHistoryHTML5 is false.
462
if (useHistoryHTML5 === false || (!Y.History && useHistoryHTML5 !== true &&
463
(!HistoryBase.html5 || !Y.HistoryHTML5))) {
464
Y.History = HistoryHash;
468
}, '3.2.0' ,{requires:['event-synthetic', 'history-base', 'yui-later']});
added
removed
src-js/lazrjs/yui/history/history-hash.js
