Navigator Objects

Using Navigator Objects

When you load a page in Navigator, it creates a number of objects corresponding to the page, its contents, and other pertinent information.

Every page always has the following objects:

window: the top-level object; contains properties that apply to the entire window. There is also a window object for each for "child window" in a frames document.
location: contains properties on the current URL
history: contains properties representing URLs the user has previously visited
document: contains properties for content in the current document, such as title, background color, and forms

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

For example, suppose you create a page named simple.html that contains the following HTML:

<TITLE>A Simple Document</TITLE> <BODY><FORM NAME="myform" ACTION="FormProc()" 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 always, there would be window, location, history, and document objects. These would have properties such as:

location.href = "http://www.terrapin.com/samples/vsimple.html"
document.title = "A Simple Document"
document.fgColor = #000000
document.bgColor = #ffffff
history.length = 7

These are just some example values. In practice, these values would be based on the document's actual location, its title, foreground and background colors, and so on.

Navigator would also create the following objects based on the contents of the page:

document.myform
document.myform.Check1
document.myform.Button1

These would have properties such as:

document.myform.action = http://terrapin/mocha/formproc()
document.myform.method = get
document.myform.length = 5
document.myform.Button1.value = Press Me
document.myform.Button1.name = Button1
document.myform.text1.value = blahblah
document.myform.text1.name = text1
document.myform.Check1.defaultChecked = true
document.myform.Check1.value = on
document.myform.Check1.name = Check1

Notice that each of the property references above starts with "document," followed by the name of the form, "myform," and then the property name (for form properties) or the name of the form element. This sequence follows the Navigator's object hierarchy, discussed in the next section.

Navigator Object Hierarchy

The objects in Navigator exist in a hierarchy that reflects the hierarchical structure of the HTML page itself. Although you cannot derive object classes from these objects, as you can in languages such as Java, it is useful to understand the Navigator's JavaScript object hierarchy. In the strict object-oriented sense, this type of hierarchy is known as an instance hierarchy, since it concerns specific instances of objects rather than object classes.

In this hierarchy, an object's "descendants" are properties of the object. For example, a form named "form1" is an object, but is also a property of document, and is referred to as "document.form1". The Navigator object hierarchy is illustrated below:

To refer to specific properties of these objects, you must specify the object name and all its ancestors. Exception: You are not required to include the window object.

JavaScript and HTML Layout

To use JavaScript properly in the Navigator, it is important to have a basic understanding of how the Navigator performs layout. Layout refers to transforming the plain text directives of HTML into graphical display on your computer. Generally speaking, layout happens sequentially in the Navigator. That is, the Navigator starts from the top of the HTML file and works its way down, figuring out how to display output to the screen as it goes. So, it starts with the HEAD of an HTML document, then starts at the top of the BODY and works its way down.

Because of this "top-down" behavior, JavaScript only reflects HTML that it has encountered. For example, suppose you define a form with a couple of text input elments:

Then these form elements are reflected as JavaScript objects document.statform.username and document.statform.userage, that you can use anywhere after the form is defined. However, you could not use these objects before the form is defined. So, for example, you could display the value of these objects in a script after the form definition:

<SCRIPT> document.write(document.statform.username.value) document.write(document.statform.userage.value) </SCRIPT>

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

Likewise, once layout has occured, setting a property value does not affect its value or its 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 layout (in this case, in the title bar of the Navigator window), you cannot change the value in JavaScript. So, if later in the page, you have the following script:

document.title = "The New Improved JavaScript Page"

it will not change the value of document.title nor affect the appearance of the page, nor will is generate an error.

Key Navigator Objects

Some of the most useful Navigator objects include document, form, and window.

Using the document Object

One of the most useful Navigator objects is the document object, because its write and writeln methods can generate HTML. These methods are the way that you display JavaScript expressions to the user. The only difference between write and writeln is that writeln adds a carriage return at the end of the line. However, since HTML ignores carriage returns, this will only affect preformatted text, such as that inside a PRE tag.

The document object also has onLoad and onUnload event-handlers to perform functions when a user first loads a page and when a user exits a page.

There is only one document object for a page, and it is the ancestor for all the form, link, and anchor objects in the page.

Using the form Object

Navigator creates a form object for each form in a document. You can name a form with the NAME attribute, as in this example:

There would be a JavaScript object named myform based on this form. The form would have a property corresponding to the text object, that you would refer to as

document.myform.quantity You would refer to the value property of this object as document.myform.quantity.value

The forms in a document are stored in an array called forms. The first (topmost in the page) form is forms[0], the second forms[1], and so on. So the above references could also be:

document.forms[0].quantity document.forms[0].quantity.value

Likewise, the elements in a form, such as text fields, radio buttons, and so on, are stored in an elements array.

Using the window Object

The window object is the "parent" object for all other objects in Navigator. You can always omit the object name in references to window properties and methods.

Window has several very useful methods that create new windows and pop-up dialog boxes:

open and close: Opens and closes a browser window
alert: Pops up an alert dialog box
confirm: Pops up a confirmation dialog box

The window object has properties for all the frames in a frameset. The frames are stored in the frames array. The frames array contains an entry for each child frame in a window. For example, if a window contains three child frames, these frames are reflected as window.frames[0], window.frames[1], and window.frames[2].

The status property enables you to set the message in the status bar at the bottom of the client window.