Yahoo! UI Library

Browser History Manager  2.5.0

Yahoo! UI Library > history > YAHOO.util.History

Show Private Show Protected

Class YAHOO.util.History

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.

Constructor

YAHOO.util.History ( )

Properties

_fqstates - private array

List of fully qualified states. This is used only by Safari.
Default Value: []

_histFrame - private HTMLIFrameElement

Our hidden IFrame used to store the browsing history.
Default Value: null

_initialized - private boolean

Flag used to tell whether YAHOO.util.History.initialize has been called.
Default Value: false

_modules - private array

List of registered modules.
Default Value: []

_stateField - private HTMLInputElement|HTMLTextAreaElement

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.
Default Value: null

Methods

_checkIframeLoaded

private void _checkIframeLoaded ( )
Periodically checks whether our internal IFrame is ready to be used.
Returns: void

_getHash

private string _getHash ( )
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.
Returns: string
The hash portion of the document's location

_handleFQStateChange

private void _handleFQStateChange ( fqstate )
Sets the new currentState attribute of all modules depending on the new fully qualified state. Also notifies the modules which current state has changed.
Parameters:
fqstate <string> Fully qualified state
Returns: void

_initialize

private void _initialize ( )
Finish up the initialization of the Browser History Manager.
Returns: void

_storeStates

private void _storeStates ( )
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.
Returns: void

_updateIFrame

private boolean _updateIFrame ( )
Update the IFrame with our new state.
Returns: boolean
true if successful. false otherwise.

getBookmarkedState

string getBookmarkedState ( module )
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.
Parameters:
module <string> Non-empty string representing your module.
Returns: string
The bookmarked state of the specified module.

getCurrentState

string getCurrentState ( module )
Returns the current state of the specified module.
Parameters:
module <string> Non-empty string representing your module.
Returns: string
The current state of the specified module.

getQueryStringParameter

string getQueryStringParameter ( paramName , queryString )
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.
Parameters:
paramName <string> Name of the parameter we want to look up.
queryString <string> Optional URL to look at. If not specified, this method uses the URL in the address bar.
Returns: string
The value of the specified parameter, or null.

initialize

void initialize ( stateField , histFrame )
Initializes the Browser History Manager. Call this method from a script block located right after the opening body tag.
Parameters:
stateField <string|HTML Element> used to store application states. Must be in the static markup.
histFrame <string|HTML Element> IFrame used to store the history (only required on Internet Explorer)
Returns: void

multiNavigate

boolean multiNavigate ( states )
Call this method when you want to store a new entry in the browser's history.
Parameters:
states <object> Associative array of module-state pairs to set simultaneously.
Returns: boolean
Indicates whether the new state was successfully added to the history.

navigate

boolean navigate ( module , state )
Call this method when you want to store a new entry in the browser's history.
Parameters:
module <string> Non-empty string representing your module.
state <string> String representing the new state of the specified module.
Returns: boolean
Indicates whether the new state was successfully added to the history.

onReady

void onReady ( fn , obj , override )
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.
Parameters:
fn <function> what to execute when the Browser History Manager is ready.
obj <object> an optional object to be passed back as a parameter to fn.
override <boolean|object> If true, the obj passed in becomes fn's execution scope.
Returns: void

register

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

Events

onLoadEvent

onLoadEvent ( )
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.


Copyright © 2007 Yahoo! Inc. All rights reserved.