/*
|
Copyright (c) 2007, Yahoo! Inc. All rights reserved.
|
Code licensed under the BSD License:
|
http://developer.yahoo.net/yui/license.txt
|
version: 2.2.0
|
*/
|
/**
|
*
|
* 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.
|
*
|
* @module history
|
* @requires yahoo,event
|
* @namespace YAHOO.util
|
* @title Browser History Manager
|
* @experimental
|
*/
|
|
/**
|
* 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() {
|
|
/**
|
* String identifying which browser we are in.
|
* Different code is run depending on which browser you are using.
|
*
|
* @property _browser
|
* @type string
|
* @default "unknown"
|
* @private
|
*/
|
var _browser = "unknown";
|
|
/**
|
* Our hidden IFrame used to store the browsing history.
|
*
|
* @property _iframe
|
* @type HTMLIFrameElement
|
* @default null
|
* @private
|
*/
|
var _iframe = 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 _storageField
|
* @type HTMLInputElement|HTMLTextAreaElement
|
* @default null
|
* @private
|
*/
|
var _storageField = null;
|
|
/**
|
* Flag used to tell whether YAHOO.util.History.initialize has been called.
|
*
|
* @property _initialized
|
* @type boolean
|
* @default false
|
* @private
|
*/
|
var _initialized = false;
|
|
/**
|
* Flag used to tell whether the storage field is ready to be used.
|
*
|
* @property _storageFieldReady
|
* @type boolean
|
* @default false
|
* @private
|
*/
|
var _storageFieldReady = false;
|
|
/**
|
* Flag used to tell whether the Browser History Manager is ready.
|
*
|
* @property _bhmReady
|
* @type boolean
|
* @default false
|
* @private
|
*/
|
var _bhmReady = 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 = [];
|
|
/**
|
* Trims a string.
|
*
|
* @method _trim
|
* @param {string} str The string to be trimmed.
|
* @return {string} The trimmed string
|
* @private
|
*/
|
function _trim( str ) {
|
return str.replace( /^\s*(\S*(\s+\S+)*)\s*$/, "$1" );
|
}
|
|
/**
|
* 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 href = top.location.href;
|
var idx = href.indexOf( "#" );
|
return idx >= 0 ? href.substr( idx+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 initialStates = [];
|
var currentStates = [];
|
for ( var moduleName in _modules ) {
|
var moduleObj = _modules[moduleName];
|
initialStates.push( moduleName + "=" + moduleObj.initialState );
|
currentStates.push( moduleName + "=" + moduleObj.currentState );
|
}
|
_storageField.value = initialStates.join( "&" ) + "|" + currentStates.join( "&" );
|
if ( _browser == "safari" ) {
|
_storageField.value += "|" + _fqstates.join( "," );
|
}
|
}
|
|
/**
|
* Periodically checks whether our internal IFrame is ready to be used.
|
*
|
* @method _checkIframeLoaded
|
* @private
|
*/
|
function _checkIframeLoaded() {
|
if ( !_iframe.contentWindow || !_iframe.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.
|
|
var doc = _iframe.contentWindow.document;
|
var elem = doc.getElementById( "state" );
|
// We must use innerText, and not innerHTML because our string contains
|
// the "&" character (which would end up being escaped as "&") and
|
// the string comparison would fail...
|
var fqstate = elem ? elem.innerText : null;
|
|
setInterval( function() {
|
doc = _iframe.contentWindow.document;
|
elem = doc.getElementById( "state" );
|
// See my comment above about using innerText instead of innerHTML...
|
var newfqstate = elem ? elem.innerText : null;
|
if ( newfqstate != fqstate ) {
|
fqstate = newfqstate;
|
_handleFQStateChange( fqstate );
|
|
var hash;
|
if ( !fqstate ) {
|
var states = [];
|
for ( var moduleName in _modules ) {
|
var moduleObj = _modules[moduleName];
|
states.push( moduleName + "=" + moduleObj.initialState );
|
}
|
hash = states.join( "&" );
|
} else {
|
hash = fqstate;
|
}
|
|
// Allow the state to be bookmarked without messing up the browser history...
|
top.location.replace( "#" + hash );
|
|
_storeStates();
|
}
|
}, 50 );
|
|
_bhmReady = true;
|
|
YAHOO.util.History.onLoadEvent.fire();
|
}
|
|
/**
|
* 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 moduleName, moduleObj, currentState;
|
|
if ( !fqstate ) {
|
// Notifies all modules
|
for ( moduleName in _modules ) {
|
moduleObj = _modules[moduleName];
|
moduleObj.currentState = moduleObj.initialState;
|
moduleObj.onStateChange( moduleObj.currentState );
|
}
|
return;
|
}
|
|
var modules = [];
|
var states = fqstate.split( "&" );
|
for ( var idx=0, len=states.length ; idx<len ; idx++ ) {
|
var tokens = states[idx].split( "=" );
|
if ( tokens.length == 2 ) {
|
moduleName = tokens[0];
|
currentState = tokens[1];
|
modules[moduleName] = currentState;
|
}
|
}
|
|
for ( moduleName in _modules ) {
|
moduleObj = _modules[moduleName];
|
currentState = modules[moduleName];
|
if ( !currentState || moduleObj.currentState != currentState ) {
|
moduleObj.currentState = currentState || moduleObj.initialState;
|
moduleObj.onStateChange( moduleObj.currentState );
|
}
|
}
|
}
|
|
/**
|
* Finish up the initialization of the Browser History Manager.
|
*
|
* @method _initialize
|
* @private
|
*/
|
function _initialize() {
|
|
_storageField = document.getElementById( "yui_hist_field" );
|
|
// Decode the content of our storage field...
|
var parts = _storageField.value.split( "|" );
|
|
if ( parts.length > 1 ) {
|
|
var idx, len, tokens, moduleName, moduleObj;
|
|
var initialStates = parts[0].split( "&" );
|
for ( idx=0, len=initialStates.length ; idx<len ; idx++ ) {
|
tokens = initialStates[idx].split( "=" );
|
if ( tokens.length == 2 ) {
|
moduleName = tokens[0];
|
var initialState = tokens[1];
|
moduleObj = _modules[moduleName];
|
if ( moduleObj ) {
|
moduleObj.initialState = initialState;
|
}
|
}
|
}
|
|
var currentStates = parts[1].split( "&" );
|
for ( idx=0, len=currentStates.length ; idx<len ; idx++ ) {
|
tokens = currentStates[idx].split( "=" );
|
if ( tokens.length >= 2 ) {
|
moduleName = tokens[0];
|
var currentState = tokens[1];
|
moduleObj = _modules[moduleName];
|
if ( moduleObj ) {
|
moduleObj.currentState = currentState;
|
}
|
}
|
}
|
}
|
|
if ( parts.length > 2 ) {
|
_fqstates = parts[2].split( "," );
|
}
|
|
_storageFieldReady = true;
|
|
if ( _browser == "msie" ) {
|
|
_iframe = document.getElementById( "yui_hist_iframe" );
|
_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!
|
var counter = history.length;
|
|
// On Gecko and Opera, we just need to watch the hash...
|
var hash = _getHash();
|
|
setInterval( function() {
|
var state;
|
var newHash = _getHash();
|
var newCounter = history.length;
|
if ( newHash != hash ) {
|
hash = newHash;
|
counter = newCounter;
|
_handleFQStateChange( hash );
|
_storeStates();
|
} else if ( newCounter != counter ) {
|
// If we ever get here, we should be on Safari...
|
hash = newHash;
|
counter = newCounter;
|
state = _fqstates[counter-1];
|
_handleFQStateChange( state );
|
_storeStates();
|
}
|
}, 50 );
|
|
_bhmReady = true;
|
|
YAHOO.util.History.onLoadEvent.fire();
|
}
|
}
|
|
// Simple browser detection code
|
// After talking with Matt Sweeney, I moved back to using the
|
// user agent string instead of doing browser detection.
|
var ua = navigator.userAgent.toLowerCase();
|
if ( ua.indexOf( "opera" ) != -1 ) {
|
// Opera (check first in case of spoof)
|
_browser = "opera";
|
} else if ( ua.indexOf( "msie" ) != -1 ) {
|
// Microsoft Internet Explorer and derivatives...
|
_browser = "msie";
|
} else if ( ua.indexOf( "safari" ) != -1 ) {
|
// Safari (check before Gecko because it includes "like Gecko")
|
_browser = "safari";
|
} else if ( ua.indexOf( "gecko" ) != -1 ) {
|
// Gecko
|
_browser = "gecko";
|
}
|
|
return {
|
|
/**
|
* Fired when the Browser History Manager is ready.
|
*
|
* @event onLoadEvent
|
*/
|
onLoadEvent : new YAHOO.util.CustomEvent( "onLoad" ),
|
|
/**
|
* 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.
|
*/
|
register : function( module, initialState, onStateChange ) {
|
if ( typeof module != "string" || _trim( module ) === "" ||
|
typeof initialState != "string" ||
|
typeof onStateChange != "function" ) {
|
throw new Error( "Missing or invalid argument passed to YAHOO.util.History.register" );
|
}
|
|
if ( _modules[module] ) {
|
throw new Error( "A module cannot be registered twice" );
|
}
|
|
// 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 );
|
|
_modules[module] = {
|
name : module,
|
initialState : initialState,
|
currentState : initialState,
|
onStateChange : onStateChange
|
};
|
},
|
|
/**
|
* Initializes the Browser History Manager. Call this method
|
* from a script block located right after the opening body tag.
|
*
|
* @method initialize
|
* @param {string} iframeTarget Optional - Path to an existing
|
* HTML document accessible from the same domain. If not
|
* specified, defaults to "blank.html"
|
* @public
|
*/
|
initialize : function( iframeTarget ) {
|
// Return if the browser history manager has already been initialized
|
if ( _initialized ) {
|
return;
|
}
|
|
if ( _browser == "unknown" ) {
|
throw new Error( "Your web browser is not supported by the Browser History Manager" );
|
}
|
|
if ( !iframeTarget ) {
|
iframeTarget = "blank.html";
|
}
|
|
if ( typeof iframeTarget != "string" || _trim( iframeTarget ) === "" ) {
|
throw new Error( "Invalid argument passed to YAHOO.util.History.initialize" );
|
}
|
|
document.write( '<input type="hidden" id="yui_hist_field">' );
|
if ( _browser == "msie" ) {
|
// Pointing the IFrame to a file on the server is absolutely
|
// essential. I tried to point it to nothing (by setting
|
// src="") and create the initial entry in the browser
|
// history (by using document.write) but it did not work
|
// when coming back to the page... Also, the file must exist
|
// on the server!
|
document.write( '<iframe id="yui_hist_iframe" src="' + iframeTarget + '" style="position:absolute;visibility:hidden;"></iframe>' );
|
}
|
|
// We have to wait for the window's onload handler. Otherwise, our
|
// hidden form field will always be empty (i.e. the browser won't
|
// have had enough time to restore the session)
|
YAHOO.util.Event.addListener( window, "load", _initialize );
|
|
_initialized = true;
|
},
|
|
/**
|
* 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 ) {
|
if ( typeof module != "string" || typeof state != "string" ) {
|
throw new Error( "Missing or invalid argument passed to YAHOO.util.History.navigate" );
|
}
|
|
if ( !_bhmReady ) {
|
throw new Error( "The Browser History Manager is not initialized" );
|
}
|
|
if ( !_modules[module] ) {
|
throw new Error( "The following module has not been registered: " + module );
|
}
|
|
// Make sure the strings passed in do not contain our separators "," and "|"
|
module = escape( module );
|
state = escape( state );
|
|
// Generate our new full state string mod1=xxx&mod2=yyy
|
var currentStates = [];
|
for ( var moduleName in _modules ) {
|
var moduleObj = _modules[moduleName];
|
var currentState = ( moduleName == module ) ? state : moduleObj.currentState;
|
currentStates.push( moduleName + "=" + currentState );
|
}
|
|
var fqstate = currentStates.join( "&" );
|
|
if ( _browser == "msie" ) {
|
|
// Add a new entry to the browser's history...
|
var html = '<html><body><div id="state">' + fqstate + '</div></body></html>';
|
try {
|
var doc = _iframe.contentWindow.document;
|
doc.open();
|
doc.write( html );
|
doc.close();
|
} catch ( e ) {
|
return false;
|
}
|
|
} 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 ( _browser == "safari" ) {
|
// 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 ) {
|
if ( typeof module != "string" ) {
|
throw new Error( "Missing or invalid argument passed to YAHOO.util.History.getCurrentState" );
|
}
|
|
if ( !_storageFieldReady ) {
|
throw new Error( "The Browser History Manager is not initialized" );
|
}
|
|
var 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 ) {
|
if ( typeof module != "string" ) {
|
throw new Error( "Missing or invalid argument passed to YAHOO.util.History.getBookmarkedState" );
|
}
|
|
var hash = top.location.hash.substr(1);
|
var states = hash.split( "&" );
|
for ( var idx=0, len=states.length ; idx<len ; idx++ ) {
|
var tokens = states[idx].split( "=" );
|
if ( tokens.length == 2 ) {
|
var moduleName = tokens[0];
|
if ( moduleName == module ) {
|
return 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 ) {
|
url = url || top.location.href;
|
var idx = url.indexOf( "?" );
|
var queryString = idx >= 0 ? url.substr( idx+1 ) : url;
|
var params = queryString.split( "&" );
|
for ( var i=0, len=params.length ; i<len ; i++ ) {
|
var tokens = params[i].split( "=" );
|
if ( tokens.length >= 2 ) {
|
if ( tokens[0] == paramName ) {
|
return tokens[1];
|
}
|
}
|
}
|
return null;
|
}
|
|
};
|
|
} )();
|
YAHOO.register("history", YAHOO.util.History, {version: "2.2.0", build: "127"});
|
