Team LiB   Previous Section   Next Section
Document represents an HTML document

Availability

JavaScript 1.0; enhanced in JavaScript 1.1, Netscape 4, and IE 4

Inherits from/Overrides

Inherits from HTMLElement

Synopsis

window.document 

document 

Properties

Document inherits properties from HTMLElement and defines the following properties. Netscape and Internet Explorer both define a number of incompatible Document properties that are used mostly for DHTML; they are listed separately after these properties.

alinkColor

alinkColor is a string property that specifies the color of activated links in document. Browsers may display this color between the times that the user presses and releases the mouse button over the link. The alink attribute of the <body> HTML tag specifies the initial value of this property. This property may be set, but only in the <head> of the document. See also the color properties of HTMLBodyElement in the DOM reference section.

anchors[]

An array of Anchor objects, one for each anchor that appears in document. An anchor is a named position within the document that can serve as the target of a hypertext link. The anchors[] array has anchors.length elements, numbered from zero to anchors.length-1. Do not confuse anchors with hypertext links, which are represented in JavaScript by the Link objects in the Document.links[] array.

Prior to JavaScript 1.2, the Anchor object was unimplemented, and the elements of anchors[] were all null.

applets[] [ JavaScript 1.1]

An array of Applet objects, one for each applet that appears in the document. You can use the Applet object to read and write all public variables in the applet, and you can invoke all of the applet's public methods. If an <applet> tag has a name attribute, the applet may also be referred to by using the name as a property of document or as an index into the applets array. Thus, if the first applet in a document has name="animator", you can refer to it in any of these ways:

document.applets[0]

document.animator

document.applets["animator"]
bgColor

A string property that specifies the background color of document. The initial value of this property comes from the bgcolor attribute of the <body> tag. The background color may be changed by assigning a value to bgColor. Unlike the other color properties, bgColor can be set at any time. See also the color properties of HTMLBodyElement in the DOM reference section.

cookie

A string that is the value of a cookie associated with this document. See the Document.cookie reference page.

domain

A string that specifies the document's Internet domain. Used for security purposes. JavaScript 1.1 and higher. See the Document.domain reference page.

embeds[] [ JavaScript 1.1]

An array of objects that represent data embedded in the document with the <embed> tag. The objects in the embeds[] array do not refer to the embedded data directly but refer instead to the object that displays that data. You can use the objects in the embeds[] array to interact with embedded data. The way you do this, however, is specific to the type of embedded data and the plugin or ActiveX control used to display it. Consult the developer's documentation for the plugin or ActiveX control to learn whether it can be scripted from JavaScript and, if so, what the supported APIs are.

Document.plugins[] is a synonym for Document.embeds[]. Do not confuse it with Navigator.plugins[].

fgColor

A string property that specifies the default color of text in document. The initial value of this property is from the text attribute of the <body> tag, and you can set the value of this property from a script within the <head> of the document. See also the color properties of HTMLBodyElement in the DOM reference section.

forms[]

An array of Form objects, one for each HTML form that appears in document. The forms[] array has forms.length elements, numbered from zero to forms.length-1.

images[] [ JavaScript 1.1]

An array of Image objects, one for each image that is embedded in the document with the HTML <img> tag. If the name attribute is specified in the <img> tag for an Image, a reference to that image is also stored in a property of the Document object. This property has the same name as the image. So if an image has a name="toggle" attribute, you can refer to the image with document.toggle.

lastModified

A read-only string that specifies the date of the most recent change to the document (as reported by the web server). See the Document.lastModified reference page.

linkColor

A string property that specifies the color of unvisited links in the document. The value of this property is set by the link attribute of the <body> tag, and it may also be set by a script in the <head> of the document. See also the color properties of HTMLBodyElement in the DOM reference section.

links[]

An array of Link objects, one for each hypertext link that appears in the document. The links[] array has links.length elements, numbered from zero to links.length-1.

location [Deprecated]

A Location object that contains the complete URL of the current document; a synonym for the Window.location property. In JavaScript 1.0, this property was instead a read-only string object that served the same purpose as the Document.URL property.

plugins[] [ JavaScript 1.1]

A synonym for the embeds[] array. Refers to an array of objects that represent the plugins or ActiveX controls used to display embedded data in a document. The embeds property is the preferred way to access this array, since it avoids confusion with the Navigator.plugins[] array.

referrer

A read-only string property that contains the URL of the document, if any, from which the current document was reached. For example, if the user follows a link in document A to document B, the Document.referrer property in document B contains the URL of document A. On the other hand, if the user types the URL of document B directly and does not follow any link to get there, the Document.referrer property for document B is an empty string.

title

A read-only string property that specifies the title of the current document. The title is any text that appears between the <title> and </title> tags in the <head> of the document.

URL

A read-only string that specifies the URL of the document. See the Document.URL reference page.

vlinkColor

A string property that specifies the color of visited links in document. The value of this property is set by the vlink attribute of the <body> tag, and you can also set it from a script within the <head> of the document. See also the color properties of HTMLBodyElement in the DOM reference section.

Netscape Properties

height [Netscape 4]

The height, in pixels, of the document.

layers[] [Netscape 4 only]

An array of Layer objects that represent the layers contained within a document. Each Layer object contains its own subdocument, accessible through the document property of the Layer object. This property is available only in Netscape 4; it has been discontinued in Netscape 6.

width [Netscape 4]

The width, in pixels, of the document.

Internet Explorer Properties

activeElement [IE 4]

A read-only property that refers to the input element within the document that is currently active (i.e., has the input focus).

all[] [IE 4]

An array of all elements within the document. See the Document.all[] reference page.

charset [IE 4]

The character set of the document.

children[] [IE 4]

An array that contains the HTML elements, in source order, that are direct children of the document. Note that this is different than the all[] array that contains all elements in the document, regardless of their position in the containment hierarchy.

defaultCharset [IE 4]

The default character set of the document.

expando [IE 4]

This property, if set to false, prevents client-side objects from being expanded. That is, it causes a runtime error if a program attempts to set the value of a nonexistent property of a client-side object. Setting expando to false can sometimes catch bugs caused by property misspellings, which can otherwise be difficult to detect. This property can be particularly helpful for programmers who are switching to JavaScript after becoming accustomed to case-insensitive languages. Although expando works only in IE 4, it can be set safely (if ineffectively) in Netscape.

parentWindow [IE 4]

The window that contains the document.

readyState

Specifies the loading status of a document. It has one of the following four string values:

uninitialized

The document has not started loading.

loading

The document is loading.

interactive

The document has loaded sufficiently for the user to interact with it.

complete

The document is completely loaded.

Methods

Document inherits methods from HTMLElement and defines the following methods. Netscape and IE both define a number of incompatible Document methods that are used mostly for DHTML; they are listed separately.

clear( )

Erases the contents of the document. This method is deprecated in JavaScript 1.1.

close( )

Closes a document stream opened with the open( ) method.

open( )

Opens a stream to which document contents may be written.

write( )

Inserts the specified string or strings into the document currently being parsed or into a document stream opened with open( ).

writeln( )

Identical to write( ), except that it appends a newline character to the output.

Netscape Methods

captureEvents( )

Requests events of specified types.

getSelection( )

Returns the currently selected document text.

releaseEvents

Stops capturing specified event types.

routeEvent( )

Routes a captured event to the next interested element. See Window.routeEvent( ).

Internet Explorer Methods

elementFromPoint( )

Returns the element located at a given (X-coordinate, Y-coordinate) point.

Event Handlers

The <body> tag has onload and onunload attributes. Technically, however, the onload and onunload event handlers belong to the Window object rather than the Document object. See Window.onload and Window.onunload.

HTML Syntax

The Document object obtains values for a number of its properties from attributes of the HTML <body> tag. Also, the HTML contents of a document appear between the <body> and </body> tags:

<body

  [ background="imageURL" ]  // A background image for the document

  [ bgcolor="color" ]        // A background color for the document

  [ text="color" ]           // The foreground color for the document's text

  [ link="color" ]           // The color for unvisited links

  [ alink="color" ]          // The color for activated links

  [ vlink="color" ]          // The color for visited links

  [ onload="handler" ]       // JavaScript to run when the document is loaded

  [ onunload="handler" ]     // JavaScript to run when the document is unloaded

>

// HTML document contents go here

</body>

Description

The Document object represents the HTML document displayed in a browser window or frame (or layer, in Netscape 4). The properties of this object provide details about many aspects of the document, from the colors of the text, background, and anchors, to the date on which the document was last modified. The Document object also contains a number of arrays that describe the contents of the document. The links[] array contains one Link object for each hypertext link in the document. Similarly, the applets[] array contains one object for each Java applet embedded in the document, and the forms[] array contains one Form object for each HTML form that appears in the document.

The write( ) method of the Document object is especially notable. When invoked in scripts that are run while the document is loading, you can call document.write( ) to insert dynamically generated HTML text into the document.

See Chapter 14 for an overview of the Document object and of many of the JavaScript objects to which it refers. See Chapter 17 for an overview of the DOM standard.

See Also

Form, the document property of the Window object; Chapter 14; Document, HTMLDocument, and HTMLBodyElement in the DOM reference section

    Team LiB   Previous Section   Next Section