[Chapter 21] Reference: History
Author: David Flanagan
Date: Fri Aug 29 11:16:25 1997

#

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

## Description

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

## See Also

"Location"

history |  | History.back()