The Document Object (JavaScript: The Definitive Guide, 4th Edition)

14.1. Document Overview

To illustrate the scope and importance of the Document object, this chapter begins with a quick summary of the methods and properties of the object. The following sections also explain other important material that is important to understand before reading the rest of the chapter.

The DOM described in this chapter predates the W3C standards. By virtue of its nearly universal implementation, however, it is a de facto standard and is often referred to as the Level 0 DOM. You can use the techniques described in this chapter in any JavaScript-enabled web browser, with the exception of very old ones such as Netscape 2. Furthermore, the Document object methods and properties listed previously have been formalized as part of the Level 1 DOM, so they are guaranteed to remain supported by future browsers.

One important thing to understand about the W3C DOM standard is that it is a document object model for both XML and HTML documents. In this standard, the Document object provides generic functionality of use for both types of documents. HTML-specific functionality is provided by the HTMLDocument subclass. All the Document properties and methods described in this chapter are HTML-specific, and you can find more details about them under the "Document" entry in the client-side reference section of this book. You'll also find related information in the DOM reference section, under "Document" and "HTMLDocument."

14.1.4. Naming Document Objects

Before we begin our discussion of the Document object and the various objects it exposes, there is one general principle that you'll find it helpful to keep in mind. As you'll see, every <form> element in an HTML document creates a numbered element in the forms[] array of the Document object. Similarly, every <img> element creates an element in the images[] array. The same applies for <a> and <applet> tags, which define elements in the links[] and applets[] arrays.

In addition to these arrays, however, a Form, Image, or Applet object may be referred to by name if its corresponding HTML tag is given a name attribute. When this attribute is present, its value is used to expose the corresponding object as a property of the Document object. So, for example, suppose an HTML document contains the following form:

<form name="f1">
<input type="button" value="Push Me">
</form>

Assuming that the <form> is the first one in the document, your JavaScript code can refer to the resulting Form object with either of the following two expressions:

document.forms[0]  // Refer to the form by position within the document
document.f1        // Refer to the form by name

In fact, setting the name attribute of a <form> also makes the Form object accessible as a named property of the forms[] array, so you could also refer to the form with either of these two expressions:

document.forms.f1      // Use property syntax
document.forms["f1"]   // Use array syntax

The same applies for images and applets: using the name attribute in your HTML allows you to refer to these objects by name in your JavaScript code.

As you might imagine, it is convenient to give names to frequently used Document objects so that you can refer to them more easily in your scripts. We'll see this technique used a number of times in this and later chapters.

14.1.5. Document Objects and Event Handlers

To be interactive, an HTML document and the elements within it must respond to user events. We discussed events and event handlers briefly in Chapter 12, and we've seen several examples that use simple event handlers. We'll see many more examples of event handlers in this chapter, because they are key to working with Document objects.

Unfortunately, we must defer a complete discussion of events and event handlers until Chapter 19. For now, remember that event handlers are defined by attributes of HTML elements, such as onclick and onmouseover. The values of these attributes should be strings of JavaScript code. This code is executed whenever the specified event occurs on the HTML element.

In addition, there is one other way to define event handlers that we'll occasionally see used in this and later chapters. We'll see in this chapter that Document objects such as Form and Image objects have JavaScript properties that match the HTML attributes of the <form> and <img> tags. For example, the HTML <img> tag has src and width attributes, and the JavaScript Image object has corresponding src and width properties. The same is true for event handlers. The HTML <a> tag supports an onclick event handler, for example, and the JavaScript Link object that represents a hyperlink has a corresponding onclick property. As another example, consider the onsubmit attribute of the <form> element. In JavaScript, the Form object has a corresponding onsubmit property. Remember that HTML is not case-sensitive, and attributes can be written in uppercase, lowercase, or mixed-case. In JavaScript, all event handler properties must be written in lowercase.

In HTML, event handlers are defined by assigning a string of JavaScript code to an event handler attribute. In JavaScript, however, they are defined by assigning a function to an event handler property. Consider the following <form> and its onsubmit event handler:

<form name="myform" onsubmit="return validateform( );">...</form>

In JavaScript, instead of using a string of JavaScript code that invokes a function and returns its result, we could simply assign the function directly to the event handler property like this:

document.myform.onsubmit = validateform;

Note that there are no parentheses after the function name. That is because we don't want to invoke the function here; we just want to assign a reference to it. As another example, consider the following <a> tag and its onmouseover event handler:

<a href="help.html" onmouseover="status='Get Help Now!';">Help</a>

If we happen to know that this <a> tag is the first one in the document, we can refer to the corresponding Link object as document.links[0] and set the event handler this way instead:

document.links[0].onmouseover = function( ) { status = 'Get Help Now!'; }

See Chapter 19 for a complete discussion of assigning event handlers in this way.

Chapter 14. The Document Object

Contents:

14.1. Document Overview

14.1.1. Document Methods

14.1.2. Document Properties

14.1.3. The Document Object and Standards

14.1.4. Naming Document Objects

14.1.5. Document Objects and Event Handlers