API: history YAHOO.util.History (YUI Library)

# Yahoo! UI Library

### Browser History Manager 2.8.1

Yahoo! UI Library > history > YAHOO.util.History
Search:
Filters Show Private Show Protected Show Deprecated

## 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.

#### _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

#### _initialize

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

#### _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.

#### _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)

#### 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 , overrideContext )`
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.
  `overrideContext <boolean|object>` If true, the obj passed in becomes fn's execution scope.

#### register

`void register ( module , initialState , onStateChange , obj , overrideContext )`
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.
  `overrideContext <boolean>` If true, the obj passed in becomes the execution scope of the listener.

### 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 © 2010 Yahoo! Inc. All rights reserved.