Availability

Navigator 2.0, Internet Explorer 3.0; enhanced in Navigator 3.0

Properties

The properties of a Location object refer the various portions of a URL, which has the following general format:

protocol://hostname:port/pathname?search#hash

hash

The hash portion of the URL, including the leading hash (#) mark. This portion specifies the name of an anchor within a single HTML file.

host

A combination of the hostname and port portions of the URL.

hostname

The hostname portion of the URL.

href

The complete URL.

pathname

The path portion of the URL.

port

The port portion of the URL.

protocol

The protocol portion of the URL, including the trailing colon.

search

The search or query portion of the URL, including the leading question mark.

Methods

reload()

Reload the current document from the cache or the server. This method was added in Navigator 3.0.

replace()

Replace the current document with a new one, without generating a new entry in the browser's session history. This method was added in Navigator 3.0.

Description

The Location object is stored in the location property of the Window object, and represents the web address (the "location") of the document currently displayed in that window. The href property contains the complete URL of that document, and the other properties of the Location object each describe a portion of that URL. The Location object is, in fact, a specialized form of the URL object--it has the same properties as that object does.

There is an important difference between the Location object and the URL object, however. The Location object represents the current "location" of the browser, but it also controls that location. If you assign a string containing a URL to the Location object, or to its href property, the web browser responds by loading the newly specified URL and displaying the document it refers to.

When you set the location or location.href properties to a URL that you have already visited, the browser will either load that URL from the cache, or will check with the server to see if the document has changed and reload it if necessary. In Navigator 2.0, it will always check with the web server. In Navigator 3.0, the action it takes depends on the Verify Document setting in Navigator's Network Preferences.

Instead of setting location or location.href to replace the current URL with a completely new one, you can also modify just a portion of the current URL by assigning strings to the other properties of the Location object. Doing this creates a new URL, with one new portion, which the browser loads and displays. For example, if you set the hash property of the Location object you can cause the browser to move to a named location within the current document (although in Navigator 2.0, the browser reloads the entire document to accomplish this; this bug is fixed in Navigator 3.0). Similarly, if you set the search property, you can cause the browser to reload the current URL with a new query string appended. If the URL refers to a CGI script, then the document resulting from the new query string may be quite different from the original document.

It is generally not so useful to set the other properties of the Location object. For example, if you loaded a document via the HTTP protocol, you would rarely be able to actually load another document simply by using the protocol property to change the URL protocol from http: to ftp:. See the URL object for a complete description of the hash, search, protocol and other properties that represent portions of a URL.

While the properties of the Location object are identical to those of the URL object, we've seen that they have quite different behavior. In Navigator 3.0, the Location object also defines methods that the URL object does not. The reload() method of the Location object reloads the current document, and the replace() method loads a new document without creating a new history entry for it--the new document "replaces" the current one in the browser's history list.

Note that the Location object bears some resemblance to the Link object which is another specialized version of the URL object. While the Location object represents and controls the current location of the browser, Link objects represent the destinations of hypertext links within a document.

See Also

"Link", "URL", "Window.location"