Using Navigator objects

his chapter describes JavaScript objects in Navigator and how to use them. These client-side JavaScript objects are sometimes referred to as Navigator objects, to distinguish them from LiveWire objects or user-defined objects.

Navigator object hierarchy

When you load a document in Navigator, it creates a number of JavaScript objects with property values based on the HTML in the document and other pertinent information. These objects exist in a hierarchy that reflects the structure of the HTML page itself.

Although you cannot derive object classes from JavaScript objects, as you can in languages such as Java, it is useful to understand the Navigator JavaScript object hierarchy. In the strict object-oriented sense, this type of hierarchy is known as an instance hierarchy, because it concerns specific instances of objects rather than object classes. The Navigator object hierarchy is illustrated in the following figure.

In this hierarchy, an object's "descendants" are properties of the object. For example, a form named form1 is an object as well as a property of document, and is referred to as document.form1.

Every page has the following objects:

navigator: has properties for the name and version of the Navigator being used.
window: the top-level object; has properties that apply to the entire window. There is also a window object for each "child window" in a frames document.
document: contains properties based on the content of the document, such as title, background color, links, and forms.
location: has properties based on the current URL.
history: contains properties representing URLs the client has previously requested.

Depending on its content, the document may contain other objects. For instance, each form (defined by a FORM tag) in the document will have a corresponding Form object.

To refer to specific properties, you must specify the object name and all its ancestors. Generally, an object gets its name from the NAME attribute of the HTML tag. For more information and examples, see Chapter 3, "Using windows and frames".

For example, the following refers to the value property of a text field named text1 in a form named myform in the current document.

document.myform.text1.value.

document properties: an example

The properties of the document object are largely content-dependent. That is, they are created based on the HTML in the document. For example, document has a property for each form and each anchor in the document.

Suppose you create a page named simple.html that contains the following HTML:

<HEAD><TITLE>A Simple Document</TITLE>
<SCRIPT>
function update(form) {
          alert("Form being updated")
</SCRIPT>
</HEAD>
<BODY>
<FORM NAME="myform" ACTION="foo.cgi" METHOD="get" >Enter a value:
<INPUT TYPE="text" NAME="text1" VALUE="blahblah" SIZE=20 >
Check if you want: 
<INPUT TYPE="checkbox" NAME="Check1" CHECKED           
          onClick="update(this.form)"> Option #1
<P>
<INPUT TYPE="button" NAME="button1" VALUE="Press Me"
          onClick="update(this.form)">
</FORM>
</BODY>

As you saw in the previous chapter, JavaScript uses the following object notation:

objectName.propertyName

So, given the preceding HTML example, the basic objects would have properties like those shown here:


Property	Value
document.title	"A Simple Document"
document.fgColor	#000000
document.bgColor	#ffffff
location.href	"http://www.sampson.com/samples/simple.html"
history.length	7

Notice that the value of document.title reflects the value specified in the TITLE tag. The values for document.fgColor (the color of text) and document.bgColor (the background color) were not set in the HTML, so they are based on the default values specified in the Navigator Options|General Preferences dialog box.

Because there is a form in the document, there is also a Form object called myform (based on the form's NAME attribute) that has child objects for the checkbox and the button. Each of these objects has a name based on the NAME attribute of the HTML tag that defines it, as follows:

These are the full names of the objects, based on the Navigator object hierarchy.

document.myform, the form
document.myform.Check1, the checkbox
document.myform.button1, the button

Thus, the Form object myform has properties based on the attributes of the FORM tag, for example,

action is http://www.sampson.com/samples/foo.cgi, the URL to which the form is submitted.
method is "get," based on the value of the METHOD attribute.
length is 3, because there are three input elements in the form.

The Form object has child objects named button1 and text1, corresponding to the button and text field in the form. These objects have their own properties based on their HTML attribute values, for example,

button1.value is "Press Me"
button1.name is "Button1"
text1.value is "blahblah"
text1.name is "text1"

In practice, you refer to these properties using their full names, for example, document.myform.button1.value. This full name is based on the Navigator object hierarchy, starting with document, followed by the name of the form, myform, then the element name, button1, and, finally, the property name.

JavaScript reflection and HTML layout

JavaScript object property values are based on the content of your HTML document, sometimes referred to as reflection because the property values reflect the HTML. To understand JavaScript reflection, it is important to understand how the Navigator performs layout--the process by which Navigator transforms HTML tags into graphical display on your computer.

Generally, layout happens sequentially in the Navigator: the Navigator starts at the top of the HTML file and works downward, displaying output to the screen as it goes. Because of this "top-down" behavior, JavaScript reflects only HTML that it has encountered. For example, suppose you define a form with a couple of text-input elements:

<FORM NAME="statform">
<INPUT TYPE = "text" name = "userName" size = 20>
<INPUT TYPE = "text" name = "Age" size = 3>

These form elements are reflected as JavaScript objects that you can use after the form is defined: document.statform.userName and document.statform.Age. For example, you could display the value of these objects in a script after defining the form:

<SCRIPT>
document.write(document.statform.userName.value)
document.write(document.statform.Age.value)
</SCRIPT>

However, if you tried to do this before the form definition (above it in the HTML page), you would get an error, because the objects don't exist yet in the Navigator.

Likewise, once layout has occurred, setting a property value does not affect its value or appearance. For example, suppose you have a document title defined as follows:

<TITLE>My JavaScript Page</TITLE>

This is reflected in JavaScript as the value of document.title. Once the Navigator has displayed this in the title bar of the Navigator window, you cannot change the value in JavaScript. If you have the following script later in the page, it will not change the value of document.title, affect the appearance of the page, nor generate an error.

document.title = "The New Improved JavaScript Page"

There are some important exceptions to this rule: you can update the value of form elements dynamically. For example, the following script defines a text field that initially displays the string "Starting Value." Each time you click the button, you add the text "...Updated!" to the value.

<FORM NAME="demoForm">
<INPUT TYPE="text" NAME="mytext" SIZE="40" VALUE="Starting Value">
<P><INPUT TYPE="button" VALUE="Click to Update Text Field"
          onClick="document.demoForm.mytext.value += '...Updated!' ">
</FORM>

This is a simple example of updating a form element after layout.

Using event handlers, you can also change a few other properties after layout has completed, for example, document.bgcolor.