# Yahoo! UI Library

### Browser History Manager 2.3.1

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

#### _bhmReady `- private boolean`

Flag used to tell whether the Browser History Manager is ready.
Default Value: false

#### _fqstates `- private array`

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

#### _iframe `- 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: []

#### _storageField `- 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

#### _storageFieldReady `- private boolean`

Flag used to tell whether the storage field is ready to be used.
Default Value: false

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

#### _trim

`private string _trim ( str )`
Trims a string.

Parameters:
  `str <string>` The string to be trimmed.

Returns: `string`
  The trimmed string

#### 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 ( iframeTarget )`
Initializes the Browser History Manager. Call this method from a script block located right after the opening body tag.

Parameters:
  `iframeTarget <string>` Optional - Path to an existing HTML document accessible from the same domain. If not specified, defaults to "blank.html". This is only useful if you use https.

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.

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

Copyright © 2007 Yahoo! Inc. All rights reserved.