13.2 The Location Object

The location property of a window is a reference to a Location object, which is 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. This 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", and 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 they cannot also be used in JavaScript-enabled pages. Example 13.2 shows how you can use JavaScript and the Location object to extract arguments embedded within your web page.

<SCRIPT LANGUAGE="JavaScript1.1">
// location.search has a question mark at the beginning, 
// so we call substring() to get rid of it.
var argstr = location.search.substring(1, location.search.length)
// Assuming that the arguments are passed in a comma-separated list, we
// can break them into an array with this line. (Using an ampersand to
// separate arguments is another common URL convention.)
var args = argstr.split(',');
// Now we can use the arguments however we want. This example just 
// prints them out. We use the unescape() function in case the arguments
// include escaped characters (like spaces and punctuation) that are 
// illegal in URLs. (See escape() and unescape() functions for details.)
for (var i = 0; i < args.length; i++)
    document.write(unescape(args[i]) + "<BR>");
</SCRIPT>

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 (this is 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 like this has a very important side effect: it causes the browser to load and display the contents of the URL you assign (this side effect occurs because the Location has a suitable assign() method). For example, you might assign a URL to the location property like this:

// If Java isn't enabled, go to a page that displays a message
// saying that you can't run this page without Java.
if (!navigator.javaEnabled()) 
    location = "needsjava.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 to accomplish this. Internet Explorer supports a navigate() method of the Window object to do this, but it is not compatible with Navigator, and therefore should not be used.

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 (in Navigator 3.0). 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 will not take the user back to the original document, as it would have if you had loaded the new document by assigning 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 quite useful. By not storing temporary pages in the history list, the Back button becomes 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 Navigator 3.0, 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 actual URL, as loaded, and location.href contains the URL as originally requested.

This does not hold for IE6 after a 404 or other web error when the "friendly error message" enabled. In that case, the URL, href, location, etc... are all the local address of the file containing the friendly version of the error message.