location and history Objects

• location Object

Properties hash host hostname href pathname port protocol search

Method reload()

• history Object

Property length

Methods back() forward() go()

• Summary

location Object

The location Object contains the current URL. Therefore, imagine that the address of your Web page is this:

http://www.someISP.com/~me/myPage.htm

In this case, the location Object refers to that address. With the Object's Properties we will be able to pull out various portions of the URL.

href

location.href contains the string value of the entire URL. Thus, given the previous sample URL, location.href is "http://www.someISP.com/~me/myPage.htm".

One possible use of this property is to pass it as a parameter to the window.open() call. Perhaps you want to open a new window, which connects to the same URL as the current window (so you can look at another portion of the same page at the same time you're looking at the current portion of the page). Simply use this call: 

window.open(location.href, "windowName", "feature1,feature2, ...");

You can also launch a new page without opening a new window. If you simply assign a new URL to location.href, the browser will attempt to connect to a new page. For example:

location.href = "http://www.someISP.com/~me/myPage.htm";

Of course, if you do this, you'll effectively be leaving your current page, including any other JavaScript programs that are in it.

host

The location.host property holds only the hostname and port of the current page's URL. Take a look at the previous example URL

http://www.someISP.com/~me/myPage.htm

where the "hostname" would be www.someISP.com. That's the Internet name of the computer on which the page resides. In the previous example, no port is specified in the URL and, therefore, location.host will only contain the value "www.someISP.com". If a port were specified in the URL, it might look like this:

http://www.someISP.com:80/~me/myPage.htm

"80" is the port in this example. If this were your URL, location.host would contain the string value "www.someISP.com:80". (Because the default port for a Web page is 80, it is usually not specified; but some URLs use a different port, in which case, it will be specified.) One possible use for this property is to construct a string for a user message or HTML link. That is, suppose you want to write a JavaScript function that you might use in numerous Web pages. The purpose of the function is to provide an HTML link that the user can click to jump to another document in a set of pages. Because your function doesn't know which machine it will be on, it could use the location.host property to concatenate an appropriate string for later output in the window as a link. 

port

The property location.port simply contains the value of the port number in the URL, if specified, as explained previously. Note that if a port was not specified in the URL, location.port contains no value. It does not contain the default 80 port unless the 80 was specified in the URL.

Home Port

A computer is more like an apartment block than a single family home: It has a street address (its IP address, such as www.someISP.com), but it also has a series of “apartments” within that address. In net-speak, these apartments are called ports. A computer “listens” on different ports for different types of connections. Generally speaking, Web servers listen for requests on port 80. However, some servers are configured differently and listen on another port. In such cases, when addressing this machine with a URL, you must specify the alternate port to send the request to.  Therefore, if www.someISP.com listens for Web requests on port 8080, you could send open an URL such as:

http://www.someISP.com:8080/~me/myPage.htm.

Assigning a value to location.host will generate an error because it is nonsensical. Whereas you can assign an entire URL to location.href, which would then connect to that URL. You cannot connect to just a host. Thus, assigning a value to location.host is of no use.

hostname

At the risk of sounding redundant, let me say that the property location.hostname will return just the hostname portion of the URL. Recall in the case above that host refers to hostname:port. Likewise, hostname refers only to the name. Yes, it is true: If there is a URL with no port specified, location.host and location.hostname contain the same value.

pathname

Once again, let's look at your example URL:

http://www.someISP.com/~me/myPage.htm

The pathname is the portion of the URL that describes the location of the Web document on the host computer. The pathname begins with and includes the slash (/) immediately succeeding the hostname (or the port, if it were specified). In the above,

/~me/mypage.htm

is the pathname. Therefore, this is the value that location.pathname would contain.

Assigning a value to this property, as in 

location.pathname = "~me/otherdocs/newdoc.htm";

will cause the Web browser to load that document into the current window. This is similar to when you assigned a value to location.href, except that the new document will come from the same host as the current document.

protocol

The protocol property contains the leftmost portion of the URL, which contains the name of the protocol to use in retrieving the specified file (Web document). The example URL used the HTTP protocol, as is most common on the Web. However, some URLs may contain different protocols, such as 

file://hostname/pathname
ftp://hostname/pathname
news://hostname/pathname

FTP, for instance, is the File Transfer Protocol and is another common way in which files can be delivered across the Internet.

In your http://www.someISP.com/~me/myPage.htm example, location.protocol would contain the value "http:". In the previous examples, location.protocol would contain "file:" and "ftp:", respectively. 

By checking the location.protocol property, the JavaScript program can determine if the page it currently resides in was delivered by HTTP, FTP, or NEWS. Conceivably (although not commonly), this could later be used in the JavaScript program to direct the user elsewhere, or to inform the user of restrictions (e.g. “Sorry, but to hear the streaming audio on this page you must retrieve the page using HTTP”).

hash

Some URLs contain special hash mark values following the pathname. For example:

http://www.someISP.com/~me/myPage.htm#item1

The hash mark (#) specifies the name of an anchor to jump to in the Web page. An anchor is a place on a page that has been marked (via the HTML tags that make up the page) as a jump-to point. This allows users to be directed to specific spots within a page, instead of always at the very top. The above URL attempts to bring the user to the anchor known as "item1" in the page myPage.htm.

Thus, the location.hash property would contain the value following the hash mark (in the preceding case, it would be item1).

Assigning a value to location.hash will cause the Web page to jump to that anchor. NOTE: of all the location properties you've seen so far, this may be one of the most useful.

search

Yet another variation on the URL is a search parameter following the pathname, denoted with a question mark (?). A form entry is probably the most common use for a search parameter. When a user enters form data into a form element and then clicks the "submit" button, the following URL is called:

http://www.someISP.com/~me/myProgram?formData

The property location.search would contain the value following the question mark. The most sensible use of this parameter would be in the page that receives the submitted form data.

For example, suppose you have two pages. One of them accepts user input in a form entry. It then sends that input to another page. This other page contains a JavaScript function that evaluates the submitted form data. Therefore, you can make a call to this function with evalform(location.search), which would pass the submitted form as a parameter.

You define a form element with the <FORM> tag. This tag may take several attributes, one of which is the METHOD attribute. METHOD may be assigned either GET or POST. This defines how the form data will be submitted to the server. The details are technical, but GET is the most popular method. It is also the method that generates the ?formData syntax in a URL.

The ACTION attribute specifies which URL to send the submitted data to. This URL will presumably be designed to process the form data in some way.

Thus, a <FORM> definition might look like this:

The preceding set of Properties for the location Object gives you all you need to pull out of the current URL any relevant information you need.

reload()

The reload() method of the location Object reloads the document that is currently displayed in the window of the location Object.

Next, we will look at the history Object, which keeps track of previously visited URLs.

history Object

When you access the history list, you're presented with a list of the pages you accessed in this browsing session. You may then choose to quickly jump to one of those previously visited URLs.

The history Object lets you send the user to somewhere in the history list from within a JavaScript program. The object contains one property and three methods.

history Property

length

Depending on how many pages the user has visited during this session, the history list can be of any length. The property history.length contains the current length of the history list.

It's worth noting that the history Object does not contain any values that reflect the actual URLs in the history list. Therefore, you cannot, for example, perform some action that reads the value of "URL number 3 in the history list." The history Object is designed for navigating the history list. That's where its methods come into the picture.

history Methods

back()

This method has a very logical behavior: history.back() simply moves the user to the URL one place previous in the history list (previous to the current position). It is the same as if the user clicked the "back" or left-pointing arrow in the Web browser's navigation toolbar.

Just as with any instance where you bring the user to a new page, you give up control from your JavaScript program. The user may never return—or he may go anywhere else that the new page links to. Therefore, it usually makes the most sense to utilize these JavaScript methods (which call up new pages) between sets of pages you have designed. In this way, your pages can all contain appropriate JavaScript programs within each to move the user along to where you want them to go.

forward()

Can you guess what this method does? I bet you can. history.forward() moves the user one URL forward, relative to current position, in the history list.

go(offset) or go(substring)

Lastly, you can use the go() method to jump to a particular position in the history list, instead of merely making one hop backward or forward. You can use this method to refer to the desired position in the history list in two different ways.

go(offset) accepts an integer parameter, positive or negative, as offset. If the parameter is a positive integer, the program will move the user that many places forward in the history list. If the parameter is negative, it'll move the user that many places backward (previous to the current position) in the history list. Your current position is always place zero. For example, this line:

history.go(2);

will send the user two locations forward in the history. Likewise, this line:

history.go(-3);

will send the user three locations backward in the history.

Alternatively, you can send go() a string instead of an integer value. For example:

history.go("email.htm");

In this case, JavaScript will search for the newest history list URL that contains the specified string somewhere within its URL string. Therefore, if the history list contains the URL http://www.someISP.com/~someOne/email.htm, that's where the user will be sent by the above example (unless, of course, there is another URL that also contains "email.htm" and has been added to the list more recently).

Remember that URLs are added to the history list when the user visits a page. Therefore, the URLs closest to the end of the history list are the newest; those closest to the beginning are the oldest.

Summary:

• The location Object possesses several Properties that relate to portions of the current URL.
• location.href contains the value of the entire URL.
• Properties host, hostname, port, pathname, and protocol each contain the value of their respective portions of the URL.
• location.hash and location.search contain the values of the strings following an anchor specification and form data, respectively.
• The history Object allows for navigation through the current session's URL history list.
• history.back() and history.forward() move the user back or forward one URL in the history list.
• history.go(integer) moves to the URL that is integer places away from the current URL; negative integers move backward (earlier) in the list from the current URL, and positive integers move forward (later in the list).
• history.go("substring") moves to the newest URL in the history list that contains "substring" somewhere within it.