The Location object

The Location Object

The Location object contains information about the current documents location and can be used to manipulate browser navigation.

For a general example for the location object, consider your browser is currently visiting the rather over-complete URL :

http://www.htmlib.com:80/example_files/file.html#findme?Stephen

all will become clear.

Location Properties
hash
The hash property returns, or sets the URL fragment part of the current location. For example, from the URL above :

vFrag=self.location.hash

would set the variable vFrag to 'findme'.

host
The host property sets or returns the host section of the current URL. The host section of a URL is basically the hostname property (see below), together with the port property (see below). So, using the above example :

vHost=self.location.host

would set vHost to www.htmlib.com:80. Note the subtle difference between this and the hostname property. (If the current URL does not contain a port setting, then host and hostname are effectively the same).

hostname
The hostname property (as mentioned above) is the name of the host computer (either a name, or IP address). For example :

vHostName=self.location.hostname

sets the vHostNane variable to www.htmlib.com

href
The href property can be regarded as a concatenation of all the other location properties. That is, if the current URL was the one given above for the example, then :

vHref=self.location.href

would make vHref be http://www.htmlib.com:80/example_files/file.html#findme?Stephen

pathname
The pathname property provides the current path for the URL. This is the section in between the hostname (including protocol) if any and the hash, or search (see below) sections (if either exists). For example :

vPathName=self.location.pathname

would return example_files/file.html as the contents of the vPathName variable.

port
As you may suspect, the port property represents any port settings for the current URL. Given the above example,

vPort=self.location.port

sets vPort to 80 (the common port for Web servers).

protocol
This property represents the protocol currently in use for the displayed document. For example :

vProtocol=self.location.protocol

sets vProtocol to 'http:'. For commonly used protocols, see the <A HREF="..."> element.

search
The search property contains information about any search strings in the current URL. For example :

vSearch=self.location.search

returns 'Stephen' as the contents of the vSearch variable.

Location Methods
assign
The Internet Explorer 4.0 specific method takes one argument (URL). It then loads the document referenced at the URL (if it exists) in place of the currently displayed document. Basically, it performs the same as changing the href property.

reload
The reload method forces a re-loading of the current URL. It should be noted that Netscape decides how to interact with the server for re-loading according to the Network Preference settings (i.e whether the user has set documents to be verified once, all the time, or never). Saying that however, this decision can be over-ruled by specifying a true parameter. This forces the browser to re-load the current document from the server, despite the current users preference settings. For example :

self.location.reload()

may re-load the document, depending on user preferences, while :

self.location.reload(true)

forces Netscape to re-visit the server to retrieve a new copy of the document.
This can be especially useful if your document changes rapidly, avoiding users seeing old copies of the document due to disk/memory caches, or if they are browsing through a proxy/cache server.

replace
This is much like the reload method, except that it loads another document and replaces the history object entry for the previous URL with the new URL loaded. Essentially, this prevents the user from returning to the previous URL, by using the browsers back button. For example, suppose you are at the URL given above for the examples and the following code gets executed :

self.location.replace('http://www.microsoft.com/')

The browser would navigate to the Microsoft web site and replace the www.htmlib.com entry in the history object with http://www.microsoft.com Unless you'd remembered the previous URL, there would be no navigating back to it.

Location Events
The Location object has no events.