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-html5', function(Y) {
11 * Provides browser history management using the HTML5 history API.
14 * @submodule history-html5
20 * Provides browser history management using the HTML5 history API.
24 * When calling the <code>add()</code>, <code>addValue()</code>,
25 * <code>replace()</code>, or <code>replaceValue()</code> methods on
26 * <code>HistoryHTML5</code>, the following additional options are supported:
30 * <dt><strong>title (String)</strong></dt>
32 * Title to use for the new history entry. Browsers will typically display
33 * this title to the user in the detailed history window or in a dropdown
34 * menu attached to the back/forward buttons. If not specified, the title
35 * of the current document will be used.
38 * <dt><strong>url (String)</strong></dt>
40 * URL to display to the user for the new history entry. This URL will be
41 * visible in the browser's address bar and will be the bookmarked URL if
42 * the user bookmarks the page. It may be a relative path ("foo/bar"), an
43 * absolute path ("/foo/bar"), or a full URL ("http://example.com/foo/bar").
44 * If you specify a full URL, the origin <i>must</i> be the same as the
45 * origin of the current page, or an error will occur. If no URL is
46 * specified, the current URL will not be changed.
51 * @extends HistoryBase
53 * @param {Object} config (optional) Configuration object. The following
54 * <code>HistoryHTML5</code>-specific properties are supported in addition to
55 * those supported by <code>HistoryBase</code>:
58 * <dt><strong>enableSessionFallback (Boolean)</strong></dt>
61 * Set this to <code>true</code> to store the most recent history state in
62 * sessionStorage in order to seamlessly restore the previous state (if any)
63 * when <code>HistoryHTML5</code> is instantiated after a
64 * <code>window.onpopstate</code> event has already fired.
68 * By default, this setting is <code>false</code>.
74 var HistoryBase = Y.HistoryBase,
78 useHistoryHTML5 = Y.config.useHistoryHTML5,
80 JSON = Y.JSON || win.JSON, // prefer YUI JSON, but fall back to native
82 ENABLE_FALLBACK = 'enableSessionFallback',
83 SESSION_KEY = 'YUI_HistoryHTML5_state',
84 SRC_POPSTATE = 'popstate',
85 SRC_REPLACE = HistoryBase.SRC_REPLACE;
87 function HistoryHTML5() {
88 HistoryHTML5.superclass.constructor.apply(this, arguments);
91 Y.extend(HistoryHTML5, HistoryBase, {
92 // -- Initialization -------------------------------------------------------
93 _init: function (config) {
94 Y.on('popstate', this._onPopState, win, this);
96 HistoryHTML5.superclass._init.apply(this, arguments);
98 // If window.onload has already fired and the sessionStorage fallback is
99 // enabled, try to restore the last state from sessionStorage. This
100 // works around a shortcoming of the HTML5 history API: it's impossible
101 // to get the current state if the popstate event fires before you've
102 // subscribed to it. Since popstate fires immediately after onload,
103 // the last state may be lost if you return to a page from another page.
104 if (config && config[ENABLE_FALLBACK] && YUI.Env.windowLoaded) {
105 // Gecko will throw an error if you attempt to reference
106 // sessionStorage on a page served from a file:// URL, so we have to
109 // See http://yuilibrary.com/projects/yui3/ticket/2529165
111 sessionStorage = win.sessionStorage;
114 this._loadSessionState();
118 // -- Protected Methods ----------------------------------------------------
121 * Returns a string unique to the current URL pathname that's suitable for
122 * use as a session storage key.
124 * @method _getSessionKey
128 _getSessionKey: function () {
129 return SESSION_KEY + '_' + win.location.pathname;
133 * Attempts to load a state entry stored in session storage.
135 * @method _loadSessionState
138 _loadSessionState: function () {
139 var lastState = JSON && sessionStorage &&
140 sessionStorage[this._getSessionKey()];
144 this._resolveChanges(SRC_POPSTATE, JSON.parse(lastState) || null);
150 * Stores the specified state entry in session storage if the
151 * <code>enableSessionFallback</code> config property is <code>true</code>
152 * and either <code>Y.JSON</code> or native JSON support is available and
153 * session storage is supported.
155 * @method _storeSessionState
156 * @param {mixed} state State to store. May be any type serializable to
160 _storeSessionState: function (state) {
161 if (this._config[ENABLE_FALLBACK] && JSON && sessionStorage) {
162 sessionStorage[this._getSessionKey()] = JSON.stringify(state || null);
167 * Overrides HistoryBase's <code>_storeState()</code> and pushes or replaces
168 * a history entry using the HTML5 history API when necessary.
170 * @method _storeState
171 * @param {String} src Source of the changes.
172 * @param {Object} newState New state to store.
173 * @param {Object} options Zero or more options.
176 _storeState: function (src, newState, options) {
177 if (src !== SRC_POPSTATE) {
178 win.history[src === SRC_REPLACE ? 'replaceState' : 'pushState'](
179 newState, options.title || doc.title || '', options.url || null
183 this._storeSessionState(newState);
184 HistoryHTML5.superclass._storeState.apply(this, arguments);
187 // -- Protected Event Handlers ---------------------------------------------
190 * Handler for popstate events.
192 * @method _onPopState
196 _onPopState: function (e) {
197 var state = e._event.state;
199 this._storeSessionState(state);
200 this._resolveChanges(SRC_POPSTATE, state || null);
203 // -- Public Static Properties ---------------------------------------------
204 NAME: 'historyhtml5',
207 * Constant used to identify state changes originating from
208 * <code>popstate</code> events.
210 * @property SRC_POPSTATE
215 SRC_POPSTATE: SRC_POPSTATE
218 if (!Y.Node.DOM_EVENTS.popstate) {
219 Y.Node.DOM_EVENTS.popstate = 1;
222 Y.HistoryHTML5 = HistoryHTML5;
226 * If <code>true</code>, the <code>Y.History</code> alias will always point to
227 * <code>Y.HistoryHTML5</code> when the history-html5 module is loaded, even if
228 * the current browser doesn't support HTML5 history.
232 * If <code>false</code>, the <code>Y.History</code> alias will always point to
233 * <code>Y.HistoryHash</code> when the history-hash module is loaded, even if
234 * the current browser supports HTML5 history.
238 * If neither <code>true</code> nor <code>false</code>, the
239 * <code>Y.History</code> alias will point to the best available history adapter
240 * that the browser supports. This is the default behavior.
243 * @property useHistoryHTML5
249 // HistoryHTML5 will always win over HistoryHash unless useHistoryHTML5 is false
250 // or HTML5 history is not supported.
251 if (useHistoryHTML5 === true || (useHistoryHTML5 !== false &&
252 HistoryBase.html5)) {
253 Y.History = HistoryHTML5;
257 }, '3.3.0' ,{optional:['json'], requires:['event-base', 'history-base', 'node-base']});