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