# Yahoo! UI Library

### Browser History Manager 2.5.1

Yahoo! UI Library > history > history.js (source view)

Show Private Show Protected

    /**
     * The Browser History Manager provides the ability to use the back/forward
     * navigation buttons in a DHTML application. It also allows a DHTML
     * application to be bookmarked in a specific state.
     *
     * This library requires the following static markup:
     *
     * &lt;iframe id="yui-history-iframe" src="path-to-real-asset-in-same-domain"&gt;&lt;/iframe&gt;
     * &lt;input id="yui-history-field" type="hidden"&gt;
     *
     * @module history
     * @requires yahoo,event
     * @namespace YAHOO.util
     * @title Browser History Manager
     */

    /**
     * The History class provides the ability to use the back/forward navigation
     * buttons in a DHTML application. It also allows a DHTML application to
     * be bookmarked in a specific state.
     *
     * @class History
     * @constructor
     */
    YAHOO.util.History = (function () {

        /**
         * Our hidden IFrame used to store the browsing history.
         *
         * @property _histFrame
         * @type HTMLIFrameElement
         * @default null
         * @private
         */
        var _histFrame = null;

        /**
         * INPUT field (with type="hidden" or type="text") or TEXTAREA.
         * This field keeps the value of the initial state, current state
         * the list of all states across pages within a single browser session.
         *
         * @property _stateField
         * @type HTMLInputElement|HTMLTextAreaElement
         * @default null
         * @private
         */
        var _stateField = null;

        /**
         * Flag used to tell whether YAHOO.util.History.initialize has been called.
         *
         * @property _initialized
         * @type boolean
         * @default false
         * @private
         */
        var _initialized = false;

        /**
         * List of registered modules.
         *
         * @property _modules
         * @type array
         * @default []
         * @private
         */
        var _modules = [];

        /**
         * List of fully qualified states. This is used only by Safari.
         *
         * @property _fqstates
         * @type array
         * @default []
         * @private
         */
        var _fqstates = [];

        /**
         * location.hash is a bit buggy on Opera. I have seen instances where
         * navigating the history using the back/forward buttons, and hence
         * changing the URL, would not change location.hash. That's ok, the
         * implementation of an equivalent is trivial.
         *
         * @method _getHash
         * @return {string} The hash portion of the document's location
         * @private
         */
        function _getHash() {
            var i, href;
            href = top.location.href;
            i = href.indexOf("#");
            return i >= 0 ? href.substr(i + 1) : null;
        }

        /**
         * Stores all the registered modules' initial state and current state.
         * On Safari, we also store all the fully qualified states visited by
         * the application within a single browser session. The storage takes
         * place in the form field specified during initialization.
         *
         * @method _storeStates
         * @private
         */
        function _storeStates() {

            var moduleName, moduleObj, initialStates = [], currentStates = [];

            for (moduleName in _modules) {
                if (YAHOO.lang.hasOwnProperty(_modules, moduleName)) {
                    moduleObj = _modules[moduleName];
                    initialStates.push(moduleName + "=" + moduleObj.initialState);
                    currentStates.push(moduleName + "=" + moduleObj.currentState);
                }
            }

            _stateField.value = initialStates.join("&") + "|" + currentStates.join("&");

            if (YAHOO.env.ua.webkit) {
                _stateField.value += "|" + _fqstates.join(",");
            }
        }

        /**
         * Sets the new currentState attribute of all modules depending on the new
         * fully qualified state. Also notifies the modules which current state has
         * changed.
         *
         * @method _handleFQStateChange
         * @param {string} fqstate Fully qualified state
         * @private
         */
        function _handleFQStateChange(fqstate) {

            var i, len, moduleName, moduleObj, modules, states, tokens, currentState;

            if (!fqstate) {
                // Notifies all modules
                for (moduleName in _modules) {
                    if (YAHOO.lang.hasOwnProperty(_modules, moduleName)) {
                        moduleObj = _modules[moduleName];
                        moduleObj.currentState = moduleObj.initialState;
                        moduleObj.onStateChange(unescape(moduleObj.currentState));
                    }
                }
                return;
            }

            modules = [];
            states = fqstate.split("&");
            for (i = 0, len = states.length; i < len; i++) {
                tokens = states[i].split("=");
                if (tokens.length === 2) {
                    moduleName = tokens[0];
                    currentState = tokens[1];
                    modules[moduleName] = currentState;
                }
            }

            for (moduleName in _modules) {
                if (YAHOO.lang.hasOwnProperty(_modules, moduleName)) {
                    moduleObj = _modules[moduleName];
                    currentState = modules[moduleName];
                    if (!currentState || moduleObj.currentState !== currentState) {
                        moduleObj.currentState = currentState || moduleObj.initialState;
                        moduleObj.onStateChange(unescape(moduleObj.currentState));
                    }
                }
            }
        }

        /**
         * Update the IFrame with our new state.
         *
         * @method _updateIFrame
         * @private
         * @return {boolean} true if successful. false otherwise.
         */
        function _updateIFrame (fqstate) {

            var html, doc;

            html = '<html><body><div id="state">' + fqstate + '</div></body></html>';

            try {
                doc = _histFrame.contentWindow.document;
                doc.open();
                doc.write(html);
                doc.close();
                return true;
            } catch (e) {
                return false;
            }
        }

        /**
         * Periodically checks whether our internal IFrame is ready to be used.
         *
         * @method _checkIframeLoaded
         * @private
         */
        function _checkIframeLoaded() {

            var doc, elem, fqstate, hash;

            if (!_histFrame.contentWindow || !_histFrame.contentWindow.document) {
                // Check again in 10 msec...
                setTimeout(_checkIframeLoaded, 10);
                return;
            }

            // Start the thread that will have the responsibility to
            // periodically check whether a navigate operation has been
            // requested on the main window. This will happen when
            // YAHOO.util.History.navigate has been called or after
            // the user has hit the back/forward button.

            doc = _histFrame.contentWindow.document;
            elem = doc.getElementById("state");
            // We must use innerText, and not innerHTML because our string contains
            // the "&" character (which would end up being escaped as "&amp;") and
            // the string comparison would fail...
            fqstate = elem ? elem.innerText : null;

            hash = _getHash();

            setInterval(function () {

                var newfqstate, states, moduleName, moduleObj, newHash, historyLength;

                doc = _histFrame.contentWindow.document;
                elem = doc.getElementById("state");
                // See my comment above about using innerText instead of innerHTML...
                newfqstate = elem ? elem.innerText : null;

                newHash = _getHash();

                if (newfqstate !== fqstate) {

                    fqstate = newfqstate;
                    _handleFQStateChange(fqstate);

                    if (!fqstate) {
                        states = [];
                        for (moduleName in _modules) {
                            if (YAHOO.lang.hasOwnProperty(_modules, moduleName)) {
                                moduleObj = _modules[moduleName];
                                states.push(moduleName + "=" + moduleObj.initialState);
                            }
                        }
                        newHash = states.join("&");
                    } else {
                        newHash = fqstate;
                    }

                    // Allow the state to be bookmarked by setting the top window's
                    // URL fragment identifier. Note that here, we are on IE, and
                    // IE does not touch the browser history when setting the hash
                    // (unlike all the other browsers). I used to write:
                    //     top.location.replace( "#" + hash );
                    // but this had a side effect when the page was not the top frame.
                    top.location.hash = newHash;
                    hash = newHash;

                    _storeStates();

                } else if (newHash !== hash) {

                    // The hash has changed. The user might have clicked on a link,
                    // or modified the URL directly, or opened the same application
                    // bookmarked in a specific state using a bookmark. However, we
                    // know the hash change was not caused by a hit on the back or
                    // forward buttons, or by a call to navigate() (because it would
                    // have been handled above) We must handle these cases, which is
                    // why we also need to keep track of hash changes on IE!

                    // Note that IE6 has some major issues with this kind of user
                    // interaction (the history stack gets completely messed up)
                    // but it seems to work fine on IE7.

                    hash = newHash;

                    // Now, store a new history entry. The following will cause the
                    // code above to execute, doing all the dirty work for us...
                    _updateIFrame(newHash);
                }

            }, 50);

            _initialized = true;
            YAHOO.util.History.onLoadEvent.fire();
        }

        /**
         * Finish up the initialization of the Browser History Manager.
         *
         * @method _initialize
         * @private
         */
        function _initialize() {

            var i, len, parts, tokens, moduleName, moduleObj, initialStates, initialState, currentStates, currentState, counter, hash;

            // Decode the content of our storage field...
            parts = _stateField.value.split("|");

            if (parts.length > 1) {

                initialStates = parts[0].split("&");
                for (i = 0, len = initialStates.length; i < len; i++) {
                    tokens = initialStates[i].split("=");
                    if (tokens.length === 2) {
                        moduleName = tokens[0];
                        initialState = tokens[1];
                        moduleObj = _modules[moduleName];
                        if (moduleObj) {
                            moduleObj.initialState = initialState;
                        }
                    }
                }

                currentStates = parts[1].split("&");
                for (i = 0, len = currentStates.length; i < len; i++) {
                    tokens = currentStates[i].split("=");
                    if (tokens.length >= 2) {
                        moduleName = tokens[0];
                        currentState = tokens[1];
                        moduleObj = _modules[moduleName];
                        if (moduleObj) {
                            moduleObj.currentState = currentState;
                        }
                    }
                }
            }

            if (parts.length > 2) {
                _fqstates = parts[2].split(",");
            }

            if (YAHOO.env.ua.ie) {

                _checkIframeLoaded();

            } else {

                // Start the thread that will have the responsibility to
                // periodically check whether a navigate operation has been
                // requested on the main window. This will happen when
                // YAHOO.util.History.navigate has been called or after
                // the user has hit the back/forward button.

                // On Safari 1.x and 2.0, the only way to catch a back/forward
                // operation is to watch history.length... We basically exploit
                // what I consider to be a bug (history.length is not supposed
                // to change when going back/forward in the history...) This is
                // why, in the following thread, we first compare the hash,
                // because the hash thing will be fixed in the next major
                // version of Safari. So even if they fix the history.length
                // bug, all this will still work!
                counter = history.length;

                // On Gecko and Opera, we just need to watch the hash...
                hash = _getHash();

                setInterval(function () {

                    var state, newHash, newCounter;

                    newHash = _getHash();
                    newCounter = history.length;
                    if (newHash !== hash) {
                        hash = newHash;
                        counter = newCounter;
                        _handleFQStateChange(hash);
                        _storeStates();
                    } else if (newCounter !== counter && YAHOO.env.ua.webkit) {
                        hash = newHash;
                        counter = newCounter;
                        state = _fqstates[counter - 1];
                        _handleFQStateChange(state);
                        _storeStates();
                    }

                }, 50);

                _initialized = true;
                YAHOO.util.History.onLoadEvent.fire();
            }
        }

        return {

            /**
             * Fired when the Browser History Manager is ready. If you subscribe to
             * this event after the Browser History Manager has been initialized,
             * it will not fire. Therefore, it is recommended to use the onReady
             * method instead.
             *
             * @event onLoadEvent
             * @see onReady
             */
            onLoadEvent: new YAHOO.util.CustomEvent("onLoad"),

            /**
             * Executes the supplied callback when the Browser History Manager is
             * ready. This will execute immediately if called after the Browser
             * History Manager onLoad event has fired.
             *
             * @method onReady
             * @param {function} fn what to execute when the Browser History Manager is ready.
             * @param {object} obj an optional object to be passed back as a parameter to fn.
             * @param {boolean|object} override If true, the obj passed in becomes fn's execution scope.
             * @see onLoadEvent
             */
            onReady: function (fn, obj, override) {

                if (_initialized) {

                    setTimeout(function () {
                        var ctx = window;
                        if (override) {
                            if (override === true) {
                                ctx = obj;
                            } else {
                                ctx = override;
                            }
                        }
                        fn.call(ctx, "onLoad", [], obj);
                    }, 0);

                } else {

                    YAHOO.util.History.onLoadEvent.subscribe(fn, obj, override);

                }
            },

            /**
             * Registers a new module.
             *
             * @method register
             * @param {string} module Non-empty string uniquely identifying the
             *     module you wish to register.
             * @param {string} initialState The initial state of the specified
             *     module corresponding to its earliest history entry.
             * @param {function} onStateChange Callback called when the
             *     state of the specified module has changed.
             * @param {object} obj An arbitrary object that will be passed as a
             *     parameter to the handler.
             * @param {boolean} override If true, the obj passed in becomes the
             *     execution scope of the listener.
             */
            register: function (module, initialState, onStateChange, obj, override) {

                var scope, wrappedFn;

                if (typeof module !== "string" || YAHOO.lang.trim(module) === "" ||
                    typeof initialState !== "string" ||
                    typeof onStateChange !== "function") {
                    throw new Error("Missing or invalid argument");
                }

                if (_modules[module]) {
                    // Here, we used to throw an exception. However, users have
                    // complained about this behavior, so we now just return.
                    return;
                }

                // Note: A module CANNOT be registered after calling
                // YAHOO.util.History.initialize. Indeed, we set the initial state
                // of each registered module in YAHOO.util.History.initialize.
                // If you could register a module after initializing the Browser
                // History Manager, you would not read the correct state using
                // YAHOO.util.History.getCurrentState when coming back to the
                // page using the back button.
                if (_initialized) {
                    throw new Error("All modules must be registered before calling YAHOO.util.History.initialize");
                }

                // Make sure the strings passed in do not contain our separators "," and "|"
                module = escape(module);
                initialState = escape(initialState);

                // If the user chooses to override the scope, we use the
                // custom object passed in as the execution scope.
                scope = null;
                if (override === true) {
                    scope = obj;
                } else {
                    scope = override;
                }

                wrappedFn = function (state) {
                    return onStateChange.call(scope, state, obj);
                };

                _modules[module] = {
                    name: module,
                    initialState: initialState,
                    currentState: initialState,
                    onStateChange: wrappedFn
                };
            },

            /**
             * Initializes the Browser History Manager. Call this method
             * from a script block located right after the opening body tag.
             *
             * @method initialize
             * @param {string|HTML Element} stateField <input type="hidden"> used
             *     to store application states. Must be in the static markup.
             * @param {string|HTML Element} histFrame IFrame used to store
             *     the history (only required on Internet Explorer)
             * @public
             */
            initialize: function (stateField, histFrame) {

                if (_initialized) {
                    // The browser history manager has already been initialized.
                    return;
                }

                if (YAHOO.env.ua.opera) {
                    // Opera cannot be supported because of several problems that
                    // have been reported to the Opera team, but never addressed:
                    //   1) Hash changes are not detected (started happening with
                    //      recent versions of Opera)
                    //   2) The entire DOM gets cached, so when you come back to
                    //      a page, the window's onload event does not get fired,
                    //      which prevents us from initializing the browser history
                    //      manager.
                    // As a consequence, the best thing we can do is to throw an
                    // exception. The application should catch it, and degrade
                    // gracefully. This is the sad state of history management.
                    YAHOO.log("Unsupported browser.", "error", this.toString());
                }

                if (typeof stateField === "string") {
                    stateField = document.getElementById(stateField);
                }

                if (!stateField ||
                    stateField.tagName.toUpperCase() !== "TEXTAREA" &&
                    (stateField.tagName.toUpperCase() !== "INPUT" ||
                     stateField.type !== "hidden" &&
                     stateField.type !== "text")) {
                    throw new Error("Missing or invalid argument");
                }

                _stateField = stateField;

                if (YAHOO.env.ua.ie) {

                    if (typeof histFrame === "string") {
                        histFrame = document.getElementById(histFrame);
                    }

                    if (!histFrame || histFrame.tagName.toUpperCase() !== "IFRAME") {
                        throw new Error("Missing or invalid argument");
                    }

                    _histFrame = histFrame;
                }

                // Note that the event utility MUST be included inline in the page.
                // If it gets loaded later (which you may want to do to improve the
                // loading speed of your site), the onDOMReady event never fires,
                // and the history library never gets fully initialized.
                YAHOO.util.Event.onDOMReady(_initialize);
            },

            /**
             * Call this method when you want to store a new entry in the browser's history.
             *
             * @method navigate
             * @param {string} module Non-empty string representing your module.
             * @param {string} state String representing the new state of the specified module.
             * @return {boolean} Indicates whether the new state was successfully added to the history.
             * @public
             */
            navigate: function (module, state) {

                var states;

                if (typeof module !== "string" || typeof state !== "string") {
                    throw new Error("Missing or invalid argument");
                }

                states = {};
                states[module] = state;

                return YAHOO.util.History.multiNavigate(states);
            },

            /**
             * Call this method when you want to store a new entry in the browser's history.
             *
             * @method multiNavigate
             * @param {object} states Associative array of module-state pairs to set simultaneously.
             * @return {boolean} Indicates whether the new state was successfully added to the history.
             * @public
             */
            multiNavigate: function (states) {

                var currentStates, moduleName, moduleObj, currentState, fqstate;

                if (typeof states !== "object") {
                    throw new Error("Missing or invalid argument");
                }

                if (!_initialized) {
                    throw new Error("The Browser History Manager is not initialized");
                }

                for (moduleName in states) {
                    if (!_modules[moduleName]) {
                        throw new Error("The following module has not been registered: " + moduleName);
                    }
                }

                // Generate our new full state string mod1=xxx&mod2=yyy
                currentStates = [];

                for (moduleName in _modules) {
                    if (YAHOO.lang.hasOwnProperty(_modules, moduleName)) {
                        moduleObj = _modules[moduleName];
                        if (YAHOO.lang.hasOwnProperty(states, moduleName)) {
                            currentState = states[unescape(moduleName)];
                        } else {
                            currentState = unescape(moduleObj.currentState);
                        }

                        // Make sure the strings passed in do not contain our separators "," and "|"
                        moduleName = escape(moduleName);
                        currentState = escape(currentState);

                        currentStates.push(moduleName + "=" + currentState);
                    }
                }

                fqstate = currentStates.join("&");

                if (YAHOO.env.ua.ie) {

                    return _updateIFrame(fqstate);

                } else {

                    // Known bug: On Safari 1.x and 2.0, if you have tab browsing
                    // enabled, Safari will show an endless loading icon in the
                    // tab. This has apparently been fixed in recent WebKit builds.
                    // One work around found by Dav Glass is to submit a form that
                    // points to the same document. This indeed works on Safari 1.x
                    // and 2.0 but creates bigger problems on WebKit. So for now,
                    // we'll consider this an acceptable bug, and hope that Apple
                    // comes out with their next version of Safari very soon.
                    top.location.hash = fqstate;
                    if (YAHOO.env.ua.webkit) {
                        // The following two lines are only useful for Safari 1.x
                        // and 2.0. Recent nightly builds of WebKit do not require
                        // that, but unfortunately, it is not easy to differentiate
                        // between the two. Once Safari 2.0 departs the A-grade
                        // list, we can remove the following two lines...
                        _fqstates[history.length] = fqstate;
                        _storeStates();
                    }

                    return true;

                }
            },

            /**
             * Returns the current state of the specified module.
             *
             * @method getCurrentState
             * @param {string} module Non-empty string representing your module.
             * @return {string} The current state of the specified module.
             * @public
             */
            getCurrentState: function (module) {

                var moduleObj;

                if (typeof module !== "string") {
                    throw new Error("Missing or invalid argument");
                }

                if (!_initialized) {
                    throw new Error("The Browser History Manager is not initialized");
                }

                moduleObj = _modules[module];
                if (!moduleObj) {
                    throw new Error("No such registered module: " + module);
                }

                return unescape(moduleObj.currentState);
            },

            /**
             * Returns the state of a module according to the URL fragment
             * identifier. This method is useful to initialize your modules
             * if your application was bookmarked from a particular state.
             *
             * @method getBookmarkedState
             * @param {string} module Non-empty string representing your module.
             * @return {string} The bookmarked state of the specified module.
             * @public
             */
            getBookmarkedState: function (module) {

                var i, len, idx, hash, states, tokens, moduleName;

                if (typeof module !== "string") {
                    throw new Error("Missing or invalid argument");
                }

                // Use location.href instead of location.hash which is already
                // URL-decoded, which creates problems if the state value
                // contained special characters...
                idx = top.location.href.indexOf("#");
                hash = idx >= 0 ? top.location.href.substr(idx + 1) : top.location.href;

                states = hash.split("&");
                for (i = 0, len = states.length; i < len; i++) {
                    tokens = states[i].split("=");
                    if (tokens.length === 2) {
                        moduleName = tokens[0];
                        if (moduleName === module) {
                            return unescape(tokens[1]);
                        }
                    }
                }

                return null;
            },

            /**
             * Returns the value of the specified query string parameter.
             * This method is not used internally by the Browser History Manager.
             * However, it is provided here as a helper since many applications
             * using the Browser History Manager will want to read the value of
             * url parameters to initialize themselves.
             *
             * @method getQueryStringParameter
             * @param {string} paramName Name of the parameter we want to look up.
             * @param {string} queryString Optional URL to look at. If not specified,
             *     this method uses the URL in the address bar.
             * @return {string} The value of the specified parameter, or null.
             * @public
             */
            getQueryStringParameter: function (paramName, url) {

                var i, len, idx, queryString, params, tokens;

                url = url || top.location.href;

                idx = url.indexOf("?");
                queryString = idx >= 0 ? url.substr(idx + 1) : url;

                // Remove the hash if any
                idx = queryString.lastIndexOf("#");
                queryString = idx >= 0 ? queryString.substr(0, idx) : queryString;

                params = queryString.split("&");

                for (i = 0, len = params.length; i < len; i++) {
                    tokens = params[i].split("=");
                    if (tokens.length >= 2) {
                        if (tokens[0] === paramName) {
                            return unescape(tokens[1]);
                        }
                    }
                }

                return null;
            }

        };

    })();

Copyright © 2007 Yahoo! Inc. All rights reserved.