Chapter 21
JavaScript Reference

History Object

Name

History Object---the URL history of the browser

Availability

Navigator 2.0, Internet Explorer 3.0; enhanced in Navigator 3.0 when data tainting is enabled

Synopsis

window.history
frame.history
history

Properties

current

A string that specifies the URL of the current document. Only available with data tainting enabled in Navigator 3.0.

length

The number of URLs that are saved in the History object.

next

A string that specifies the URL of the document after this one in the history list. Only available with data tainting enabled in Navigator 3.0.

previous

A string that specifies the URL of the document before this one in the history list. Only available with data tainting enabled in Navigator 3.0.

Methods

back()

Go backwards to a previously visited URL.

forward()

Go forward to a previously visited URL.

go()

Go to a previously visited URL.

toString()

Return an HTML-formatted table containing the window's browsing history. Only available with data tainting enabled in Navigator 3.0.

The History object is a read-only array of strings that specify the URLs that have been previously visited by the browser. The contents of this array are equivalent to the URLs listed in Navigator's Go menu. For security and privacy reasons, the contents of the array are not available to JavaScript in Navigator 2.0, or in Navigator 3.0 when the data-tainting security model is not enabled.

In Navigator 2.0, and Navigator 3.0 without data tainting enabled, JavaScript can use the length property to determine the number of entries on the History object's URL list, and can use the back(), forward() and go() methods to cause the browser to revisit any of the URLs in the array, but it cannot directly or indirectly read the URLs stored in the array.

In Navigator 3.0 and later, when the data-tainting security model is enabled, the elements of the array are available and may be read (but not changed). Also, the current, next, and previous properties are available. These properties are strings that specify the URL of the current document, and the URLs of the documents that precede and follow it in the history array. Finally, enabling data tainting also makes the toString() method of the History object functional. This method returns a string of HTML text. When this string is formatted by a browser (i.e., written with document.write()), it displays the browser history as a table of URLs, each with an appropriate hyperlink.

Usage

You can use the History object to implement your own Forward and Back buttons, or other navigation controls, within a window. This is most often useful for sites that use frames. With data tainting enabled, more sophisticated navigation aids are possible.

Example

With or without data tainting, you can use the back(), forward(), and go() methods of the History object. The following line performs the same action as clicking the Back button:

history.back();

The following performs the same action as clicking the Back button twice:

history.go(-2);

With data tainting enabled, you can access the history object as an array and read URLs directly. The first URL displayed by the current window is:

history[0]

The last URL displayed by that window is:

history[history.length-1]

The currently displayed URL is:

history.current

And the URLs of the documents before and after that one in the history array are:

history.previous
history.next