A history management object. Can be instantiated in user-visible mode (uses the address fragment to manage state) or in hidden mode. This object should be created from a script in the document body before the document has finished loading. To store the hidden states in browsers other than IE, a hidden iframe is used. It must point to a valid html page on the same domain (which can and probably should be blank.) Sample instantiation and usage:
// Instantiate history to use the address bar for state.
var h = new goog.History();
goog.events.listen(h, goog.history.EventType.NAVIGATE, navCallback);
h.setEnabled(true);

// Any changes to the location hash will call the following function.
function navCallback(e) {
  alert('Navigated to state "' + e.token + '"');
}

// The history token can also be set from code directly.
h.setToken('foo');

Inheritance

Constructor

goog.History(opt_invisibleopt_blankPageUrlopt_inputopt_iframe)

Parameters

opt_invisible : boolean=
True to use hidden history states instead of the user-visible location hash.
opt_blankPageUrl : string=
A URL to a blank page on the same server. Required if opt_invisible is true. This URL is also used as the src for the iframe used to track history state in IE (if not specified the iframe is not given a src attribute). Access is Denied error may occur in IE7 if the window's URL's scheme is https, and this URL is not specified.
opt_input : HTMLInputElement=
The hidden input element to be used to store the history token. If not provided, a hidden input element will be created using document.write.
opt_iframe : HTMLIFrameElement=
The hidden iframe that will be used by IE for pushing history state changes, or by all browsers if opt_invisible is true. If not provided, a hidden iframe element will be created using document.write.

Instance Methods

Public Protected Private
Defined in goog.History
check_(isNavigation)
Checks the state of the document fragment and the iframe title to detect navigation changes. If goog.HistoryisOnHashChangeSupported() is false, then this runs approximately twenty times per second.
Arguments:
isNavigation : boolean
True if the event was initiated by a browser action, false if it was caused by a setToken call. See goog.history.Event.
code »
disposeInternal()
No description.
code »
getIframeToken_() ?string
Return the current state string from the hidden iframe. On internet explorer, this is stored as a string in the document body. Other browsers use the location hash of the hidden iframe. Older versions of webkit cannot access the iframe location, so always return null in that case.
Returns: ?string  The state token saved in the iframe (possibly null if the iframe has never loaded.).
code »
getLocationFragment_(win) string
Gets the location fragment for the current URL. We don't use location.hash directly as the browser helpfully urlDecodes the string for us which can corrupt the tokens. For example, if we want to store: label/%2Froot it would be returned as label//root.
Arguments:
win : Window
The window object to use.
Returns: string  The fragment.
code »
getToken() string
No description.
Returns: string  The current token.
code »
onDocumentLoaded()
Callback for the window onload event in IE. This is necessary to read the value of the hidden input after restoring a history session. The value of input elements is not viewable until after window onload for some reason (the iframe state is similarly unavailable during the loading phase.) If setEnabled is called before the iframe has completed loading, the history object will actually be enabled at this point.
code »
onHashChange_(e)
Handles HTML5 onhashchange events on browsers where it is supported. This is very similar to #check_, except that it is not executed continuously. It is only used when goog.History.isOnHashChangeSupported() is true.
Arguments:
e : goog.events.BrowserEvent
The browser event.
code »
onShow_(e)
Handler for the Gecko pageshow event. Restarts the history object so that the correct state can be restored in the hash or iframe.
Arguments:
e : goog.events.BrowserEvent
The browser event.
code »
operaDefibrillator_()
Opera cancels all outstanding timeouts and intervals after any rapid succession of navigation events, including the interval used to detect navigation events. This function restarts the interval so that navigation can continue. Ideally, only events which would be likely to cause a navigation change (mousedown and keydown) would be bound to this function. Since Opera seems to ignore keydown events while the alt key is pressed (such as alt-left or right arrow), this function is also bound to the much more frequent mousemove event. This way, when the update loop freezes, it will unstick itself as the user wiggles the mouse in frustration.
code »
replaceToken(tokenopt_title)
Replaces the current history state without affecting the rest of the history stack.
Arguments:
token : string
The history state identifier.
opt_title : string=
Optional title used when setting the hidden iframe title in IE.
code »
setEnabled(enable)
Starts or stops the History polling loop. When enabled, the History object will immediately fire an event for the current location. The caller can set up event listeners between the call to the constructor and the call to setEnabled. On IE, actual startup may be delayed until the iframe and hidden input element have been loaded and can be polled. This behavior is transparent to the caller.
Arguments:
enable : boolean
Whether to enable the history polling loop.
code »
setHash_(tokenopt_replace)
Sets or replaces the URL fragment. The token does not need to be URL encoded according to the URL specification, though certain characters (like newline) are automatically stripped. If opt_replace is not set, non-IE browsers will append a new entry to the history list. Setting the hash does not affect the history stack in IE (unless there is a pre-existing named anchor for that hash.) Older versions of Webkit cannot query the location hash, but it still can be set. If we detect one of these versions, always replace instead of creating new history entries. window.location.replace replaces the current state from the history stack. http://www.whatwg.org/specs/web-apps/current-work/#dom-location-replace http://www.whatwg.org/specs/web-apps/current-work/#replacement-enabled
Arguments:
token : string
The new string to set.
opt_replace : boolean=
Set to true to replace the current token without appending a history entry.
code »
setHistoryState_(tokenreplaceopt_title)
Sets the history state. When user visible states are used, the URL fragment will be set to the provided token. Setting opt_replace to true will cause the navigation to occur, but will replace the current history entry without affecting the length of the stack.
Arguments:
token : string
The history state identifier.
replace : boolean
Set to replace the current history entry instead of appending a new history state.
opt_title : string=
Optional title used when setting the hidden iframe title in IE.
code »
setIframeToken_(tokenopt_replaceopt_title)
Sets the hidden iframe state. On IE, this is accomplished by writing a new document into the iframe. In Firefox, the iframe's URL fragment stores the state instead. Older versions of webkit cannot set the iframe, so ignore those browsers.
Arguments:
token : string
The new string to set.
opt_replace : boolean=
Set to true to replace the current iframe state without appending a new history entry.
opt_title : string=
Optional title used when setting the hidden iframe title in IE.
code »
setLongerPolling_(longerPolling)
Sets if the history oject should use longer intervals when polling.
Arguments:
longerPolling : boolean
Whether to enable longer polling.
code »
setToken(tokenopt_title)
Sets the history state. When user visible states are used, the URL fragment will be set to the provided token. Sometimes it is necessary to set the history token before the document title has changed, in this case IE's history drop down can be out of sync with the token. To get around this problem, the app can pass in a title to use with the hidden iframe.
Arguments:
token : string
The history state identifier.
opt_title : string=
Optional title used when setting the hidden iframe title in IE.
code »
update_(tokenisNavigation)
Updates the current history state with a given token. Called after a change to the location or the iframe state is detected by poll_.
Arguments:
token : string
The new history state.
isNavigation : boolean
True if the event was initiated by a browser action, false if it was caused by a setToken call. See goog.history.Event.
code »
addEventListener(typeopt_captureopt_handlerScope)
Use #listen instead, when possible. Otherwise, use goog.events.listen if you are passing Object (instead of Function) as handler. Adds an event listener to the event target. The same handler can only be added once per the type. Even if you add the same handler multiple times using the same type then it will only be called once when the event is dispatched.
Arguments:
type : string
The type of the event to listen for.
: ?function():? | ?{handleEvent:function():?
No description.
opt_capture : boolean=
In DOM-compliant browsers, this determines whether the listener is fired during the capture or bubble phase of the event.
opt_handlerScope : Object=
Object in whose scope to call the listener.
code »
assertInitialized_()
Asserts that the event target instance is initialized properly.
code »
dispatchEvent()
No description.
code »
disposeInternal()
Removes listeners from this object. Classes that extend EventTarget may need to override this method in order to remove references to DOM Elements and additional listeners.
code »
fireListeners()
No description.
code »
getListener()
No description.
code »
getListeners()
No description.
code »
getParentEventTarget() goog.events.EventTarget
Returns the parent of this event target to use for bubbling.
Returns: goog.events.EventTarget  The parent EventTarget or null if there is no parent.
code »
hasListener()
No description.
code »
listen()
No description.
code »
listenOnce()
No description.
code »
removeAllListeners()
No description.
code »
removeEventListener(typeopt_captureopt_handlerScope)
Use #unlisten instead, when possible. Otherwise, use goog.events.unlisten if you are passing Object (instead of Function) as handler. Removes an event listener from the event target. The handler must be the same object as the one added. If the handler has not been added then nothing is done.
Arguments:
type : string
The type of the event to listen for.
: ?function():? | ?{handleEvent:function():?
No description.
opt_capture : boolean=
In DOM-compliant browsers, this determines whether the listener is fired during the capture or bubble phase of the event.
opt_handlerScope : Object=
Object in whose scope to call the listener.
code »
setParentEventTarget(parent)
Sets the parent of this event target to use for capture/bubble mechanism.
Arguments:
parent : goog.events.EventTarget
Parent listenable (null if none).
code »
setTargetForTesting(target)
Sets the target to be used for event.target when firing event. Mainly used for testing. For example, see goog.testing.events.mixinListenable.
Arguments:
target : !Object
The target.
code »
unlisten()
No description.
code »
unlistenByKey()
No description.
code »
addOnDisposeCallback(callbackopt_scope)
Invokes a callback function when this object is disposed. Callbacks are invoked in the order in which they were added.
Arguments:
callback : function(this:T):?
The callback function.
opt_scope : T=
An optional scope to call the callback in.
code »
dispose() void
Disposes of the object. If the object hasn't already been disposed of, calls #disposeInternal. Classes that extend goog.Disposable should override #disposeInternal in order to delete references to COM objects, DOM nodes, and other disposable objects. Reentrant.
Returns: void  Nothing.
code »
disposeInternal()
Deletes or nulls out any references to COM objects, DOM nodes, or other disposable objects. Classes that extend goog.Disposable should override this method. Not reentrant. To avoid calling it twice, it must only be called from the subclass' disposeInternal method. Everywhere else the public dispose method must be used. For example:
  mypackage.MyClass = function() {
    mypackage.MyClass.base(this, 'constructor');
    // Constructor logic specific to MyClass.
    ...
  };
  goog.inherits(mypackage.MyClass, goog.Disposable);

  mypackage.MyClass.prototype.disposeInternal = function() {
    // Dispose logic specific to MyClass.
    ...
    // Call superclass's disposeInternal at the end of the subclass's, like
    // in C++, to avoid hard-to-catch issues.
    mypackage.MyClass.base(this, 'disposeInternal');
  };
code »
getDisposed() boolean
Use #isDisposed instead. No description.
Returns: boolean  Whether the object has been disposed of.
code »
isDisposed() boolean
No description.
Returns: boolean  Whether the object has been disposed of.
code »
registerDisposable(disposable)
Associates a disposable object with this object so that they will be disposed together.
Arguments:
disposable : goog.disposable.IDisposable
that will be disposed when this object is disposed.
code »

Instance Properties

Defined in goog.History
constructor :
No description.
Code »
documentLoaded :
IE-only variable for determining if the document has loaded.
Code »
enabled_ :
Status of when the object is active and dispatching events.
Code »
eventHandler_ : goog.events.EventHandler
An object to keep track of the history event listeners.
Code »
hiddenInput_ :
An input element that stores the current iframe state. Used to restore the state when returning to the page on non-IE browsers.
Code »
iframeSrc_ :
The base URL for the hidden iframe. Must refer to a document in the same domain as the main page.
Code »
iframe_ :
Internet Explorer uses a hidden iframe for all history changes. Other browsers use the iframe only for pushing invisible states.
Code »
lastToken_ :
The last token set by the history object, used to poll for changes.
Code »
lockedToken_ :
If not null, polling in the user invisible mode will be disabled until this token is seen. This is used to prevent a race condition where the iframe hangs temporarily while the location is changed.
Code »
longerPolling_ :
Whether the object is performing polling with longer intervals. This can occur for instance when setting the location of the iframe when in invisible mode and the server that is hosting the blank html page is down. In FF, this will cause the location of the iframe to no longer be accessible, with permision denied exceptions being thrown on every access of the history token. When this occurs, the polling interval is elongated. This causes exceptions to be thrown at a lesser rate while allowing for the history object to resurrect itself when the html page becomes accessible.
Code »
shouldEnable_ :
IE-only variable for storing whether the history object should be enabled once the document finishes loading.
Code »
timer_ : goog.Timer
A timer for polling the current history state for changes.
Code »
unsetIframe_ :
Whether the hidden iframe has had a document written to it yet in this session.
Code »
userVisible_ :
True if the state tokens are displayed in the address bar, false for hidden history states.
Code »
window_ :
The window whose location contains the history token fragment. This is the window that contains the hidden input. It's typically the top window. It is not necessarily the same window that the js code is loaded in.
Code »
actualEventTarget_ : goog.events.EventTarget
The object to use for event.target. Useful when mixing in an EventTarget to another object.
Code »
constructor :
No description.
Code »
eventTargetListeners_ : goog.events.ListenerMap
Maps of event type to an array of listeners.
Code »
parentEventTarget_ : goog.events.EventTarget
Parent event target, used during event bubbling. TODO(user): Change this to goog.events.Listenable. This currently breaks people who expect getParentEventTarget to return goog.events.EventTarget.
Code »
creationStack :
If monitoring the goog.Disposable instances is enabled, stores the creation stack trace of the Disposable instance.
Code »
disposed_ :
Whether the object has been disposed of.
Code »
onDisposeCallbacks_ :
Callbacks to invoke when this object is disposed.
Code »

Static Methods

goog.History.isOnHashChangeSupported() boolean
Whether the browser supports HTML5 history management's onhashchange event. http://www.w3.org/TR/html5/history.html. IE 9 in compatibility mode indicates that onhashchange is in window, but testing reveals the event isn't actually fired.
Returns: boolean  Whether onhashchange is supported.
code »

Static Properties

goog.History.HASH_ALWAYS_REQUIRED :
Whether the browser always requires the hash to be present. Internet Explorer before version 8 will reload the HTML page if the hash is omitted.
Code »
goog.History.IFRAME_SOURCE_TEMPLATE_ :
Minimal HTML page used to populate the iframe in Internet Explorer. The title is visible in the history dropdown menu, the iframe state is stored as the body innerHTML.
Code »
goog.History.IFRAME_TEMPLATE_ :
HTML template for an invisible iframe.
Code »
goog.History.INPUT_EVENTS_ :
List of user input event types registered in Opera to restart the history timer (@see goog.History#operaDefibrillator_).
Code »
goog.History.INPUT_TEMPLATE_ :
HTML template for an invisible named input element.
Code »
goog.History.LEGACY_IE :
Whether the current browser is Internet Explorer prior to version 8. Many IE specific workarounds developed before version 8 are unnecessary in more current versions.
Code »
goog.History.historyCount_ :
Counter for the number of goog.History objects that have been instantiated. Used to create unique IDs.
Code »
goog.History.superClass_ :
No description.
Code »

Enumerations

goog.History.EventType :
Constant for the history change event type.
Constants:
Code »
goog.History.PollingType :
Types of polling. The values are in ms of the polling interval.
Constants:
LONG
No description.
NORMAL
No description.
Code »

Package History

Package Reference