history-html5.js revision 9dca8e91b0a6c21f0a2f3b8317d0c02867a1633f
e2673f16114b6a41bd355a022227d22520a46cb8Ryan Grove * Provides browser history management using the HTML5 history API.
e2673f16114b6a41bd355a022227d22520a46cb8Ryan Grove * @module history
e2673f16114b6a41bd355a022227d22520a46cb8Ryan Grove * @submodule history-html5
8cd254d0dce086b53ca23716e564309f8da89eddRyan Grove * @since 3.2.0
8cd254d0dce086b53ca23716e564309f8da89eddRyan Grove * Provides browser history management using the HTML5 history API.
8cd254d0dce086b53ca23716e564309f8da89eddRyan Grove * When calling the <code>add()</code>, <code>addValue()</code>,
8cd254d0dce086b53ca23716e564309f8da89eddRyan Grove * <code>replace()</code>, or <code>replaceValue()</code> methods on
8cd254d0dce086b53ca23716e564309f8da89eddRyan Grove * <code>HistoryHTML5</code>, the following additional options are supported:
8cd254d0dce086b53ca23716e564309f8da89eddRyan Grove * <dt><strong>title (String)</strong></dt>
8cd254d0dce086b53ca23716e564309f8da89eddRyan Grove * Title to use for the new history entry. Browsers will typically display
8cd254d0dce086b53ca23716e564309f8da89eddRyan Grove * this title to the user in the detailed history window or in a dropdown
8cd254d0dce086b53ca23716e564309f8da89eddRyan Grove * menu attached to the back/forward buttons. If not specified, the title
8cd254d0dce086b53ca23716e564309f8da89eddRyan Grove * of the current document will be used.
8cd254d0dce086b53ca23716e564309f8da89eddRyan Grove * <dt><strong>url (String)</strong></dt>
8cd254d0dce086b53ca23716e564309f8da89eddRyan Grove * URL to display to the user for the new history entry. This URL will be
8cd254d0dce086b53ca23716e564309f8da89eddRyan Grove * visible in the browser's address bar and will be the bookmarked URL if
8cd254d0dce086b53ca23716e564309f8da89eddRyan Grove * the user bookmarks the page. It may be a relative path ("foo/bar"), an
8cd254d0dce086b53ca23716e564309f8da89eddRyan Grove * absolute path ("/foo/bar"), or a full URL ("http://example.com/foo/bar").
8cd254d0dce086b53ca23716e564309f8da89eddRyan Grove * If you specify a full URL, the origin <i>must</i> be the same as the
8cd254d0dce086b53ca23716e564309f8da89eddRyan Grove * origin of the current page, or an error will occur. If no URL is
8cd254d0dce086b53ca23716e564309f8da89eddRyan Grove * specified, the current URL will not be changed.
e2673f16114b6a41bd355a022227d22520a46cb8Ryan Grove * @class HistoryHTML5
e2673f16114b6a41bd355a022227d22520a46cb8Ryan Grove * @extends HistoryBase
e2673f16114b6a41bd355a022227d22520a46cb8Ryan Grove * @constructor
9dca8e91b0a6c21f0a2f3b8317d0c02867a1633fRyan Grove * @param {Object} config (optional) Configuration object.
e2673f16114b6a41bd355a022227d22520a46cb8Ryan Grove HistoryHTML5.superclass.constructor.apply(this, arguments);
e2673f16114b6a41bd355a022227d22520a46cb8Ryan Grove // -- Initialization -------------------------------------------------------
9dca8e91b0a6c21f0a2f3b8317d0c02867a1633fRyan Grove // If an initialState was provided, merge the bookmarked state into it
9dca8e91b0a6c21f0a2f3b8317d0c02867a1633fRyan Grove // (the bookmarked state wins).
9dca8e91b0a6c21f0a2f3b8317d0c02867a1633fRyan Grove // If both the initial state and the bookmarked state are objects, merge
9dca8e91b0a6c21f0a2f3b8317d0c02867a1633fRyan Grove // them (bookmarked state wins).
9dca8e91b0a6c21f0a2f3b8317d0c02867a1633fRyan Grove this._initialState = Y.merge(config.initialState,
9dca8e91b0a6c21f0a2f3b8317d0c02867a1633fRyan Grove // Otherwise, the bookmarked state always wins if there is one. If
9dca8e91b0a6c21f0a2f3b8317d0c02867a1633fRyan Grove // there isn't a bookmarked state, history-base will take care of
9dca8e91b0a6c21f0a2f3b8317d0c02867a1633fRyan Grove // falling back to config.initialState or null.
3995ff82c4b76564553f917aff54463461e59416Ryan Grove HistoryHTML5.superclass._init.apply(this, arguments);
e2673f16114b6a41bd355a022227d22520a46cb8Ryan Grove // -- Protected Methods ----------------------------------------------------
8cd254d0dce086b53ca23716e564309f8da89eddRyan Grove * Overrides HistoryBase's <code>_storeState()</code> and pushes or replaces
8cd254d0dce086b53ca23716e564309f8da89eddRyan Grove * a history entry using the HTML5 history API when necessary.
8cd254d0dce086b53ca23716e564309f8da89eddRyan Grove * @method _storeState
8cd254d0dce086b53ca23716e564309f8da89eddRyan Grove * @param {String} src Source of the changes.
8cd254d0dce086b53ca23716e564309f8da89eddRyan Grove * @param {Object} newState New state to store.
8cd254d0dce086b53ca23716e564309f8da89eddRyan Grove * @param {Object} options Zero or more options.
8cd254d0dce086b53ca23716e564309f8da89eddRyan Grove * @protected
8cd254d0dce086b53ca23716e564309f8da89eddRyan Grove win.history[src === SRC_REPLACE ? 'replaceState' : 'pushState'](
8cd254d0dce086b53ca23716e564309f8da89eddRyan Grove HistoryHTML5.superclass._storeState.apply(this, arguments);
8cd254d0dce086b53ca23716e564309f8da89eddRyan Grove // -- Protected Event Handlers ---------------------------------------------
8cd254d0dce086b53ca23716e564309f8da89eddRyan Grove * Handler for popstate events.
8cd254d0dce086b53ca23716e564309f8da89eddRyan Grove * @method _onPopState
8cd254d0dce086b53ca23716e564309f8da89eddRyan Grove * @param {Event} e
8cd254d0dce086b53ca23716e564309f8da89eddRyan Grove * @protected
8cd254d0dce086b53ca23716e564309f8da89eddRyan Grove _onPopState: function (e) {
9dca8e91b0a6c21f0a2f3b8317d0c02867a1633fRyan Grove this._resolveChanges(SRC_POPSTATE, e._event.state || null);
e2673f16114b6a41bd355a022227d22520a46cb8Ryan Grove // -- Public Static Properties ---------------------------------------------
8cd254d0dce086b53ca23716e564309f8da89eddRyan Grove * Constant used to identify state changes originating from
8cd254d0dce086b53ca23716e564309f8da89eddRyan Grove * <code>popstate</code> events.
8cd254d0dce086b53ca23716e564309f8da89eddRyan Grove * @property SRC_POPSTATE
8cd254d0dce086b53ca23716e564309f8da89eddRyan Grove * @type String
96f90701a09dfccf7b2503c9a3014b80d48f0c01Ryan Grove * If <code>true</code>, the <code>Y.History</code> alias will always point to
96f90701a09dfccf7b2503c9a3014b80d48f0c01Ryan Grove * <code>Y.HistoryHTML5</code> when the history-html5 module is loaded, even if
96f90701a09dfccf7b2503c9a3014b80d48f0c01Ryan Grove * the current browser doesn't support HTML5 history.
96f90701a09dfccf7b2503c9a3014b80d48f0c01Ryan Grove * If <code>false</code>, the <code>Y.History</code> alias will always point to
96f90701a09dfccf7b2503c9a3014b80d48f0c01Ryan Grove * <code>Y.HistoryHash</code> when the history-hash module is loaded, even if
96f90701a09dfccf7b2503c9a3014b80d48f0c01Ryan Grove * the current browser supports HTML5 history.
96f90701a09dfccf7b2503c9a3014b80d48f0c01Ryan Grove * If neither <code>true</code> nor <code>false</code>, the
96f90701a09dfccf7b2503c9a3014b80d48f0c01Ryan Grove * <code>Y.History</code> alias will point to the best available history adapter
96f90701a09dfccf7b2503c9a3014b80d48f0c01Ryan Grove * that the browser supports. This is the default behavior.
96f90701a09dfccf7b2503c9a3014b80d48f0c01Ryan Grove * @property useHistoryHTML5
96f90701a09dfccf7b2503c9a3014b80d48f0c01Ryan Grove * @type boolean
96f90701a09dfccf7b2503c9a3014b80d48f0c01Ryan Grove * @for config
96f90701a09dfccf7b2503c9a3014b80d48f0c01Ryan Grove * @since 3.2.0
96f90701a09dfccf7b2503c9a3014b80d48f0c01Ryan Grove// HistoryHTML5 will always win over HistoryHash unless useHistoryHTML5 is false
96f90701a09dfccf7b2503c9a3014b80d48f0c01Ryan Grove// or HTML5 history is not supported.
96f90701a09dfccf7b2503c9a3014b80d48f0c01Ryan Groveif (useHistoryHTML5 === true || (useHistoryHTML5 !== false &&