2 Copyright (c) 2009, Yahoo! Inc. All rights reserved.
3 Code licensed under the BSD License:
4 http://developer.yahoo.net/yui/license.txt
8 * The Browser History Manager provides the ability to use the back/forward
9 * navigation buttons in a DHTML application. It also allows a DHTML
10 * application to be bookmarked in a specific state.
12 * This library requires the following static markup:
14 * <iframe id="yui-history-iframe" src="path-to-real-asset-in-same-domain"></iframe>
15 * <input id="yui-history-field" type="hidden">
18 * @requires yahoo,event
19 * @namespace YAHOO.util
20 * @title Browser History Manager
24 * The History class provides the ability to use the back/forward navigation
25 * buttons in a DHTML application. It also allows a DHTML application to
26 * be bookmarked in a specific state.
31 YAHOO.util.History = (function () {
34 * Our hidden IFrame used to store the browsing history.
36 * @property _histFrame
37 * @type HTMLIFrameElement
41 var _histFrame = null;
44 * INPUT field (with type="hidden" or type="text") or TEXTAREA.
45 * This field keeps the value of the initial state, current state
46 * the list of all states across pages within a single browser session.
48 * @property _stateField
49 * @type HTMLInputElement|HTMLTextAreaElement
53 var _stateField = null;
56 * Flag used to tell whether YAHOO.util.History.initialize has been called.
58 * @property _initialized
63 var _initialized = false;
66 * List of registered modules.
76 * List of fully qualified states. This is used only by Safari.
86 * location.hash is a bit buggy on Opera. I have seen instances where
87 * navigating the history using the back/forward buttons, and hence
88 * changing the URL, would not change location.hash. That's ok, the
89 * implementation of an equivalent is trivial.
92 * @return {string} The hash portion of the document's location
97 href = top.location.href;
98 i = href.indexOf("#");
99 return i >= 0 ? href.substr(i + 1) : null;
103 * Stores all the registered modules' initial state and current state.
104 * On Safari, we also store all the fully qualified states visited by
105 * the application within a single browser session. The storage takes
106 * place in the form field specified during initialization.
108 * @method _storeStates
111 function _storeStates() {
113 var moduleName, moduleObj, initialStates = [], currentStates = [];
115 for (moduleName in _modules) {
116 if (YAHOO.lang.hasOwnProperty(_modules, moduleName)) {
117 moduleObj = _modules[moduleName];
118 initialStates.push(moduleName + "=" + moduleObj.initialState);
119 currentStates.push(moduleName + "=" + moduleObj.currentState);
123 _stateField.value = initialStates.join("&") + "|" + currentStates.join("&");
125 if (YAHOO.env.ua.webkit) {
126 _stateField.value += "|" + _fqstates.join(",");
131 * Sets the new currentState attribute of all modules depending on the new
132 * fully qualified state. Also notifies the modules which current state has
135 * @method _handleFQStateChange
136 * @param {string} fqstate Fully qualified state
139 function _handleFQStateChange(fqstate) {
141 var i, len, moduleName, moduleObj, modules, states, tokens, currentState;
144 // Notifies all modules
145 for (moduleName in _modules) {
146 if (YAHOO.lang.hasOwnProperty(_modules, moduleName)) {
147 moduleObj = _modules[moduleName];
148 moduleObj.currentState = moduleObj.initialState;
149 moduleObj.onStateChange(unescape(moduleObj.currentState));
156 states = fqstate.split("&");
157 for (i = 0, len = states.length; i < len; i++) {
158 tokens = states[i].split("=");
159 if (tokens.length === 2) {
160 moduleName = tokens[0];
161 currentState = tokens[1];
162 modules[moduleName] = currentState;
166 for (moduleName in _modules) {
167 if (YAHOO.lang.hasOwnProperty(_modules, moduleName)) {
168 moduleObj = _modules[moduleName];
169 currentState = modules[moduleName];
170 if (!currentState || moduleObj.currentState !== currentState) {
171 moduleObj.currentState = currentState || moduleObj.initialState;
172 moduleObj.onStateChange(unescape(moduleObj.currentState));
179 * Update the IFrame with our new state.
181 * @method _updateIFrame
183 * @return {boolean} true if successful. false otherwise.
185 function _updateIFrame (fqstate) {
189 html = '<html><body><div id="state">' + fqstate + '</div></body></html>';
192 doc = _histFrame.contentWindow.document;
203 * Periodically checks whether our internal IFrame is ready to be used.
205 * @method _checkIframeLoaded
208 function _checkIframeLoaded() {
210 var doc, elem, fqstate, hash;
212 if (!_histFrame.contentWindow || !_histFrame.contentWindow.document) {
213 // Check again in 10 msec...
214 setTimeout(_checkIframeLoaded, 10);
218 // Start the thread that will have the responsibility to
219 // periodically check whether a navigate operation has been
220 // requested on the main window. This will happen when
221 // YAHOO.util.History.navigate has been called or after
222 // the user has hit the back/forward button.
224 doc = _histFrame.contentWindow.document;
225 elem = doc.getElementById("state");
226 // We must use innerText, and not innerHTML because our string contains
227 // the "&" character (which would end up being escaped as "&") and
228 // the string comparison would fail...
229 fqstate = elem ? elem.innerText : null;
233 setInterval(function () {
235 var newfqstate, states, moduleName, moduleObj, newHash, historyLength;
237 doc = _histFrame.contentWindow.document;
238 elem = doc.getElementById("state");
239 // See my comment above about using innerText instead of innerHTML...
240 newfqstate = elem ? elem.innerText : null;
242 newHash = _getHash();
244 if (newfqstate !== fqstate) {
246 fqstate = newfqstate;
247 _handleFQStateChange(fqstate);
251 for (moduleName in _modules) {
252 if (YAHOO.lang.hasOwnProperty(_modules, moduleName)) {
253 moduleObj = _modules[moduleName];
254 states.push(moduleName + "=" + moduleObj.initialState);
257 newHash = states.join("&");
262 // Allow the state to be bookmarked by setting the top window's
263 // URL fragment identifier. Note that here, we are on IE, and
264 // IE does not touch the browser history when setting the hash
265 // (unlike all the other browsers). I used to write:
266 // top.location.replace( "#" + hash );
267 // but this had a side effect when the page was not the top frame.
268 top.location.hash = newHash;
273 } else if (newHash !== hash) {
275 // The hash has changed. The user might have clicked on a link,
276 // or modified the URL directly, or opened the same application
277 // bookmarked in a specific state using a bookmark. However, we
278 // know the hash change was not caused by a hit on the back or
279 // forward buttons, or by a call to navigate() (because it would
280 // have been handled above) We must handle these cases, which is
281 // why we also need to keep track of hash changes on IE!
283 // Note that IE6 has some major issues with this kind of user
284 // interaction (the history stack gets completely messed up)
285 // but it seems to work fine on IE7.
289 // Now, store a new history entry. The following will cause the
290 // code above to execute, doing all the dirty work for us...
291 _updateIFrame(newHash);
297 YAHOO.util.History.onLoadEvent.fire();
301 * Finish up the initialization of the Browser History Manager.
303 * @method _initialize
306 function _initialize() {
308 var i, len, parts, tokens, moduleName, moduleObj, initialStates, initialState, currentStates, currentState, counter, hash;
310 // Decode the content of our storage field...
311 parts = _stateField.value.split("|");
313 if (parts.length > 1) {
315 initialStates = parts[0].split("&");
316 for (i = 0, len = initialStates.length; i < len; i++) {
317 tokens = initialStates[i].split("=");
318 if (tokens.length === 2) {
319 moduleName = tokens[0];
320 initialState = tokens[1];
321 moduleObj = _modules[moduleName];
323 moduleObj.initialState = initialState;
328 currentStates = parts[1].split("&");
329 for (i = 0, len = currentStates.length; i < len; i++) {
330 tokens = currentStates[i].split("=");
331 if (tokens.length >= 2) {
332 moduleName = tokens[0];
333 currentState = tokens[1];
334 moduleObj = _modules[moduleName];
336 moduleObj.currentState = currentState;
342 if (parts.length > 2) {
343 _fqstates = parts[2].split(",");
346 if (YAHOO.env.ua.ie) {
348 if (typeof document.documentMode === "undefined" || document.documentMode < 8) {
350 // IE < 8 or IE8 in quirks mode or IE7 standards mode
351 _checkIframeLoaded();
355 // IE8 in IE8 standards mode
356 YAHOO.util.Event.on(top, "hashchange",
358 var hash = _getHash();
359 _handleFQStateChange(hash);
364 YAHOO.util.History.onLoadEvent.fire();
370 // Start the thread that will have the responsibility to
371 // periodically check whether a navigate operation has been
372 // requested on the main window. This will happen when
373 // YAHOO.util.History.navigate has been called or after
374 // the user has hit the back/forward button.
376 // On Safari 1.x and 2.0, the only way to catch a back/forward
377 // operation is to watch history.length... We basically exploit
378 // what I consider to be a bug (history.length is not supposed
379 // to change when going back/forward in the history...) This is
380 // why, in the following thread, we first compare the hash,
381 // because the hash thing will be fixed in the next major
382 // version of Safari. So even if they fix the history.length
383 // bug, all this will still work!
384 counter = history.length;
386 // On Gecko and Opera, we just need to watch the hash...
389 setInterval(function () {
391 var state, newHash, newCounter;
393 newHash = _getHash();
394 newCounter = history.length;
395 if (newHash !== hash) {
397 counter = newCounter;
398 _handleFQStateChange(hash);
400 } else if (newCounter !== counter && YAHOO.env.ua.webkit) {
402 counter = newCounter;
403 state = _fqstates[counter - 1];
404 _handleFQStateChange(state);
411 YAHOO.util.History.onLoadEvent.fire();
418 * Fired when the Browser History Manager is ready. If you subscribe to
419 * this event after the Browser History Manager has been initialized,
420 * it will not fire. Therefore, it is recommended to use the onReady
426 onLoadEvent: new YAHOO.util.CustomEvent("onLoad"),
429 * Executes the supplied callback when the Browser History Manager is
430 * ready. This will execute immediately if called after the Browser
431 * History Manager onLoad event has fired.
434 * @param {function} fn what to execute when the Browser History Manager is ready.
435 * @param {object} obj an optional object to be passed back as a parameter to fn.
436 * @param {boolean|object} overrideContext If true, the obj passed in becomes fn's execution scope.
439 onReady: function (fn, obj, overrideContext) {
443 setTimeout(function () {
445 if (overrideContext) {
446 if (overrideContext === true) {
449 ctx = overrideContext;
452 fn.call(ctx, "onLoad", [], obj);
457 YAHOO.util.History.onLoadEvent.subscribe(fn, obj, overrideContext);
463 * Registers a new module.
466 * @param {string} module Non-empty string uniquely identifying the
467 * module you wish to register.
468 * @param {string} initialState The initial state of the specified
469 * module corresponding to its earliest history entry.
470 * @param {function} onStateChange Callback called when the
471 * state of the specified module has changed.
472 * @param {object} obj An arbitrary object that will be passed as a
473 * parameter to the handler.
474 * @param {boolean} overrideContext If true, the obj passed in becomes the
475 * execution scope of the listener.
477 register: function (module, initialState, onStateChange, obj, overrideContext) {
479 var scope, wrappedFn;
481 if (typeof module !== "string" || YAHOO.lang.trim(module) === "" ||
482 typeof initialState !== "string" ||
483 typeof onStateChange !== "function") {
484 throw new Error("Missing or invalid argument");
487 if (_modules[module]) {
488 // Here, we used to throw an exception. However, users have
489 // complained about this behavior, so we now just return.
493 // Note: A module CANNOT be registered after calling
494 // YAHOO.util.History.initialize. Indeed, we set the initial state
495 // of each registered module in YAHOO.util.History.initialize.
496 // If you could register a module after initializing the Browser
497 // History Manager, you would not read the correct state using
498 // YAHOO.util.History.getCurrentState when coming back to the
499 // page using the back button.
501 throw new Error("All modules must be registered before calling YAHOO.util.History.initialize");
504 // Make sure the strings passed in do not contain our separators "," and "|"
505 module = escape(module);
506 initialState = escape(initialState);
508 // If the user chooses to override the scope, we use the
509 // custom object passed in as the execution scope.
511 if (overrideContext === true) {
514 scope = overrideContext;
517 wrappedFn = function (state) {
518 return onStateChange.call(scope, state, obj);
523 initialState: initialState,
524 currentState: initialState,
525 onStateChange: wrappedFn
530 * Initializes the Browser History Manager. Call this method
531 * from a script block located right after the opening body tag.
534 * @param {string|HTML Element} stateField <input type="hidden"> used
535 * to store application states. Must be in the static markup.
536 * @param {string|HTML Element} histFrame IFrame used to store
537 * the history (only required on Internet Explorer)
540 initialize: function (stateField, histFrame) {
543 // The browser history manager has already been initialized.
547 if (YAHOO.env.ua.opera && typeof history.navigationMode !== "undefined") {
548 // Disable Opera's fast back/forward navigation mode and puts
549 // it in compatible mode. This makes anchor-based history
550 // navigation work after the page has been navigated away
551 // from and re-activated, at the cost of slowing down
552 // back/forward navigation to and from that page.
553 history.navigationMode = "compatible";
556 if (typeof stateField === "string") {
557 stateField = document.getElementById(stateField);
561 stateField.tagName.toUpperCase() !== "TEXTAREA" &&
562 (stateField.tagName.toUpperCase() !== "INPUT" ||
563 stateField.type !== "hidden" &&
564 stateField.type !== "text")) {
565 throw new Error("Missing or invalid argument");
568 _stateField = stateField;
570 // IE < 8 or IE8 in quirks mode or IE7 standards mode
571 if (YAHOO.env.ua.ie && (typeof document.documentMode === "undefined" || document.documentMode < 8)) {
573 if (typeof histFrame === "string") {
574 histFrame = document.getElementById(histFrame);
577 if (!histFrame || histFrame.tagName.toUpperCase() !== "IFRAME") {
578 throw new Error("Missing or invalid argument");
581 _histFrame = histFrame;
584 // Note that the event utility MUST be included inline in the page.
585 // If it gets loaded later (which you may want to do to improve the
586 // loading speed of your site), the onDOMReady event never fires,
587 // and the history library never gets fully initialized.
588 YAHOO.util.Event.onDOMReady(_initialize);
592 * Call this method when you want to store a new entry in the browser's history.
595 * @param {string} module Non-empty string representing your module.
596 * @param {string} state String representing the new state of the specified module.
597 * @return {boolean} Indicates whether the new state was successfully added to the history.
600 navigate: function (module, state) {
604 if (typeof module !== "string" || typeof state !== "string") {
605 throw new Error("Missing or invalid argument");
609 states[module] = state;
611 return YAHOO.util.History.multiNavigate(states);
615 * Call this method when you want to store a new entry in the browser's history.
617 * @method multiNavigate
618 * @param {object} states Associative array of module-state pairs to set simultaneously.
619 * @return {boolean} Indicates whether the new state was successfully added to the history.
622 multiNavigate: function (states) {
624 var currentStates, moduleName, moduleObj, currentState, fqstate;
626 if (typeof states !== "object") {
627 throw new Error("Missing or invalid argument");
631 throw new Error("The Browser History Manager is not initialized");
634 for (moduleName in states) {
635 if (!_modules[moduleName]) {
636 throw new Error("The following module has not been registered: " + moduleName);
640 // Generate our new full state string mod1=xxx&mod2=yyy
643 for (moduleName in _modules) {
644 if (YAHOO.lang.hasOwnProperty(_modules, moduleName)) {
645 moduleObj = _modules[moduleName];
646 if (YAHOO.lang.hasOwnProperty(states, moduleName)) {
647 currentState = states[unescape(moduleName)];
649 currentState = unescape(moduleObj.currentState);
652 // Make sure the strings passed in do not contain our separators "," and "|"
653 moduleName = escape(moduleName);
654 currentState = escape(currentState);
656 currentStates.push(moduleName + "=" + currentState);
660 fqstate = currentStates.join("&");
662 if (YAHOO.env.ua.ie && (typeof document.documentMode === "undefined" || document.documentMode < 8)) {
664 return _updateIFrame(fqstate);
668 // Known bug: On Safari 1.x and 2.0, if you have tab browsing
669 // enabled, Safari will show an endless loading icon in the
670 // tab. This has apparently been fixed in recent WebKit builds.
671 // One work around found by Dav Glass is to submit a form that
672 // points to the same document. This indeed works on Safari 1.x
673 // and 2.0 but creates bigger problems on WebKit. So for now,
674 // we'll consider this an acceptable bug, and hope that Apple
675 // comes out with their next version of Safari very soon.
676 top.location.hash = fqstate;
677 if (YAHOO.env.ua.webkit) {
678 // The following two lines are only useful for Safari 1.x
679 // and 2.0. Recent nightly builds of WebKit do not require
680 // that, but unfortunately, it is not easy to differentiate
681 // between the two. Once Safari 2.0 departs the A-grade
682 // list, we can remove the following two lines...
683 _fqstates[history.length] = fqstate;
693 * Returns the current state of the specified module.
695 * @method getCurrentState
696 * @param {string} module Non-empty string representing your module.
697 * @return {string} The current state of the specified module.
700 getCurrentState: function (module) {
704 if (typeof module !== "string") {
705 throw new Error("Missing or invalid argument");
709 throw new Error("The Browser History Manager is not initialized");
712 moduleObj = _modules[module];
714 throw new Error("No such registered module: " + module);
717 return unescape(moduleObj.currentState);
721 * Returns the state of a module according to the URL fragment
722 * identifier. This method is useful to initialize your modules
723 * if your application was bookmarked from a particular state.
725 * @method getBookmarkedState
726 * @param {string} module Non-empty string representing your module.
727 * @return {string} The bookmarked state of the specified module.
730 getBookmarkedState: function (module) {
732 var i, len, idx, hash, states, tokens, moduleName;
734 if (typeof module !== "string") {
735 throw new Error("Missing or invalid argument");
738 // Use location.href instead of location.hash which is already
739 // URL-decoded, which creates problems if the state value
740 // contained special characters...
741 idx = top.location.href.indexOf("#");
743 hash = top.location.href.substr(idx + 1);
744 states = hash.split("&");
745 for (i = 0, len = states.length; i < len; i++) {
746 tokens = states[i].split("=");
747 if (tokens.length === 2) {
748 moduleName = tokens[0];
749 if (moduleName === module) {
750 return unescape(tokens[1]);
760 * Returns the value of the specified query string parameter.
761 * This method is not used internally by the Browser History Manager.
762 * However, it is provided here as a helper since many applications
763 * using the Browser History Manager will want to read the value of
764 * url parameters to initialize themselves.
766 * @method getQueryStringParameter
767 * @param {string} paramName Name of the parameter we want to look up.
768 * @param {string} queryString Optional URL to look at. If not specified,
769 * this method uses the URL in the address bar.
770 * @return {string} The value of the specified parameter, or null.
773 getQueryStringParameter: function (paramName, url) {
775 var i, len, idx, queryString, params, tokens;
777 url = url || top.location.href;
779 idx = url.indexOf("?");
780 queryString = idx >= 0 ? url.substr(idx + 1) : url;
782 // Remove the hash if any
783 idx = queryString.lastIndexOf("#");
784 queryString = idx >= 0 ? queryString.substr(0, idx) : queryString;
786 params = queryString.split("&");
788 for (i = 0, len = params.length; i < len; i++) {
789 tokens = params[i].split("=");
790 if (tokens.length >= 2) {
791 if (tokens[0] === paramName) {
792 return unescape(tokens[1]);
803 YAHOO.register("history", YAHOO.util.History, {version: "2.8.0r4", build: "2449"});