• The Navigator Object Tree
• The navigator Object
• The window Object
  • The status Property
  • Working with Dialog Boxes
  • Opening and Closing Windows
  • Window Focus
• The history Object
• The document Object
  • Writing Text to the Current Document Stream
  • Working with Document Colors
  • The anchors Array
  • The links Array
  • The location Object
  • Opening and Closing Documents
• Summary

- 5 -
The Netscape Navigator Object Tree

The Navigator Object Tree is at the core of client JavaScript. It is a hierarchical collection of core objects for scripting client-side applications using JavaScript.

The objects in the Navigator Object Tree provide methods and properties for working with windows, frames, URLs, documents and the Navigator history list.

The five objects in the Navigator Object Tree are covered in this chapter:

• The navigator Object
  
  
• The window Object
  
  
• The location Object
  
  
• The history Object
  
  
• The document Object
  
  

The Navigator Object Tree

The Navigator Object Tree provides the core objects—with associated properties and methods—for working with the client Navigator environment in JavaScript. These objects can be used for a variety of tasks including working with Navigator itself, manipulating client windows and their loaded documents, as well as manipulating URLs and Navigator's history list.

The Navigator Object Tree is organized into a hierarchy with two top-level objects: navigator and window. The structure of the tree and its objects is outlined in Figure 5.1.

Figure 5.1. The Navigator Object Tree

The objects in the Navigator Object Tree are described in Table 5.1.

The navigator Object

The navigator object provides six properties and one method, which provide information about the overall Navigator environment:

• appName—Reflects the name of the browser represented as a string. In the case of Navigator, appName takes the value "Netscape".
  
  
• appVersion—Reflects the version number of the browser represented as a string in the form VersionNumber (Platform; Version) where VersionNumber is the version number of the browser, Platform represents the operating system the browser runs under, and Version indicates whether the browser is the international or domestic version. For instance, in the international release version of Navigator 2.0 for Windows 3.1, navigator.appVersion has the value "2.0 (Win16; I)".
  
  
• appCodeName—Reflects the code name of the current browser represented as a string. For all versions of Navigator, navigator.appCodeName takes the value "Mozilla".
  
  
• javaEnabled()—Returns a Boolean value indicating if Java is enabled in the client browser.
  
  
• userAgent—Reflects the complete user agent identification of the browser as a string combining appName, appVersion, and appCodeName (i.e. "Mozilla/2.0 (Win16; I)").
  
  
• mimeTypes—Reflects the mime types available in Navigator in an array of mimeType objects.
  
  
• plugins—Reflects the plug-ins available in Navigator in an array of plugin objects.
  
  

The plugins and mimeTypes properties are discussed in more detail in Chapter 16, "Navigator Plug-Ins."

One of the more popular uses of the properties of the navigator object is to reflect the users back to them in a Web page. Many Web pages enable users to know what browser they are using to visit a site. This can be done with CGI-BIN scripts, but JavaScript enables it to happen entirely at the client end.

In addition, the navigator object can be used to customize content based on the version of the browser the user is using. For instance, Navigator 3.0 support additional features, such as background colors in individual table cells. If incorrectly used, users of browsers that don't support cell background may be faced with unreadable text.

The following HTML document displays its title in a single table cell. On Navigator 3.0, the background of the cell is black with white text but on Navigator 2.0, the text should be the default color for the document with the default background color.

This is done using the appVersion property of the navigator object:

<HTML>
<HEAD>
<TITLE>navigator Example</TITLE>
</HEAD>
<BODY>
<DIV ALIGN=CENTER>
<TABLE WIDTH=50% BGCOLOR="black" BORDER=1 ALIGN=CENTER>
<TR>
<TD>
<SCRIPT LANGUAGE="JavaScript">
if (navigator.appVersion.charAt(0) == "3")
  document.writeln('<FONT COLOR="white">');
</SCRIPT>
<DIV ALIGN=CENTER>
<H1>WELCOME</H1>
</CENTER>
<SCRIPT LANGUAGE="JavaScript">
if (navigator.appVersion.charAt(0) == "3")
  document.writeln('</FONT>');
</SCRIPT>
</TD>
</TR>
</TABLE>
This page is customized to your browser using JavaScript.
</DIV>
</BODY>
</HTML>

The results of this script look like those shown in Figure 5.2.

Figure 5.2. Using JavaScript's navigator object it is possible to customize content based the version of Navigator being used.

In this example, checking the first character of the navigator.appVersion string using the charAt() method of the string object enables the script to determine if Navigator 3.0 is being used. If Navigator 3.0 is being used, then the <FONT> tag is used to change the color of the title text to white.

The window Object

The window object is the parent object for each open Navigator window and its loaded document, location object, and history list.

Generally, the window object is not referred to explicitly because it is the assumed parent for any object, property, or method reference. For instance, the document object can be referred to as document rather than window.document and the confirm() method as confirm() rather than window.confirm().

It is possible to use the special keyword self to refer to the current window. For instance, self.location refers to the location object for the current window.

Table 5.2 outlines the properties and methods of the window object.

Some of these properties and methods deserve a more detailed discussion.

The status Property

The status bar at the bottom of Navigator windows can be used by script authors for many purposes, including the display of welcome messages, displaying descriptions of links, and presenting scrolling text messages.

The status bar can be dynamically updated by assigning a new value to window.status. The following script demonstrates how window.status can be used to display descriptions of links when the user points at a link:

<HTML>
<HEAD>
<TITLE>status Example</TITLE>
</HEAD>
<BODY>
Point at these links and look at the status bar:
<A HREF="home.html"
 onMouseover="self.status='Go back home ...'; return true">Home</A><BR>
<A HREF="next.html"
 onMouseover="self.status='Go to the next page'; return true">Next</A>
</BODY>
</HTML>

Here, the onMouseover event handler is used to update the status property (as shown in Figure 5.3). Event handlers are discussed in more detail in Chapter 6, " Event Processing." Notice the use of the self keyword to refer to the window object for the current window.

Figure 5.3. Using the status property, it's possible to display custom text in the status bar.

Working with Dialog Boxes

As indicated in Table 5.2, there are three methods for producing dialog boxes:

• alert()
  
  
• confirm()
  
  
• prompt()
  
  

Each of these produces different results.

The alert() method is generally used to display just that—an alert message—to the user. It takes a single string argument:

window.alert("This is a test");

and produces results similar to those shown in Figure 5.4.

Figure 5.4. An Alert Dialog Box.

Here the user can press the OK button and has no other choices.

The confirm() method adds one feature to the dialog box—a Cancel button, producing results similar to those shown in Figure 5.5:

window.confirm("Continue?");

Figure 5.5. A Confirm Dialog Box.

Because the confirm() dialog box returns a Boolean value based on the user's selection, it can be used to interact with the user. For instance, the following code segment only executes if the user clicks OK in the confirm dialog box:

if (confirm(message)) {
   JavaScript Code
}

The prompt() method takes dialog box interaction a step further: it offers the user the opportunity to enter information. The prompt() method takes two arguments—a message and default text for the text entry field:

prompt("Enter a color:","Blue");

which produces results similar to those shown in Figure 5.6.

Figure 5.6. A Prompt Dialog Box.

Here, the value in the text field is returned by the prompt() method if the user clicks on OK. If the user clicks on Cancel, then the null value is returned.

Opening and Closing Windows

The open() and close() methods provide the ability to open and close windows.

The open() method takes three arguments—two required arguments and one optional argument:

open("URL","windowName","parameterList");

parameterList is a comma-separated list of entries that specify the size and appearance of the new Navigator window. The possible entries in the parameter list follow:

• toolbar—specifies if the standard tool bar should appear
  
  
• location—specifies if the location field should be displayed
  
  
• directories—specifies if the directory buttons should be displayed
  
  
• status—specifies if the status bar appears
  
  
• menubar—indicates if the menu bar should be presented
  
  
• scrollbars—indicates if scroll bars should be used when the document is larger than the window
  
  
• resizable—specifies if the user should be allowed to resize the window
  
  
• width—specifies the width of the window in pixels
  
  
• height—indicates the height of the window in pixels
  
  

With the exception of width and height which take integer values, these parameters can be set with a value of 1 or yes or turned off with a value of 0 or no.

For instance, the command

window.open("new.html","newWindow","toolbar=no,location=yes,directories=no,status=no,menubar=no,scrollbars=no,resizable=0,width=200,height=300");

produces a 200x300 pixel window with a visible location field, no toolbar, no directory buttons, no status bar. and no scrollbars. The window is not resizable by the user. This window would look like Figure 5.7.

Figure 5.7. Using the open() method, new windows can be customized.

The close() method takes no arguments and can be used to close a window opened by the script or the window containing the script. To close the current window, simply use

self.close();

Closing a window opened by the script requires that a reference to the new window be created when it is first opened. This is accomplished by assigning the window object for the new window to a variable and then using the pointer to the window object to call the close() method for the new window:

windowPointer = window.open("URL","windowName");
windowPointer.close();

Window Focus

By using the focus() and blur() methods it is possible to control which window is in the front and to arbitrarily send a window to the back.

The following page provides two simple buttons: one creates a new window and the other brings it to the front, like in Figure 5.8:

<HTML>
<HEAD>
<TITLE>focus Example</TITLE>
<SCRIPT LANGUAGE="JavaScript">
var pointer;
</SCRIPT>
</HEAD>
<BODY>
<FORM>
<INPUT TYPE=button VALUE="Create Window"
 onClick="pointer = self.open('new.html','newWindow');"><BR>
<INPUT TYPE=button VALUE="Bring Window to Front"
 onClick="pointer.focus()">
</FORM>
</BODY>
</HTML>

Figure 5.8. The focus() method brings a window to the top.

The history Object

The history object provides the properties and methods needed to work with the history list of a window or frame.

The history object does not actually make the content of the list available to the script for security. This is done to prevent scripts from obtaining information about the browsing habits of users and returning it to a server. In addition, some URLs actually encode passwords and other information into the URL, and this needs to be protected from malicious scripts.

Instead, the methods and properties of the history object are designed to allow for navigation of the history list:

• length—An integer reflecting the length of the history list
  
  
• back()—Loads the previous URL in the history list
  
  
• forward()—Loads the next URL in the history list
  
  
• go()—Loads the URL indicated by an offset from the current place in the list
  
  

For instance, history.back() jumps back to the previous document while histoy.go(2) jumps forward two documents in the history list.

A string argument also can be passed to the go() method. This loads the nearest document in the list that contains the string passed as an argument. This string matching is case insensitive.

The document Object

The document object is the primary top-level object inside each window or frame. It provides the necessary properties and methods to interact with most of the elements inside a Web document.

The properties and methods of the document object are outlined in Table 5.3.

Writing Text to the Current Document Stream

The write() and writeln() methods can be used to output text in the current HTML as it is being rendered.

A basic example of this follows, producing results like those shown in Figure 5.9:

<BODY>
<H1>
<SCRIPT LANGUAGE="JavaScript">
document.writeln("Output by JavaScript");
</SCRIPT>
</H1>
</BODY>

Figure 5.9. The writeln() method can produce HTML output in the current document.

Working with Document Colors

The color properties—alinkColor, bgColor, fgColor, linkColor, vlinkColor—reflect the various color attributes set in the <BODY> tag, such as BGCOLOR, LINK, and VLINK.

These colors are generally specified as hexadecimal triplets. Netscape also supports a list of color names, which are outlined in Appendix E.

More than just reflecting the settings in a document, these color properties can be used to dynamically change colors. This is done by assigning new values to the properties.

The following page provides simple form to change background color dynamically:

<HTML>
<HEAD>
<TITLE>Color Example</TITLE>
</HEAD>
<BODY BGCOLOR="#FFFFFF">
<H1>Color Example</H1>
Use the following form to change the background color:
<BR>
<FORM>
<INPUT TYPE=text NAME="color">
<BR>
<INPUT TYPE=button VALUE="Change Color"
 onClick="document.bgColor=this.form.color.value">
</FORM>
</BODY>
</HTML>

This example produces results like those shown in Figure 5.10. This example uses forms and event handlers which are described in Chapters 7 and 5.

Figure 5.10. Document colors can be updated dynamically.

The anchors Array

Anchors in HTML are created using the <A> tag in the form

<A NAME="name">

These anchors can be referenced internally within a document by linking to <A HREF="#name"> or from another document by linking to <A HREF="URL#name">.

These anchors are exposed in JavaScript through the anchors array. Each entry in the array is a single anchor object. Anchors appear in the array in the order of their appearance in the HTML source code, starting with an index of 0.

The anchors array has a single property: length. The actual names of anchors are not reflected in the anchor object. Rather, the array can be used to verify if anchors exist.

The links Array

Links are defined in HTML using the <A> tag of the form

<A HREF="URL">

These links are reflected into an array of link objects and Area objects called links. As with the anchors array, links are reflected into the array in the order of their appearance in the HTML code and the array has a single property: length.

The link and Area objects has several properties:

• hash—A string reflecting the anchor portion of the link URL (after the "#")
  
  
• host—A string reflecting the hostname:port portion of the link URL
  
  
• hostname—A string reflecting the host and domain name of the link URL
  
  
• href—Reflects the entire link URL
  
  
• pathname—A string reflecting the path portion of the link URL
  
  
• port—A string reflecting the port number from the link URL
  
  
• protocol—A string reflecting the protocol of the link URL (before the ":")
  
  
• search—A string reflecting the query portion of the link URL (after the "?")
  
  
• target—A string reflecting the TARGET attribute of the <A> tag
  
  

These properties can be updated dynamically by assigning new values to them.

The location Object

The location object is similar to the link object except that it reflects the URL of the current document rather than the URL of a link. It has the same properties as the link object—with the exception of the target property—and adds several methods:

• reload()—Reloads the current document.
  
  
• replace()—Replaces the current document in the history list. Takes a string argument indicating the URL to load into the current place in the history list.
  
  

Opening and Closing Documents

The open() method allows an existing window to be opened for writing a new document of a specified MIME type. For instance, the following prepares the existing window referenced by windowPointer for receiving HTML.

windowPointer.document.open("text/html");

Once this stream has been opened, document.write() and document.writeln() can be used to output the data to be displayed. This stream of data continues until document.close() is issued, closing the document stream. Subsequent document.write() statements can't write to the document.

For example,

<SCRIPT LANGUAGE="JavaScript">
newWindow = window.open("","anotherWindow");
newWindow.document.open("text/html");
newWindow.document.writeln("<H1>Hello in another window!</H1>");
newWindow.document.close();
</SCRIPT>

opens a new window called anotherWindow, opens a document stream for HTML output, writes out a message, and closes the document.

The clear() method can be used after the close() method to clear a document window.

Summary

The Navigator Object Tree provides the core of client JavaScript. It includes objects for working with the navigator environment, windows, documents, history lists and URLs.

In the later chapters, some of the features of the Navigator Object Tree are examined more closely, including the form object, and Frames.

Chapter 6 covers events processing, which is the key to creating interactive Web applications and dynamic forms.