webgui/www/extras/yui/docs/YAHOO.util.History.html
JT Smith 20f8df1291 upgrading to YUI 2.6
data tables are going to need some work yet, but the other stuff seems to be working 100%
2008-10-22 23:53:29 +00:00

1140 lines
54 KiB
HTML

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
<html>
<head>
<title>API: history YAHOO.util.History (YUI Library)</title>
<link rel="stylesheet" type="text/css" href="assets/api.css">
<script type="text/javascript" src="assets/api-js"></script>
<script type="text/javascript" src="assets/ac-js"></script>
</head>
<body id="yahoo-com">
<div id="doc3" class="yui-t2">
<div id="hd">
<a href="http://developer.yahoo.com/yui/"><h1>Yahoo! UI Library</h1></a>
<h3>Browser History Manager&nbsp; <span class="subtitle">2.6.0</span></h3>
<p>
<a href="./index.html">Yahoo! UI Library</a>
&gt; <a href="./module_history.html">history</a>
&gt; YAHOO.util.History
</p>
</div>
<div id="bd">
<div id="yui-main">
<div class="yui-b">
<form name="yui-classopts-form">
<span id="classopts"><input type="checkbox" name="showprivate" id="showprivate" /> <label for="showprivate">Show Private</label></span>
<span id="classopts"><input type="checkbox" name="showprotected" id="showprotected" /> <label for="showprotected">Show Protected</label></span>
<span id="classopts"><input type="checkbox" name="showdeprecated" id="showdeprecated" /> <label for="showdeprecated">Show Deprecated</label></span>
</form>
<h2>
Class <b>YAHOO.util.History</b>
<span class="extends">
</span>
<span class="extends">
</span>
</code>
</h2>
<!-- class tree goes here -->
<div class="summary description">
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.
</div>
<div class="section field details">
<h3 id="properties">Properties</h3>
<div class="content">
<div class="private">
<h4><a name="property__fqstates">_fqstates</a>
<code>- private array</code>
</h4>
<div class="detail">
<div class="description">
List of fully qualified states. This is used only by Safari.
</div>
</div>
<div class="default">
Default Value: []
</div>
<hr />
</div>
<div class="private">
<h4><a name="property__histFrame">_histFrame</a>
<code>- private HTMLIFrameElement</code>
</h4>
<div class="detail">
<div class="description">
Our hidden IFrame used to store the browsing history.
</div>
</div>
<div class="default">
Default Value: null
</div>
<hr />
</div>
<div class="private">
<h4><a name="property__initialized">_initialized</a>
<code>- private boolean</code>
</h4>
<div class="detail">
<div class="description">
Flag used to tell whether YAHOO.util.History.initialize has been called.
</div>
</div>
<div class="default">
Default Value: false
</div>
<hr />
</div>
<div class="private">
<h4><a name="property__modules">_modules</a>
<code>- private array</code>
</h4>
<div class="detail">
<div class="description">
List of registered modules.
</div>
</div>
<div class="default">
Default Value: []
</div>
<hr />
</div>
<div class="private">
<h4><a name="property__stateField">_stateField</a>
<code>- private HTMLInputElement|HTMLTextAreaElement</code>
</h4>
<div class="detail">
<div class="description">
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.
</div>
</div>
<div class="default">
Default Value: null
</div>
<hr />
</div>
<div class="private">
<h4><a name="property_QUERY_STRING_REGEXP">QUERY_STRING_REGEXP</a>
<code>- private RegExp</code>
</h4>
<div class="detail">
<div class="description">
Regular expression used to parse "&"-separated key-value pairs
</div>
</div>
<hr />
</div>
</div>
</div>
<div class="section method details">
<h3 id="methods">Methods</h3>
<div class="content">
<div class="private">
<h4>
<a name="method__checkIframeLoaded">_checkIframeLoaded</a></h4>
<div class="detail">
<code>
private
void
<strong>_checkIframeLoaded</strong>
(
)
</code>
<div class="description">
Periodically checks whether our internal IFrame is ready to be used.
</div>
<div class="description">
<dl>
<dt>Returns:
<code>
void
</code></dt>
<dd></dd>
</dl>
</div>
</div>
<hr />
</div>
<div class="private">
<h4>
<a name="method__getHash">_getHash</a></h4>
<div class="detail">
<code>
private
string
<strong>_getHash</strong>
(
)
</code>
<div class="description">
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.
</div>
<div class="description">
<dl>
<dt>Returns:
<code>
string
</code></dt>
<dd>The hash portion of the document's location</dd>
</dl>
</div>
</div>
<hr />
</div>
<div class="private">
<h4>
<a name="method__handleFQStateChange">_handleFQStateChange</a></h4>
<div class="detail">
<code>
private
void
<strong>_handleFQStateChange</strong>
(
fqstate
)
</code>
<div class="description">
Sets the new currentState attribute of all modules depending on the new
fully qualified state. Also notifies the modules which current state has
changed.
</div>
<div class="description">
<dl>
<dt>Parameters:</dt>
<dd>
<code>fqstate &lt;string&gt;</code>
Fully qualified state
</dd>
</dl>
<dl>
<dt>Returns:
<code>
void
</code></dt>
<dd></dd>
</dl>
</div>
</div>
<hr />
</div>
<div class="private">
<h4>
<a name="method__initialize">_initialize</a></h4>
<div class="detail">
<code>
private
void
<strong>_initialize</strong>
(
)
</code>
<div class="description">
Finish up the initialization of the Browser History Manager.
</div>
<div class="description">
<dl>
<dt>Returns:
<code>
void
</code></dt>
<dd></dd>
</dl>
</div>
</div>
<hr />
</div>
<div class="private">
<h4>
<a name="method__storeStates">_storeStates</a></h4>
<div class="detail">
<code>
private
void
<strong>_storeStates</strong>
(
)
</code>
<div class="description">
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.
</div>
<div class="description">
<dl>
<dt>Returns:
<code>
void
</code></dt>
<dd></dd>
</dl>
</div>
</div>
<hr />
</div>
<div class="private">
<h4>
<a name="method__updateIFrame">_updateIFrame</a></h4>
<div class="detail">
<code>
private
boolean
<strong>_updateIFrame</strong>
(
)
</code>
<div class="description">
Update the IFrame with our new state.
</div>
<div class="description">
<dl>
<dt>Returns:
<code>
boolean
</code></dt>
<dd>true if successful. false otherwise.</dd>
</dl>
</div>
</div>
<hr />
</div>
<div class="">
<h4>
<a name="method_getBookmarkedState">getBookmarkedState</a></h4>
<div class="detail">
<code>
string
<strong>getBookmarkedState</strong>
(
module
)
</code>
<div class="description">
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.
</div>
<div class="description">
<dl>
<dt>Parameters:</dt>
<dd>
<code>module &lt;string&gt;</code>
Non-empty string representing your module.
</dd>
</dl>
<dl>
<dt>Returns:
<code>
string
</code></dt>
<dd>The bookmarked state of the specified module.</dd>
</dl>
</div>
</div>
<hr />
</div>
<div class="">
<h4>
<a name="method_getCurrentState">getCurrentState</a></h4>
<div class="detail">
<code>
string
<strong>getCurrentState</strong>
(
module
)
</code>
<div class="description">
Returns the current state of the specified module.
</div>
<div class="description">
<dl>
<dt>Parameters:</dt>
<dd>
<code>module &lt;string&gt;</code>
Non-empty string representing your module.
</dd>
</dl>
<dl>
<dt>Returns:
<code>
string
</code></dt>
<dd>The current state of the specified module.</dd>
</dl>
</div>
</div>
<hr />
</div>
<div class="">
<h4>
<a name="method_getQueryStringParameter">getQueryStringParameter</a></h4>
<div class="detail">
<code>
string
<strong>getQueryStringParameter</strong>
(
paramName
,
queryString
)
</code>
<div class="description">
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.
</div>
<div class="description">
<dl>
<dt>Parameters:</dt>
<dd>
<code>paramName &lt;string&gt;</code>
Name of the parameter we want to look up.
</dd>
<dd>
<code>queryString &lt;string&gt;</code>
Optional URL to look at. If not specified,
this method uses the URL in the address bar.
</dd>
</dl>
<dl>
<dt>Returns:
<code>
string
</code></dt>
<dd>The value of the specified parameter, or null.</dd>
</dl>
</div>
</div>
<hr />
</div>
<div class="">
<h4>
<a name="method_initialize">initialize</a></h4>
<div class="detail">
<code>
void
<strong>initialize</strong>
(
stateField
,
histFrame
)
</code>
<div class="description">
Initializes the Browser History Manager. Call this method
from a script block located right after the opening body tag.
</div>
<div class="description">
<dl>
<dt>Parameters:</dt>
<dd>
<code>stateField &lt;string|HTML Element&gt;</code>
<input type="hidden"> used
to store application states. Must be in the static markup.
</dd>
<dd>
<code>histFrame &lt;string|HTML Element&gt;</code>
IFrame used to store
the history (only required on Internet Explorer)
</dd>
</dl>
<dl>
<dt>Returns:
<code>
void
</code></dt>
<dd></dd>
</dl>
</div>
</div>
<hr />
</div>
<div class="">
<h4>
<a name="method_multiNavigate">multiNavigate</a></h4>
<div class="detail">
<code>
boolean
<strong>multiNavigate</strong>
(
states
)
</code>
<div class="description">
Call this method when you want to store a new entry in the browser's history.
</div>
<div class="description">
<dl>
<dt>Parameters:</dt>
<dd>
<code>states &lt;object&gt;</code>
Associative array of module-state pairs to set simultaneously.
</dd>
</dl>
<dl>
<dt>Returns:
<code>
boolean
</code></dt>
<dd>Indicates whether the new state was successfully added to the history.</dd>
</dl>
</div>
</div>
<hr />
</div>
<div class="">
<h4>
<a name="method_navigate">navigate</a></h4>
<div class="detail">
<code>
boolean
<strong>navigate</strong>
(
module
,
state
)
</code>
<div class="description">
Call this method when you want to store a new entry in the browser's history.
</div>
<div class="description">
<dl>
<dt>Parameters:</dt>
<dd>
<code>module &lt;string&gt;</code>
Non-empty string representing your module.
</dd>
<dd>
<code>state &lt;string&gt;</code>
String representing the new state of the specified module.
</dd>
</dl>
<dl>
<dt>Returns:
<code>
boolean
</code></dt>
<dd>Indicates whether the new state was successfully added to the history.</dd>
</dl>
</div>
</div>
<hr />
</div>
<div class="">
<h4>
<a name="method_onReady">onReady</a></h4>
<div class="detail">
<code>
void
<strong>onReady</strong>
(
fn
,
obj
,
override
)
</code>
<div class="description">
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.
</div>
<div class="description">
<dl>
<dt>Parameters:</dt>
<dd>
<code>fn &lt;function&gt;</code>
what to execute when the Browser History Manager is ready.
</dd>
<dd>
<code>obj &lt;object&gt;</code>
an optional object to be passed back as a parameter to fn.
</dd>
<dd>
<code>override &lt;boolean|object&gt;</code>
If true, the obj passed in becomes fn's execution scope.
</dd>
</dl>
<dl>
<dt>Returns:
<code>
void
</code></dt>
<dd></dd>
</dl>
</div>
</div>
<hr />
</div>
<div class="">
<h4>
<a name="method_register">register</a></h4>
<div class="detail">
<code>
void
<strong>register</strong>
(
module
,
initialState
,
onStateChange
,
obj
,
override
)
</code>
<div class="description">
Registers a new module.
</div>
<div class="description">
<dl>
<dt>Parameters:</dt>
<dd>
<code>module &lt;string&gt;</code>
Non-empty string uniquely identifying the
module you wish to register.
</dd>
<dd>
<code>initialState &lt;string&gt;</code>
The initial state of the specified
module corresponding to its earliest history entry.
</dd>
<dd>
<code>onStateChange &lt;function&gt;</code>
Callback called when the
state of the specified module has changed.
</dd>
<dd>
<code>obj &lt;object&gt;</code>
An arbitrary object that will be passed as a
parameter to the handler.
</dd>
<dd>
<code>override &lt;boolean&gt;</code>
If true, the obj passed in becomes the
execution scope of the listener.
</dd>
</dl>
<dl>
<dt>Returns:
<code>
void
</code></dt>
<dd></dd>
</dl>
</div>
</div>
<hr />
</div>
</div>
</div>
<div class="section method details">
<h3 id="events">Events</h3>
<div class="content">
<div class="">
<h4>
<a name="event_onLoadEvent">onLoadEvent</a></h4>
<div class="detail">
<code>
<strong>onLoadEvent</strong>
(
)
</code>
<div class="description">
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.
</div>
<div class="description">
</div>
</div>
<hr />
</div>
</div>
</div>
</div>
</div>
<div class="yui-b">
<div class="nav">
<div class="module">
<h4>Modules</h4>
<ul class="content">
<li class=""><a href="module_animation.html">animation</a></li>
<li class=""><a href="module_autocomplete.html">autocomplete</a></li>
<li class=""><a href="module_button.html">button</a></li>
<li class=""><a href="module_calendar.html">calendar</a></li>
<li class=""><a href="module_carousel.html">carousel</a></li>
<li class=""><a href="module_charts.html">charts</a></li>
<li class=""><a href="module_colorpicker.html">colorpicker</a></li>
<li class=""><a href="module_connection.html">connection</a></li>
<li class=""><a href="module_container.html">container</a></li>
<li class=""><a href="module_cookie.html">cookie</a></li>
<li class=""><a href="module_datasource.html">datasource</a></li>
<li class=""><a href="module_datatable.html">datatable</a></li>
<li class=""><a href="module_dom.html">dom</a></li>
<li class=""><a href="module_dragdrop.html">dragdrop</a></li>
<li class=""><a href="module_editor.html">editor</a></li>
<li class=""><a href="module_element.html">element</a></li>
<li class=""><a href="module_event.html">event</a></li>
<li class=""><a href="module_get.html">get</a></li>
<li class="selected"><a href="module_history.html">history</a></li>
<li class=""><a href="module_imagecropper.html">imagecropper</a></li>
<li class=""><a href="module_imageloader.html">imageloader</a></li>
<li class=""><a href="module_json.html">json</a></li>
<li class=""><a href="module_layout.html">layout</a></li>
<li class=""><a href="module_logger.html">logger</a></li>
<li class=""><a href="module_menu.html">menu</a></li>
<li class=""><a href="module_paginator.html">paginator</a></li>
<li class=""><a href="module_profiler.html">profiler</a></li>
<li class=""><a href="module_profilerviewer.html">profilerviewer</a></li>
<li class=""><a href="module_resize.html">resize</a></li>
<li class=""><a href="module_selector.html">selector</a></li>
<li class=""><a href="module_slider.html">slider</a></li>
<li class=""><a href="module_tabview.html">tabview</a></li>
<li class=""><a href="module_treeview.html">treeview</a></li>
<li class=""><a href="module_uploader.html">uploader</a></li>
<li class=""><a href="module_yahoo.html">yahoo</a></li>
<li class=""><a href="module_yuiloader.html">yuiloader</a></li>
<li class=""><a href="module_yuitest.html">yuitest</a></li>
</ul>
</div>
<div class="module">
<h4>Classes</h4>
<ul class="content">
<li class="selected"><a href="YAHOO.util.History.html">YAHOO.util.History</a></li>
</ul>
</div>
<div class="module">
<h4>Files</h4>
<ul class="content">
<li class=""><a href="history.js.html">history.js</a></li>
</ul>
</div>
<div class="module">
<h4>Properties</h4>
<ul class="content">
<li class="private"><a href="#property__fqstates">_fqstates</a>
<!--<code>&lt;RegExp&gt;</code>-->
</li>
<li class="private"><a href="#property__histFrame">_histFrame</a>
<!--<code>&lt;RegExp&gt;</code>-->
</li>
<li class="private"><a href="#property__initialized">_initialized</a>
<!--<code>&lt;RegExp&gt;</code>-->
</li>
<li class="private"><a href="#property__modules">_modules</a>
<!--<code>&lt;RegExp&gt;</code>-->
</li>
<li class="private"><a href="#property__stateField">_stateField</a>
<!--<code>&lt;RegExp&gt;</code>-->
</li>
<li class="private"><a href="#property_QUERY_STRING_REGEXP">QUERY_STRING_REGEXP</a>
<!--<code>&lt;RegExp&gt;</code>-->
</li>
</ul>
</div>
<div class="module">
<h4>Methods</h4>
<ul class="content">
<li class="private"><!--<code>void</code>-->
<a href="#method__checkIframeLoaded">_checkIframeLoaded</a>
</li>
<li class="private"><!--<code>string</code>-->
<a href="#method__getHash">_getHash</a>
</li>
<li class="private"><!--<code>void</code>-->
<a href="#method__handleFQStateChange">_handleFQStateChange</a>
</li>
<li class="private"><!--<code>void</code>-->
<a href="#method__initialize">_initialize</a>
</li>
<li class="private"><!--<code>void</code>-->
<a href="#method__storeStates">_storeStates</a>
</li>
<li class="private"><!--<code>boolean</code>-->
<a href="#method__updateIFrame">_updateIFrame</a>
</li>
<li class=""><!--<code>string</code>-->
<a href="#method_getBookmarkedState">getBookmarkedState</a>
</li>
<li class=""><!--<code>string</code>-->
<a href="#method_getCurrentState">getCurrentState</a>
</li>
<li class=""><!--<code>string</code>-->
<a href="#method_getQueryStringParameter">getQueryStringParameter</a>
</li>
<li class=""><!--<code>void</code>-->
<a href="#method_initialize">initialize</a>
</li>
<li class=""><!--<code>boolean</code>-->
<a href="#method_multiNavigate">multiNavigate</a>
</li>
<li class=""><!--<code>boolean</code>-->
<a href="#method_navigate">navigate</a>
</li>
<li class=""><!--<code>void</code>-->
<a href="#method_onReady">onReady</a>
</li>
<li class=""><!--<code>void</code>-->
<a href="#method_register">register</a>
</li>
</ul>
</div>
<div class="module">
<h4>Events</h4>
<ul class="content">
<li class="">
<a href="#event_onLoadEvent">onLoadEvent</a>
</li>
</ul>
</div>
</div>
</div>
</div>
<div id="ft">
<hr />
Copyright &copy; 2008 Yahoo! Inc. All rights reserved.
</div>
</div>
</body>
</html>