Table of Contents | Previous | Next | Index

# History

Contains an array of information on the URLs that the client has visited within a window. This information is stored in a history list and is accessible through the browser's Go menu.

Client-side object |
Implemented in | JavaScript 1.0 JavaScript 1.1: added `current, next,` and `previous` properties.

#### Created by

`History` objects are predefined JavaScript objects that you access through the `history` property of a `window` object.

#### Description

To change a window's current URL without generating a history entry, you can use the `Location.replace` method. This replaces the current page with a new one without generating a history entry. See `Location.replace`. You can refer to the history`` entries by using the `window.history` array. This array contains an entry for each history entry in source order. Each array entry is a string containing a URL. For example, if the history list contains three named entries, these entries are reflected as `history[0]`, `history[1]`, and `history[2]`. If you access the `history` array without specifying an array element, the browser returns a string of HTML which displays a table of URLs, each of which is a link.

#### Property Summary

Property | Description
--- | ---
    current
| Specifies the URL of the current history entry.
    length
| Reflects the number of entries in the history list.
    next
| Specifies the URL of the next history entry.
    previous
| Specifies the URL of the previous history entry.

#### Method Summary

Method | Description
--- | ---
    back
| Loads the previous URL in the history list.
    forward
| Loads the next URL in the history list.
    go
| Loads a URL from the history list.

In addition, this object inherits the `watch` and `unwatch` methods from `Object`.

#### Examples

Example 1. The following example goes to the URL the user visited three clicks ago in the current window.

    history.go(-3)

Example 2. You can use the `history` object with a specific window or frame. The following example causes `window2` to go back one item in its window (or session) history:

    window2.history.back()

Example 3. The following example causes the second frame in a frameset to go back one item:

    parent.frames[1].history.back()

Example 4. The following example causes the frame named `frame1` in a frameset to go back one item:

    parent.frame1.history.back()

Example 5. The following example causes the frame named `frame2` in `window2` to go back one item:

    window2.frame2.history.back()

Example 6. The following code determines whether the first entry in the `history` array contains the string `"NETSCAPE"`. If it does, the function `myFunction` is called.

    if (history[0].indexOf("NETSCAPE") != -1) {
       myFunction(history[0])
    }

Example 7. The following example displays the entire history list:

    document.writeln("<B>history is</B> " + history)

This code displays output similar to the following:

    history is
    Welcome to Netscape http://home.netscape.com/
    Sun Microsystems http://www.sun.com/
    Royal Airways http://www.supernet.net/~dugbrown/

#### See also

`Location`, `Location.replace`

## back

Loads the previous URL in the history list.

Method of | `History`
Implemented in | JavaScript 1.0

#### Syntax

    back()

#### Parameters

None

#### Description

This method performs the same action as a user choosing the Back button in the browser. The `back` method is the same as `history.go(-1)`.

#### Examples

The following custom buttons perform the same operation as the browser's Back button:

    <P><INPUT TYPE="button" VALUE="< Go Back"
       onClick="history.back()">
    <P><INPUT TYPE="button" VALUE="> Go Back"
       onClick="myWindow.back()">

#### See also

`History.forward`, `History.go`

## current

A string specifying the complete URL of the current history entry.

Property of | `History`
Read-only |
Implemented in | JavaScript 1.1

#### Security

Getting the value of this property requires the `UniversalBrowserRead` privilege. It has no value if you do not have this privilege. For information on security, see the Client-Side JavaScript Guide. JavaScript 1.1. This property is tainted by default. It has no value of data tainting is disabled. For information on data tainting, see the Client-Side JavaScript Guide.

#### Examples

The following example determines whether `history.current` contains the string `"netscape.com"`. If it does, the function `myFunction` is called.

    if (history.current.indexOf("netscape.com") != -1) {
       myFunction(history.current)
    }

#### See also

`History.next`, `History.previous`

## forward

Loads the next URL in the history list.

Method of | `History`
Implemented in | JavaScript 1.0

#### Syntax

    forward()

#### Parameters

None

#### Description

This method performs the same action as a user choosing the Forward button in the browser. The `forward` method is the same as `history.go(1)`.

#### Examples

The following custom buttons perform the same operation as the browser's Forward button:

    <P><INPUT TYPE="button" VALUE="< Forward"
       onClick="history.forward()">
    <P><INPUT TYPE="button" VALUE="> Forward"
       onClick="myWindow.forward()">

#### See also

`History.back`, `History.go`

## go

Loads a URL from the history list.

Method of | `History`
Implemented in | JavaScript 1.0

#### Syntax

    go(delta)
    go(location)

#### Parameters

    delta
| An integer representing a relative position in the history list.
    location
| A string representing all or part of a URL in the history list.

#### Description

The `go` method navigates to the location in the history list determined by the specified parameter. If the `delta` argument is 0, the browser reloads the current page. If it is an integer greater than 0, the `go` method loads the URL that is that number of entries forward in the history list; otherwise, it loads the URL that is that number of entries backward in the history list. The `location` argument is a string. Use `location` to load the nearest history entry whose URL contains `location` as a substring. Matching the URL to the `location` parameter is case-insensitive. Each section of a URL contains different information. See `Location` for a description of the URL components. The `go` method creates a new entry in the history list. To load a URL without creating an entry in the history list, use `Location.replace`.

#### Examples

The following button navigates to the nearest history entry that contains the string `"home.netscape.com"`:

    <P><INPUT TYPE="button" VALUE="Go"
       onClick="history.go('home.netscape.com')">

The following button navigates to the URL that is three entries backward in the history list:

    <P><INPUT TYPE="button" VALUE="Go"
       onClick="history.go(-3)">

#### See also

`History.back`, `History.forward`, `Location.reload`, `Location.replace`

## length

The number of elements in the `history` array.

Property of | `History`
Read-only |
Implemented in | JavaScript 1.0

#### Security

Getting the value of this property requires the `UniversalBrowserRead` privilege. For information on security, see the Client-Side JavaScript Guide.

## next

A string specifying the complete URL of the next history entry.

Property of | `History`
Read-only |
Implemented in | JavaScript 1.1

#### Security

Getting the value of this property requires the `UniversalBrowserRead` privilege. It has no value if you do not have this privilege. For information on security, see the Client-Side JavaScript Guide. JavaScript 1.1. This property is tainted by default. It has no value if data tainting is disabled. For information on data tainting, see the Client-Side JavaScript Guide.

#### Description

The `next` property reflects the URL that would be used if the user chose Forward from the Go menu.

#### Examples

The following example determines whether `history.next` contains the string `"NETSCAPE.COM"`. If it does, the function `myFunction` is called.

    if (history.next.indexOf("NETSCAPE.COM") != -1) {
       myFunction(history.next)
    }

#### See also

`History.current`, `History.previous`

## previous

A string specifying the complete URL of the previous history entry.

Property of | `History`
Read-only |
Implemented in | JavaScript 1.1

#### Security

Getting the value of this property requires the `UniversalBrowserRead` privilege. It has no value if you do not have this privilege. For information on security, see the Client-Side JavaScript Guide. JavaScript 1.1. This property is tainted by default. It has no value of data tainting is disabled. For information on data tainting, see the Client-Side JavaScript Guide.

#### Description

The `previous` property reflects the URL that would be used if the user chose Back from the Go menu.

#### Examples

The following example determines whether `history.previous` contains the string `"NETSCAPE.COM"`. If it does, the function `myFunction` is called.

    if (history.previous.indexOf("NETSCAPE.COM") != -1) {
       myFunction(history.previous)
    }

#### See also

`History.current`, `History.next`

Table of Contents | Previous | Next | Index

Last Updated: 05/28/99 11:59:35

Copyright (c) 1999 Netscape Communications Corporation