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