history-hash.js revision 93b759b0868ace9713d90e7e64ba2f96e3aff780
/**
* Provides browser history management backed by
* <code>window.location.hash</code>, as well as convenience methods for working
* with the location hash and a synthetic <code>hashchange</code> event that
* normalizes differences across browsers.
*
* @module history
* @submodule history-hash
* @since 3.2.0
* @class HistoryHash
* @extends HistoryBase
* @constructor
* @param {Object} config (optional) Configuration object. See the HistoryBase
* documentation for details.
*/
var HistoryBase = Y.HistoryBase,
Obj = Y.Object,
SRC_HASH = 'hash',
function HistoryHash() {
}
// -- Initialization -------------------------------------------------------
// Use the bookmarked state as the initialState if no initialState was
// specified.
// Subscribe to the synthetic hashchange event (defined below) to handle
// changes.
},
// -- Protected Methods ----------------------------------------------------
// Update the location hash with the changes, but only if the new hash
// actually differs from the current hash (this avoids creating multiple
// history entries for a single state).
}
},
// -- Protected Event Handlers ---------------------------------------------
/**
* Handler for hashchange events.
*
* @method _afterHashChange
* @param {Event} e
* @protected
*/
_afterHashChange: function (e) {
}
}, {
// -- Public Static Properties ---------------------------------------------
NAME: 'historyHash',
/**
* Constant used to identify state changes originating from
* <code>hashchange</code> events.
*
* @property SRC_HASH
* @type String
* @static
* @final
*/
/**
* <p>
* Prefix to prepend when setting the hash fragment. For example, if the
* prefix is <code>!</code> and the hash fragment is set to
* <code>#foo=bar&baz=quux</code>, the final hash fragment in the URL will
* become <code>#!foo=bar&baz=quux</code>. This can be used to help make an
* Ajax application crawlable in accordance with Google's guidelines at
* </p>
*
* <p>
* Note that this prefix applies to all HistoryHash instances. It's not
* possible for individual instances to use their own prefixes since they
* all operate on the same URL.
* </p>
*
* @property hashPrefix
* @type String
* @default ''
* @static
*/
hashPrefix: '',
// -- Protected Static Properties ------------------------------------------
/**
*
* @property _REGEX_HASH
* @type RegExp
* @protected
* @static
* @final
*/
_REGEX_HASH: /([^\?#&]+)=([^&]+)/g,
// -- Public Static Methods ------------------------------------------------
/**
* pairs.
*
* @method createHash
* @return {String} location hash string
* @static
*/
createHash: function (params) {
hash = [];
}
});
},
/**
* Wrapper around <code>decodeURIComponent()</code> that also converts +
* chars into spaces.
*
* @method decode
* @param {String} string string to decode
* @return {String} decoded string
* @static
*/
},
/**
* Wrapper around <code>encodeURIComponent()</code> that converts spaces to
* + chars.
*
* @method encode
* @param {String} string string to encode
* @return {String} encoded string
* @static
*/
},
/**
* Gets the raw (not decoded) current location hash, minus the preceding '#'
* character and the hashPrefix (if one is set).
*
* @method getHash
* @return {String} current location hash
* @static
*/
// Gecko's window.location.hash returns a decoded string and we want all
// encoding untouched, so we need to get the hash value from
// window.location.href instead. We have to use UA sniffing rather than
// feature detection, since the only way to detect this would be to
// actually change the hash.
} : function () {
// Slight code duplication here, but execution speed is of the essence
// since getHash() is called every 20ms or so to poll for changes in
// browsers that don't support native onhashchange. An additional
// function call would add unnecessary overhead.
}),
/**
* Gets the current bookmarkable URL.
*
* @method getUrl
* @return {String} current bookmarkable URL
* @static
*/
getUrl: function () {
},
/**
* pairs. If <i>hash</i> is not specified, the current location hash will
* be used.
*
* @method parseHash
* @param {String} hash (optional) location hash string
* @static
*/
i,
len,
params = {},
if (prefix) {
}
}
}
return params;
},
/**
* Replaces the browser's current location hash with the specified hash
* and removes all forward navigation states, without creating a new browser
* history entry. Automatically prepends the <code>hashPrefix</code> if one
* is set.
*
* @method replaceHash
* @param {String} hash new location hash
* @static
*/
replaceHash: function (hash) {
}
},
/**
* Sets the browser's location hash to the specified string. Automatically
* prepends the <code>hashPrefix</code> if one is set.
*
* @method setHash
* @param {String} hash new location hash
* @static
*/
}
}
});
// -- Synthetic hashchange Event -----------------------------------------------
// TODO: YUIDoc currently doesn't provide a good way to document synthetic DOM
// events. For now, we're just documenting the hashchange event on the YUI
// object, which is about the best we can do until enhancements are made to
// YUIDoc.
/**
* <p>
* Synthetic <code>window.onhashchange</code> event that normalizes differences
* across browsers and provides support for browsers that don't natively support
* <code>onhashchange</code>.
* </p>
*
* <p>
* This event is provided by the <code>history-hash</code> module.
* </p>
*
* <p>
* <strong>Usage example:</strong>
* </p>
*
* <code><pre>
* YUI().use('history-hash', function (Y) {
* Y.on('hashchange', function (e) {
* // Handle hashchange events on the current window.
* }, Y.config.win);
* });
* </pre></code>
*
* @event hashchange
* @param {EventFacade} e Event facade with the following additional
* properties:
*
* <dl>
* <dt>oldHash</dt>
* <dd>
* Previous hash fragment value before the change.
* </dd>
*
* <dt>oldUrl</dt>
* <dd>
* Previous URL (including the hash fragment) before the change.
* </dd>
*
* <dt>newHash</dt>
* <dd>
* New hash fragment value after the change.
* </dd>
*
* <dt>newUrl</dt>
* <dd>
* New URL (including the hash fragment) after the change.
* </dd>
* </dl>
* @for YUI
*/
// Ignore this subscriber if the node is anything other than the
// window or document body, since those are the only elements that
// should support the hashchange event. Note that the body could also be
// a frameset, but that's okay since framesets support hashchange too.
}
},
// but also not documented. Also, subscriber counts don't seem to be
// updated after detach().
}
}
});
if (HistoryBase.nativeHashChange) {
// Wrap the browser's native hashchange event.
});
});
}, win);
} else {
// Begin polling for location hash changes if there's not already a global
// poll running.
// cache. This works around a nasty Safari bug when the back button
// is used to return from a page on another domain, but results in
// slightly worse performance. This bug is not present in Chrome.
//
// Unfortunately a UA sniff is unavoidable here, but the
// consequences of a false positive are minor.
//
// Current as of Safari 5.0 (6533.16).
}
});
});
}
}, null, true);
}
}
Y.HistoryHash = HistoryHash;
// Only point Y.History at HistoryHash if it doesn't already exist and if the
// current browser doesn't support HTML5 history, or if the HistoryHTML5 class
// is not present. The history-hash module is always loaded after history-html5
// if history-html5 is loaded, so this check doesn't introduce a race condition.
Y.History = HistoryHash;
}