[Chapter 13] 13.3 The History Object

13.3 The History Object

The history property of the Window object refers to a History object for the window. The History object is an array of the URLs in the browsing history of the window or frame. For a top-level Navigator window, the History object is a representation of the contents of the browser's Go menu.

A user's browsing session history is private information and, so for security reasons, there are heavy restrictions on how the History object can be used. In Navigator 3.0, with the data-tainting security model enabled, (see Chapter 20, JavaScript Security) the elements of the history array are accessible to JavaScript programs. On all other platforms, however, they are never accessible, and the History object is much less useful. In Navigator, the length property of the History object can be read, although it is not actually good for much. In Internet Explorer, even this length property is hidden for security reasons--querying it always returns 0.

Besides its array elements and length property, the History object also supports three methods. The back() and forward() methods perform the same action as clicking on the Back and Forward browser buttons. The third method, go(), suffers from bugs in Navigator 2.0 and 3.0, and has incompatible behavior in Internet Explorer; it is best avoided. Example 13.3 shows how you might use the back() and forward() methods of the History object, and also the Location object to add a "navigation bar" to a framed web site. Figure 13.1 shows what it looks like.

Figure 13.1: A navigation bar

[Graphic: Figure 13-1]

Example 13.3: A Navigation Bar Using the History and Location Objects

<!--  This file implements a navigation bar, designed to go in a frame at
      the bottom of a window. Include it in a frameset like the following:
        <frameset rows="*,75">
        <frame src="about:blank">
        <frame src="navigation.html">
        </frameset>
-->
<SCRIPT>
// The function is invoked by the Back button in our navigation bar.
function go_back() 
{
    // First, clear the URL entry field in our form
    document.navbar.url.value = "";
    // Then use the History object of the main frame to go back.
    parent.frames[0].history.back();
    // Wait a second, and then update the URL entry field in the form
    // from the location.href property of the main frame. The wait seems
    // to be necessary to allow the location.href property to get in sync.
    setTimeout("document.navbar.url.value = parent.frames[0].location.href;",
               1000);
}
// This function is invoked by the Forward button in the navigation bar.
// It works just like the one above.
function go_forward()
{
    document.navbar.url.value = "";
    parent.frames[0].history.forward();
    setTimeout("document.navbar.url.value = parent.frames[0].location.href;",
               1000);
}
// This function is invoked by the Go button in the navigation bar, and also
// when the form is submitted (when the user hits the Return key).
function go_to()
{
    // Just set the location property of the main frame to the URL
    // that the user typed in.
    parent.frames[0].location = document.navbar.url.value;
}
</SCRIPT>
<!-- Here's the form, with event handlers that invoke the functions above -->
<FORM NAME="navbar" onSubmit="go_to(); return false">
<INPUT TYPE="button" VALUE="Back"  onClick="go_back();">
<INPUT TYPE="button" VALUE="Forward"  onClick="go_forward()">
URL:
<INPUT TYPE="text" NAME="url" SIZE=50">
<INPUT TYPE="button" VALUE="Go" onClick="go_to()">
</FORM>