• The window Object
  • window Object Properties
• Changing the Status Line
  • window Object Methods
• Opening and Closing Windows
• Using Prompts, Alerts, and Confirmation Dialogs
• Updating a Page with Timeouts
• Using window Object Event Handlers
• The location Object
• The document Object
  • document Object Properties
  • document Object Methods
• The history Object
• Implementing BACK and FORWARD Buttons
• The link Object
• The anchor Object
• form Objects
• Workshop Wrap-Up
  • Next Steps
  • Q&A
    

One of JavaScript's strengths is the capability of working with elements of the Web page directly. This is handled through the JavaScript object hierarchy. This hierarchy includes a variety of objects that represent data on the current Web page and in the current browser window.

These objects are organized into a hierarchy of parent and child objects. A child object is simply an object that is used as a property of another object (the parent object).

Each of the objects in the hierarchy includes properties, which are often objects in themselves. It may also include methods to perform functions on the object. Finally, it may include event handlers, which call functions or JavaScript statements when an event happens to that object.

A diagram of the object hierarchy is given in Figure 5.1. The hierarchy begins with the window object, which serves as the parent object for most of the other objects. This chapter describes each object in the following sections, beginning with the window object and working downward through the hierarchy.

Figure 5.1 : The JavaScript object hierarchy.

The window Object

The window object is at the top of the object hierarchy. A window object exists for each open browser window. The properties of this object describe the document in the window and provide information about the window. Three of the window object's properties are child objects:

• The location object stores the location (URL) that is displayed in the window.
• The document object holds the Web page itself.
• The history object contains a list of sites visited before and after the current site.

Each of these objects is described in detail later in this chapter. In most cases, there is only one window object, so you can omit the window object name when referring to the current script's window. For example, this statement sets the current window's status property:

status = "This is a test."

There are several terms that refer to window objects:

• window refers to the current window object.
• self also refers to the current window object.
• top refers to the topmost (usually, the first) browser window.
• parent refers to the parent window when frames are used. Frames will be introduced later in this section.
• opener is used for windows you create and refers to the window that opened the current window.

You will now take a closer look at the properties, methods, and event handlers of the window object. The child objects (location, document, and history) will be covered in their own sections later in this chapter.

window Object Properties

The window object has a variety of properties that specify information about the window and its components. The simplest property is the name property; this contains the name of the current window.

If you create a window yourself, using the open() method described later in this chapter, you give it a name; otherwise, the name property remains blank. You will now look at the other properties of the window object, which enable you to deal with the status line and with framed documents.

Changing the Status Line

One of the simplest window object properties enables you to manipulate the status line-the gray-background line at the bottom of the window. This line is usually used to display URLs of links as you move the mouse over them. With JavaScript, you can display anything you like in this area.

As an example, Listing 5.1 shows an HTML page that uses a JavaScript event handler to enable you to modify the status line when you press a button.

Listing 5.1. (STATUS.asp) An HTML document that uses JavaScript to change the status line.

<HTML> <HEAD><TITLE>The Amazing Status Line Changer</TITLE> </HEAD> <BODY> <H1>Change the Status Line</H1> <HR> Enter the text for the status line in the space below, then press the chANGE button to change it.<HR> <FORM NAME="statform"> <INPUT TYPE="text" SIZE="65" NAME="input1"><BR> <INPUT TYPE="button" VALUE="chANGE" onClick="window.status=document.statform.input1.value;"> </FORM> <HR> end. </BODY> </HTML>

This is an example of how much you can do with a single JavaScript statement. The HTML defines a form called statform with two fields: a text field and a button. You enter the text in the text field. Each time you press the button, the onClick event handler changes the status line to match the text field. Netscape's display of this page, including a modified status line, is shown in Figure 5.2.

Figure 5.2 : The status line changing program, as displayed by Netscape.

Although this application is an example of how much fun you can have with JavaScript in only one statement, it's not very useful. A more common (and more practical) application is to use the status line for onMouseOver event handlers, which enables you to provide useful instructions for links and form elements. You'll learn about this use of the status property in Chapter 8.

Using Frames

Some browsers (including the latest Netscape and Microsoft browsers) support frames or framesets. These enable you to divide the browser window into multiple panes, called frames. Each frame can contain a separate URL or the output of a script.

When you use frames, there are several window objects: one for the main (parent) window, and one for each frame. The window object has two properties that are used with frame documents:

• The frames array is used to store information about each frame. It is made up of frame objects, which work as window objects in themselves. You can also refer to a frame's window object by name.
• The parent.frames.length property specifies the number of frames in the window.

Because frames can make for some complicated-and useful-programming, they are described in detail in Chapter 9 "Using Frames, Cookies, and Other Advanced Features."

window Object Methods

Along with the properties you have already looked at, the window object includes a variety of methods. These enable you to perform window-related functions: opening, closing, and manipulating windows and displaying dialog boxes. Methods are also included to set timers to perform an action after a certain time.

The window.open() method enables you to open a new browser window. A typical statement to open a new window looks like this:

WindowName=window.open("URL", "WindowName", "Feature List");

The following are the components of the window.open() statement:

• The WindowName variable is used to store the new window object. You can access methods and properties of the new object by using this name.
• The first parameter of the window.open() method is an URL, which will be loaded into the new window. If left blank, no Web page will be loaded.
• The second parameter specifies a window name (here, WindowName again). This is assigned to the window object's name property and is used for targets, which are explained in Chapter 9.
• The third parameter is a list of optional features, separated by commas. You can customize the new window by choosing whether to include the toolbar, status line, and other features. This enables you to create a variety of "floating" windows, which may look nothing like a typical browser window.

The features available in the third parameter of the window.open() method include width and height, to set the size of the window, and several features that can be set to either yes (1) or no (0): toolbar, location, directories, status, menubar, scrollbars, and resizable. You can list only the features you want to change from the default. This example creates a small window with no toolbar or status line:

SmallWin = window.open("","small","width=100,height=120,toolbar=0,status=0");

Opening and Closing Windows

Of course, you can close windows as well. The window.close() method closes a window. Netscape doesn't enable you to close the main browser window without the user's permission; its main purpose is for closing windows you have created. For example, this statement closes a window called updatewindow:

updatewindow.close();

As another example, Listing 5.2 shows an HTML document that enables you to open a new window by pressing a button. (I have specified a very small size for the second window so you can tell them apart.) You can then press another button to close the new window. The third button attempts to close the current window; Netscape allows this, but asks for confirmation first.

Listing 5.2. (WINDOWS.asp) An HTML document that uses JavaScript to enable you to create and close windows.

<HTML> <HEAD><TITLE>Create a New Window</TITLE> </HEAD> <BODY> <H1>Create a New Window</H1> <HR> Use the buttons below to test opening and closing windows in JavaScript. <HR> <FORM NAME="winform"> <INPUT TYPE="button" VALUE="Open New Window" onClick="NewWin=window.open('','NewWin', 'toolbar=no,status=no,width=200,height=100'); "> <P><INPUT TYPE="button" VALUE="Close New Window" onClick="NewWin.close();" > <P><INPUT TYPE="button" VALUE="Close Main Window" onClick="window.close();"> </FORM> <BR>Have fun! <HR> </BODY> </HTML>

Again, this example uses event handlers to do its work, one for each of the buttons. Figure 5.3 shows Netscape's display of this page, with the small new window on top.

Figure 5.3 : A new Netscape window opened with JavaScript.

Displaying Dialogs

The window object includes three methods that are useful for displaying messages and interacting with the user:

• The alert() method displays an alert dialog box, shown in Figure 5.4. This dialog simply gives the user a message.
• The confirm() method displays a confirmation dialog. This displays a message and includes OK and Cancel buttons. This method returns true if OK is pressed and false if Cancel is pressed. A confirmation is displayed in Figure 5.5.
• The prompt() method displays a message and prompts the user for input. It returns the text entered by the user.

Figure 5.4 : A JavaScript alert dialog displays a message.

Figure 5.5 : A JavaScript confirm dialog asks for confirmation.

Using Prompts, Alerts, and Confirmation Dialogs

As a further illustration of these types of dialogs, Listing 5.3 lists an HTML document that uses buttons and event handlers to enable you to test dialogs.

Listing 5.3. (DIALOG.asp) An HTML document that uses JavaScript to display alerts, confirmations, and prompts.

<HTML> <HEAD><TITLE>Alerts, Confirmations, and Prompts</TITLE> </HEAD> <BODY> <H1>Alerts, Confirmations, and Prompts</H1> <HR> Use the buttons below to test dialogs in JavaScript. <HR> <FORM NAME="winform"> <INPUT TYPE="button" VALUE="Display an Alert" onClick="window.alert('This is a test alert.'); "> <P><INPUT TYPE="button" VALUE="Display a Confirmation" onClick="temp = window.confirm('Would you like to confirm?'); window.status=(temp)?'confirm: true':'confirm: false'; "> <P><INPUT TYPE="button" VALUE="Display a Prompt" onClick="var temp = window.prompt('Enter some Text:','This is the default value'); window.status=temp; "> </FORM> <BR>Have fun! <HR> </BODY> </HTML>

This example displays three buttons, and each uses an event handler to display one of the dialogs. Let's take a detailed look at each one:

• The alert dialog is displayed when you click on the button.
• The confirmation dialog displays when you press the button, and displays a message in the status line indicating whether true or false was returned. The returned value is stored in the temp variable.
• The third button displays the prompt dialog. Notice that the prompt() method accepts a second parameter, which is used to set a default value for the entry. The value you enter is stored in the temp variable and displayed on the status line. Notice that if you press the Cancel button in the prompt dialog, the null value is returned.

Figure 5.6 shows the program in Listing 5.3 in action. The prompt dialog is currently displayed and shows the default value, and the status line is still displaying the result of a previous confirmation dialog.

Figure 5.6 : The dialog box example's output, including a prompt dialog.

Using Timeouts

Two more methods of the window object enable you to set timeouts. These are statements (or groups of statements) that will be executed after a certain amount of time elapses. These are handy for periodically updating a Web page or for delaying a message or function.

You begin a timeout with the setTimeout() method. This method has two parameters. The first is a JavaScript statement, or group of statements, enclosed in quotes. The second parameter is the time to wait in milliseconds (thousandths of seconds). For example, this statement displays an alert dialog after 10 seconds:

ident=window.setTimeout("alert('Time's up!')",10000);

A variable (ident in this example) stores an identifier for the timeout. This enables you to set multiple timeouts, each with its own identifier. Before a timeout has elapsed, you can stop it with the clearTimeout() method, specifying the identifier of the timeout to stop:

window.clearTimeout(ident);

These timeouts execute only once; they do not repeat unless you set another timeout each time.

Updating a Page with Timeouts

You can make a timeout repeat by issuing the setTimeout() method call again in the function called by the timeout. Listing 5.4 is an HTML document that demonstrates a repeating timeout.

Listing 5.4. (TIMEOUT.asp) Using the timeout methods to update a page every 2 seconds.

<HTML> <HEAD><TITLE>Timeout Example</TITLE> <SCRIPT> var counter = 0; // call Update function in 2 seconds after first load id=window.setTimeout("Update();",2000); function Update() { counter ++; window.status="The counter is now at " + counter; document.form1.input1.value="The counter is now at " + counter; // set another timeout for the next count id=window.setTimeout("Update();",2000); } </SCRIPT> </HEAD> <BODY> <H1>Timeout Example</H1> <HR> The text value below and the status line are being updated every two seconds. Press the RESET button to restart the count, or the STOP button to stop it. <HR> <FORM NAME="form1"> <INPUT TYPE="text" NAME="input1" SIZE="40"><BR> <INPUT TYPE="button" VALUE="RESET" onClick="counter = 0;"><BR> <INPUT TYPE="button" VALUE="STOP" onClick="window.clearTimeout(ID);"> <HR> </BODY> </HTML>

This program displays a message in the status line and in a text field every two seconds, including a counter that increments each time. You can use the RESET button to start the count over and the STOP button to stop the counting.

The setTimeout() method is used when the page first loads and again at each update. The Update() function performs the update, adding one to the counter and setting the next timeout. The RESET button sets the counter to zero, and the STOP button demonstrates the clearTimeout() method. Figure 5.7 shows Netscape's display of the timeout example after the counter has been running for a while.

Figure 5.7 : The output of the Timeout Example, as displayed by Netscape.

As you can see, timeouts can be useful for performing regular updates to a Web page's fields. You see this further with a scrolling message in Chapter 8and with a graphical clock display in < Chapter 12, " Working with Graphics in JavaScript."

Other window Object Methods

The window object has three remaining methods, which enable you to manipulate the window itself:

• The scroll() method scrolls the window, either horizontally or vertically. The parameters are x and y (column and row) offsets in pixels. For example, window.scroll(0,10) scrolls the window down 10 pixels.
• The focus() method gives a window focus-in other words, brings it to the top. This is handy when you have several windows open.
• The blur() method is the opposite-it removes focus from the specified window, sending it to the background.

Using window Object Event Handlers

The window object has several event handlers:

• The onLoad event occurs when the document in the window is finished loading.
• The onUnload event occurs when another document starts to load, replacing the window's current document.
• The onFocus event occurs when the window receives focus.
• The onBlur event occurs when the window loses focus.
• The onError event occurs if the document in the window fails to load properly.

You can specify JavaScript statements or functions for these events using attributes of a Web page's <BODY> tag. For example, Listing 5.5 shows an HTML document that displays an alert message when it is loaded and another when it is unloaded.

Listing 5.5. (ONLOAD.asp) Using the onLoad and onUnload events to display dialogs.

<HTML> <HEAD><TITLE>onLoad and onUnload Example</TITLE> </HEAD> <BODY onLoad="window.alert('Hello, and welcome to this page.');" onUnload="window.alert('You unloaded the page. Goodbye!');"> <H1>The onLoad and onUnload Methods</H1> <HR> This page displays a "hello" dialog when you load it, and a "goodbye" dialog when you unload it. Annoying, isn't it? <HR> This is done through event handlers specified in this document's &LTBODY&GT tag. Aside from that tag, the rest of the document doesn't affect the dialogs. <HR> </BODY> </HTML>

This document will display a "hello" alert when it loads and a "goodbye" alert when it unloads. You can unload the page by closing the browser window or by loading a different page. Figure 5.8 shows Netscape's display of this document, including the onLoad alert.

Figure 5.8 : The output of the onLoad and onUnload example.

The location Object

The location object is a property of the window object. It contains information about the current URL being displayed by the window. It has a set of properties to hold the different components of the URL, but no methods.

As you know, the URL format is used to specify the location of the Web page. Here is an example of a URL:

http://www.starlingtech.com:80/guides/javascript/test.asp#part2

The following are the components of the URL as they correspond with properties of the location object:

• location.protocol is the protocol (or method) of the URL. This specifies the protocol to be used-world-wide web, gopher, and so forth. In the example, the protocol is http:. The colon is included in the protocol property.
• location.hostname specifies the host where the resource is located (www.starlingtech.com in the example).
• location.port specifies the communication port number on the host, usually 80 for the Web (and in the example).
• location.host is a combination of the host name and port (www.starlingtech.com:80 in the example).
• location.pathname is the directory to find the document on the host and the name of the file (/guides/javascript/test.asp in the example).
• location.hash is the name of an anchor within the document, if specified (#part2 in the example). You can set this value to different anchor names to jump around the Web page.
• location.target specifies the TARGET attribute of the link that was used to reach the current location. You will examine this attribute in detail in Chapter 9.
• location.query specifies a query string; if the location is a CGI program, this string is passed as a parameter to the program.
• Finally, location.href is the whole URL, including all the parts listed.

The location object has two methods:

• location.reload() reloads the current document; this is the same as the reload button on Netscape's toolbar.
• location.replace() replaces the current location with a new one; this is similar to setting the location object's properties yourself. The difference is that the new location replaces the current history entry rather than adding to the history.

The document Object

Another child of the window object is the document object. This object represents the contents of the current HTML Web page. This object includes a wide variety of attributes that specify information about the current page.

In addition, the document object includes the form, link, and anchor objects to describe forms, links, and anchors on the page. You will look at each of these later in this chapter. The document object has no event handlers of its own.

document Object Properties

The properties of the document object represent characteristics of the current HTML page. Many of these are specified in the <BODY> tag of the document, and others are set by the browser when the document is loaded.

Information About the Document

Several properties of the document object include information about the current document in general:

• The URL property (formerly location) specifies the document's URL. Don't confuse this with the location object explained earlier: it's a simple text field. You can't change this property; if you need to send the user to a different location, use the window.location.href property.
• The title property lists the title of the current page, defined by the HTML <TITLE> tag.
• The referrer property is the URL of the page the user was viewing prior to the current page-usually, the page with a link to the current page.
• The lastModified property is the date the document was last modified. This date is sent from the server along with the page.

As an example, this is a short HTML document that displays its last-modified date:

<HTML><HEAD><TITLE>Test Document</TITLE></HEAD> <BODY> This page was last modified on: <SCRIPT> document.write(document.lastModified); </SCRIPT> <BR> </HTML>

This can be a useful indication to the user of when the page was last changed, and if you use JavaScript, you don't have to remember to update the date each time you modify the page.

Link and Form Information

The next set of properties of the document object concern the links, forms, anchors, and images in the HTML document:

• The form objects include information about each <FORM> in the current document.
• The anchors array identifies each of the anchors (places that can be jumped to) in the current document.
• The links array includes information for each of the links in the current document.
• The images array contains information about each of the images in the document.

The forms, anchors, and links objects are each discussed in their own sections later in this chapter. The images array is explained in Chapter 12.

Controlling Document appearance

The final set of document object properties are used to store information about color settings for the document. Again, you can't change these directly; they are specified as attributes to the document's <BODY> tag. Here are the available color properties:

• bgColor is the background color, specified with the BGCOLOR attribute.
• fgColor is the foreground (text) color, specified with the TEXT attribute.
• linkColor is the color used for nonvisited links, specified with the LINK attribute.
• vlinkColor is the color for visited links, specified with the VLINK attribute.

document Object Methods

In addition to these properties, the document object has a few handy methods. These can be used to control the opening and closing of documents and to output HTML as part of the document.

Writing HTML Text

The simplest document object methods are also the ones you will use most often. In fact, you've used one of them already. The document.write() method prints text as part of the HTML page in a document window. This statement is used whenever you need to include output in a Web page.

An alternative statement, document.writeln(), also prints text, but it also includes a newline (\n) character at the end. This is handy when you want your text to be the last thing on the line.

You can only use these methods within the body of the Web page, so they will be executed when the page loads; you can't add to a page that has already loaded. You can write new content for a document, however, as the next section explains.

Opening and Closing Streams

The document object includes open() and close() methods. Unlike the window object methods of the same name, these methods don't actually open and close new documents or windows. Instead, the open() method opens a stream; this clears the document and enables you to create a new one with the write() or writeln() methods.

The data you send to a stream isn't actually displayed until the close() method is used. You can use this to ensure that blocks of write commands execute at the same time. Chapter 9includes an example of using these methods to write new content to a frame.

You can optionally specify a MIME document type in the document.open command. This enables you to create a document of any type, including images and documents used by plug-in applications. You'll learn about plug-ins in detail in Chapter 13, "Working with Multimedia and Plug-ins."

Clearing the Document Window

The final document method is the clear() method. It simply clears the document's contents. For example, the following statement clears the main window:

document.clear();

The history Object

The history object is another child (property) of the window object. This object holds information about the URLs that have been visited before and after the current one, and it includes methods to go to previous or next locations.

The history object has one property: length. This keeps track of the length of the history list-in other words, the number of different locations that the user has visited.

You might notice one thing missing from the history object's properties: the URLs themselves. These used to be available as a property, but Netscape removed them due to privacy concerns. When they worked, Web pages could grab your history list and use it for statistics, marketing, or even blackmail.

The history object's methods enable you to send the user to other locations:

• history.back() goes back to the previous location. This is equivalent to the browser's back-arrow button.
• history.forward() goes forward to the next location. This is equivalent to the browser's forward-arrow button.
• history.go() goes to a specified location in the history list. You can specify a positive number to go forward, a negative number to go back, or a string to be searched for in the history list.

Implementing BACK and FORWARD Buttons

As an example of the history object's methods, Listing 5.6 shows an HTML page that includes BACK and FORWARD buttons, implemented with JavaScript event handlers. These work in the same way as the browser's back- and forward-arrow buttons. The output of this example is shown in Figure 5.9.

Figure 5.9 : The BACK and FORWARD example's output in Netscape.

Listing 5.6. A Web page that uses JavaScript to include BACK and FORWARD buttons.

<HTML> <HEAD><TITLE>Back and Forward Example</TITLE> </HEAD> <BODY> <H1>Back and Forward Example</H1> <HR> This page allows you to go back or forward to pages in the history list. These should be equivalent to the back and forward arrow buttons in the browser's toolbar. <HR> <FORM NAME="form1"> <INPUT TYPE="button" VALUE="< - BACK" onClick="history.back();"> ... <INPUT TYPE="button" VALUE="FORWARD - >" onClick="history.forward();"> <HR> </BODY> </HTML>

The link Object

Another child of the document object is the link object. Actually, there can be multiple link objects in a document. Each one includes information about a link to another location or anchor.

You can access link objects with the links array. Each member of the array is one of the link objects in the current page. A property of the array, document.links.length, indicates the number of links in the page.

Each link object (or member of the links array) has a list of properties defining the URL. These are the same properties as the location object, defined earlier in this chapter. You can refer to a property by indicating the link number and property name. For example, this statement assigns the variable link1 to the entire URL of the first link (index 0):

link1 = links[0].href;

The link object includes two event handlers:

• The onMouseOver event happens when the mouse pointer moves over the link's text.
• The onClick event happens when the user clicks on the link.

You'll use the onMouseOver event to create friendly status-line descriptions for links in Chapter 8. As for the onClick event handler, it's very handy for executing a JavaScript function when the user clicks on a link. For example, this defines a link that displays an alert:

<a href="#" onClick="window.alert('This is a test.');">

Notice that I used a simple # sign as the URL in this example, to avoid sending the user to another page when the link is clicked. Another use for the onClick event handler is to prevent a link from being followed; your event handler can do this by returning false. For example, this link asks for confirmation:

<a href="sound.wav" onClick="return window.confirm('play sound?');">

If the user clicks the OK button, the link is followed because true is returned; otherwise, false is returned and the link is ignored. This might be handy for files that will take a while to download, or any situation where you want to control links with JavaScript.

The anchor Object

anchor objects are also children of the document object. Each anchor object represents an anchor in the current document-a particular location that can be jumped to directly.

Like links, anchors can be accessed through an array: anchors. Each element of this array is an anchor object. The document.anchors.length property gives you the number of elements in the anchors array.

At least for now, the number of anchors is all you can know. The anchor objects don't include the name or locations of the anchors. The exact reason for this is a mystery, but it will hopefully be remedied in a future version of Netscape (or another browser).

form Objects

Another child of the document object is the form object, which represents an HTML form. Like anchors and links, there can be several form objects within a document. You can access a form by name (specified with the NAME attribute to the <FORM> tag) or by using the forms array, which includes an element for each form.

The form has many properties that are objects themselves: the elements, or components, of the form. These are the text fields, buttons, and other objects that make up a form. You can access these by using their individual names, or once again with an array; the elements array indexes each element of the form.

Forms have been used in a few of the examples in this chapter. Because forms are one of the greatest strengths of JavaScript, there's a lot of information to cover. Chapter 6covers forms and form objects in detail.

Workshop Wrap-Up

In this chapter, you took a guided tour of the JavaScript object hierarchy, which contains objects to represent parts of the current window and document:

• The window object represents the browser window or each window in a framed document.
• The document object represents the currently loaded document in a window.
• The location object stores the current location or URL for each window.
• The history object stores the history of documents for a window or frame.
• The link and anchor objects store information about links and link targets in a document.
• The forms array, or form objects, store information about each form in a document.

Next Steps

You should now know the JavaScript object hierarchy inside and out. Continue with one of these:

• To learn about built-in objects outside the hierarchy, such as Math, Date, Array, and String, see Chapter 4 "Using Built-In Objects and Custom Objects."
• To learn to use the objects to work with HTML forms, see Chapter 6, "Using Interactive Forms."
• To learn more about using frames and other features of the latest generation of Web browsers, see Chapter 9 "Using Frames, Cookies, and Other Advanced Features."
• To see some of the techniques in this chapter in action, see Chapter 7 "Real-Life Examples I."
• To learn techniques for perfecting and debugging your JavaScript programs, see Chapter 14, "Debugging JavaScript Programs."

Q&A