JavaScript: Windows and Frames
Pages: 1, 2, 3, 4, 5, 6, 7

The Location Object

The location property of a window is a reference to a Location object--a representation of the URL of the document currently being displayed in that window. The href property of the Location object is a string that contains the complete text of the URL. Other properties of this object, such as protocol, host, pathname, and search, specify the various individual parts of the URL.

The search property of the Location object is an interesting one. It contains any portion of a URL following (and including) a question mark. This is often some sort of query string. In general, the question-mark syntax in a URL is a technique for embedding arguments in the URL. While these arguments are usually intended for CGI scripts run on a server, there is no reason why they cannot also be used in JavaScript-enabled pages. Example 13-5 shows the definition of a general-purpose getArgs( ) function that you can use to extract arguments from the search property of a URL. It also shows how this getArgs( ) method could have been used to set initial values of the bouncing window animation parameters in Example 13-4.

Example 13-5: Extracting arguments from a URL

/*
 * This function parses comma-separated name=value 
 * argument pairs from the query string of the URL. 
 * It stores the name=value pairs in 
 * properties of an object and returns that object.
 */
function getArgs(  ) {
    var args = new Object(  );
    var query = location.search.substring(1);     
      // Get query string
    var pairs = query.split(",");
     // Break at comma
    for(var i = 0; i < pairs.length; i++) {
        var pos = pairs[i].indexOf('=');
          // Look for "name=value"
        if (pos == -1) continue;
          // If not found, skip
        var argname = pairs[i].substring(0,pos);
          // Extract the name
        var value = pairs[i].substring(pos+1);
          // Extract the value
        args[argname] = unescape(value);
         // Store as a property
       // In JavaScript 1.5, use decodeURIComponent(  ) 
       // instead of escape(  )
    }
    return args;     // Return the object
}
 
/*
 * We could have used getArgs(  ) in the previous bouncing window example
 * to parse optional animation parameters from the URL
 */
var args = getArgs(  );             // Get arguments
if (args.x) x = parseInt(args.x);   // If arguments are defined...
if (args.y) y = parseInt(args.y);   // override default values
if (args.w) w = parseInt(args.w);
if (args.h) h = parseInt(args.h);
if (args.dx) dx = parseInt(args.dx);
if (args.dy) dy = parseInt(args.dy);
if (args.interval) interval = parseInt(args.interval);

In addition to its properties, the Location object can be used as if it were itself a primitive string value. If you read the value of a Location object, you get the same string as you would if you read the href property of the object (because the Location object has a suitable toString( ) method). What is far more interesting, though, is that you can assign a new URL string to the location property of a window. Assigning a URL to the Location object this way has an important side effect: it causes the browser to load and display the contents of the URL you assign. For example, you might assign a URL to the location property like this:

// If the user is using an old browser that 
// can't display DHTML content, redirect to a page 
// that contains only static HTML
if (parseInt(navigator.appVersion) < 4)
    location = "staticpage.html";

As you can imagine, making the browser load specified web pages into windows is a very important programming technique. While you might expect there to be a method you can call to make the browser display a new web page, assigning a URL to the location property of a window is the supported technique for accomplishing this end. Example 13-6, later in this chapter, includes an example of setting the location property.

Although the Location object does not have a method that serves the same function as assigning a URL directly to the location property of a window, this object does support two methods (added in JavaScript 1.1). The reload( ) method reloads the currently displayed page from the web server. The replace( ) method loads and displays a URL that you specify. But invoking this method for a given URL is different than assigning that URL to the location property of a window. When you call replace( ), the specified URL replaces the current one in the browser's history list, rather than creating a new entry in that history list. Therefore, if you use replace( ) to overwrite one document with a new one, the Back button does not take the user back to the original document, as it does if you load the new document by assigning a URL to the location property. For web sites that use frames and display a lot of temporary pages (perhaps generated by a CGI script), using replace( ) is often useful. Since temporary pages are not stored in the history list, the Back button is more useful to the user.

Finally, don't confuse the location property of the Window object, which refers to a Location object, with the location property of the Document object, which is simply a read-only string with none of the special features of the Location object. document.location is a synonym for document.URL, which in JavaScript 1.1 is the preferred name for this property (because it avoids the potential confusion). In most cases, document.location is the same as location.href. When there is a server redirect, however, document.location contains the URL as loaded, and location.href contains the URL as originally requested.

The History Object

The history property of the Window object refers to a History object for the window. The History object was originally designed to model the browsing history of a window as an array of recently visited URLs. This turned out to be a poor design choice, however; for important security and privacy reasons, it is almost never appropriate to give a script access to the list of web sites that the user has previously visited. Thus, the array elements of the History object are never actually accessible to scripts (except when the user has granted permission to a signed script in Netscape 4 and later). The length property of the History object is accessible, but it does not provide any useful information.

Although its array elements are inaccessible, the History object supports three methods (which can be used by normal, unsigned scripts in all browser versions). The back( ) and forward( ) methods move backward or forward in a window's (or frame's) browsing history, replacing the currently displayed document with a previously viewed one. This is similar to what happens when the user clicks on the Back and Forward browser buttons. The third method, go( ), takes an integer argument and can skip forward or backward in the history list by multiple pages. Unfortunately, go( ) suffers from bugs in Netscape 2 and 3 and has incompatible behavior in Internet Explorer 3; it is best avoided prior to fourth-generation browsers.

Example 13-6 shows how you might use the back( ) and forward( ) methods of the History and Location objects to add a navigation bar to a framed web site. Figure 13-3 shows what a navigation bar looks like. Note that the example uses JavaScript with multiple frames, which is something we will discuss shortly. It also contains a simple HTML form and uses JavaScript to read and write values from the form. This behavior is covered in detail in Chapter 15.

Example 13-6: 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 previous one
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 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>