Table of Contents | Previous | Next | Index

# document

Contains information about the current document, and provides methods for displaying HTML output to the user.

Client-side object
Implemented in | JavaScript 1.0 JavaScript 1.1: added `onBlur` and `onFocus` syntax; added `applets`, `domain`, `embeds`, `forms`, `formName`, `images`, and `plugins` properties. JavaScript 1.2: added `classes`, `ids`, `layers`, and `tags` `` properties; added `captureEvents`, `contextual`, `getSelection`, `handleEvent`, `releaseEvents`, and `routeEvent` methods.

#### Created by

The HTML `BODY` tag. The JavaScript runtime engine creates a `document` object for each HTML page. Each `window` object has a `document` property whose value is a `document` object. To define a `document` object, use standard HTML syntax for the `BODY` tag with the addition of JavaScript event handlers.

#### Event handlers

The `onBlur`, `onFocus`, `onLoad`, and `onUnload` event handlers are specified in the `BODY` tag but are actually event handlers for the `window` object. The following are event handlers for the `document` object.

- `onClick`
- `onDblClick`
- `onKeyDown`
- `onKeyPress`
- `onKeyUp`
- `onMouseDown`
- `onMouseUp`

#### Description

An HTML document consists of `HEAD` and `BODY` tags. The `HEAD` tag includes information on the document's title and base (the absolute URL base to be used for relative URL links in the document). The `BODY` tag encloses the body of a document, which is defined by the current URL. The entire body of the document (all other HTML elements for the document) goes within the `BODY` tag. You can load a new document by setting the `window.location` property. You can clear the document pane (and remove the text, form elements, and so on so they do not redisplay) with these statements:

    document.close();
    document.open();
    document.write();

You can omit the `document.open` call if you are writing text or HTML, since `write` does an implicit open of that MIME type if the document stream is closed. You can refer to the anchors, forms, and links of a document by using the `anchors`, `forms`, and `links` arrays. These arrays contain an entry for each anchor, form, or link in a document and are properties of the `document` object. Do not use `location` as a property of the `document` object; use the `document.URL` property instead. The `document.location` property, which is a synonym for `document.URL`, is deprecated.

#### Property Summary

Property | Description
--- | ---

    alinkColor

A string that specifies the `ALINK` attribute.

    anchors

An array containing an entry for each anchor in the document.

    applets

An array containing an entry for each applet in the document.

    bgColor

A string that specifies the `BGCOLOR` attribute.

    classes

Creates a `Style` object that can specify the styles of HTML tags with a specific CLASS attribute.

    cookie

Specifies a cookie.

    domain

Specifies the domain name of the server that served a document.

    embeds

An array containing an entry for each plug-in in the document.

    fgColor

A string that specifies the `TEXT` attribute.

    formName

A separate property for each named form in the document.

    forms

An array a containing an entry for each form in the document.

    height

The height of the document, in pixels.

    ids

Creates a `Style` object that can specify the style of individual HTML tags.

    images

An array containing an entry for each image in the document.

    lastModified

A string that specifies the date the document was last modified.

    layers

Array containing an entry for each layer within the document.

    linkColor

A string that specifies the `LINK` attribute.

    links

An array containing an entry for each link in the document.

    plugins

An array containing an entry for each plug-in in the document.

    referrer

A string that specifies the URL of the calling document.

    tags

Creates a `Style` object that can specify the styles of HTML tags.

    title

A string that specifies the contents of the `TITLE` tag.

    URL

A string that specifies the complete URL of a document.

    vlinkColor

A string that specifies the `VLINK` attribute.

    width

The width of the document, in pixels.

#### Method Summary

Method | Description
--- | ---

    captureEvents

Sets the document to capture all events of the specified type.

    close

Closes an output stream and forces data to display.

    contextual

Uses contextual selection criteria to specify a `Style` object that can set the style of individual HTML tags.

    getSelection

Returns a string containing the text of the current selection.

    handleEvent

Invokes the handler for the specified event.

    open

Opens a stream to collect the output of `write` or `writeln` methods.

    releaseEvents

Sets the window or document to release captured events of the specified type, sending the event to objects further along the event hierarchy.

    routeEvent

Passes a captured event along the normal event hierarchy.

    write

Writes one or more HTML expressions to a document in the specified window.

    writeln

Writes one or more HTML expressions to a document in the specified window and follows them with a newline character.

In addition, this object inherits the `watch` and `unwatch` methods from `Object`.

#### Examples

The following example creates two frames, each with one document. The document in the first frame contains links to anchors in the document of the second frame. Each document defines its colors. `doc0.html`, which defines the frames, contains the following code:

    <HTML>
    <HEAD>
    <TITLE>Document object example</TITLE>
    </HEAD>
    <FRAMESET COLS="30%,70%">
    <FRAME SRC="doc1.html" NAME="frame1">
    <FRAME SRC="doc2.html" NAME="frame2">
    </FRAMESET>
    </HTML>

`doc1.html`, which defines the content for the first frame, contains the following code:

    <HTML>
    <SCRIPT>
    </SCRIPT>
    <BODY
       BGCOLOR="antiquewhite"
       TEXT="darkviolet"
       LINK="fuchsia"
       ALINK="forestgreen"
       VLINK="navy">
    <P><B>Some links</B>
    <LI><A HREF="doc2.html#numbers" TARGET="frame2">Numbers</A>
    <LI><A HREF="doc2.html#colors" TARGET="frame2">Colors</A>
    <LI><A HREF="doc2.html#musicTypes" TARGET="frame2">Music types</A>
    <LI><A HREF="doc2.html#countries" TARGET="frame2">Countries</A>
    </BODY>
    </HTML>

`doc2.html`, which defines the content for the second frame, contains the following code:

    <HTML>
    <SCRIPT>
    </SCRIPT>
    <BODY
       BGCOLOR="oldlace" onLoad="alert('Hello, World.')"
       TEXT="navy">
    <P><A NAME="numbers"><B>Some numbers</B></A>
    <UL><LI>one
    <LI>two
    <LI>three
    <LI>four</UL>
    <P><A NAME="colors"><B>Some colors</B></A>
    <UL><LI>red
    <LI>orange
    <LI>yellow
    <LI>green</UL>
    <P><A NAME="musicTypes"><B>Some music types</B></A>
    <UL><LI>R&B
    <LI>Jazz
    <LI>Soul
    <LI>Reggae</UL>
    <P><A NAME="countries"><B>Some countries</B></A>
    <UL><LI>Afghanistan
    <LI>Brazil
    <LI>Canada
    <LI>Finland</UL>
    </BODY>
    </HTML>

#### See also

`Frame`, `window`

## alinkColor

A string specifying the color of an active link (after mouse-button down, but before mouse-button up).

Property of | `document`
Implemented in | JavaScript 1.0

#### Description

The `alinkColor` property is expressed as a hexadecimal RGB triplet or as a string literal (see the Client-Side JavaScript Guide). This property is the JavaScript reflection of the `ALINK` attribute of the `BODY` tag. If you express the color as a hexadecimal RGB triplet, you must use the format `rrggbb`. For example, the hexadecimal RGB values for salmon are `red=FA`, `green=80`, and `blue=72`, so the RGB triplet for salmon is `"FA8072"`.

#### Examples

The following example sets the color of active links using a string literal:

    document.alinkColor="aqua"

The following example sets the color of active links to aqua using a hexadecimal triplet:

    document.alinkColor="00FFFF"

#### See also

`document.bgColor`, `document.fgColor`, `document.linkColor`, `document.vlinkColor`

## anchors

An array of objects corresponding to named anchors in source order.

Property of | `document`
Read-only
Implemented in | JavaScript 1.0

#### Description

You can refer to the `Anchor` objects in your code by using the `anchors` array. This array contains an entry for each `A` tag containing a `NAME` attribute in a document; these entries are in source order. For example, if a document contains three named anchors whose `NAME` attributes are `anchor1`, `anchor2`, and `anchor3`, you can refer to the anchors either as:

    document.anchors["anchor1"]
    document.anchors["anchor2"]
    document.anchors["anchor3"]

or as:

    document.anchors[0]
    document.anchors[1]
    document.anchors[2]

To obtain the number of anchors in a document, use the `length` property: `document.anchors.length`. If a document names anchors in a systematic way using natural numbers, you can use the `anchors` array and its `length` property to validate an anchor name before using it in operations such as setting `location.hash`.

## applets

An array of objects corresponding to the applets in a document in source order.

Property of | `document`
Read-only
Implemented in | JavaScript 1.1

#### Description

You can refer to the applets in your code by using the `applets` array. This array contains an entry for each `Applet` object (`APPLET` tag) in a document; these entries are in source order. For example, if a document contains three applets whose `NAME` attributes are `app1`, `app2`, and `app3`, you can refer to the anchors either as:

    document.applets["app1"]
    document.applets["app2"]
    document.applets["app3"]

or as:

    document.applets[0]
    document.applets[1]
    document.applets[2]

To obtain the number of applets in a document, use the `length` property: `document.applets.length`.

## bgColor

A string specifying the color of the document background.

Property of | `document`
Implemented in | JavaScript 1.0

#### Description

The `bgColor` property is expressed as a hexadecimal RGB triplet or as a string literal (see the Client-Side JavaScript Guide). This property is the JavaScript reflection of the `BGCOLOR` attribute of the `BODY` tag. The default value of this property is set by the user with the preferences dialog box. If you express the color as a hexadecimal RGB triplet, you must use the format `rrggbb`. For example, the hexadecimal RGB values for salmon are `red=FA`, `green=80`, and `blue=72`, so the RGB triplet for `salmon` is `"FA8072"`.

#### Examples

The following example sets the color of the document background to aqua using a string literal:

    document.bgColor="aqua"

The following example sets the color of the document background to aqua using a hexadecimal triplet:

    document.bgColor="00FFFF"

#### See also

`document.alinkColor`, `document.fgColor`, `document.linkColor`, `document.vlinkColor`

## captureEvents

Sets the document to capture all events of the specified type.

Method of | `document`
Implemented in | JavaScript 1.2

#### Syntax

    captureEvents(eventType)

#### Parameters

    eventType

The type of event to be captured. The available event types are listed with the `event` object.

#### Description

When a window with frames wants to capture events in pages loaded from different locations (servers), you need to use `window.captureEvents` in a signed script and precede it with `window.enableExternalCapture`. For more information and an example, see `window.enableExternalCapture`. `captureEvents` works in tandem with `releaseEvents`, `routeEvent`, and `handleEvent`. For more information on events, see the Client-Side JavaScript Guide.

## classes

Creates a `Style` object that can specify the styles of HTML tags with a specific `CLASS` attribute.

Property of | `document`
Implemented in | JavaScript 1.2

#### Syntax

    document.classes.className.tagName

#### Parameters

    className

The case-insensitive value of the `CLASS` attribute of the specified HTML tag in `tagName`.

    tagName

The case-insensitive name of any HTML tag, such as `H1` or `BLOCKQUOTE`. If the value of `tagName` is `all`, `tagName` refers to all HTML tags.

#### Description

Use the `classes` property to specify the style of HTML tags that have a specific `CLASS` attribute. For example, you can specify that the color of the `GreenBody` class of both the `P` or the `BLOCKQUOTE` tags is green. See the `Style` object for a description of the style properties you can specify for `classes`. If you use the `classes` property within the `STYLE` tag (instead of within the `SCRIPT` tag), you can optionally omit `document` from the `classes` syntax. The `classes` property always applies to the current `document` object.

#### Examples

This example sets the color of all tags using the `GreenBody` `CLASS` attribute to green:

    <STYLE TYPE="text/javascript">
       classes.GreenBody.all.color="green"
    </STYLE>

Notice that you can omit the document object within the `STYLE` tag. Within the `SCRIPT` tag, you must specify the document object as follows:

    <SCRIPT LANGUAGE="JavaScript1.2">
       document.classes.GreenBody.all.color="green"
    </SCRIPT>

In this example, text appearing within either of the following tags appears green:

    <P CLASS="GreenBody">
    <BLOCKQUOTE CLASS="GreenBody">

#### See also

`document.contextual`, `document.ids`, `document.tags`, `Style`

## close

Closes an output stream and forces data sent to layout to display.

Method of | `document`
Implemented in | JavaScript 1.0

#### Syntax

    close()

#### Parameters

None.

#### Description

The `close` method closes a stream opened with the `document.open` method. If the stream was opened to layout, the `close` method forces the content of the stream to display. Font style tags, such as `BIG` and `CENTER`, automatically flush a layout stream. The `close` method also stops the "meteor shower" in the Netscape icon and displays Document: Done in the status bar.

#### Examples

The following function calls `document.close` to close a stream that was opened with `document.open`. The `document.close` method forces the content of the stream to display in the window.

    function windowWriter1() {
       var myString = "Hello, world!"
       msgWindow.document.open()
       msgWindow.document.write(myString + "<P>")
       msgWindow.document.close()
    }

#### See also

`document.open`, `document.write`, `document.writeln`

## contextual

Uses contextual selection criteria to specify a `Style` object that can set the style of individual HTML tags.

Method of | `document`
Implemented in | JavaScript 1.2

#### Syntax

    contextual(context1, ...[contextN,] affectedStyle)

#### Parameters

    context1, ...[contextN]

The `Style` objects, described by `document.classes` or `document.tags`, that establish the context for the affected `Style` object.

    affectedStyle

The `Style` object whose style properties you want to change.

#### Description

The `contextual` method provides a fine level of control for specifying styles. It lets you selectively apply a style to an HTML element that appears in a very specific context. For example, you can specify that the color of text within any `EM` tag that appears in an `H1` is blue. You can further narrow the selection by specifying multiple contexts. For example, you can set the color of any `LI` tags with two or more `UL` parents by specifying `UL` for the first two contexts.

#### Examples

Example 1. This example sets the color of text within any `EM` tag that appears in an `H1` to blue.

    <STYLE TYPE="text/javascript">
       contextual(document.tags.H1, document.tags.EM).color="blue";
    </STYLE>

Notice that you can omit the document object within the `STYLE` tag. Within the `SCRIPT` tag, you must specify the document object as follows:

    <SCRIPT LANGUAGE="JavaScript1.2">
    document.contextual(document.tags.H1, document.tags.EM).color="blue";
    </SCRIPT>

In this example, text appearing within the `EM` tag is blue:

    <H1 CLASS="Main">The following text is <EM>blue</EM></H1>

Example 2. This example sets the color of an `LI` element with two or more `UL` parents to red.

    <STYLE TYPE="text/javascript">
       contextual(tags.UL, tags.UL, tags.LI).color="red";
    </STYLE>

#### See also

`document.classes`, `document.tags`, `Style`

## cookie

String value representing all of the cookies associated with this document.

Property of | `document`
Implemented in | JavaScript 1.0

#### Security

JavaScript 1.1. This property is tainted by default. For information on data tainting, see the Client-Side JavaScript Guide.

#### Description

A cookie is a small piece of information stored by the web browser in the `cookies.txt` file. Use `string` methods such as `substring`, `charAt`, `indexOf`, and `lastIndexOf` to determine the value stored in the cookie. See Appendix C, "Netscape Cookies" for a complete specification of the cookie syntax. You can set the `cookie` property at any time. The `"expires="` component in the cookie file sets an expiration date for the cookie, so it persists beyond the current browser session. This date string is formatted as follows:

    Wdy, DD-Mon-YY HH:MM:SS GMT

This format represents the following values:

- `Wdy` is a string representing the full name of the day of the week.

- `DD` is an integer representing the day of the month.

- `Mon` is a string representing the three-character abbreviation of the month.

- `YY` is an integer representing the last two digits of the year.

- `HH`, `MM`, and `SS` are 2-digit representations of hours, minutes, and seconds, respectively.

For example, a valid cookie expiration date is

    expires=Wednesday, 09-Nov-99 23:12:40 GMT

The cookie date format is the same as the date returned by `toGMTString`, with the following exceptions:

- Dashes are added between the day, month, and year.

- The year is a 2-digit value for cookies.

#### Examples

The following function uses the `cookie` property to record a reminder for users of an application. The cookie expiration date is set to one day after the date of the reminder.

    function RecordReminder(time, expression) {
       // Record a cookie of the form "@<T>=<E>" to map
       // from <T> in milliseconds since the epoch,
       // returned by Date.getTime(), onto an encoded expression,
       // <E> (encoded to contain no white space, semicolon,
       // or comma characters)
       document.cookie = "@" + time + "=" + expression + ";"
       // set the cookie expiration time to one day
       // beyond the reminder time
       document.cookie += "expires=" + cookieDate(time + 24*60*60*1000)
       // cookieDate is a function that formats the date
       //according to the cookie spec
    }

#### See also

`Hidden`

## domain

Specifies the domain name of the server that served a document.

Property of | `document`
Implemented in | JavaScript 1.1

#### Security

JavaScript 1.1. This property is tainted by default. For information on data tainting, see the Client-Side JavaScript Guide.

#### Description

JavaScript 1.1. The `domain` property lets scripts on multiple servers share properties when data tainting is not enabled. With tainting disabled, a script running in one window can read properties of another window only if both windows come from the same Web server. But large Web sites with multiple servers might need to share properties among servers. For example, a script on the host `www.royalairways.com` might need to share properties with a script on the host `search.royalairways.com`. If scripts on two different servers change their `domain` property so that both scripts have the same domain name, both scripts can share properties. For example, a script loaded from `search.royalairways.com` could set its `domain` property to `"royalairways.com"`. A script from `www.royalairways.com` running in another window could also set its `domain` property to `"royalairways.com"`. Then, since both scripts have the domain `"royalairways.com"`, these two scripts can share properties, even though they did not originate from the same server. You can change `domain` only in a restricted way. Initially, `domain` contains the hostname of the Web server from which the document was loaded. You can set `domain` only to a domain suffix of itself. For example, a script from `search.royalairways.com` can't set its `domain` property to `"search.royalairways"`. And a script from `IWantYourMoney.com` cannot set its domain to `"royalairways.com"`. Once you change the `domain` property,`` you cannot change it back to its original value. For example, if you change `domain` from `"search.royalairways.com"` to `"royalairways.com"`, you cannot reset it to `"search.royalairways.com"`.

#### Examples

The following statement changes the `domain` property to `"braveNewWorld.com"`. This statement is valid only if `"braveNewWorld.com"` is a suffix of the current domain, such as `"www.braveNewWorld.com"`.

    document.domain="braveNewWorld.com"

## embeds

An array containing an entry for each object embedded in the document.

Property of | `document`
Read-only
Implemented in | JavaScript 1.1

#### Description

You can refer to embedded objects (created with the `EMBED` tag) in your code by using the `embeds` array. This array contains an entry for each `EMBED` tag in a document in source order. For example, if a document contains three embedded objects whose `NAME` attributes are `e1`, `e2`, and `e3`, you can refer to the objects either as:

    document.embeds["e1"]
    document.embeds["e2"]
    document.embeds["e3"]

or as:

    document.embeds[0]
    document.embeds[1]
    document.embeds[2]

To obtain the number of embedded objects in a document, use the `length` property: `document.embeds.length`. Elements in the `embeds` array may have public callable functions, if they refer to a plug-in that uses LiveConnect. See the LiveConnect information in the Client-Side JavaScript Guide. Use the elements in the `embeds` array to interact with the plug-in that is displaying the embedded object. If a plug-in is not Java-enabled, you cannot do anything with its element in the `embeds` array. The fields and methods of the elements in the `embeds` array vary from plug-in to plug-in; see the documentation supplied by the plug-in manufacturer. When you use the `EMBED` tag to generate output from a plug-in application, you are not creating a `Plugin` object.

#### Examples

The following code includes an audio plug-in in a document.

    <EMBED SRC="train.au" HEIGHT=50 WIDTH=250>

#### See also

`Plugin`

## fgColor

A string specifying the color of the document (foreground) text.

Property of | `document`
Implemented in | JavaScript 1.0

#### Description

The `fgColor` property is expressed as a hexadecimal RGB triplet or as a string literal (see the Client-Side JavaScript Guide). This property is the JavaScript reflection of the `TEXT` attribute of the `BODY` tag. The default value of this property is set by the user with the preferences dialog box You cannot set this property after the HTML source has been through layout. If you express the color as a hexadecimal RGB triplet, you must use the format `rrggbb`. For example, the hexadecimal RGB values for salmon are `red=FA`, `green=80`, and `blue=72`, so the RGB triplet for `salmon` is `"FA8072"`. You can override the value set in the `fgColor` property in either of the following ways:

- Setting the `COLOR` attribute of the `FONT` tag.

- Using the `fontcolor` method.

## formName

Property of | `document`
Implemented in | JavaScript 1.1

The `document` object contains a separate property for each form in the document. The name of this property is the value of its `NAME` attribute. See `Hidden` for information on `Form` objects. You cannot add new forms to the document by creating new properties, but you can modify the form by modifying this object.

## forms

An array containing an entry for each form in the document.

Property of | `document`
Read-only
Implemented in | JavaScript 1.1

#### Security

JavaScript 1.1. This property is tainted by default. For information on data tainting, see the Client-Side JavaScript Guide.

#### Description

You can refer to the forms in your code by using the `forms` array (you can also use the form name). This array contains an entry for each `Form` object (`FORM` tag) in a document; these entries are in source order. For example, if a document contains three forms whose `NAME` attributes are `form1`, `form2`, and `form3`, you can refer to the objects in the `forms` array either as:

    document.forms["form1"]
    document.forms["form2"]
    document.forms["form3"]

or as:

    document.forms[0]
    document.forms[1]
    document.forms[2]

Additionally, the document object has a separate property for each named form, so you could refer to these forms also as:

    document.form1
    document.form2
    document.form3

For example, you would refer to a `Text` object named `quantity` in the second form as `document.forms[1].quantity`. You would refer to the `value` property of this `Text` object as `document.forms[1].quantity.value`. The value of each element in the `forms` array is `<object nameAttribute>`, where `nameAttribute` is the `NAME` attribute of the form. To obtain the number of forms in a document, use the `length` property: `document.forms.length`.

## getSelection

Returns a string containing the text of the current selection.

Method of | `document`
Implemented in | JavaScript 1.2

#### Syntax

    getSelection()

#### Description

This method works only on the current document.

#### Security

You cannot determine selected areas in another window.

#### Examples

If you have a form with the following code and you click on the button, JavaScript displays an alert box containing the currently selected text from the window containing the button:

    <INPUT TYPE="BUTTON" NAME="getstring"
       VALUE="Show highlighted text (if any)"
       onClick="alert('You have selected:\n'+document.getSelection());">

## handleEvent

Invokes the handler for the specified event.

Method of | `document`
Implemented in | JavaScript 1.2

#### Syntax

    handleEvent(event)

#### Parameters

    event

The name of an event for which the specified object has an event handler.

#### Description

For information on handling events, see the Client-Side JavaScript Guide.

## height

The height of a document, in pixels.

Property of | `document`
Implemented in | JavaScript 1.2

#### See also

`document.width`

## ids

Creates a `Style` object that can specify the style of individual HTML tags.

Property of | `document`
Implemented in | JavaScript 1.2

#### Syntax

    document.ids.idValue

#### Parameters

    idValue

The case-insensitive value of the `ID` attribute of any HTML tag.

#### Description

Use the `ids` property to specify the style of any HTML tag that has a specific `ID` attribute. For example, you can specify that the color of the `NewTopic` `ID` is green. See the `Style` object for a description of the style properties you can specify for `ids`. The `ids` property is useful when you want to provide an exception to a class defined in the `document.classes` property. If you use the `ids` property within the `STYLE` tag (instead of within the `SCRIPT` tag), you can optionally omit `document` from the `ids` syntax. The `ids` property always applies to the current `document` object.

#### Examples

This example sets the Main `CLASS` attribute to 18-point bold green, but provides an exception for tags whose `ID` is `NewTopic`:

    <STYLE TYPE="text/javascript">
       classes.Main.all.color="green"
       classes.Main.all.fontSize="18pt"
       classes.Main.all.fontWeight="bold"
       ids.NewTopic.color="blue"
    </STYLE>

Notice that you can omit the document object within the `STYLE` tag. Within the `SCRIPT` tag, you must specify the document object as follows:

    <SCRIPT LANGUAGE="JavaScript1.2">
       document.classes.Main.all.color="green"
       document.classes.Main.all.fontSize="18pt"
       document.classes.Main.all.fontWeight="bold"
       document.ids.NewTopic.color="blue"
    </SCRIPT>

In this example, text appearing within the following tag is 18-point bold green:

    <H1 CLASS="Main">Green head</H1>

However, text appearing within the following tag is 18-point bold blue:

    <H1 CLASS="Main" ID="NewTopic">Blue head</H1>

#### See also

`document.classes`, `document.contextual`, `document.tags`, `Style`

## images

An array containing an entry for each image in the document.

Property of | `document`
Read-only
Implemented in | JavaScript 1.1

You can refer to the images in a document by using the `images` array. This array contains an entry for each `Image` object (`IMG` tag) in a document; the entries are in source order. Images created with the `Image` constructor are not included in the `images` array. For example, if a document contains three images whose `NAME` attributes are `im1`, `im2`, and `im3`, you can refer to the objects in the `images` array either as:

    document.images["im1"]
    document.images["im2"]
    document.images["im3"]

or as:

    document.images[0]
    document.images[1]
    document.images[2]

To obtain the number of images in a document, use the `length` property: `document.images.length`.

## lastModified

A string representing the date that a document was last modified.

Property of | `document`
Read-only
Implemented in | JavaScript 1.0

#### Security

JavaScript 1.1. This property is tainted by default. For information on data tainting, see the Client-Side JavaScript Guide.

#### Description

The `lastModified` property is derived from the HTTP header data sent by the web server. Servers generally obtain this date by examining the file's modification date. The last modified date is not a required portion of the header, and some servers do not supply it. If the server does not return the last modified information, JavaScript receives a 0, which it displays as January 1, 1970 GMT. The following code checks the date returned by `lastModified` and prints out a value that corresponds to unknown.

    lastmod = document.lastModified // get string of last modified date
    lastmoddate = Date.parse(lastmod)   // convert modified string to date
    if(lastmoddate == 0){               // unknown date (or January 1, 1970 GMT)
       document.writeln("Lastmodified: Unknown")
       } else {
       document.writeln("LastModified: " + lastmod)
    }

#### Examples

In the following example, the `lastModified` property is used in a `SCRIPT` tag at the end of an HTML file to display the modification date of the page:

    document.write("This page updated on " + document.lastModified)

## layers

The layers property is an array containing an entry for each layer within the document.

Property of | `document`
Implemented in | JavaScript 1.2

#### Description

You can refer to the layers in your code by using the `layers` array. This array contains an entry for each `Layer` object (`LAYER` or `ILAYER` tag) in a document; these entries are in source order. For example, if a document contains three layers whose `NAME` attributes are `layer1`, `layer2`, and `layer3`, you can refer to the objects in the `layers` array either as:

    document.layers["layer1"]
    document.layers["layer2"]
    document.layers["layer3"]

or as:

    document.layers[0]
    document.layers[1]
    document.layers[2]

When accessed by integer index, array elements appear in z-order from back to front, where 0 is the bottommost layer and higher layers are indexed by consecutive integers. The index of a layer is not the same as its `zIndex` property, as the latter does not necessarily enumerate layers with consecutive integers. Adjacent layers can have the same `zIndex` property values. These are valid ways of accessing layer objects:

    document.layerName
    document.layers[index]
    document.layers["layerName"]
    // example of using layers property to access nested layers:
    document.layers["parentlayer"].layers["childlayer"]

Elements of a layers array are JavaScript objects that cannot be set by assignment, though their properties can be set. For example, the statement

    document.layers[0]="music"

is invalid (and ignored) because it attempts to alter the `layers` array. However, the properties of the objects in the array readable and some are writable. For example, the statement

    document.layers["suspect1"].left = 100;

is valid. This sets the layer's horizontal position to 100. The following example sets the background color to blue for the layer `bluehouse` which is nested in the layer `houses`.

    document.layers["houses"].layers["bluehouse"].bgColor="blue";

To obtain the number of layers in a document, use the `length` property: `document.layers.length`.

## linkColor

A string specifying the color of the document hyperlinks.

Property of | `document`
Implemented in | JavaScript 1.0

#### Description

The `linkColor` property is expressed as a hexadecimal RGB triplet or as a string literal (see the Client-Side JavaScript Guide). This property is the JavaScript reflection of the `LINK` attribute of the `BODY` tag. The default value of this property is set by the user with the preferences dialog box. You cannot set this property after the HTML source has been through layout. If you express the color as a hexadecimal RGB triplet, you must use the format `rrggbb`. For example, the hexadecimal RGB values for salmon are `red=FA`, `green=80`, and `blue=72`, so the RGB triplet for salmon is `"FA8072"`.

#### Examples

The following example sets the color of document links to aqua using a string literal:

    document.linkColor="aqua"

The following example sets the color of document links to aqua using a hexadecimal triplet:

    document.linkColor="00FFFF"

#### See also

`document.alinkColor`, `document.bgColor`, `document.fgColor`, `document.vlinkColor`

## links

An array of objects corresponding to `Area` and `Link` objects in source order.

Property of | `document`
Read-only
Implemented in | JavaScript 1.0

#### Security

JavaScript 1.1. This property is tainted by default. For information on data tainting, see the Client-Side JavaScript Guide.

#### Description

You can refer to the `Area` and `Link` objects in your code by using the `links` array. This array contains an entry for each `Area` (`<AREA HREF="...">` tag) and `Link` (`<A HREF="...">` tag) object in a document in source order. It also contains links created with the `link` method. For example, if a document contains three links, you can refer to them as:

    document.links[0]
    document.links[1]
    document.links[2]

To obtain the number of links in a document, use the `length` property: `document.links.length`.

## open

Opens a stream to collect the output of `write` or `writeln` methods.

Method of | `document`
Implemented in | JavaScript 1.0 JavaScript 1.1: added `"replace"` parameter; `document.open()` or `document.open("text/html")` clears the current document if it has finished loading

#### Syntax

    open([mimeType, [replace]])

#### Parameters

    mimeType

A string specifying the type of document to which you are writing. If you do not specify `mimeType`, `text/html` is the default.

    replace

The string `"replace"`. If you supply this parameter, `mimeType` must be `"text/html"`. Causes the new document to reuse the history entry that the previous document used.

#### Description

Sample values for `mimeType` are:

- `text/html` specifies a document containing ASCII text with HTML formatting.

- `text/plain` specifies a document containing plain ASCII text with end-of-line characters to delimit displayed lines.

- `image/gif` specifies a document with encoded bytes constituting a GIF header and pixel data.

- `image/jpeg` specifies a document with encoded bytes constituting a JPEG header and pixel data.

- `image/x-bitmap` specifies a document with encoded bytes constituting a bitmap header and pixel data.

- `plugIn` loads the specified plug-in and uses it as the destination for `write` and `writeln` methods. For example, `"x-world/vrml"` loads the VR Scout VRML plug-in from Chaco Communications, and `"application/x-director"` loads the Macromedia Shockwave plug-in. Plug-in MIME types are only valid if the user has installed the required plug-in software.

The `open` method opens a stream to collect the output of `write` or `writeln` methods. If the `mimeType` is `text` or `image`, the stream is opened to layout; otherwise, the stream is opened to a plug-in. If a document exists in the target window, the `open` method clears it. End the stream by using the `document.close` method. The `close` method causes text or images that were sent to layout to display. After using `document.close`, call `document.open` again when you want to begin another output stream. In JavaScript 1.1 and later, `document.open` or `document.open("text/html")` clears the current document if it has finished loading. This is because this type of `open` call writes a default `<BASE HREF=>` tag so you can generate relative URLs based on the generating script's document base. The `"replace"` keyword`` causes the new document to reuse the history entry that the previous document used. When you specify `"replace"` while opening a document, the target window's history length is not incremented even after you write and close. `"replace"` is typically used on a window that has a blank document or an `"about:blank"` URL. After `"replace"` is specified, the `write` method typically generates HTML for the window, replacing the history entry for the blank URL. Take care when using generated HTML on a window with a blank URL. If you do not specify `"replace"`, the generated HTML has its own history entry, and the user can press the Back button and back up until the frame is empty. After `document.open("text/html","replace")` executes, `history.current` for the target window is the URL of document that executed `document.open`.

#### Examples

Example 1. The following function calls `document.open` to open a stream before issuing a `write` method:

    function windowWriter1() {
       var myString = "Hello, world!"
       msgWindow.document.open()
       msgWindow.document.write("<P>" + myString)
       msgWindow.document.close()
    }

Example 2. The following function calls `document.open` with the `"replace"` keyword to open a stream before issuing `write` methods. The HTML code in the `write` methods is written to `msgWindow`, replacing the current history entry. The history length of `msgWindow` is not incremented.

    function windowWriter2() {
       var myString = "Hello, world!"
       msgWindow.document.open("text/html","replace")
       msgWindow.document.write("<P>" + myString)
       msgWindow.document.write("<P>history.length is " +
          msgWindow.history.length)
       msgWindow.document.close()
    }

The following code creates the `msgWindow` window and calls the function:

    msgWindow=window.open('','',
       'toolbar=yes,scrollbars=yes,width=400,height=300')
    windowWriter2()

Example 3. In the following example, the `probePlugIn` function determines whether a user has the Shockwave plug-in installed:

    function probePlugIn(mimeType) {
       var havePlugIn = false
       var tiny = window.open("", "teensy", "width=1,height=1")
       if (tiny != null) {
          if (tiny.document.open(mimeType) != null)
             havePlugIn = true
          tiny.close()
       }
       return havePlugIn
    }

    var haveShockwavePlugIn = probePlugIn("application/x-director")

#### See also

`document.close`, `document.write`, `document.writeln`, `Location.reload`, `Location.replace`

## plugins

An array of objects corresponding to `Plugin` objects in source order.

Property of | `document`
Read-only
Implemented in | JavaScript 1.1

You can refer to the `Plugin` objects in your code by using the `plugins` array. This array contains an entry for each `Plugin` object in a document in source order. For example, if a document contains three plugins, you can refer to them as:

    document.plugins[0]
    document.plugins[1]
    document.plugins[2]

## referrer

Specifies the URL of the calling document when a user clicks a link.

Property of | `document`
Read-only
Implemented in | JavaScript 1.0

#### Security

JavaScript 1.1. This property is tainted by default. For information on data tainting, see the Client-Side JavaScript Guide.

#### Description

When a user navigates to a destination document by clicking a `Link` object on a source document, the `referrer` property contains the URL of the source document. `referrer` is empty if the user typed a URL in the Location box, or used some other means to get to the current URL. `referrer` is also empty if the server does not provide environment variable information.

#### Examples

In the following example, the `getReferrer` function is called from the destination document. It returns the URL of the source document.

    function getReferrer() {
       return document.referrer
    }

## releaseEvents

Sets the document to release captured events of the specified type, sending the event to objects further along the event hierarchy.

Method of | `document`
Implemented in | JavaScript 1.2

> NOTE: If the original target of the event is a window, the window receives the event even if it is set to release that type of event.

#### Syntax

    releaseEvents(eventType)

#### Parameters

    eventType

Type of event to be captured.

#### Description

`releaseEvents` works in tandem with `captureEvents`, `routeEvent`, and `handleEvent`. For more information on events, see the Client-Side JavaScript Guide.

## routeEvent

Passes a captured event along the normal event hierarchy.

Method of | `document`
Implemented in | JavaScript 1.2

#### Syntax

    routeEvent(event)

#### Parameters

    event

Name of the event to be routed.

#### Description

If a sub-object (document or layer) is also capturing the event, the event is sent to that object. Otherwise, it is sent to its original target. `routeEvent` works in tandem with `captureEvents`, `releaseEvents`, and `handleEvent`. For more information on events, see the Client-Side JavaScript Guide.

## tags

Creates a `Style` object that can specify the styles of HTML tags.

Property of | `document`
Implemented in | JavaScript 1.2

#### Syntax

    document.tags.tagName

#### Parameters

    tagName

The case-insensitive name of any HTML tag, such as `H1` or `BLOCKQUOTE`.

#### Description

Use the `tags` property to specify the style of HTML tags. For example, you can specify that the color of any `H1` tag is blue, and that the alignment of any `H1` or `H2` tag is centered. See the `Style` object for a description of the properties you can specify for HTML tags. Because all HTML elements inherit from the `BODY` tag, you can specify a default document style by setting the style properties of `BODY`. If you use the `tags` property within the `STYLE` tag (instead of within the `SCRIPT` tag), you can optionally omit `document` from the `tags` syntax. The `tags` property always applies to the current `document` object.

#### Examples

Example 1. This example sets the color of all `H1` tags to blue:

    <STYLE TYPE="text/javascript">
       tags.H1.color="blue"
    </STYLE>

Notice that you can omit the `document` object within the `STYLE` tag. Within the `SCRIPT` tag, you must specify the `document` object as follows:

    <SCRIPT LANGUAGE="JavaScript1.2">
       document.tags.H1.color="blue"
    </SCRIPT>

Example 2. This example sets a universal left margin for a document:

    document.tags.Body.marginLeft="20pt"

Because all HTML tags inherit from `BODY`, this example sets the left margin for the entire document to 20 points.

#### See also

`document.classes`, `document.contextual`, `document.ids`, `Style`

## title

A string representing the title of a document.

Property of | `document`
Read-only
Implemented in | JavaScript 1.0

#### Security

JavaScript 1.1. This property is tainted by default. For information on data tainting, see the Client-Side JavaScript Guide.

#### Description

The `title` property is a reflection of the value specified between the `TITLE` start and end tags. If a document does not have a title, the `title` property is null.

#### Examples

In the following example, the value of the `title` property is assigned to a variable called `docTitle`:

    var newWindow = window.open("http://home.netscape.com")
    var docTitle = newWindow.document.title

## URL

A string specifying the complete URL of the document.

Property of | `document`
Read-only
Implemented in | JavaScript 1.0

#### Security

JavaScript 1.1. This property is tainted by default. For information on data tainting, see the Client-Side JavaScript Guide.

#### Description

`URL` is a string-valued property containing the full URL of the document. It usually matches what `window.location.href` is set to when you load the document, but redirection may change `location.href`.

#### Examples

The following example displays the URL of the current document:

    document.write("The current URL is " + document.URL)

#### See also

`Location.href`

## vlinkColor

A string specifying the color of visited links.

Property of | `document`
Implemented in | JavaScript 1.0

#### Description

The `vlinkColor` property is expressed as a hexadecimal RGB triplet or as a string literal (see the Client-Side JavaScript Guide). This property is the JavaScript reflection of the `VLINK` attribute of the `BODY` tag. The default value of this property is set by the user with the preferences dialog box. You cannot set this property after the HTML source has been through layout. If you express the color as a hexadecimal RGB triplet, you must use the format `rrggbb`. For example, the hexadecimal RGB values for salmon are `red=FA`, `green=80`, and `blue=72`, so the RGB triplet for salmon is `"FA8072"`.

#### Examples

The following example sets the color of visited links to aqua using a string literal:

    document.vlinkColor="aqua"

The following example sets the color of active links to aqua using a hexadecimal triplet:

    document.vlinkColor="00FFFF"

#### See also

`document.alinkColor`, `document.bgColor`, `document.fgColor`, `document.linkColor`

## width

The width of a document, in pixels.

Property of | `document`
Implemented in | JavaScript 1.2

#### See also

`document.height`

## write

Writes one or more HTML expressions to a document in the specified window.

Method of | `document`
Implemented in | JavaScript 1.0

#### Syntax

    document.write(expr1[, ...,exprN])

#### Parameters

    expr1, ... exprN

Any JavaScript expressions.

#### Description

The `write` method displays any number of expressions in the document window. You can specify any JavaScript expression with the `write` method, including numeric, string, or logical expressions. The `write` method is the same as the `writeln` method, except the `write` method does not append a newline character to the end of the output. Use the `write` method within any `SCRIPT` tag or within an event handler. Event handlers execute after the original document closes, so the `write` method implicitly opens a new document of `mimeType` `text/html` if you do not explicitly issue a `document.open` method in the event handler. You can use the `write` method to generate HTML and JavaScript code. However, the HTML parser reads the generated code as it is being written, so you might have to escape some characters. For example, the following `write` method generates a comment and writes it to `window2`:

    window2=window.open('','window2')
    beginComment="\<!--"
    endComment="--\>"
    window2.document.write(beginComment)
    window2.document.write(" This some text inside a comment. ")
    window2.document.write(endComment)

Printing, saving, and viewing generated HTML. In Navigator 3.0 and later, users can print and save generated HTML using the commands on the File menu. If you choose Page Source from the Navigator View menu or View Frame Source from the right-click menu, the web browser displays the content of the HTML file with the generated HTML. (This is what would be displayed using a `wysiwyg:` URL.) If you instead want to view the HTML source showing the scripts which generate HTML (with the `document.write` and `document.writeln` methods), do not use the Page Source or View Frame Source menu items. In this situation, use the `view-source:` protocol. For example, assume the file `file://c|/test.html` contains this text:

    <HTML>
    <BODY>
    Hello,
    <SCRIPT>document.write(" there.")</SCRIPT>
    </BODY>
    </HTML>

If you load this URL into the web browser, it displays the following:

    Hello, there.

If you choose View Document Source, the browser displays:

    <HTML>
    <BODY>
    Hello,
     there.
    </BODY>
    </HTML>

If you load `view-source:file://c|/test.html`, the browser displays:

    <HTML>
    <BODY>
    Hello,
    <SCRIPT>document.write(" there.")</SCRIPT>
    </BODY>
    </HTML>

For information on specifying the `view-source:` protocol in the `location` object, see the `Location` object.

#### Examples

In the following example, the `write` method takes several arguments, including strings, a numeric, and a variable:

    var mystery = "world"
    // Displays Hello world testing 123
    msgWindow.document.write("Hello ", mystery, " testing ", 123)

In the following example, the `write` method takes two arguments. The first argument is an assignment expression, and the second argument is a string literal.

    //Displays Hello world...
    msgWindow.document.write(mystr = "Hello ", "world...")

In the following example, the `write` method takes a single argument that is a conditional expression. If the value of the variable `age` is less than 18, the method displays "Minor." If the value of `age` is greater than or equal to 18, the method displays "Adult."

    msgWindow.document.write(status = (age >= 18) ? "Adult" : "Minor")

#### See also

`document.close`, `document.open`, `document.writeln`

## writeln

Writes one or more HTML expressions to a document in the specified window and follows them with a newline character.

Method of | `document`
Implemented in | JavaScript 1.0

#### Syntax

    writeln(expr1[, ... exprN])

#### Parameters

    expr1, ... exprN

Any JavaScript expressions.

#### Description

The `writeln` method displays any number of expressions in a document window. You can specify any JavaScript expression, including numeric, string, or logical expressions. The `writeln` method is the same as the `write` method, except the `writeln` method appends a newline character to the end of the output. HTML ignores the newline character, except within certain tags such as the `PRE` tag. Use the `writeln` method within any `SCRIPT` tag or within an event handler. Event handlers execute after the original document closes, so the `writeln` method will implicitly open a new document of `mimeType` `text/html` if you do not explicitly issue a `document.open` method in the event handler. In Navigator 3.0 and later, users can print and save generated HTML using the commands on the File menu.

#### Examples

All the examples used for the `write` method are also valid with the `writeln` method.

#### See also

`document.close`, `document.open`, `document.write`

Table of Contents | Previous | Next | Index

Last Updated: 05/28/99 11:59:17

Copyright (c) 1999 Netscape Communications Corporation