File: history/js/history-html5.js

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