Alphabetical Object Reference (Dynamic HTML: The Definitive Reference, 2nd Edition)

a	`NN 6 IE 4 DOM 1`

The a object reflects the a element, regardless of whether the element is set up to be an anchor, link, or both. Early versions of Navigator and Internet Explorer treat this object only as a member of the links[] and/or anchors[ ] arrays of a document. Starting with IE 4 and Netscape 6, you can access the object through supported element object reference syntax (e.g., the document.all[] collection for IE or document.getElementById( ) for IE 5 and later and Netscape 6).

HTML Equivalent

<a>

Object Model Reference

[window.]document.links[i]
[window.]document.anchors[i]
[window.]document.getElementById("elementID")

Object-Specific Properties

`charset`	`coords`	`dataFld`	`dataFormatAs`	`dataSrc`	`hash`
`host`	`hostname`	`href`	`hreflang`	`Methods`	`mimeType`
`name`	`nameProp`	`pathname`	`port`	`protocol`	`protocolLong`
`rev`	`search`	`shape`	`target`	`text`	`type`
`urn`

Object-Specific Methods

None.

Object-Specific Event Handler Properties

Handler	NN	IE	DOM
`onblur`	n/a	4	n/a
`onclick`	2	3	2
`ondblclick`	4	4	n/a
`onfocus`	n/a	4	n/a
`onhelp`	n/a	4	n/a
`onmousedown`	4	4	2
`onmousemove`	6	4	2
`onmouseout`	3	4	2
`onmouseover`	2	3	2
`onmouseup`	4	4	2

Anchor-only a objects have no event handlers in Navigator through Version 4.

charset NN 6 IE 6 DOM 1
Read/Write
Character encoding of the document's content.

Example

if (document.getElementById("myAnchor").charset == "csISO5427Cyrillic") { // process for Cyrillic charset }

Value

Case-insensitive alias from the character set registry (ftp://ftp.isi.edu/in-notes/iana/assignments/character-sets).

Default

Determined by browser.

coords NN 6 IE 6 DOM 1
Read/Write
Defines the outline of an area to be associated with a particular link or scripted action. This property is a member of the a object, but really belongs to the area object, which inherits the properties of the a object. Coordinate values are entered as a comma-delimited list. If hotspots of two areas should overlap, the area that is defined earlier in the code takes precedence.

Example

document.getElementById("mapArea2").coords = "25, 5, 50, 70";

Value

Each coordinate is a length value, but the number of coordinates and their order depend on the shape specified by the shape attribute, which may optionally be associated with the element. For shape="rect", there are four coordinates (left, top, right, bottom); for shape="circle" there are three coordinates (center-x, center-y, radius); for shape="poly" there are two coordinate values for each point that defines the shape of the polygon.

Default

None.

dataFld NN n/a IE 4 DOM n/a
Read/Write
Used with IE data binding to associate a remote data source column value in lieu of an href attribute for a link. The datasrc attribute must also be set for the element. Setting both the dataFld and dataSrc properties to empty strings breaks the binding between element and data source. Works only with text file data sources in IE 5/Mac.

Example

document.getElementById("hotlink").dataFld = "linkURL";

Value

Case-sensitive identifier of the data source column.

Default

None.

dataFormatAs NN n/a IE 4 DOM n/a
Read/Write
Used with IE data binding, this property advises the browser whether the source material arriving from the data source is to be treated as plain text or as tagged HTML.

Example

document.getElementById("hotlink").dataFormatAs = "HTML";

Value

IE recognizes two possible settings: text | html.

Default

text

dataSrc NN n/a IE 4 DOM n/a
Read/Write
Used with IE data binding to specify the ID of the page's object element that loads the data source object for remote data access. Content from the data source to be inserted into the a element text is specified via the datafld property. Setting both the dataFld and dataSrc properties to empty strings breaks the binding between element and data source. Works only with text file data sources in IE 5/Mac.

Example

document.all.hotlink.dataSrc = "#DBSRC3";

Value

Case-sensitive identifier of the data source.

Default

None.

hash NN 2 IE 3 DOM 1
Read/Write
Provides that portion of the href attribute's URL following the # symbol, referring to an anchor location in a document. Do not include the # symbol when setting the property.

Example

document.getElementById("myLink").hash = "section3"; document.links[2].hash = "section3";

Value

String.

Default

None.

host NN 2 IE 3 DOM 1
Read/Write
This is the combination of the hostname and port (if any) of the server of the destination document for the link. If the port is explicitly part of the URL, the hostname and port are separated by a colon, just as they are in the URL. If the port number is not specified in an HTTP URL for IE, it automatically returns the default, port 80.

Example

document.getElementById("myLink").host = "www.megacorp.com:80"; document.links[2].host = "www.megacorp.com:80";

Value

String of hostname optionally followed by a colon and port number.

Default

Depends on server.

hostname NN 2 IE 3 DOM 1
Read/Write
This is the hostname of the server (i.e., a "two-dot" address consisting of server name and domain) of the destination document for the link. The hostname property does not include the port number.

Example

document.getElementById("myLink").hostname = "www.megacorp.com"; document.links[2].hostname = "www.megacorp.com";

Value

String of hostname (server and domain).

Default

Depends on server.

href NN 2 IE 3 DOM 1
Read/Write
Provides the URL specified by the element's href attribute.

Example

document.getElementById("myLink").href = "http://www.megacorp.com"; document.links[2].href = "http://www.megacorp.com";

Value

String of complete or relative URL.

Default

None.

hreflang NN 6 IE 6 DOM 1
Read/Write
Provides the language code of the content at the destination of a link. Requires that the href attribute or property also be set.

Example

document.getElementById("myLink").hreflang = "DE";

Value

Case-insensitive language code.

Default

None.

Methods NN n/a IE 4 DOM n/a
Read/Write
Provides an advisory attribute about the functionality of the destination of a link. A browser could use this information to display special colors or images for the element content based on what the destination does for the user, but Internet Explorer does not appear to do anything with this information.

Example

document.links[1].Methods = "post";

Value

Any valid HTTP method as a string.

Default

None.

mimeType NN n/a IE 4 DOM n/a
Read-only
Returns a plain-language version of the MIME type of the destination document at the other end of the link specified by the href attribute. You could use this information to set the cursor type during a mouse rollover. Don't confuse this property with the navigator.mimeTypes[] array and individual mimeType objects that Netscape Navigator refers to. This is not available in IE 4/Macintosh.

Example

if (document.getElementById("myLink").mimeType == "GIF Image") { ... }

Value

A plain-language reference to the MIME type as a string.

Default

None.

name NN 2 IE 3 DOM 1
Read/Write
This is the identifier associated with an element that turns it into an anchor. You can also use the name as part of the object reference.

Example

if (document.links[12].name == "section3") { ... }

Value

Case-sensitive identifier that follows the rules of identifier naming: it may contain no whitespace, cannot begin with a numeral, and should avoid punctuation except for the underscore character.

Default

None.

nameProp NN n/a IE 4 DOM n/a
Read-only
Returns just the filename, rather than the full URL, of the href attribute set for the element. Not available in IE 4/Macintosh.

Example

if (document.getElementById("myLink").nameProp == "logo2.gif") { ... }

Value

String.

Default

None.

pathname NN 2 IE 3 DOM 1
Read/Write
Provides the pathname component of the URL assigned to the element's href attribute. This consists of all URL information following the last character of the domain name, including the initial forward slash symbol.

Example

document.getElementById("myLink").pathname = "/images/logoHiRes.gif"; document.links[2].pathname = "/images/logoHiRes.gif";

Value

String.

Default

None.

port NN 2 IE 3 DOM 1
Read/Write
Provides the port component of the URL assigned to the element's href attribute. This consists of all URL information following the colon after the last character of the domain name. The colon is not part of the port property value.

Example

document.getElementById("myLink").port = "80"; document.links[2].port = "80";

Value

String (a numeric value as string).

Default

None.

protocol NN 2 IE 3 DOM 1
Read/Write
Indicates the protocol component of the URL assigned to the element's href attribute. This consists of all URL information up to and including the first colon of a URL. Typical values are: "http:", "file:", "ftp:", and "mailto:".

Example

document.getElementById("secureLink").protocol = "https:";

Value

String.

Default

None.

protocolLong NN n/a IE 4 DOM n/a
Read-only
Provides a verbose description of the protocol implied by the URL of the href attribute or href property. Not supported in IE 4/Macintosh, and appears to be deprecated .

Example

if (document.getElementById("myLink").protocolLong == "HyperText Transfer Protocol") { // statements for treating document as server file }

Value

String.

Default

None

rel NN 6 IE 4 DOM 1
Read/Write
Defines the relationship between the current element and the destination of the link. Also known as a forward link, not to be confused in any way with the destination document whose address is defined by the href attribute. Mainstream browsers do not take advantage of this attribute for the a element, but you can treat the attribute as a kind of parameter to be checked and/or modified under script control. See the discussion of the a element's rel attribute in Chapter 8 for a glimpse of how this property may be used in the future.

Value

Case-insensitive, space-delimited list of HTML 4.0 standard link types (as a single string) applicable to the element. Sanctioned link types are:

alternate

appendix

bookmark

chapter

contents

copyright

glossary

help

index

next

prev

section

start

stylesheet

subsection

Default

None.

rev NN n/a IE 4 DOM 1
Read/Write
Defines the relationship between the current element and the destination of the link. Also known as a reverse link. This property is not exploited yet in mainstream browsers, but you can treat the attribute as a kind of parameter to be checked and/or modified under script control. See the discussion of the a element's rev attribute in Chapter 8 for a glimpse of how this property may be used in the future.

Value

Case-insensitive, space-delimited list of HTML 4.0 standard link types (as a single string) applicable to the element. See the rel property for sanctioned link types.

Default

None.

search NN 2 IE 3 DOM 1
Read/Write
Provides the URL-encoded portion of a URL assigned to the href attribute that begins with the ? symbol. A document that is served up as the result of the search also may have the search portion available as part of the window.location property. You can modify this property with a script. Doing so sends the URL and search criteria to the server. You must know the format of data (usually name/value pairs) expected by the server to perform this properly.

Example

document.getElementById("searchLink").search="?p=Tony+Blair&d=y&g=0&s=a&w=s&m=25"; document.links[1].search="?p=Tony+Blair&d=y&g=0&s=a&w=s&m=25";

Value

String starting with the ? symbol.

Default

None.

shape NN 6 IE 6 DOM 1
Read/Write
Indicates the shape of a server-side image map area, with coordinates that are specified with the COORDS attribute. Intended for use by the area object, which inherits the properties of the a object.

Example

document.getElementById("myLink").shape = "circle";

Value

Case-insensitive shape constant as string: default | rect | rectangle | circle | poly | polygon.

Default

rect

target NN 2 IE 3 DOM 1
Read/Write
Provides the name of the window or frame that is to receive content as the result of navigating to a link. Such names are assigned to frames by the frame element's name attribute; for subwindows, the name is assigned via the second parameter of the window.open( ) method. If you need the services of a target attribute to open a linked page in a blank browser window and you also need the HTML to validate under strict HTML or XHTML DTDs (see Chapter 1), you can omit the target attribute in the code, but you must assign a value to the a element's target property by script after the page loads.

Example
document.getElementById("homeLink").target = "_top";
document.links[3].target = "_top";
Value

String value of the window or frame name, or any of the following constants (as a string): _parent | _self | _top | _blank. The _parent value targets the frameset to which the current document belongs; the _self value targets the current window; the _top value targets the main browser window, thereby eliminating all frames; and the _blank value creates a new window of default size.

Default

None.

text NN 4 IE n/a DOM n/a
Read-only
Returns the text between the a element's start and end tags. This property pre-dates the W3C DOM and should be used only if needed for Navigator 4.

Value

String value.

Default

None.

type NN 6 IE 6 DOM 1
Read/Write
This is the MIME type of the destination document at the other end of the link specified by the href attribute. A browser might use this information to assist in preparing support for a resource requiring a multimedia player or plugin.

Example

if (document.getElementById("myLink").type == "image/jpeg") { ... }

Value

Case-insensitive MIME type. A catalog of registered MIME types is available from ftp://ftp.isi.edu/in-notes/iana/assignments/media-types/.

Default

None.

urn NN n/a IE 4 DOM n/a
Read/Write
Indicates a Uniform Resource Name (URN) version of the destination document specified in the href attribute. This attribute is intended to offer support in the future for the URN format of URI, an evolving recommendation under discussion at the IETF (see RFC 2141). Although supported in IE, this attribute does not take the place of the href attribute.

Example

document.getElementById("link3").urn = "http://www.megacorp.com";

Value

Complete or relative URN as a string.

Default

None.

acronym, cite, code, dfn, em, kbd, samp, strong, var NN 6 IE 4 DOM 1

All these objects reflect the corresponding HTML phrase elements of the same name. Each of these phrase elements provides a context for an inline sequence of content. Some of these elements are rendered in ways to distinguish themselves from running text. See the HTML element descriptions in Chapter 8 for details. From a scripted standpoint, all phrase element objects share the same set of properties, methods, and event handlers.

HTML Equivalent

<acronym>
<cite>
<code>
<dfn>
<em>
<kbd>
<samp>
<strong>
<var>

Object Model Reference

[window.]document.getElementById("elementID")

Object-Specific Properties

None.

Object-Specific Methods

None.

Object-Specific Event Handler Properties

None.

all NN n/a IE 4 DOM n/a

A collection of elements nested within the current element. A reference to document.all, for example, returns a collection (array) of all element objects contained by the document, including elements that may be deeply nested inside the document's first level of elements. The collection is sorted in source code order of the element tags. You can retrieve a reference to an element with its ID by any of the following syntaxes:

document.all.elementID
document.all["elementID"]
document.all("elementID"]
document.all.item("elementID")
document.all.namedItem("elementID")

The W3C DOM equivalent (the document.getElementById( ) method) operates only from the document object, providing global reach to elements throughout the entire document.

Object Model Reference

elementReference.all

Object-Specific Properties

length

Object-Specific Methods

item( )

namedItem( )

tags( )

urns( )

Object-Specific Event Handler Properties

None.

length NN n/a IE 4 DOM n/a
Read-only
Returns the number of elements in the collection.

Example

var howMany = document.all.length;

Value

Integer.

item( ) NN n/a IE 4 DOM n/a
item(index[, subindex])
Returns a single object or collection of objects corresponding to the element matching the index value (or, optionally, the index and subindex values).

Returned Value

One object or collection (array) of objects. If there are no matches to the parameters, the returned value is null.

Parameters

index

When the parameter is a zero-based integer, the returned value is a single element corresponding to the specified item in source code order (nested within the current element); when the parameter is a string, the returned value is a collection of elements whose id or name properties match that string.

subindex

If you specify a string value for the first parameter, you can use the second parameter to specify a zero-based index that retrieves the specified element from the collection whose id or name properties match the first parameter's string value.

namedItem( ) NN n/a IE 6 DOM n/a
namedItem(IDOrName)
Returns a single object or collection of objects corresponding to the element matching the parameter string value.

Returned Value

One object or collection (array) of objects. If there are no matches to the parameters, the returned value is null.

Parameters

IDOrName

The string that contains the same value and case as the desired element's id or name attribute.

tags( ) NN n/a IE 4 DOM n/a
tags(tagName)
Returns a collection of objects (among all objects nested within the current element) whose tags match the tagName parameter.

Returned Value

A collection (array) of objects. If there are no matches to the parameters, the returned value is an array of zero length.

Parameters

tagName

A case-insensitive string that contains the element tag name only (no angle brackets), as in document.all.tags("p").

urns( ) NN n/a IE 5(Win) DOM n/a
urns(URN)
Returns a collection of nested element objects that have behaviors attached to them and whose URNs match the URN parameter.

Returned Value

A collection (array) of objects. If there are no matches to the parameters, the returned value is an array of zero length.

Parameters

URN

A string with a local or external behavior file URN.

anchors NN 2 IE 3 DOM 1

A collection of all a elements with assigned name attributes that make them behave as anchors (instead of links). Collection members are sorted in source code order. Navigator and Internet Explorer let you use array notation to access a single anchor in the collection (e.g., document.anchors[0], document.anchors["section3"]). Internet Explorer 4 also allows the index value to be placed inside parentheses instead of brackets (e.g., document.anchors(0)). If you want to use the anchor's name as an index value (always as a string identifier), be sure to use the value of the name attribute, rather than the id attribute. To use the id attribute in a reference to an anchor, access the object via a document.all.elementID (in IE only) or document.getElementById("elementID") reference.

Object Model Reference

document.anchors

Object-Specific Properties

length

Object-Specific Methods

item( )

namedItem( )

tags( )

urns( )

Object-Specific Event Handler Properties

None.

length NN 2 IE 3 DOM 1
Read-only
Returns the number of elements in the collection.

Example

var howMany = document.anchors.length;

Value

Integer.

item( ) NN 6 IE 4 DOM 1
item(index[, subindex]) item(index)
Returns a single anchor object or collection of anchor objects corresponding to the element matching the index value (or, optionally in IE, the index and subindex values).

Returned Value

One anchor object or collection (array) of anchor objects. If there are no matches to the parameters, the returned value is null.

Parameters

index

When the parameter is a zero-based integer (required in Netscape 6), the returned value is a single element that corresponds to the specified item in source code order (nested within the current element). When the parameter is a string, the returned value is a collection of elements whose id or name properties match that string.

subindex

In IE only, if you specify a string value for the first parameter (IE only), you can use the second parameter to specify a zero-based index that retrieves the specified element from the collection with id or name properties that match the first parameter's string value.

namedItem( ) NN 6 IE 6 DOM 1
namedItem(IDOrName)
Returns a single anchor object or collection of anchor objects corresponding to the element matching the parameter string value.

Returned Value

One anchor object or collection (array) of anchor objects. If there are no matches to the parameters, the returned value is null.

Parameters

IDOrName

The string that contains the same value as the desired element's id or name attribute.

tags( ) NN n/a IE 4 DOM n/a
tags(tagName)
Returns a collection of objects (among all objects nested within the current collection) with tags that match the tagName parameter. Implemented in all IE collections (see the all.tags( ) method), but redundant for collections of the same element type.

urns( ) NN n/a IE 5(Win) DOM n/a
urns(URN)
See the all.urns( ) method.

applet NN 3 IE 4 DOM 1

The applet object reflects the applet element.

HTML Equivalent

<applet>

Object Model Reference

[window.]document.appletName
[window.]document.getElementById("elementID")

Object-Specific Properties

`align`	`alt`	`altHTML`	`archive`	`code`
`codeBase`	`dataFld`	`dataSrc`	`height`	`hspace`
`name`	`object`	`src`	`vspace`	`width`

Object-Specific Methods

None.

Object-Specific Event Handler Properties

None.

align NN 6 IE 4 DOM 1
Read/Write
Defines the alignment of the element within its surrounding container. Only partially implemented in Netscape 6.2. See Section 8.1.5 at the beginning of Chapter 8 for the various meanings that different values bring to this property.

Example
document.getElementById("myApplet").align = "center";
Value

Any of the alignment constants: absbottom | absmiddle | baseline | bottom | left | middle | right | texttop | top.

Default

left

alt NN 6 IE 6 DOM 1
Read/Write
This is the text message to be displayed if the object or applet fails to load. There is little indication that setting this property on an existing applet object has any visual effect.

Example

document.myApplet.alt= "Image Editor Applet";

Value

Any quoted string of characters, but HTML tags are not interpreted.

Default

None.

altHTML NN n/a IE 4 DOM n/a
Read/Write
Provides the HTML content to be displayed if the object or applet fails to load. This can be a message, static image, or any other HTML that best fits the scenario. There is little indication that setting this property on an existing applet object has any visual effect.

Example

document.myApplet.altHTML = "<img src='appletAlt.gif'>";

Value

Any quoted string of characters, including HTML tags.

Default

None.

archive NN 6 IE 6 DOM 6
Read-only
Reflects the archive attribute of the applet element. Only partially implemented in the browsers. See the discussion of the archive attribute in Chapter 8.

Example
if (document.applets["clock"].archive == "myClock.zip") {
    // process for the found class file
}
Value

Case-sensitive URI as a string.

Default

None.

code NN 6 IE 4 DOM 1
Read-only
Provides the name of the Java applet class file set to the code attribute. Not fully implemented in Netscape 7.

Example

if (document.applets["clock"].code == "XMAScounter.class") { // process for the found class file }

Value

Case-sensitive applet class filename as a string.

Default

None.

codeBase NN 6 IE 4 DOM 1
Read-only
Provides the path to the directory holding the class file designated in the code attribute. The codebase attribute does not name the class file, just the path. Not fully implemented in Netscape 7.

Example

if (document.applets["clock"].codeBase == "classes") { // process for the found class file directory }

Value

Case-sensitive pathname, usually relative to the directory storing the current HTML document.

Default

None.

dataFld NN n/a IE 4 DOM n/a
Read/Write
It is unclear how you would use this property with an applet object because the dataFld and dataSrc properties (as set in element attributes) are applied to individual param elements.

Value

Case-sensitive identifier of the data source column.

Default

None.

dataSrc NN n/a IE 4 DOM n/a
Read/Write
It's unclear how you would use this property with an applet object because the dataFld and dataSrc properties (as set in element attributes) are applied to individual param elements.

Value

Case-sensitive identifier of the data source.

Default

None.

height, width NN 6 IE 4 DOM 1
Read/Write
Indicate the height and width in pixels of the element as set by the tag attributes. Changing the values does not necessarily change the actual rectangle of the applet after it has loaded. Not fully implemented in Netscape 7.

Example

var appletHeight = document.myApplet.height;

Value

Integer.

Default

None.

hspace, vspace NN 6 IE 4 DOM 1
Read/Write
Indicate the pixel measure of horizontal and vertical margins surrounding an applet. The hspace property affects the left and right edges of the element equally; the vspace affects the top and bottom edges of the element equally. These margins are not the same as margins set by style sheets, but they have the same visual effect.

Example

document.getElementById("myApplet").hspace = 5; document.getElementById("myApplet").vspace = 8;

Value

Integer of pixel count.

Default

0

name NN 6 IE 4 DOM 1
Read-only
This is the identifier associated with the applet. Use the name when referring to the object in the form document.appletName.

Value

Case-sensitive identifier that follows the rules of identifier naming: it may contain no whitespace, cannot begin with a numeral, and should avoid punctuation except for the underscore character.

Default

None.

object NN n/a IE 4 DOM n/a
Read-only
Returns a reference to the applet object so that a script can access a property or method of the applet whose name is identical to a property or method of the applet element object.

Value

Applet object (not the applet element object) reference.

Default

None.

src NN n/a IE 4 DOM n/a
Read-only
Internet Explorer defines this attribute as the URL for an associated file. The src property is not a substitute for the code and/or codebase properties.

Value

Complete or relative URL as a string.

Default

None.

vspace
See hspace.

width
See height.

applets NN 2 IE 3 DOM 1

A collection of all the Java applets in the current element, sorted in source code order. Navigator and Internet Explorer let you use array notation to access a single applet in the collection (e.g., document.applets[0], document.applets["clockApplet"]). Internet Explorer allows the index value to be placed inside parentheses instead of brackets (e.g., document.applets(0)). If you wish to use the applet's name as an index value (always as a string identifier), use the value of the name attribute rather than the id attribute. To use the id attribute in a reference to an applet, access the object via a document.all.elementID (in IE only) or document.getElementById("elementID") reference.

Object Model Reference

document.applets[i]

Object-Specific Properties

length

Object-Specific Methods

item( )

namedItem( )

length NN 2 IE 3 DOM 1
Read-only
Returns the number of elements in the collection.

Example

var howMany = document.applets.length;

Value

Integer.

item( ) NN 6 IE 4 DOM 1
item(index[, subindex]) item(index)
Returns a single applet object or collection of applet objects corresponding to the element matching the index value (or, optionally in IE, the index and subindex values).

Returned Value

One applet object or collection (array) of applet objects. If there are no matches to the parameters, the returned value is null.

Parameters

index

When the parameter is a zero-based integer, the returned value is a single element corresponding to the specified item in source code order (nested within the current element); when the parameter is a string, the returned value is a collection of elements whose id or name properties match that string.

subindex

In IE only, if you specify a string value for the first parameter, you can use the second parameter to specify a zero-based index that retrieves the specified element from the collection whose id or name properties match the first parameter's string value.

namedItem( ) NN 6 IE 6 DOM 1
namedItem(IDOrName)
Returns a single applet object or collection of applet objects corresponding to the element matching the parameter string value.

Returned Value

One applet object or collection (array) of applet objects. If there are no matches to the parameters, the returned value is null.

Parameters

IDOrName

The string that contains the same value as the desired element's id or name attribute.

area NN 3 IE 4 DOM 1

The area object reflects the area element, which defines the shape, coordinates, and destination of a clickable region of a client-side image map. Navigator and Internet Explorer treat an area object as a member of the links collection, since an area object behaves much like a link, but for a segment of an image.

HTML Equivalent

<area>

Object Model Reference

[window.]document.links[i]
[window.]document.getElementById("elementID")

Object-Specific Properties

`alt`	`coords`	`hash`	`host`	`hostname`
`href`	`noHref`	`pathname`	`port`	`protocol`
`search`	`shape`	`target`

Object-Specific Methods

None.

Object-Specific Event Handler Properties

None.

alt NN 6 IE 4 DOM 1
Read/Write
Future nongraphical browsers may use the alt property setting to display a brief description of the meaning of the (invisible) image's hotspots.

Example

document.getElementById("elementID").alt = "To Next Page";

Value

Any quoted string of characters.

Default

None.

coords NN 6 IE 4 DOM 1
Read/Write
Defines the outline of the area to be associated with a particular link or scripted action. Coordinate values are entered as a comma-delimited list. If hotspots of two areas should overlap, the area that is defined earlier in the code takes precedence.

Example

document.getElementById("mapArea2").coords = "25, 5, 50, 70";

Value

Each coordinate is a pixel length value, but the number of coordinates and their order depend on the shape specified by the shape attribute, which may optionally be associated with the element. For shape="rect", there are four coordinates (left, top, right, bottom); for shape="circle", there are three coordinates (center-x, center-y, radius); for shape="poly", there are two coordinate values for each point that defines the shape of the polygon.

Default

None.

hash NN 2 IE 3 DOM 1
Read/Write
This is that portion of the href attribute's URL following the # symbol, referring to an anchor location in a document. Do not include the # symbol when setting the property.

Example

document.getElementById("mapArea2").hash = "section3";

Value

String.

Default

None.

host NN 2 IE 3 DOM 1
Read/Write
Provides the combination of the hostname and port (if any) of the server of the destination document for the area link. If the port is explicitly part of the URL, the hostname and port are separated by a colon, just as they are in the URL. If the port number is not specified in an HTTP URL for IE, it automatically returns the default, port 80.

Example

document.getElementById("mapArea2").host = "www.megacorp.com:80";

Value

String of hostname optionally followed by a colon and port number.

Default

Depends on server.

hostname NN 2 IE 3 DOM 1
Read/Write
Provides the hostname of the server (i.e., a two-dot address consisting of server name and domain) of the destination document for the area link. The hostname property does not include the port number.

Example

document.links[2].hostname = "www.megacorp.com";

Value

String of hostname (server and domain).

Default

Depends on server.

href NN 2 IE 3 DOM 1
Read/Write
This is the URL specified by the element's href attribute.

Example

document.links[2].href = "http://www.megacorp.com";

Value

String of complete or relative URL.

Default

None.

noHref NN 6 IE 4 DOM 1
Read/Write
Specifies whether the area defined by the coordinates has a link associated with it. When you set this property to true, scriptable browsers no longer treat the element as a link.

Example

document.links[4].noHref = "true";

Value

Boolean value: true | false.

Default

false

pathname NN 2 IE 3 DOM 1
Read/Write
Provides the pathname component of the URL assigned to the element's href attribute. This consists of all URL information following the last character of the domain name, including the initial forward slash symbol.

Example

document.getElementById("myLink").pathname = "/images/logoHiRes.gif";

Value

String.

Default

None.

port NN 2 IE 3 DOM 1
Read/Write
Provides the port component of the URL assigned to the element's href attribute. This consists of all URL information following the colon after the last character of the domain name. The colon is not part of the port property value.

Example

document.getElementById("myLink").port = "80";

Value

String (a numeric value as string).

Default

None.

protocol NN 2 IE 3 DOM 1
Read/Write
Indicates the protocol component of the URL assigned to the element's href attribute. This consists of all URL information up to and including the first colon of a URL. Typical values are "http:", "file:", "ftp:", and "mailto:".

Example

document.getElementById("secureLink").protocol = "https:";

Value

String.

Default

None.

search NN 2 IE 3 DOM 1
Read/Write
This is the URL-encoded portion of a URL assigned to the href attribute that begins with the ? symbol. A document that is served up as the result of the search also may have the search portion available as part of the window.location property. You can modify this property with a script. Doing so sends the URL and search criteria to the server. You must know the format of data (usually name/value pairs) expected by the server to perform this properly.

Example

document.getElementById("searchLink").search="?p=Tony+Blair&d=y&g=0&s=a&w=s&m=25";

Value

String starting with the ? symbol.

Default

None.

shape NN 6 IE 4 DOM 1
Read/Write
Indicates the shape of a server-side image map area with coordinates that are specified with the coords attribute.

Example

document.getElementById("area51").shape = "circle";

Value

Case-insensitive shape constant as string: default | rect | rectangle | circle | poly | polygon.

Default

RECT (IE); empty string but rect implied (Netscape 6).

target NN 2 IE 3 DOM 1
Read/Write
This is the name of the window or frame that is to receive content as the result of navigating to an area link. Such names are assigned to frames by the frame element's name attribute; for subwindows, the name is assigned via the second parameter of the window.open( ) method. If you need the services of a target attribute to open a linked page in a blank browser window and you also need the HTML to validate under strict HTML or XHTML DTDs, you can omit the target attribute in the code, but assign a value to the area element's target property by script after the page loads.

Example

document.getElementById("homeArea").target = "_blank";

Value

String value of the window or frame name, or any of the following constants (as a string): _parent | _self | _top | _blank. The _parent value targets the frameset to which the current document belongs; the _self value targets the current window; the _top value targets the main browser window, thereby eliminating all frames; and the _blank value creates a new window of default size.

Default

None.

areas NN 6 IE 4 DOM 1

A collection of all area elements associated with a map element. Notice that individual items of an areas collection are also members of the document-wide links collection (document.links[] array). But the members of an areas collection are local to a single map element.

Object Model Reference

document.getElementById("mapElementID").areas

Object-Specific Properties

length

Object-Specific Methods

item( )

namedItem( )

tags( )

urns( )

length NN 6 IE 4 DOM 1
Read-only
Returns the number of elements in the collection.

Example

var howMany = document.areas.length;

Value

Integer.

item( ) NN 6 IE 4 DOM 1
item(index[, subindex]) item(index)
Returns a single area object or collection of area objects corresponding to the element matching the index value (or, optionally in IE, the index and subindex values).

Returned Value

One area object or collection (array) of area objects. If there are no matches to the parameters, the returned value is null.

Parameters

index

When the parameter is a zero-based integer, the returned value is a single element corresponding to the specified item in source code order (nested within the current element); when the parameter is a string, the returned value is a collection of elements whose id or name properties match that string.

subindex

In IE only, if you specify a string value for the first parameter, you can use the second parameter to specify a zero-based index that retrieves the specified element from the collection whose id or name properties match the first parameter's string value.

namedItem( ) NN 6 IE 6 DOM 1
namedItem(IDOrName)
Returns a single area object or collection of area objects corresponding to the element matching the parameter string value.

Returned Value

One area object or collection (array) of area objects. If there are no matches to the parameters, the returned value is null.

Parameters

IDOrName

The string that contains the same value as the desired element's id or name attribute.

tags( ) NN n/a IE 4 DOM n/a
tags(tagName)
Returns a collection of objects (among all objects nested within the current collection) with tags that match the tagName parameter. Implemented in all IE collections (see the all.tags( ) method), but redundant for collections of the same element type.

urns( ) NN n/a IE 5(Win) DOM n/a
urns(URN)
See the all.urns( ) method.

Attr, attribute NN 6 IE 5 DOM 1

An abstract representation of an element's attribute name/value pair is an object known in the W3C DOM vernacular as the Attr object; in IE terminology, it is called an attribute object. They are different names for the same object. An attribute object is created in both environments via the document.createAttribute( ) method; the reference to the attribute object then becomes the parameter to an element's setAttributeNode( ) method to insert that attribute object into the element. For example:

var newAttr = document.createAttribute("author");
newAttr.value = "William Shakespeare";
document.getElementById("hamlet").setAttributeNode(newAttr);

Some W3C DOM element methods (most notably, the getAttributeNode( ) method) return attribute objects, which have properties that may be accessed like any scriptable object.

In the W3C DOM abstract model, the Attr object inherits all properties and methods of the Node object. Some Node object properties, however, are not inherited by the attribute object in IE/Windows until Version 6, even though they are implemented for element and text nodes in Version 5.

HTML Equivalent

Any name/value pair inside a start tag.

Object Model Reference

[window.]document.getElementById("elementID").attributes[i]
[window.]document.getElementById("elementID").attributes.item(i)
[window.]document.getElementById("elementID").attributes.getNamedItem[attrName]

Object-Specific Properties

expando

name

ownerElement

specified

value

Object-Specific Methods

None.

Object-Specific Event Handler Properties

None.

expando NN n/a IE 6 DOM n/a
Read-only
Returns Boolean true if the attribute, once it is inserted into an element, is not one of the native attributes for the element. This property is false for an attribute created by document.createAttribute( ) until the attribute is added to the element (via the setAttributeNode( ) method), at which time the property's value is reevaluated within the context of the element's native attributes.

Example

var isCustomAttr = document.getElementById("book3928").getAttributeNode("author").expando;

Value

Boolean value: true | false.

Default

false

name NN 6 IE 5 DOM 1
Read-only
This is the name portion of the name/value pair of the attribute. It is identical to the nodeName property of the Attr node. You may not modify the name of an attribute by script because other dependencies may lead to document tree confusion. Instead, replace the old attribute with a newly created one, the name of which is a required parameter of the document.createAttribute( ) method.

Example

if (myAttr.name == "author") { // process author attribute }

Value

String value.

Default

Empty string, although creating a new attribute requires a name.

ownerElement NN 6 IE n/a DOM 2
Read-only
Refers to the element that contains the current attribute object. Until a newly created attribute is inserted into an element, this property is null.

Example

if (myAttr.ownerElement.tagName == "fred") { // process attribute of <fred> element }

Value

Element node reference.

Default

null

specified NN 6 IE 5 DOM 1
Read-only
Returns Boolean true if the value of the attribute is explicitly assigned in the source code or adjusted by script. If the browser reflects an attribute that is not explicitly set (IE does this), the specified property for that value is false, even though the attribute may have a default value determined by the document's DTD. The W3C DOM Level 2 indicates that the specified property of a freshly created Attr object should be true, but both IE 6 and Netscape 6.2 and later leave it false until the attribute is inserted into an element.

Example

if (myAttr.specified) { // process attribute whose value is something other than DTD default }

Value

Boolean value: true | false.

Default

false

value NN 6 IE 6 DOM 1
Read/Write
Provides the value portion of the name/value pair of the attribute. Identical to the nodeValue property of the Attr node, as well as data accessed more directly via an element's getAttribute( ) and setAttribute( ) methods. If you create a new attribute object, you can assign its value via the value property prior to inserting the attribute into the element. Attribute node values are always strings, including in IE, which otherwise allows Number or Boolean data types for the corresponding properties.

Example

document.getElementById("hamlet").getAttributeNode("author").value = "Shakespeare";

Value

String value.

Default

Empty string, except in IE/Windows, which returns the string undefined (that is, not a value whose type evaluates to the undefined value).

attributes, NamedNodeMap NN 6 IE 5 DOM 1

The object returned by the attributes property of every W3C DOM element object is a collection (array) of references to Attr (a.k.a. attribute) objects. An attribute type of node always has a name associated with it, which opens the way for methods of the collection of such nodes to access them directly by name, rather than iterating through the array in search of a matching node name. In the W3C DOM structure, the abstract representation of this array of named nodes is called the NamedNodeMap object, which shares some properties and methods of the IE attributes object. Since both objects refer to the same parts of a document tree, they are treated here together. A couple of other W3C DOM collections are also of the NamedNodeMap variety, but your primary contact with the NamedNodeMap in HTML documents is as a collection of Attr objects. Collection members are sorted in source code order.

There are more direct ways to access an attribute of an element (such as the getAttribute( ) or getAttributeNode( ) methods of all elements). The property and methods shown here, however, assume that your script has been handed a collection of attributes independent of their host element, and your processing starts from that point.

Object Model Reference

elementReference.attributes

Object-Specific Properties

length

Object-Specific Methods

`getNamedItem( )`	`getNamedItemNS( )`	`item( )`	`removeNamedItem( )`
`removeNamedItemNS( )`	`setNamedItem( )`	`setNamedItemNS( )`

Object-Specific Event Handler Properties

None.

length NN 6 IE 5 DOM 1
Read-only
Returns the number of elements in the collection.

Example

var howMany = document.getElementById("myTable").attributes.length;

Value

Integer.

getNamedItem( ) NN 6 IE 6 DOM 1
getNamedItem("attributeName")
Returns a single Attr object corresponding to the attribute whose node name matches the parameter value.

Returned Value

Reference to one Attr object. If there is no match to the parameter value, the returned value is null.

Parameters

attributeName

String corresponding to the name portion of an attribute's name/value pair.

getNamedItemNS( ) NN 6 IE n/a DOM 2
getNamedItemNS("namespaceURI", "localName")
Returns a single Attr object with a local name and namespace URI that match the parameter values.

Returned Value

Reference to one Attr object. If there is no match to the parameter values, the returned value is null.

Parameters

namespaceURI

URI string matching a URI assigned to a label earlier in the document.

localName

The local name portion of the attribute.

item( ) NN 6 IE 5 DOM 1
item(index)
Returns a single Attr object corresponding to the element matching the index value.

Returned Value

Reference to one Attr object. If there is no match to the index value, the returned value is null. Unlike some other collections in IE, a string index value is not allowed for the attributes object.

Parameters

index

A zero-based integer corresponding to the specified item in source code order.

removeNamedItem( ) NN 6 IE 6 DOM 1
removeNamedItem("attributeName")
Removes from the collection a single Attr object corresponding to the attribute whose node name matches the parameter value.

Returned Value

Reference to the removed Attr object. If there is no match to the parameter value, the returned value is null.

Parameters

attributeName

String corresponding to the name portion of an attribute's name/value pair.

removeNamedItemNS( ) NN 6 IE n/a DOM 2
removeNamedItemNS("namespaceURI", "localName")
Removes from the collection a single Attr object whose local name and namespace URI match the parameter values.

Returned Value

Reference to the removed Attr object. If there is no match to the parameter values, the method generates an error.

Parameters

namespaceURI

URI string matching a URI assigned to a label earlier in the document.

localName

The local name portion of the attribute.

setNamedItem( ) NN 6 IE 6 DOM 1
setNamedItem(attrObjectReference)
Inserts a single Attr object into the current collection of attributes. If the destination of the attribute is an existing element, you may also use the setAttributeNode( ) method on the element to insert the Attr object. When the setNamedItem( ) method is invoked, the browser first looks for a match between the new attribute's name and existing attribute names within the collection. If there is a match, the new attribute replaces the original one; otherwise, the new attribute is added to the collection.

Returned Value

Reference to an Attr object either created anew or referenced from elsewhere in the document tree.

Parameters

attrObjectReference

A reference to an Attr node object created through document.createAttribute( ) or an Attr node from another element in the document tree.

setNamedItemNS( ) NN 6 IE n/a DOM 2
setNamedItemNS(attrObjectReference)
Inserts a single Attr object into the current collection of attributes. If the destination of the attribute is an existing element, you may also use the setAttributeNodeNS( ) method on the element to insert the Attr object. When the setNamedItemNS( ) method is invoked, the browser first looks for a match between the new attribute's pairing of local name and namespace URI and existing attribute local names and namespace URIs within the collection. If there is a match, the new attribute replaces the original one; otherwise, the new attribute is added to the collection.

Returned Value

Reference to an Attr object either created anew or referenced from elsewhere in the document tree.

Parameters

attrObjectReference

A reference to an Attr node object created through document.createAttributeNS( ) or an Attr node from another element in the document tree.

b, big, i, s, small, strike, tt, u NN 6 IE 4 DOM 1

All these objects reflect the HTML font style elements of the same name. Each of these elements specifies a rendering style for an inline sequence of content. All the elements are deprecated in HTML 4 in favor of style sheet attributes. See the HTML element descriptions in Chapter 8 for details. From a scripted standpoint, all font style element objects share the same set of properties, methods, event handlers, and collections.

HTML Equivalent

<b>
<big>
<i>
<s>
<small>
<strike>
<tt>
<u>

Object Model Reference

[window.]document.getElementById("elementID")

Object-Specific Properties

None.

Object-Specific Methods

None.

Object-Specific Event Handler Properties

None.

base NN 6 IE 4 DOM 1

A base object instructs the browser about the URL path to the current document. This path is then used as the basis for all relative URLs that are used to specify various src and href attributes throughout the document.

HTML Equivalent

<base>

Object Model Reference

[window.]document.getElementById("elementID")

Object-Specific Properties

href

target

Object-Specific Methods

None.

Object-Specific Event Handler Properties

None.

href NN 6 IE 4 DOM 1
Read/Write
Provides the URL of a document whose server path is to be used as the base URL for all relative references in the document. This is typically the URL of the current document, but it can be set to another path if it makes sense to your document organization and directory structure.

Example

document.getElementById("myBase").href = "http://www.megacorp.com";

Value

String of complete or relative URL.

Default

Current document pathname.

target NN 6 IE 4 DOM 1
Read/Write
Provides the name of the window or frame that is to receive content as the result of navigating to a link or any other action on the page that loads a new document. Such names are assigned to frames by the frame element's name attribute; for subwindows, the name is assigned via the second parameter of the window.open( ) method. If you need the services of a target attribute to open a linked page in a blank browser window and you also need the HTML to validate under strict HTML or XHTML DTDs, you can omit the target attribute in the code, but assign a value to the base element's target property by script after the page loads.

Example

document.getElementById("myBase").target = "_blank";

Value

String value of the window or frame name, or any of the following constants (as a string): _parent | _self | _top | _blank. The _parent value targets the frameset to which the current document belongs; the _self value targets the current window; the _top value targets the main browser window, thereby eliminating all frames; and the _blank value creates a new window of default size.

Default

_self

basefont NN 6 IE 4 DOM 1

A basefont element advises the browser of some font information to be used as the basis for text rendering of the current page below the basefont element. The basefont element overrides the default font settings in the browser's user preferences settings.

If you intend to alter this element by script, do so only via the properties shown here or W3C DOM-compatible document tree manipulations. Other approaches either risk the display of the document or are not permitted by the browser.

HTML Equivalent

<basefont>

Object Model Reference

[window.]document.getElementById("elementID")

Object-Specific Properties

color

face

size

Object-Specific Methods

None.

Object-Specific Event Handler Properties

None.

color NN 6 IE 4 DOM 1
Read/Write
Sets the font color of all text below the basefont element.

Example

document.getElementsByTagName("basefont")[0].color = "#c0c0c0";

Value

Case-insensitive hexadecimal triplet or plain-language color name as a string. See Appendix A for acceptable plain-language color names.

Default

Browser default.

face NN 6 IE 4 DOM 1
Read/Write
Indicates a hierarchy of font faces to use for the default font of a section headed by a basefont element. The browser looks for the first font face in the comma-delimited list of font face names until it either finds a match in the client system or runs out of choices, at which point the browser default font face is used. Font face names must match the system font face names exactly.

Example

document.getElementById("myBaseFont").face = "Bookman, Times Roman, serif";

Value

One or more font face names in a comma-delimited list within a string. You may use real font names or the recognized generic faces: serif | sans-serif | cursive | fantasy | monospace.

Default

Browser default.

size NN 6 IE 4 DOM 1
Read/Write
Provides the size of the font in the 1-7 browser relative scale.

Example

document.getElementById("myBaseFont").size = "+1";

Value

Either an integer (as a quoted string) or a quoted relative value consisting of a + or - symbol and an integer value.

Default

3

bgsound NN n/a IE 4 DOM n/a

A bgsound element defines a sound file that is to play in the background while the user visits the page. Set properties to control the volume and how many times the sound track plays even after the sound file has loaded. A few properties, such as innerHTML and innerText, are exposed in the Windows version, but they don't apply to an element that does not have an end tag.

HTML Equivalent

<bgsound>

Object Model Reference

[window.]document.getElementById("elementID")

Object-Specific Properties

balance

loop

src

volume

Object-Specific Methods

None.

Object-Specific Event Handler Properties

None.

balance NN n/a IE 4 DOM n/a
Read-only
Specifies how the audio is divided between the left and right speakers. Once this attribute value is set in the element, its value cannot be changed by script control.

Example

var currBal = document.getElementsByTagName("bgsound")[0].balance;

Value

A signed integer between -10,000 and +10,000. A value of 0 is equally balanced on both sides. A negative value means the left side is dominant; a positive value means the right side is dominant.

Default

0

loop NN n/a IE 4 DOM n/a
Read/Write
Specifies the number of times the sound plays. Assigning a value of -1 means the sound plays continuously until the page is unloaded.

Example

document.getElementById("mySound").loop = 3;

Value

Integer.

Default

1

src NN n/a IE 4 DOM n/a
Read/Write
Provides the URL of the sound file to be played. Change tunes by assigning a new URL to the property. The new tune plays according to the loop property setting.

Example

document.getElementById("tunes").src = "sounds/blues.aif";

Value

Complete or relative URL as a string.

Default

None.

volume NN n/a IE 4 DOM n/a
Read/Write
Specifies how loud the background sound plays relative to the maximum sound output level as adjusted by user preferences in the client computer. Maximum volume—a setting of zero—is only as loud as the user has set the Sound control panel. Attribute adjustments are negative values as low as -10,000 (although most users lose the sound at values much higher than that value).

Example

var currVolume = document.getElementById("themeSong").volume;

Value

Integer.

Default

Varies with operating system and sound settings.

blockquote NN 6 IE 4 DOM 1

The blockquote object reflects the blockquote element, which is intended to set off a long, block-level quote inside a document.

HTML Equivalent

<blockquote>

Object Model Reference

[window.]document.getElementById("elementID")

Object-Specific Properties

cite

Object-Specific Methods

None.

Object-Specific Event Handler Properties

None.

cite NN 6 IE 5(Mac) DOM 1
Read/Write
Provides a URL pointing to an online source document from which the quotation is taken. This is not in any way a mechanism for copying or extracting content from another document. IE 6 for Windows incorrectly calls this property clear. No mainstream browser does anything special with this information.

Value

Any valid URL to a document on the World Wide Web, including absolute or relative URLs.

Default

None.

body NN 6 IE 4 DOM 1

The body object reflects the body element, which is distinct from the document object. The body object refers to just the element and its nested content. There can be only one body element in an HTML page, so both the IE and W3C DOMs provide a shortcut reference to the object, document.body. Event handlers listed here appear as attributes in the <body> tag, but in truth are document-level events (best referenced in property form as document.eventName). While IE for the Mac doesn't share the sets of client and scroll properties with all element objects, those properties are defined for the body object.

In its effort to institute the standards-compatible mode in IE 6 for Windows (see the DOCTYPE element in Chapter 8), Microsoft has rendered useless the old trick of using the body element's clientHeight and clientWidth properties to obtain the equivalent of Netscape's window.innerHeight and window.innerWidth properties. In standards-compatibility mode (where document.compatMode == "CSS1Compat"), you must use the html element's clientHeight and clientWidth properties to find these values. Use these effective reference shortcuts:

document.body.parentNode.clientHeight
document.body.parentNode.clientWidth

HTML Equivalent

<body>

Object Model Reference

[window.]document.body

Object-Specific Properties

`alink`	`background`	`bgColor`	`bgProperties`	`bottomMargin`
`leftMargin`	`link`	`noWrap`	`rightMargin`	`scroll`
`text`	`topMargin`	`vLink`

Object-Specific Methods

createTextRange( )

Object-Specific Event Handler Properties

Handler	IE Windows	IE Mac	NN	W3C DOM
`onafterprint`	5	n/a	n/a	n/a
`onbeforeprint`	5	n/a	n/a	n/a
`onbeforeunload`	4	n/a	n/a	n/a
`onload`	3	3.01	2	2
`onselect`	n/a	n/a	6	n/a
`onunload`	3	3.01	2	2

aLink NN 6 IE 4 DOM 1
Read/Write
Indicates a color of a hypertext link as it is being clicked. The color is applied to the link text or border around an image or object embedded within an a element. See also link and vLink properties for unvisited and visited link colors. The deprecated but backward-compatible version of this property is the alinkColor property of the document object.

Example

document.body.aLink = "green";

Value

A hexadecimal triplet or plain-language color name. See Appendix A for acceptable plain-language color names.

Default

#0000FF

background NN 6 IE 4 DOM 1
Read/Write
Provides the URL of the background image for the entire document. If you set a bgColor to the element as well, the color appears if the image fails to load; otherwise, the image overlays the color.

Example

document.body.background = "images/watermark.jpg";

Value

Complete or relative URL to the background image file.

Default

None.

bgColor NN 6 IE 4 DOM 1
Read/Write
Provides the background color of the element. Even if the bgcolor attribute or bgColor property is set with a plain-language color name, the returned value is always a hexadecimal triplet.

Example

document.body.bgColor = "yellow";

Value

A hexadecimal triplet or plain-language color name. See Appendix A for acceptable plain-language color names.

Default

Varies with browser and operating system.

bgProperties NN n/a IE 4 DOM n/a
Read/Write
Specifies whether the background image remains in a fixed position or scrolls as a user scrolls the page. When the background image is set to remain in a fixed position, scrolled content flows past the background image very much like film credits roll past a background image on the screen.

Example

document.body.bgProperties = "fixed";

Value

An empty string (indicating the normal scrolling behavior) or the case-insensitive constant string fixed.

Default

Empty string.

bottomMargin NN n/a IE 4 DOM n/a
Read/Write
Indicates the amount of blank space between the very end of content and the bottom of a scrollable page. The setting has no visual effect if the length of the content or size of the window does not cause the window to scroll. The default value is for the end of content to be flush with the end of the document, but in the Macintosh version of Internet Explorer, there is about a 10-pixel margin visible even when the property is set to zero. Larger sizes are reflected properly. This property offers somewhat of a shortcut or alternative to setting the marginBottom style sheet property for the body element object.

Example

document.body.bottomMargin = 20;

Value

An integer value (zero or greater) of the number of pixels of clear space at the bottom of the document.

Default

0

leftMargin NN n/a IE 4 DOM n/a
Read/Write
Provides the width in pixels of the left margin of the body element in the browser window or frame. By default, the browser inserts a small margin to keep content from abutting the left edge of the window. Setting the property to an empty string is the same as setting it to zero.

Example

document.body.leftMargin = 16;

Value

Integer of pixel count.

Default

10 (Windows); 8 (Macintosh).

link NN 6 IE 4 DOM 1
Read/Write
Indicates the color of a hypertext link that has not been visited (that is, the URL of the link is not in the browser's cache). This is one of three states for a link: unvisited, active, and visited. The color is applied to the link text or border around an image or object embedded within an a element. This property has the same effect as setting the document object's linkColor property.

Example

document.body.link = "#00FF00";

Value

A hexadecimal triplet or plain-language color name. See Appendix A for acceptable plain-language color names.

Default

#0000FF

noWrap NN n/a IE 4 DOM 1
Read/Write
Specifies whether the browser should render the body content as wide as necessary to display a line of nonbreaking text on one line. Abuse of this attribute can force the user into a great deal of inconvenient horizontal scrolling of the page to view all of the content.

Example

document.body.noWrap = "true";

Value

Boolean value: true | false.

Default

false

rightMargin NN n/a IE 4 DOM n/a
Read/Write
Provides the width in pixels of the right margin of the body element in the browser window or frame. By default, the browser inserts a small margin to keep content from abutting the right edge of the window (except on the Macintosh). Setting the property to an empty string is the same as setting it to zero.

Example

document.body.leftMargin = 16;

Value

Integer of pixel count.

Default

10 (Windows); 0 (Macintosh).

scroll NN n/a IE 4 DOM n/a
Read/Write
Specifies whether the window (or frame) displays scrollbars when the content exceeds the window size. If your document specifies a standards-compatible DOCTYPE definition (see Chapter 8), the scroll property does not respond to changes for the body element. Nor does the html element object gain this property, as Microsoft's developer documentation purports.

Example
document.body.scroll = "no";
Value

Not exactly a Boolean value. Requires one of the following string values: yes | no | auto.

Default

yes

text NN 6 IE 4 DOM 1
Read/Write
Indicates the color of text for the entire document body. Equivalent to the foreground color.

Example

document.body.text = "darkred";

Value

A hexadecimal triplet or plain-language color name. See Appendix A for acceptable plain-language color names.

Default

Browser default (user customizable).

topMargin NN n/a IE 4 DOM n/a
Read/Write
Provides the width in pixels of the top margin of the body element in the browser window or frame. By default, the browser inserts a small margin to keep content from abutting the top edge of the window. Setting the property to an empty string is the same as setting it to zero.

Example

document.body.topMargin = 16;

Value

Integer of pixel count.

Default

15 (Windows); 8 (Macintosh).

vLink NN 6 IE 4 DOM 1
Read/Write
Indicates the color of a hypertext link that has been visited recently. The color is applied to the link text or border around an image or object embedded within an a element. See also link and aLink properties for unvisited and clicked link colors. The deprecated but backward-compatible version of this property is the vlinkColor property of the document object.

Example

document.body.vLink = "gold";

Value

A hexadecimal triplet or plain-language color name. See Appendix A for acceptable plain-language color names.

Default

#551a8b (Navigator 4); #800080 (Internet Explorer 4 Windows); #006010 (Internet Explorer 4 Macintosh).

createTextRange( ) NN n/a IE 4(Win) DOM n/a
Creates a TextRange object from the rendered text content of the current element. See the TextRange object for details.

Returned Value

TextRange object.

Parameters

None.

br	`NN 6` IE 4 DOM1

The br object reflects the br element.

HTML Equivalent

<br>

Object Model Reference

[window.]document.getElementById("elementID")

Object-Specific Properties

clear

Object-Specific Methods

None.

Element-Specific Event Handler Attributes

None.

clear NN 6 IE 4 DOM 1
Read/Write
Tells the browser how to treat the next line of text following a br element if the current text is wrapping around a floating image or other object. The value you use depends on the side of the page to which one or more inline images are pegged and how you want the next line of text to be placed in relation to those images.

Example

document.getElementById("specialBreak").clear = "all";

Value

Case-insensitive string of any of the following constants: all | left | none | right.

Default

none

button NN 6 IE 4 DOM 1

The button object reflects the button element. While IE for the Mac doesn't share the sets of client- and scroll- properties with all element objects, those properties are defined for the button object. See the discussion of the button element in Chapter 8 to see how it differs from the input element of type button.

HTML Equivalent

<button>

Object Model Reference

[window.]document.getElementById("elementID")

Object-Specific Properties

`dataFld`	`dataFormatAs`	`dataSrc`	`form`	`name`
`status`	`type`	`value`

Object-Specific Methods

createTextRange( )

Object-Specific Event Handler Properties

None.

dataFld NN n/a IE 4 DOM n/a
Read/Write
Used with IE data binding to associate a remote data source column name to a button object's label. A datasrc attribute must also be set for the element. Setting both the dataFld and dataSrc properties to empty strings breaks the binding between element and data source.

Example

document.getElementById("myButton").dataFld = "linkURL";

Value

Case-sensitive identifier of the data source column.

Default

None.

dataFormatAs NN n/a IE 4 DOM n/a
Read/Write
Used with IE data binding, this property advises the browser whether the source material arriving from the data source is to be treated as plain text or as tagged HTML.

Example

document.getElementById("myButton").dataFormatAs = "html";

Value

String constant values: text | html.

Default

text

dataSrc NN n/a IE 4 DOM n/a
Read/Write
Used with IE data binding to specify the ID of the page's object element that loads the data source object for remote data access. Content from the data source is specified via the datafld attribute in the button element. Setting both the dataFld and dataSrc properties to empty strings breaks the binding between element and data source.

Example

document.getElementById("myButton").dataSrc = "DBSRC3";

Value

Case-sensitive identifier of the object element.

Default

None.

form NN 6 IE 4 DOM 1
Read-only
Returns a reference to the form element that contains the current element (if any).

Example

var theForm = event.srcElement.form;

Value

Object reference.

Default

None.

name NN 6 IE 4 DOM 1
Read/Write
This is the identifier associated with the element when used as a form control. The value of this property is submitted as one-half of the name/value pair when the form is submitted to the server. Names are hidden from user view, since control labels are assigned via other means, depending on the control type. Form control names may also be used by script references to the objects.

Example

document.forms[0].compName.name = "company";

Value

Case-sensitive identifier that follows the rules of identifier naming: it may contain no whitespace, cannot begin with a numeral, and should avoid punctuation except for the underscore character.

Default

None.

status NN n/a IE 4 DOM n/a
Read/Write
Unlike the status property of other types of form controls, the property has no visual or functional impact on the button.

Value

Boolean value: true | false; or null.

Default

null

type NN 6 IE 4 DOM 1
Read-only
Specifies whether the button element is specified as a button, reset, or submit style button.

Example

if (evt.target.type == "button") { // process button element }

Value

One of the three constants (as a string): button | reset | submit.

Default

button

value NN 6 IE 4 DOM 1
Read-only
Provides the current value associated with the form control that is submitted with the name/value pair for the element. Unlike the button-type input element object, this value property's value is unseen by the user; the label is set by the element's content (innerHTML property or nested node).

Example

var val = document.getElementById("myButton").value;

Value

String.

Default

None.

createTextRange( ) NN n/a IE 4(Win) DOM n/a
Creates a TextRange object containing the button's label text. See the TextRange object.

Returned Value

TextRange object.

Parameters

None.

caption NN 6 IE 4 DOM 1

The caption object reflects the caption element, which must always be nested inside a table element. IE/Mac implements the client and scroll property sets for this object.

HTML Equivalent

<caption>

Object Model Reference

[window.]document.getElementById("elementID")

Object-Specific Properties

align

vAlign

Object-Specific Methods

None.

Object-Specific Event Handler Properties

None.

align NN 6 IE 4 DOM 1
Read/Write
Determines the position of the caption in the table. See the align attribute of the caption element in Chapter 8 for details on the interaction between the align and vAlign attributes and properties in IE for Windows. The W3C DOM uses the align property predominantly for placing the caption above or below the table.

Example
document.getElementById("myCaption").align = "bottom";
Value

Any of the following constants (as a string): bottom | left | right | top.

Default

top

vAlign NN n/a IE 4 DOM n/a
Read/Write
Specifies whether the table caption appears above or below the table.

Example

document.getElementById("tabCaption").vAlign = "bottom"

Value

Case-insensitive constant (as a string): bottom | top.

Default

top

cells NN 6 IE 4 DOM 1

A collection of all td elements contained within a single tr element. Collection members are sorted in source code order.

Object Model Reference

document.getElementById("rowID").cells

Object-Specific Properties

length

Object-Specific Methods

item( )

namedItem( )

tags( )

urns( )

Object-Specific Event Handler Properties

None.

length NN 6 IE 4 DOM 1
Read-only
Returns the number of elements in the collection.

Example

var howMany = document.getElementById("myTable").rows[0].cells.length;

Value

Integer.

item( ) NN 6 IE 4 DOM 1
item(index[, subindex]) item(index)
Returns a single td object or collection of td objects corresponding to the element matching the index value (or, optionally in IE, the index and subindex values).

Returned Value

One td object or collection (array) of td objects. If there are no matches to the parameters, the returned value is null.

Parameters

index

When the parameter is a zero-based integer, the returned value is a single element corresponding to the specified item in source code order (nested within the current element); when the parameter is a string (IE only), the returned value is a collection of elements whose id properties match that string.

subindex

In IE only, if you specify a string value for the first parameter, you can use the second parameter to specify a zero-based index that retrieves the specified element from the collection whose id properties match the first parameter's string value.

namedItem( ) NN 6 IE 6 DOM 1
namedItem("ID")
Returns a single td object or collection of td objects corresponding to the element matching the parameter string value.

Returned Value

One td object or collection (array) of td objects. If there are no matches to the parameters, the returned value is null.

Parameters

ID

The string that contains the same value as the desired element's id attribute.

tags( ) NN n/a IE 4 DOM n/a
tags("tagName")
Returns a collection of objects (among all objects nested within the current collection) whose tags match the tagName parameter. Implemented in all IE collections (see the all.tags( ) method), but redundant for collections of the same element type.

urns( ) NN n/a IE 5(Win) DOM n/a
urns(URN)
See the all.urns( ) method.

childNodes, NodeList NN 6 IE 5 DOM 1

The object returned by the childNodes property of several W3C DOM objects is a collection (array) of references to Node objects that are immediate children of the current node object. In the W3C DOM structure, the abstract representation of this array is called the NodeList object, which shares some properties and methods of the IE childNodes object. Since both objects refer to the same parts of a document tree, they are treated here together. Collection members are sorted in source code order.

Object Model Reference

nodeReference.childNodes

Object-Specific Properties

length

Object-Specific Methods

item( )

urns( )

Object-Specific Event Handler Properties

None.

length NN 6 IE 4 DOM 1
Read-only
Returns the number of nodes in the collection.

Example

var howMany = document.getElementById("myTable").attributes.length;

Value

Integer.

item( ) NN 6 IE 5 DOM 1
item(index)
Returns a single Node object corresponding to the element matching the index value.

Returned Value

Reference to one Node object. If there is no match to the index value, the returned value is null. Unlike some other collections in IE, a string index value is not allowed for the childNodes object.

Parameters

index

A zero-based integer corresponding to the specified item in source code order (nested within the current node).

urns( ) NN n/a IE 5(Win) DOM n/a
urns(URN)
See the all.urns( ) method.

children NN n/a IE 4 DOM n/a

A collection of all elements contained in the current element. Note that unlike the childNodes collection, children counts only elements and not text nodes. Collection members are sorted in source code order. Internet Explorer lets you use array notation or parentheses to access a single element in the collection.

Object Model Reference

document.getElementById("elementID").children(i)
document.getElementById("elementID").children[i]

Object-Specific Properties

length

Object-Specific Methods

item( )

namedItem( )

tags( )

urns( )

Object-Specific Event Handler Properties

None.

length NN n/a IE 4 DOM n/a
Read-only
Returns the number of elements in the collection.

Example

var howMany = document.body.children.length;

Value

Integer.

item( ) NN n/a IE 4 DOM n/a
item(index)
Returns an element object corresponding to the element matching the index value in source code order.

Returned Value

Reference to an element object. If there is no matches to the parameter, the returned value is null.

Parameters

index

A zero-based integer corresponding to the specified item in source code order (nested within the current element).

namedItem( ) NN n/a IE 6 DOM n/a
namedItem(IDOrName)
Returns an element object or collection of objects corresponding to the element matching the parameter string value.

Returned Value

One element object or collection (array) of element objects. If there are no matches to the parameters, the returned value is null.

Parameters

IDOrName

The string that contains the same value as the desired element's id or name attribute.

tags( ) NN n/a IE 4 DOM n/a
tags(tagName)
Returns a collection of objects (among all objects nested within the current collection) whose tags match the tagName parameter. Implemented in all IE collections (see the all.tags( ) method), but redundant for collections of the same element type.

urns( ) NN n/a IE 5(Win) DOM n/a
urns(URN)
See the all.urns( ) method.

clipboardData NN n/a IE 5(Win) DOM n/a

The clipboardData object (accessible as a property of a window or frame object) is a temporary container that scripts in IE 5 and later for Windows can use to transfer text data, particularly during script-controlled operations that simulate cutting, copying, and pasting, or that control dragging. Your script controls what data is stored in the clipboardData object, such as just the text of an element, an element's entire HTML, or the URL of an image. For example, a page for children could display simple icon images of several different kinds of animals. If the user starts dragging the dog icon, the script initiated by the img element's onDragStart event handler stores a custom attribute value of that element (perhaps the URL of a pretty dog photo) into the clipboardData object. When the user drops the icon into the designated area, the onDrop event handler's function reads the clipboardData object's data and loads the photo image into position on the page.

Data stored in this object survives navigation to other pages within the same domain and protocol. Therefore, you can use it to pass text data (including arrays that have been converted to strings by the Array.join( ) method) from one page to another without using cookies or location.search strings. But this is not the system clipboard (for security reasons).

For more information on transferring data via this object and the event.dataTransfer object, visit http://msdn.microsoft.com/workshop/author/datatransfer/overview.asp.

HTML Equivalent

None.

Object Model Reference

[window.]clipboardData

Object-Specific Properties

dropEffect

effectAllowed

Object-Specific Methods

clearData( )

getData( )

setData( )

Object-Specific Event Handler Properties

None.

dropEffect, effectAllowed NN n/a IE 5(Win) DOM n/a
Read/Write
These two properties belong to the clipboardData object by inheritance from the dataTransfer object, to which they genuinely apply. Ignore these properties for the clipboardData object.

clearData( ) NN n/a IE 5(Win) DOM n/a
clearData([dataFormat])
Removes data from the clipboardData object.

Returned Value

None.

Parameters

dataFormat

An optional string specifying a single format for the data to be removed. Earlier plans to allow multiple data types appear to have fallen through. As of IE 6, the only reliable format is Text. Omitting the parameter removes all data of all types.

getData( ) NN n/a IE 5(Win) DOM n/a
getData(dataFormat)
Returns a copy of data from the clipboardData object. The clipboardData contents remain intact for subsequent reading in other script statements.

Returned Value

String.

Parameters

dataFormat

A string specifying the format for the data to be read. Earlier plans to allow multiple data types appear to have fallen through. As of IE 6, the only reliable format is Text.

setData( ) NN n/a IE 5(Win) DOM n/a
setData(dataFormat, stringData)
Stores string data in the clipboardData object. Returns Boolean true if the assignment is successful

Returned Value

Boolean value: true | false.

Parameters

dataFormat

A string specifying the format for the data to be read. Earlier plans to allow multiple data types appear to have fallen through. As of IE 6, the only reliable format is Text. While the method accepts URL as a format, reading a set value in that format is not successful.

stringData

Any string value, including strings that contain HTML tags.

col, colgroup NN 6 IE 4 DOM 1

The col object reflects the col element; the colgroup object reflects the colgroup element. Both elements provide ways of assigning multiple adjacent columns to groups for convenience in assigning styles, widths, and other visual treatments.

HTML Equivalent

<col>
<colgroup>

Object Model Reference

[window.]document.getElementById("elementID")

Object-Specific Properties

`align`	`ch`	`chOff`	`span`	`vAlign`
`width`

Object-Specific Methods

None.

Object-Specific Event Handler Properties

None.

align NN 6 IE 4 DOM 1
Read/Write
Defines the horizontal alignment of content within cells covered by the col or colgroup element.

Example

document.getElementById("myCol").align = "center";

Value

Any of the three horizontal alignment constants: center | char | left | right.

Default

left

ch NN 6 IE 6 DOM 1
Read/Write
Defines the text character used as an alignment point for text within a column or column group (reflecting the char attribute). This property is normally of value only for the align attribute set to "char". In practice, neither IE nor Navigator respond to these properties.

Example

document.getElementById("myCol").ch = ".";

Value

Single character string.

Default

None.

chOff NN 6 IE 6 DOM 1
Read/Write
Defines the offset point at which the character specified by the char attribute is to appear within a cell. In practice, neither IE 6 nor Netscape 6 respond to these properties.

Example

document.getElementById("myCol").chOff = "80%";

Value

String value of the number of pixels or percentage (within the cell).

Default

None.

span NN 6 IE 4 DOM 1
Read/Write
Provides the number of adjacent columns for which the element's attribute and style settings apply.

Example

document.getElementById("myColgroup").span = 2;

Value

Integer.

Default

1

vAlign NN 6 IE 4 DOM 1
Read/Write
Provides the manner of vertical alignment of text within the column grouping's cells.

Example

document.getElementById("myCol").vAlign = "baseline";

Value

Case-insensitive constant (as a string): baseline | bottom | middle | top.

Default

middle

width NN 6 IE 4 DOM 1
Read/Write
Provides the width in pixels of each column of the column grouping. Changes to these values are immediately reflected in reflowed content on the page.

Example

document.getElementById("myColgroup").width = 150;

Value

Integer.

Default

None.

comment, Comment NN 6 IE 4 DOM 1

The comment object reflects the ! element in an HTML document. But in a W3C DOM environment, such as Netscape 6, this object is not a genuine element in the context of the W3C DOM abstract model. Instead, the object is simply a special kind of node. Such a node has a nodeType value of 8, which identifies it as a Comment node. A Comment node has the following inheritance chain in the DOM abstract model: Node->CharacterData->Comment. While a Comment node has special values automatically assigned to some of its properties (such as nodeValue), a Comment node has no properties or methods beyond the ones inherited from the Node and CharacterData objects. Node properties and methods are discussed earlier in this chapter among the shared items; CharacterData properties and methods are covered in detail with the Text object, which also inherits from CharacterData, and is more likely to be scripted.

To reference a comment element, use relative element or node properties. While IE provides an id property by virtue of its inheritance model, you cannot assign an identifier to the element via an id attribute. Such an element in IE does, however, have a tag name value of !. Therefore, you can reference an IE HTML comment element via the collection of elements returned by the document.all.tags("!") method.

HTML Equivalent

<!--comment text-->

Object Model Reference

nodeReference

Object-Specific Properties

data

length

text

Object-Specific Methods

`appendData( )`	`deleteData( )`	`insertData( )`	`replaceData( )`
`substringData( )`

Object-Specific Event Handler Properties

None.

data NN 6 IE 6 DOM 1
Read/Write
Provides the text content of the comment. See Text.data.

length NN 6 IE 6 DOM 1
Read-only
Provides the character count of the comment data. See Text.length.

text NN n/a IE 4 DOM 1
Read/Write
Provides the text content of the element. Due to the nature of this element, the value of the text property is identical to the values of the innerHTML and outerHTML properties. Changes to this property do not affect the text of the comment as viewed in the browser's source code version of the document. This property is not available in IE 4/Macintosh.

Example

document.all.tags("!")[4].text = "Replaced comment, but no one will know.";

Value

String.

Default

None.

appendData(), deleteData(), insertData(), replaceData( ), substringData( ) NN 6 IE 6 DOM 1
Provide methods for manipulating comment text. See these methods in the Text object.

cssRule, CSSRule, rule NN 6 IE 5 DOM 2

A style sheet rule object is a member of the collection of styleSheet objects in the document. The IE and W3C DOMs have different syntax for referencing each of these rule objects. For IE, the reference is via the rules collection (a single object being known as a rule object); for W3C, as implemented in Netscape 6 and IE 5 for the Macintosh, the reference is via the cssRules collection (a single object being known as a cssRule object). Note that the cssRule object is not in the Windows version of IE through Version 6.

The corresponding W3C DOM abstract object is called the CSSRule object, but that form of the object name is important only to scripters who wish to modify the prototype properties and methods of the CSSRule object in Netscape 6. The W3C DOM goes further to define special types of CSSRule objects for each of the @ rule types (CSSImportRule, CSSMediaRule, and so on). A member of the cssRules collection can be any one of those types, and is identified as such by its type property. Each type has its own set of properties and/or methods that apply to that cssRule type. In the item property and method listings below, observe the type(s) for which they apply. By and large, however, the inline rules you will script are of the CSSStyleRule type.

Use scriptable access to a rule or cssRule object with caution. If you modify a rule's selector or style definition, the changes affect the entire document, and could, with a misplaced colon, ruin other rules in the document. To toggle among two or more styles for a single element, class, or element type, it is generally more reliable and efficient to use other techniques that work with multiple rules (swapping className assignments on elements) or multiple style sheets (enabling and disabling styleSheet objects). But for the sake of the completeness of the object model, the W3C DOM in particular provides full access to style sheet rule pieces if you absolutely need them.

Object Model Reference

document.styleSheets[i].rules[j]
document.styleSheets[i].cssRules[j]

Object-Specific Properties

`cssRules`	`cssText`	`encoding`	`href`
`media`	`parentRule`	`parentStyleSheet`	`readOnly`
`selectorText`	`style`	`styleSheet`	`type`

Object-Specific Methods

deleteRule( )

insertRule( )

Object-Specific Event Handler Properties

None.

cssRules NN 6 IE n/a DOM 2
Read-only
Returns a collection of cssRule objects nested within an @media rule.

W3C DOM CSSRule Types

CSSMediaRule

Value

Reference to a cssRules collection object.

Default

Array of zero length.

cssText NN 6 IE 5(Mac) DOM 2
Read/Write
Indicates the complete text of the style sheet rule, including selector and attribute name/value pairs inside curly braces. IE 6 for Windows provides no equivalent property. In supporting browsers, changes do not influence the object or rendering.

W3C DOM CSSRule Types

All.

Example

document.styleSheets[0].cssRules[2].cssText = "td {text-align:center}";

Value

String.

Default

None.

encoding NN 6 IE n/a DOM 2
Read-only
Returns the character set code (e.g., ISO-8859-1 or UTF-8) associated with an @charset rule.

W3C DOM CSSRule Types

CSSCharsetRule

Value

String.

Default

None.

href NN 6 IE n/a DOM 2
Read-only
Returns the URI of the external style sheet file imported via an @import rule.

W3C DOM CSSRule Types

CSSImportRule

Value

String.

Default

None.

media NN 6 IE n/a DOM 2
Read-only
Returns the media type specified for an @import or @media rule.

W3C DOM CSSRule Types

CSSImportRule CSSMediaRule

Value

String constant for media types supported by the browser (e.g., screen or print).

Default

all

parentRule NN 6 IE n/a DOM 2
Read-only
Refers to the cssRule object that contains the current cssRule, such as a rule nested inside an @ rule. Accessing this property value can crash Netscape 6.2.

W3C DOM CSSRule Types

All.

Example

var superRule = document.styleSheets[0].cssRules[1].parentRule;

Value

cssRule object reference.

Default

null

parentStyleSheet NN 6 IE 5(Mac) DOM 2
Read-only
Refers to the styleSheet object that contains the current cssRule. Allows a function that might be passed a reference to a cssRule object to obtain a reference to the containing styleSheet object, possibly to learn more about what else is in the style sheet.

W3C DOM CSSRule Types

All.

Example

var ss = document.styleSheets[0].cssRules[3].parentStyleSheet;

Value

styleSheet object reference.

Default

Current object.

readOnly NN n/a IE 5 DOM n/a
Read-only
Returns Boolean true for rules that arrive to a document via an @import rule or a link element. Such rules may not be modified by script, although an element governed by such a rule can have individual style properties modified because the modifications are made to the element's own style property, and not the rule object.

Example

if (!document.styleSheets[2].cssRules[0].readOnly) { // not read-only, so OK to modify here }

Value

Boolean value: true | false.

Default

Varies with rule type.

selectorText NN 6 IE 5 DOM 2
Read/Write
Indicates the selector portion of the style sheet rule. Although this property is read/write (except in IE 5/Mac), changes do not influence the object or rendering.

W3C DOM CSSRule Types

CSSPageRule CSSStyleRule

Example

document.styleSheets[0].cssRules[2].selectorText = "td.leftHeaders";

Value

String.

Default

None.

style NN 6 IE 5 DOM 2
Read/Write
Returns a style object with properties that reflect the attribute settings of the current rule. This is the same kind of style object associated with elements in the document (corresponding to the W3C DOM CSSStyleDeclaration object). If you must modify style sheet settings at the rule level, do so via the style property of the rule or cssRule. Changes register themselves immediately, and the elements affected by the rule render their changes accordingly.

W3C DOM CSSRule Types

CSSFontRule CSSPageRule CSSStyleRule

Example

var oneRule; if (document.styleSheets) { if (document.styleSheets[0].cssRules) { oneRule = document.styleSheets[2].cssRules[1]; } else if (document.styleSheets[0].rules) { oneRule = document.styleSheets[2].rules[1]; } } if (oneRule) { oneRule.style.color = "red"; oneRule.style.fontWeight = "bold"; }

Value

Reference to a style (W3C CSSStyleDeclaration) object.

Default

Current style object.

styleSheet NN 6 IE n/a DOM 2
Read-only
Returns a reference to the styleSheet object contained by the imported style sheet. From here you can inspect cssRule objects belonging to that styleSheet object—essentially drilling down one more level to the styleSheet object structure of the remote style sheet file.

W3C DOM CSSRule Types

CSSImportRule

Value

styleSheet object reference.

Default

None.

type NN 6 IE n/a DOM 2
Read-only
Returns an integer corresponding to one of seven cssRule types, as defined by the W3C DOM. Every cssRule object in Netscape 6 comes equipped with plain-language constant properties corresponding to the rule types, as follows.

Constant

Equivalent integer

cssRuleReference.UNKNOWN_RULE

0

cssRuleReference.STYLE_RULE

1

cssRuleReference.CHARSET_RULE

2

cssRuleReference.IMPORT_RULE

3

cssRuleReference.MEDIA_RULE

4

cssRuleReference.FONT_FACE_RULE

5

cssRuleReference.PAGE_RULE

6

W3C DOM CSSRule Types

All.

Example

var oneRule = document.styleSheets[2].cssRules[1]; if (oneRule.type == oneRule.IMPORT_RULE) { // process @import rule }

Value

Integer.

Default

1

deleteRule( ) NN 6 IE n/a DOM 2
deleteRule(index)
Removes the zero-based index numbered rule from the current @media rule.

W3C DOM CSSRule Types

CSSMediaRule

Returned Value

None.

Parameters

index

A zero-based integer corresponding to the specified item in source code order.

insertRule( ) NN 6 IE n/a DOM 2
insertRule("rule", index)
Inserts a new rule (selector text and style attributes) into the current @media rule at the position indicated by the second parameter.

W3C DOM CSSRule Types

CSSMediaRule

Returned Value

Integer of inserted position.

Parameters

rule

A string containing selector and curly-braced style attributes comprising the rule to be inserted.

index

A zero-based integer corresponding to the specified item in source code order.

cssRules, CSSRuleList, rules NN 6 IE 4 DOM 2

A collection of cssRule (Netscape 6 and IE 5/Mac) or rule (IE 4 and later) objects that are members of a styleSheet object. The W3C DOM abstract representation of this collection is called a CSSRuleList object. Members of this collection are accessed only via their integer index number, but you may iterate through the collection and examine properties of each rule object (such as the selectorText property) to distinguish one rule from another.

Object Model Reference

IE (Windows): document.styleSheets[i].rules
NN and IE (Mac): document.styleSheets[i].cssRules

Object-Specific Properties

length

Object-Specific Methods

item( )

Object-Specific Event Handler Properties

None.

length NN 6 IE 4 DOM 2
Read-only
Returns the number of elements in the collection, including @ rules.

Example

var howMany = document.styleSheets[1].cssRules.length;

Value

Integer.

item( ) NN 6 IE 4 DOM 2
item(index)
Returns a style sheet rule object corresponding to the rule matching the index value in source code order.

Returned Value

Reference to a cssRule or rule object, depending on the object model. If there are no matches to the parameters, the returned value is null.

Parameters

index

A zero-based integer corresponding to the specified item in source code order (nested within the current styleSheet object).

dataTransfer NN n/a IE 5(Win) DOM n/a

The dataTransfer object (accessible as a property of the event object) is a temporary container that scripts in IE 5 and later for Windows can use to transfer text data, particularly during script-controlled operations that simulate cutting, copying, and pasting, or that control dragging. Your script controls what data is stored in the dataTransfer object, such as just the text of an element, an element's entire HTML, or the URL of an image. For example, a page for children could display simple icon images of several different kinds of animals. If the user starts dragging the dog icon, the script initiated by the img element's ondragstart event handler can store a custom attribute value of that element (perhaps the URL of a pretty dog photo) into the dataTransfer object. When the user drops the icon into the designated area, the ondrop event handler's function reads the dataTransfer object's data, and loads the photo image into position on the page.

Even though an event object changes its properties with each new event action, the dataTransfer object preserves its data from one event to the next, until a script removes the data from the object or other data is stored in it. Properties of the dataTransfer object distinguish its powers from those of the clipboardData object. By setting the dropEffect and effectAllowed properties, your scripts can control the type of cursor icon that appears during drag and drop operations. Example 9-1 demonstrates how the properties and methods of the dataTransfer object can be wired to dragging events such that the cursor changes to a "copy" style when rolled atop a desired drop target.

Example 9-1. Using the dataTransfer object

<html>
<head>
<title>dataTransfer Demo</title>
<style type="text/css">
td {text-align:center}
th {text-decoration:underline}
.cyan {color:cyan}
.yellow {color:yellow}
.magenta {color:magenta}
#blank1 {text-decoration:underline}
</style>
<script type="text/javascript">
// set stage when dragging a desired source element
function setupDrag( ) {
    if (event.srcElement.tagName != "TD") {
        // don't allow dragging for any other elements
        event.returnValue = false;
    } else {
        // set cursor to look like copy action
        event.dataTransfer.effectAllowed = "copy";
        // store dragged cell text to transfer
        event.dataTransfer.setData("Text", event.srcElement.innerText);
    }
}
// perform drop operations
function handleDrop( ) {
    var elem = event.srcElement;
    var passedData = event.dataTransfer.getData("Text");
    if (passedData) {
        // show drop target cursor
        event.dataTransfer.dropEffect = "copy";
        // apply data to drop target
        elem.innerText = passedData;
        elem.className = passedData;
        document.selection.empty( );
    }
}
// we're dragging/copying, but not to here
function cancelDefault( ) {
    // set cursor to "No" symbol
    event.dataTransfer.dropEffect = "copy";
    event.returnValue = false;
}
</script>
</head>
<body ondragstart="setupDrag( );">
<table cellpadding="5">
<tr><th>Drag Your Favorite Color</th></tr>
<tr><td>cyan</td></tr>
<tr><td>yellow</td></tr>
<tr><td>magenta</td></tr>
</table>

<p>My favorite color is <span id="blank1" ondragenter="cancelDefault( );" 
ondragover="cancelDefault( );" ondrop="handleDrop( );">
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</span> .</p>
</body>
</html>

For more information on transferring data via this object and the clipboardData object, visit http://msdn.microsoft.com/workshop/author/datatransfer/overview.asp.

HTML Equivalent

None.

Object Model Reference

[window.]event.dataTransfer

Object-Specific Properties

dropEffect

effectAllowed

Object-Specific Methods

clearData( )

getData( )

setData( )

Object-Specific Event Handler Properties

None.

dropEffect, effectAllowed NN n/a IE 5 DOM n/a
Read/Write
These two properties work together but at different stages along a dragging operation that involves the dataTransfer object. They both control the appearance of the cursor during the drag and drop process. Assign a cursor style at the beginning of a drag operation via the ondragstart event and effectAllowed property. The drop target's ondragover and ondragenter event handlers should set the dropEffect property to the desired cursor style, and also set the event.returnValue property to false. This opens the way for the ondrop event handler not only to set the cursor via the dropEffect property, but to process the drop action. See Example 9-1 for a simple demonstration of the interaction of all these events and properties.

Example
event.dataTransfer.dropEffect= "copy";
Value

Case-insensitive constant (as a string): copy | link | move | none.

Default

none

clearData( ) NN n/a IE 5(Win) DOM n/a
clearData([dataFormat])
Removes data from the dataTransfer object.

Returned Value

None.

Parameters

dataFormat

An optional string specifying the format for the data to be removed. Earlier plans to allow multiple data types appear to have fallen through. As of IE 6, the only reliable format is Text. Omitting the parameter deletes all data of all types.

getData( ) NN n/a IE 5(Win) DOM n/a
getData(dataFormat)
Returns a copy of data from the dataTransfer object. The dataTransfer contents remain intact for subsequent reading in other script statements.

Returned Value

String.

Parameters

dataFormat

A string specifying the format for the data to be read. Earlier plans to allow multiple data types appear to have fallen through. As of IE 6, the only reliable format is Text.

setData( ) NN n/a IE 5(Win) DOM n/a
setData(dataFormat, stringData)
Stores string data in the dataTransfer object. Returns Boolean true if the assignment is successful

Returned Value

Boolean value: true | false.

Parameters

dataFormat

A string specifying the format for the data to be read. Earlier plans to allow multiple data types appear to have fallen through. As of IE 6, the only reliable format is Text. While the method accepts URL as a format, reading a set value in that format is not successful.

stringData

Any string value, including strings that contain HTML tags.

dd	`NN 6` IE 4 DOM 1

The dd object reflects the dd element.

HTML Equivalent

<dd>

Object Model Reference

[window.]document.getElementById("elementID")

Object-Specific Properties

noWrap

Object-Specific Methods

None.

Object-Specific Event Handler Properties

None.

noWrap NN n/a IE 4 DOM n/a
Read/Write
Specifies whether the browser should render the element as wide as is necessary to display a line of nonbreaking text on one line. Abuse of this attribute can force the user into a great deal of inconvenient horizontal scrolling of the page to view all of the content.

Example

document.getElementById("wideBody").noWrap = "true";

Value

Boolean value: true | false.

Default

false

del NN 6 IE 4 DOM 1

The del object reflects the del element.

HTML Equivalent

<del>

Object Model Reference

[window.]document.getElementById("elementID")

Object-Specific Properties

cite

dateTime

Object-Specific Methods

None.

Object-Specific Event Handler Properties

None.

cite, dateTime NN 6 IE 5(Mac)/6(Win) DOM 1
Read/Write
These two properties are listed among the shared properties earlier in this chapter due to an IE 6 implementation oddity. IE 5/Macintosh and Netscape 6 correctly implement these properties only for the del and ins objects, as specified in the W3C DOM, but in no mainstream browser do they convey any special powers. See the shared cite and dateTime properties.

Dialog Helper NN n/a IE 6(Win) DOM n/a

The Dialog Helper object is an ActiveX control delivered with IE 6 for Windows that provides a short assortment of potentially useful system and document information; the method also displays a color selector dialog from which your scripts can obtain a user's color choice. Most typically, it would be used when scripting IE's edit mode, where users need to make color, font, and element choices. But you might find the object's properties and methods useful in traditional browser document settings.

Loading this object into the page requires the following <object> tag:

<object id="dlgHelper" classid="clsid:3050f819-98b5-11cf-bb82-00aa00bdce0b" 
        width="0px" height="0px">
</object>

Because this object is not rendered, you may place its tag in the head portion of your document. You may also assign your choice of identifier to the id attribute. Once the object is loaded, reference it as a global object in the window.

HTML Equivalent

None.

Object Model Reference

[window.]document.getElementById("elementID")

Object-Specific Properties

blockFormats

fonts

Object-Specific Methods

ChooseColorDlg( )

getCharset( )

Object-Specific Event Handler Properties

None.

blockFormats NN n/a IE 6 DOM n/a
Read-only
Returns a collection of plain-language names of block-level elements supported by the browser. Unlike other IE collections, to read the number of items, you must access its Count property, rather than length property. The names of items returned are strings, such as "Heading 1" and "Numbered List" (corresponding to the h1 and ol elements, respectively). Access each item in the collection via the collection's item( ) method.

Example

var blockList = dlgHelper.blockFormats; var blockNames = new Array( ); for (var i = 0; i < blockList.Count; i++) { blockNames[blockNames.length]= blockList.item(i); }

Value

Array of strings

Default

Implementation-dependent.

fonts NN n/a IE 6 DOM n/a
Read-only
Returns a collection of plain-language names of system fonts. Unlike other IE collections, to read the number of items, you must access its Count property, rather than length property. The names of items returned are strings, such as "MS Sans Serif" and "Verdana". Access each item in the collection via the collection's item( ) method.

Example

var fontList = dlgHelper.fonts; var fontNames = new Array( ); for (var i = 0; i < fontList.Count; i++) { fontNames [fontNames .length]= fontList .item(i); }

Value

Array of strings

Default

Implementation-dependent.

ChooseColorDlg( ) NN n/a IE 6 DOM n/a
ChooseColorDlg([initialHexColor])
Displays a color selector dialog box, and returns a decimal number corresponding to the color chosen by the user. To apply the color to style or other color property settings, you may have to convert the decimal value to a suitable hexadecimal triplet value of the #RRGGBB format. The following fragment demonstrates the sequence of obtaining the color, converting it to the desired base and digit count, and assigning the value to a style property:
var colorChoice = dlgHelper.ChooseColorDlg( ); var hexColor = colorChoice.toString(16); while (hexColor.length < 6) {hexColor = "0" + hexColor;} document.body.style.color = "#" + hexColor;
If the user selects a custom color in the dialog and adds it to a little shortcut box, the color does not reappear in the box the next time the dialog appears. But a custom color can still be pre-selected by passing its hex value as a parameter to the method.

Returned Value

Decimal integer of the selected color (0 through as many colors of the client settings).

Parameters

initialHexColor

Optional hexadecimal number that presets the initially-selected color in the dialog box.

getCharset( ) NN n/a IE 6 DOM n/a
getCharset("fontName")
Returns an integer corresponding to a constant associated with a character set known by the operating system. Among the common values returned for font families installed on Latin-based systems are 0 (for plain ANSI character set) and 2 (for a symbol set). The required parameter is the name of a font to inspect for its character set. Such names may be retrieved from the fonts property of the Dialog Helper object:
var setID = dlgHelper.getCharset(dlgHelper.fonts.item(4));
Not all Windows versions have the same character set suite installed.

Returned Value

Integer.

Parameters

fontName

String name of installed system font.

dir NN 6 IE 4 DOM 1

The dir object reflects the dir element. This element, originally intended as a multicolumn list format, is treated the same as the ul element.

HTML Equivalent

<dir>

Object Model Reference

[window.]document.getElementById("elementID")

Object-Specific Properties

compact

Object-Specific Methods

None.

Object-Specific Event Handler Properties

None.

compact NN 6 IE 5(Mac)/6(Win) DOM 1
Read/Write
Provided for this element for the sake of compatibility with the W3C DOM standard. However, mainstream browsers do not act upon this property or its corresponding attribute.

Value

Boolean value: true | false.

Default

false

directories, locationbar, menubar, personalbar, scrollbars, statusbar, toolbar NN 4 IE n/a DOM n/a

These objects belong to the window object and represent portions of the "chrome" surrounding the content area of the browser window (the directories object is new for Netscape 6). With signed scripts in Navigator 4 or later (and the user's permission), you can dynamically hide and show these elements in a browser window. These features can also be turned off via the third parameter of the window.open( ) method, but only when generating a new window. To change the visibility of these items in an existing window, signed scripts are required. Internet Explorer has no equivalent functionality for a window that is already open.

Object Model Reference

[window.]directories
[window.]locationbar
[window.]menubar
[window.]personalbar
[window.]scrollbars
[window.]statusbar
[window.]toolbar

Object-Specific Properties

visible

Object-Specific Methods

None.

Object-Specific Event Handler Properties

None.

visible NN 4 IE n/a DOM n/a
Read/Write
Accessible only through signed scripts in Navigator 4 or later, determines whether the window chrome feature is displayed.

Example

netscape.security.PrivilegeManager.enablePrivilege("UniversalBrowserWrite"); window.statusbar.visible = "false"; netscape.security.PrivilegeManager.revertrivilege("UniversalBrowserWrite");

Value

Boolean value: true | false.

Default

true

div NN 6 IE 4 DOM 1

The div object reflects the div element. This element creates a block-level element often used for element positioning or containment grouping of several related elements. In the Windows version of IE 4, the client- and scroll-related properties are not available unless the div element has its position style attribute set to absolute. The client and scroll properties are active in IE for the Macintosh.

HTML Equivalent

<div>

Object Model Reference

[window.]document.getElementById("elementID")

Object-Specific Properties

align

dataFld

dataFormatAs

dataSrc

noWrap

Object-Specific Methods

None.

Object-Specific Event Handler Properties

None.

align NN 6 IE 4 DOM 1
Read/Write
Defines the horizontal alignment of content within the element's box. Unless otherwise reined in, the box width is that of the next outermost positioning context—usually the body.

Example

document.getElementById("myDIV").align = "center";

Value

Any of the three horizontal alignment constants: center | left | right.

Default

left

dataFld NN n/a IE 4 DOM n/a
Read/Write
Used with IE data binding to associate a remote data source column name to a div element's content. A datasrc attribute must also be set for the element. Setting both the dataFld and dataSrc properties to empty strings breaks the binding between element and data source. Works only for text data sources in IE 5 for the Macintosh.

Example

document.getElementById("myDiv").dataFld = "comment";

Value

Case-sensitive identifier of the data source column.

Default

None.

dataFormatAs NN n/a IE 4 DOM n/a
Read/Write
Used with IE data binding, this property advises the browser whether the source material arriving from the data source is to be treated as plain text or as tagged HTML.

Example

document.getElementById("myDiv").dataFormatAs = "text";

Value

String constants: text | html.

Default

text

dataSrc NN n/a IE 4 DOM n/a
Read/Write
Used with IE data binding to specify the ID of the page's object element that loads the data source object for remote data access. Content from the data source is specified via the datafld attribute. Setting both the dataFld and dataSrc properties to empty strings breaks the binding between element and data source.

Example

document.getElementById("myDiv").dataSrc = "DBSRC3";

Value

Case-sensitive identifier of the data source.

Default

None.

noWrap NN n/a IE 4 DOM n/a
Read/Write
Specifies whether the browser should render the element as wide as is necessary to display a line of nonbreaking text on one line. Abuse of this attribute can force the user into a great deal of inconvenient horizontal scrolling of the page to view all of the content. The corresponding attribute is deprecated.

Example

document.getElementById("wideDiv").noWrap = "true";

Value

Boolean value: true | false.

Default

false

dl	`NN 6` IE 4 DOM 1

The dl object reflects the dl element. This element is the wrapper for a definition list grouping.

HTML Equivalent

<dl>

Object Model Reference

[window.]document.getElementById("elementID")

Object-Specific Properties

compact

Object-Specific Methods

None.

Object-Specific Event Handler Properties

None.

compact NN 6 IE 4 DOM 1
Read/Write
When set to true, the compact property instructs the browser to render a related dt and dd pair on the same line if space allows. This compact styling is intended for dt elements consisting of only a few characters.

Example

document.getElementById("maindl").compact = true;

Value

Boolean value: true | false.

Default

false

document NN 2 IE 3 DOM 1

The document object represents both the content viewed in the browser window or frame and the other content of the HTML file loaded into the window or frame. Thus, all information from the head portion of the file is also part of the document object. All references to elements must include a reference to the document object. The document object has no name other than its hard-wired object name: document.

For a browser with internal architecture based closely on the W3C DOM, this document object represents the HTMLDocument object—a special kind (internal subclass) of the core module's Document object, suited to holding HTML documents. In other words, the HTMLDocument object inherits the properties and methods of the core Document object (sharing facilities with XML documents) and gets additional properties and methods that apply only to HTML documents. Of course, there is the conceptual incongruity about whether an HTMLDocument is applicable to an XHTML document because such a document theoretically is an XML document. But, in practice, even an XHTML document becomes an HTML document for scripting purposes, and has all the HTMLDocument properties and methods available to it.

One more important practical side to a W3C DOM implementation (as evidenced by the Netscape 6 implementation) is that the document object internally implements document-level properties and methods from other DOM modules, such as views, events, and styles. Each of these modules defines an object (DocumentEvent, DocumentRange, DocumentStyle, and DocumentView) that provides a vital connection between the HTMLDocument and these add-on module features. Thus, it is the styleSheets property of the DocumentStyle object in the W3C DOM that the scriptable document object described here uses to reach the styleSheet objects and their rules. And the DocumentEvent object links in its createEvent( ) method that allows the scriptable document object to generate an event outside the normal user- or system-created events. All of these features become subsumed by the document object you reference and script in Netscape 6 and similar browsers. The precise source module for a particular feature is not important to the scripter—all you need to know is that the properties and methods belong to the scriptable document object.

Object Model Reference

[window.]document

Object-Specific Properties

`activeElement`	`alinkColor`	`anchors[ ]`	`applets[ ]`
`bgColor`	`body`	`charset`	`characterSet`
`compatMode`	`cookie`	`defaultCharset`	`defaultView`
`doctype`	`documentElement`	`domain`	`embeds[ ]`
`expando`	`fgColor`	`fileCreatedDate`	`fileModifiedDate`
`fileSize`	`fileUpdatedDate`	`forms[]`	`frames[]`
`height`	`ids[]`	`images[]`	`implementation`
`lastModified`	`layers[]`	`linkColor`	`links[]`
`location`	`media`	`mimeType`	`nameProp`
`namespaces[]`	`parentWindow`	`plugins[]`	`protocol`
`readyState`	`referrer`	`scripts[]`	`security`
`selection`	`styleSheets[]`	`tags[]`	`title`
`URL`	`URLUnencoded`	`vlinkColor`	`width`

Object-Specific Methods

`addBinding( )`	`captureEvents( )`
`clear( )`	`close( )`
`createAttribute( )`	`createAttributeNS( )`
`createCDATASection( )`	`createComment( )`
`createDocumentFragment( )`	`createElement( )`
`createElementNS( )`	`createEntityReference( )`
`createEvent( )`	`createEventObject( )`
`createNodeIterator( )`	`createProcessingInstruction( )`
`createRange( )`	`createStyleSheet( )`
`createTextNode( )`	`createTreeWalker( )`
`elementFromPoint( )`	`execCommand( )`
`getAnonymousElementByAttribute( )`	`getAnonymousNodes( )`
`getBindingParent( )`	`getElementById( )`
`getElementsByName( )`	`getSelection( )`
`handleEvent( )`	`hasFocus( )`
`importNode( )`	`loadBindingDocument( )`
`open( )`	`queryCommandEnabled( )`
`queryCommandIndeterm( )`	`queryCommandState( )`
`queryCommandSupported( )`	`queryCommandText( )`
`queryCommandValue( )`	`recalc( )`
`releaseEvents( )`	`removeBinding( )`
`routeEvent( )`	`write( )`
`writeln( )`

Object-Specific Event Handler Properties

Handler	NN	IE	DOM
`onselectionchange`	n/a	4	n/a
`onstop`	n/a	4	n/a

activeElement NN n/a IE 4 DOM n/a
Read-only
Refers to the object that is currently designated as the active element in the document. To learn more about the returned object, you'll need to examine the object's tagName, id, or other properties. Because buttons and other elements do not receive focus on the IE 4 for Macintosh, the returned value of this property may vary with operating system. While an element (especially a form control) that receives focus also becomes active, an element might be active, but due to other settings in newer IE versions, does not have focus. See the shared setActive( ) method.

Example

var currObj = document.activeElement;

Value

Element object reference.

Default

None.

alinkColor NN 2 IE 3 DOM n/a
Read/Write (IE)
Specifies the color of a hypertext link as it is being clicked. The color is applied to the link text or border around an image or object embedded within an a element. See also linkColor and vlinkColor properties for unvisited and visited link colors. Replaced in the W3C DOM by the aLink property of the body object, which is supported in IE 4 and later and in Netscape 6. Dynamically changed values for alinkColor are not reflected on the page in Navigator through Version 4.

Example

document.alinkColor = "green";

Value

A hexadecimal triplet or plain-language color name. See Appendix A for acceptable plain-language color names.

Default

#0000FF

anchors[ ] NN 2 IE 3 DOM 1
Returns an array of all anchor objects in the current document. This includes a elements that are designed as either anchors or combination anchors and links. Items in this array are indexed (zero-based) in source code order.

Example

var aCount = document.anchors.length;

Value

Array of anchor element objects.

Default

Array of length zero.

applets[ ] NN 2 IE 3 DOM 1
Returns an array of all Java applet objects in the current document. An applet must be started and running before it is counted as an object. Items in this array are indexed (zero-based) in source code order.

Example

var appletCount = document.applets.length

Value

Array of applet element objects.

Default

Array of length zero.

bgColor NN 2 IE 3 DOM n/a
Read/Write
Provides the background color of the document. Even if the bgcolor attribute or bgColor property is set with a plain-language color name, the returned value is always a hexadecimal triplet.
Setting the bgColor property of a document in Navigator 2 or 3 for Macintosh or Unix does not properly redraw the window. Window content is obscured by the new color on those platforms. For browsers that support the document.body object, use the bgColor property of that object instead.

Example

document.bgColor = "yellow";

Value

A hexadecimal triplet or plain-language color name. See Appendix A for acceptable plain-language color names.

Default

Varies with browser and operating system.

body NN 6 IE 4 DOM 1
Read-only
Returns a reference to the body object defined by the body element within the document. This property is used as a gateway to the body object's properties.

Example

document.body.leftMargin = 15;

Value

Object reference.

Default

The current body object.

charset NN n/a IE 4 DOM n/a
Read/Write
Indicates the character encoding of the document's content. This property is dropped from IE 6 for Windows in favor of the document.defaultCharset property. For Netscape 6, use the document.characterSet property.

Example

if (document.charset == "csISO5427Cyrillic") { // process for Cyrillic charset }

Value

Case-insensitive alias from the character set registry (ftp://ftp.isi.edu/in-notes/iana/assignments/character-sets).

Default

Determined by browser.

characterSet NN 6 IE n/a DOM n/a
Read-only
Indicates the character encoding of the document's content.

Example

if (document.characterSet == "ISO-8859-1") { // process for standard Latin character set }

Value

Case-insensitive alias from the character set registry (ftp://ftp.isi.edu/in-notes/iana/assignments/character-sets).

Default

Determined by browser.

compatMode NN 7 IE 6 DOM n/a
Read-only
Returns the compatibility mode for the document, as controlled by the DOCTYPE element's content. See the DOCTYPE element discussion in Chapter 8 for details on how to force the browser to treat a document in either backward compatibility or standards compatibility mode for element positioning and other implementation details. Because the choice of mode can impact some style property results, you can use this property to branch between two calculations in a shared library so that they treat the current document correctly, regardless of mode.

Example
if (document.compatMode == "BackCompat") {
    // process as if IE 5.5 or earlier or Netscape "quirks" mode
}
Value

String constant: BackCompat | CSS1Compat.

Default

BackCompat

cookie NN 2 IE 3 DOM 1
Read/Write
Indicates the HTTP cookie associated with the domain of the document and stored on the client machine. The Netscape browsers group all cookie data together into a single file, while IE creates a separate file for each domain's cookie data. Reading and writing the cookie property are not parallel operations. Reading a cookie property returns a semicolon-delimited list of name/value pairs in the following format:
name=value
Up to 20 of these pairs can be stored in the cookie property for a given domain (regardless of the number of HTML documents used in that web site). A total of 4,000 characters can be stored in the cookie, but it is advisable to keep each name/value pair to less than 2,000 characters in length. It is up to your scripting code to parse the cookie property value for an individually named cookie's value.
Writing cookie property values allows more optional pairs of data associated with a single name/value pair. Cookie data must be a string, but you can deconstruct an array into a string via the Array.join( ) method for writing the cookie value, and then use String.split( ) to reconstruct the array after reading the cookie data. The format is as follows:
document.cookie = "name=value [; expires=timeInGMT] [; path=pathName] [; domain=domainName] [; secure]";
No matter how many optional subproperties you set per cookie, only the name/value pair may be retrieved. All cookie data written to the cookie property is maintained in the browser's memory until the browser quits. If an expiration date has been made part of the cookie data and that time has not yet expired, the cookie data is saved to the actual cookie file; otherwise, the cookie data is discarded. The browser automatically deletes cookie data that has expired when the browser next starts.

Example

var exp = new Date( ); var nowPlusOneWeek = exp.getTime( ) + (7 * 24 * 60 * 60 * 1000); exp.setTime(nowPlusOneWeek); document.cookie = "userName=visitor; expires=" + exp.toGMTString( );

Value

Cookie data as string. See description.

Default

None.

defaultCharset NN n/a IE 4 DOM n/a
Read-only
Indicates the character encoding of the content of the document.

Example

var cset = document.defaultCharset;

Value

Case-insensitive alias from the character set registry (ftp://ftp.isi.edu/in-notes/iana/assignments/character-sets).

Default

Determined by browser.

defaultView NN 6 IE n/a DOM 2
Read-only
Returns a reference to the W3C DOM abstract representation of a "viewer" that renders the document (the formal name for the object is AbstractView). In Netscape 6, this object equates to the window or frame object that contains the document. A script function that has access to a document object (such as via the element object's ownerDocument property) can obtain a valid reference to the document's window via this defaultView property. The document's view includes knowledge about cascaded style rules applied to each element. See Chapter 4 for an example of obtaining the effective style of an element with the help of the document.defaultView property and the getComputedStyle( ) method.
This is as close as the W3C DOM Level 2 comes to acknowledging the existence of a window object. More is to come in Level 3.

Example
var theWin = elemRef.ownerDocument.defaultView;
Value

Reference to a window object.

Default

The document's window.

doctype NN 6 IE 5(Mac) DOM 1
Read-only
Returns a reference to the DOCTYPE element object (the same as the W3C DOM abstract DocumentType node object). The property returns a reference value only if the DOCTYPE is specified in the document; otherwise the property returns null. As of Version 6, IE for Windows does not implement this property or node type. See the DocumentType object for properties available in various browsers. In a pure W3C DOM environment, the doctype property is inherited from the core document object, and is thus available to XML documents, as well.

Example

var docsType = document.doctype;

Value

Node reference.

Default

None.

documentElement NN 6 IE 5 DOM 1
Read-only
Returns a reference to the root element node of the document. For HTML documents, the reference is to the html element that encompasses the document's head and body elements. In a pure W3C DOM environment, the documentElement property is inherited from the core document object, and is thus available to XML documents, as well.

Example

var rootElem = document.documentElement;

Value

Element node reference.

Default

The current html element object.

domain NN 3 IE 4 DOM 1
Read/Write
Provides the hostname of the server that served up the document. If documents from different servers on the same domain must exchange content with each other, the domain properties of both documents must be set to the same domain to avoid security restrictions. Normally, if the hosts don't match, browser security disallows access to the other document's form data. This property allows, for example, a page from the www server to communicate with a page served up by a secure server.

Example

document.domain = "megaCorp.com";

Value

String of the domain name that two documents have in common (exclusive of the server name).

Default

None.

embeds[ ] NN 3 IE 4 DOM n/a
Returns an array of all embedded objects (embed elements) in the current document. Items in this array are indexed (zero-based) in source code order.

Example

var embedCount = document.embeds.length;

Value

Array of embed object references.

Default

Array of zero length.

expando NN n/a IE 4 DOM n/a
Read/Write
Specifies whether scripts in the current document allow the creation and use of custom properties assigned to the document object. The extensible nature of JavaScript allows scripters to create a new object property by just assigning a value to it (as in document.stooge = "Curly"). This also means the document accepts incorrectly spelled property assignments, such as forgetting to set a middle letter of a long property name to uppercase (marginLeftColor). Such assignments are accepted without question, but the desired result is nowhere to be seen. If you don't intend to create custom properties, consider setting document.expando to false in an opening script statement as you author a page. This could help prevent spelling errors from causing bugs. The setting affects only scripts in the current document.

Example

document.expando = false;

Value

Boolean value: true | false.

Default

true

fgColor NN 2 IE 3 DOM n/a
Read/Write
Provides the foreground (text) color for the document. While you can change this property in all versions of Navigator, the text does not change dynamically in versions prior to 6. Still supported in current browsers, this property is replaced in IE 4 and Netscape 6 by document.body.text or style sheet settings.

Example

document.fgColor = "darkred";

Value

A hexadecimal triplet or plain-language color name. See Appendix A for acceptable plain-language color names.

Default

Browser default (usually black).

fileCreatedDate NN n/a IE 4(Win) DOM n/a
Read-only
Returns a string of the date (but not the time) that the server (or local filesystem) reports the currently-loaded file was created. IE 4's value is a long date format, but starting with IE 5, the date information is formatted as mm/dd/yyyy. The value may be corrupted if the server supplies the data in a format that IE does not expect. Not implemented in IE Mac through Version 5.1.

Example

var dateObj = new Date(document.fileCreatedDate);

Value

Date string.

Default

None.

fileModifiedDate NN n/a IE 4(Win) DOM n/a
Read-only
Returns a string of the date (but not the time) that the server (or local file system) reports the currently-loaded file was most recently modified. IE 4's value is a long date format, but starting with IE 5, the date information is formatted as mm/dd/yyyy. The value may be corrupted or incorrect if the server supplies the data in a format that IE does not expect. Not implemented in IE Mac through Version 5.1.

Example

var dateObj = new Date(document.fileModifiedDate);

Value

Date string.

Default

None.

fileSize NN n/a IE 4 DOM n/a
Read-only
Returns the number of bytes for the size of the currently-loaded document. IE for Windows returns this value as a string, while IE for Macintosh returns a number value (an important distinction if you need to perform math operations on the value).

Example

var byteCount = parseInt(document.fileSize, 10);

Value

Integer as string (Windows) or number (Mac).

Default

None.

fileUpdatedDate NN n/a IE 5.5(Win) DOM n/a
Read-only
Returns an empty string. Apparently not officially supported for the document object.

forms[ ] NN 2 IE 3 DOM 1
Read-only
Returns an array of all form objects (form elements) in the current document. Items in this array are indexed (zero-based) in source code order, but may also be accessed by using the form's name as a string index value.

Example

var elemCount = document.forms[0].elements.length;

Value

Array of form objects.

Default

Array of zero length.

frames[ ] NN n/a IE 4 DOM n/a
Read-only
Returns an array of all iframe objects (iframe element objects, not to be confused with window-like frame objects) in the current document. Items in this array are indexed (zero-based) in source code order. For cross-compatibility with IE 5 and later and Netscape 6, use document.getElementsByTagName("iframe") instead.

Example

var iframeCount = document.frames.length;

Value

Array of iframe objects.

Default

Array of zero length.

height, width NN 4 IE n/a DOM n/a
Read-only
Return the pixel dimensions of the entire rendered document. These values coincide with the offsetHeight and offsetWidth property values for the document.body object. Since neither property pairing is yet sanctioned by the W3C DOM, you might prefer the offset pair, because they are at least cross-browser compatible.

Example

var howTall = document.height;

Value

Number of pixels.

Default

Current document size.

ids[ ] NN |4| IE n/a DOM n/a
Read-only
Used with the Navigator 4-only JavaScript syntax of style sheets, the ids[] collection is part of a reference to a single ID and the style property assigned to it in the syntax form [document.]ids.idName.stylePropertyName. For a list of related properties, see the tags object listing in this chapter.

images[ ] NN 2 IE 3 DOM 1
Read-only
Returns an array of all img element objects (exclusive of pre-cached images loaded via the new Image( ) constructor) in the current document. Items in this array are indexed (zero-based) in source code order, and may be accessed by number or by string name. The presence of this property indicates support for live, swappable images.

Example

document.images["home"].src = "images/homeHilite.jpg";

Value

Array of img objects.

Default

Array of zero length.

implementation NN 6 IE 5(Mac)/6(Win) DOM 1
Read-only
Returns a reference to the W3C DOMImplementation object, which represents, to a limited degree, the environment that makes up the document container—the browser, for our purposes. Methods of the object let you see which DOM modules the browser reports supporting. This object is also a gateway to creating virtual W3C Document and DocumentType objects outside of the current document tree. Thus, in Netscape 6 you can use the document.implementation property as a start to generating a nonrendered document for external XML documents. See the DOMImplementation object for details about the methods and their browser support.

Example

var xDoc = document.implementation.createDocument("", "theXdoc", null);

Value

Reference to a DOMImplementation object.

Default

Current DOMImplementation object.

lastModified NN 2 IE 3 DOM n/a
Read-only
Provides the date and time (as a string) on which the server says the document file was last modified. Some servers don't supply this information at all or correctly. Non-Windows browsers also tend to have a rough time interpreting the information correctly. Only in recent browsers is the date string in a form suitable as a parameter for a Date object constructor.

Example

document.write(document.lastModified);

Value

String representation of a date and time.

Default

None.

layers[ ] NN |4| IE n/a DOM n/a
Read-only
Returns an array of all Navigator 4-only layer element objects in the current document. Also included in the array are references to other HTML elements with style sheets that set the element to be relative- or absolute-positioned (in which case, Navigator 4 treats those elements as layer objects). Items in this array are indexed (zero-based) in source code order, and may be accessed by number or by string name. As a dead-end feature implemented only in Navigator 4, the presence of this property indicates support for the unique referencing requirements for Netscape layers.

Example

if (document.layers) { // use document.layers[] syntax for references }

Value

Array of layer objects or their equivalent.

Default

Array of zero length.

linkColor NN 2 IE 3 DOM n/a
Read/Write
Indicates the color of a hypertext link that has not been visited (that is, the URL of the link is not in the browser's cache). This is one of three states for a link: unvisited, active, and visited. The color is applied to the link text or border around an image or object embedded within an a element. Changes to this property do not dynamically change the link color in Navigator 4 or earlier. Starting with IE 4 and Netscape 6, you should switch to using the W3C DOM alternative, document.body.link, or style sheets.

Example

document.link Color= "#00FF00";

Value

A hexadecimal triplet or plain-language color name. See Appendix A for acceptable plain-language color names.

Default

#0000FF

location NN <6 IE 3 DOM n/a
Read/Write
Indicates the URL of the current document. This property was deprecated because it may conflict with the window.location property. Netscape 6 drops support for this property entirely. Use either the document.URL property, or, better, the window.location.href property.

Example

document.location = "products/widget33.html";

Value

A full or relative URL as a string.

Default

Document URL.

media NN n/a IE 5.5(Win) DOM n/a
Read/Write
Returns a string indicating the output medium for which the content is formatted. The property returns an empty string as of IE 6, and throws a security error if you assign accepted string values (all, print, or screen) to it. Avoid using this property with the document object.

mimeType NN n/a IE 5(Win) DOM n/a
Read-only
Returns a string indicating the basic document type, but not in a MIME format. For an HTML document, the string returned changed starting with IE 5.5 to HTML Document. Do not confuse this document object property with the Netscape and IE/Mac navigator.mimeTypes property, which is an entirely different animal.

Example

var what = document.mimeType;

Value

String.

Default

"HTML Document"

nameProp NN n/a IE 6(Win) DOM n/a
Read-only
Returns a string containing the same data as document.title, including an empty string if no title element exists in the document. This property may not be officially supported for the document object.

Value

String.

Default

Empty string.

namespaces[ ] NN n/a IE 5.5(Win) DOM n/a
Read-only
Returns a collection of IE namespace objects implemented in the current document. A namespace object is a gateway to loading external behaviors. For more details, visit http://msdn.microsoft.com/workshop/author/behaviors/overview/elementb_ovw.asp.

Example
var IENSCount = document.namespaces.length;
Value

Array of namespace object references.

Default

Array of zero length.

parentWindow NN n/a IE 4 DOM n/a
Read-only
Returns a reference to the window object (which may be a frame in a frameset) that contains the current document. Use this reference to access the window's properties and methods directly. The returned value is the same as the window reference from the document.

Example

var siblingCount = document.parentWindow.frames.length;

Value

window or frame object reference.

Default

window object.

plugins[ ] NN 4 IE 4 DOM n/a
Read-only
Returns an array of all embedded objects (embed elements) in the current document. Items in this array are indexed (zero-based) in source code order. Do not confuse this collection with the navigator.plugins collection in Netscape Navigator.

Example

var embedCount = document.plugins.length;

Value

Array of embed object references.

Default

Array of zero length.

protocol NN n/a IE 4 DOM n/a
Read-only
Returns a plain-language string describing the protocol used to load the current document. Unlike the location.protocol property's literal value (e.g., http: or file:), the document.protocol is human-readable (e.g., Hypertext Transfer Protocol or File Protocol).

Example

if (document.protocol == "File Protocol") { // process for file access in IE }

Value

Plain-language string.

Default

Current document's protocol type.

readyState NN n/a IE 4 DOM n/a
Read-only
Returns the current download status of the document content. If a script (especially one initiated by a user event) can perform some actions while the document is still loading, but must avoid other actions until the entire page has loaded, this property provides intermediate information about the loading process. You would use its value in condition tests. The value of this property changes during loading as the loading state changes. Each change of the property value fires an onreadystatechange event.

Example

if (document.readyState == "loading") { // statements for alternate handling }

Value

One of the following values (as strings): complete | interactive | loading | uninitialized. Some elements may allow the user to interact with partial content, in which case the property may return interactive until all loading has completed.

Default

None.

referrer NN 2 IE 3 DOM 1
Read-only
Returns a string of the URL of the page from which the current page was accessed, provided the original page had a link to the current page. Many server logs capture this information as well. Scripts can see whether the visitor reached the current document from specific origins and perhaps present slightly different content on the page accordingly. If the visitor arrived by another method, such as typing the document URL into a browser dialog or by selecting a bookmark, the referrer property returns an empty string. Many versions of IE for Windows fail to report the correct referrer URL, often showing the URL of the current page instead.

Example

if (document.referrer) { document.write("Thanks for following the link to our web site."); }

Value

String.

Default

None.

scripts[ ] NN n/a IE 4 DOM n/a
Read-only
Returns an array of all script objects (script elements) in the current document. Each script object may contain any number of functions. The scripts[] collection counts the number of actual <script> tags in the document. Items in this array are indexed (zero-based) in source code order.

Example

var scriptCount = document.scripts.length;

Value

Array of script element references.

Default

Array of zero length.

security NN n/a IE 5.5(Win) DOM n/a
Read-only
Returns a string describing the security policy in force for the current document.

Example

var secPolicy = document.security;

Value

String.

Default

"This type of document does not have a security certificate."

selection NN n/a IE 4 DOM n/a
Read-only
Returns a selection object. To work with text that has been selected by the user or script, you must convert the selection to a TextRange object. This is possible only in Internet Explorer for Win32. Access to the Netscape 6 selection is via the window.selection property.

Example

var range = document.selection.createRange( );

Value

Object reference.

Default

None.

styleSheets[ ] NN 6 IE 4 DOM 2
Read-only
Returns an array of all styleSheet objects in the current document. Each style object may contain any number of style sheet rules. The styleSheets[] collection counts the number of actual <style> tags in the document as well as <link> tags that load external style sheet files. Items in this array are indexed (zero-based) in source code order. An @import style sheet object is accessible via a styleSheet object's cssRule.styleSheet property. See the styleSheet object.

Example

for (var i = 0; i < document.styleSheets.length; i++) { // loop through each styleSheet object }

Value

Array of styleSheet object references.

Default

Array of zero length.

tags[ ] NN |4| IE n/a DOM n/a
Read-only
Used with the Navigator 4-only JavaScript syntax of style sheets, the tags[] collection is part of a reference to a single tag type and the style property assigned to it. For a list of properties, see the tags object listing in this chapter. Do not confuse this Navigator use of the tags[] collection with Internet Explorer's use of the tags[] collection that belongs to the all collection.

Example

document.tags.H1.color= "red";

Value

Array of Navigator 4 JavaScript Style Sheet tag object references.

Default

Array of zero length.

title NN 2 IE 3 DOM 1
Read/Write
Unlike the title property for objects that reflect HTML elements, the document.title property refers to the content of the title element defined in the head portion of a document. The title content appears in the browser's titlebar to help identify the document. This is also the content that goes into a bookmark listing for the page. Although the property is read/write, don't be surprised if a browser version does not alter the window titlebar in response.

Example

document.title = "Fred\'s Home Page";

Value

String.

Default

None.

URL NN 3 IE 4 DOM 1
Read/Write
Provides the URL of the current document. The value is the same as location.href. The document.URL property evolved as a replacement for document.location to avoid potential confusion (by scripters and JavaScript interpreter engines) between the location object and document.location property. To navigate to another page, it is safest (for cross-browser and backward compatibility) to assign a URL string value to the location.href property, rather than this document-centered property.

Example

document.URL = "http://www.megacorp.com";

Value

Complete or relative URL as a string.

Default

The current document's URL.

URLUnencoded NN n/a IE 5.5(Win) DOM n/a
Read-only
Returns the URL of the current document, but with any URL-encoded characters returned to their plain-language version (e.g., %20 is converted to a space character). The returned value is the same as if applying the JavaScript decodeURI( ) function to document.URL.

Example

var straightPath = document.URLUnencoded;

Value

Complete or relative URL as a string.

Default

The current document's URL.

vlinkColor NN 2 IE 3 DOM n/a
Read/Write (IE)
Color of a hypertext link that has been visited recently. The color is applied to the link text or border around an image or object embedded within an a element. See also alinkColor and linkColor properties for clicked and unvisited link colors. Changes to this property do not dynamically change the link color in Navigator 4 or earlier. Starting with IE 4 and Netscape 6, you should switch to using the W3C DOM alternative, document.body.vLink, or style sheets.

Example

document.vlinkColor = "gold";

Value

A hexadecimal triplet or plain-language color name. See Appendix A for acceptable plain-language color names.

Default

#551a8b (Navigator); #800080 (Internet Explorer Windows); #006010 (Internet Explorer Macintosh).

getAnonymousElementByAttribute( )

See height.

addBinding( ), getAnonymousElementByAttribute( ), getAnonymousNodes( ), getBindingParent( ), loadBindingDocument( ), removeBinding( ) NN 6 IE n/a DOM n/a
This series of Netscape 6 document object methods are part of a browser programming feature called Extensible Binding Language (XBL), an adjunct to the XML-based mechanism that the browser uses for generating user interface skins. To learn more about XBL, visit http://www.mozilla.org/docs/xul/xulnotes/xulnote_xbl.html.

captureEvents( ) NN 4 IE n/a DOM n/a
captureEvents(eventTypeList)
Instructs the browser to grab events of a specific type before they reach their intended target objects. The object invoking this method must then have event handlers defined for the given event types to process the event. Although this method is part of the Navigator 4 event model, it continues to be supported in Netscape 6, creating the equivalent of a W3C DOM capture-mode event listener for the document object. Continue to use this method if you must support Navigator 4, but migrate new code to the W3C DOM event listener syntax as described in Chapter 6.

Returned Value

None.

Parameters

eventTypeList

A comma-separated list of case-sensitive event types as derived from the available static Event object constants, such as Event.CLICK or Event.MOUSEMOVE.

clear( ) NN 2 IE 3 DOM n/a
Removes the current document from the window or frame, usually in preparation to open a new stream for writing new content. The document.write( ) and document.writeln( ) methods automatically invoke this method. Many bugs with the document.clear( ) method plagued earlier browser versions. Even today, it is best to let the document writing methods handle the job for you. The W3C DOM explicitly omits this method.

Returned Value

None.

Parameters

None.

close( ) NN 2 IE 3 DOM 1
Closes the document writing stream to a window or frame. If a script uses document.write( ) or document.writeln( ) to generate all-new content for a window or frame, you must append a document.close( ) method to make sure the entire content is written to the document. Omitting this method may cause some content not to be written. This method also prepares the window or frame for a brand new set of content with the next document writing method. Do not, however, use document.close( ) if you use the document writing methods to dynamically write content to a page while loading from the server.

Returned Value

None.

Parameters

None.

createAttribute( ) NN 6 IE 5(Mac)/6(Win) DOM 1
createAttribute("attributeName")
Generates in memory an instance of an attribute node (Attr object). A typical sequence is to create the attribute, assign a value to it via its nodeValue property, and then insert the Attr node into an element's attribute list via the element's setAttributeNode( ) method.

Returned Value

Attr node object reference.

Parameters

attributeName

A case-sensitive string of the attribute's name.

createAttributeNS( ) NN 6 IE n/a DOM 2
createAttributeNS("namespaceURI", "qualifiedName")
Generates in memory an instance of an attribute node (Attr object) whose name is defined in an external namespace. A typical sequence is to create the attribute, assign a value to it via its nodeValue property, and then insert the Attr node into an element's attribute list via the element's setAttributeNodeNS( ) method.

Returned Value

Attr node object reference.

Parameters

namespaceURI

URI string that will match a URI assigned to a label earlier in the document into which the attribute is eventually added.

qualifiedName

The full name for the attribute, consisting of the local name prefix (if any), a colon, and the local name.

createCDATASection( ) NN 6 IE 5(Mac) DOM 1
createCDATASection("data")
Generates in memory an instance of a character data section node (CDATASection object) in an XML (including XHTML) document. Not fully implemented as of Netscape 7.

Returned Value

CDATASection node object reference.

Parameters

data

String data that comprises the content of the section.

createComment( ) NN 6 IE 5(Mac)/6(Win) DOM 1
createComment("commentText")
Generates in memory an instance of a comment node (Comment object with a nodeValue of 8). A typical sequence is to create the Comment node, then insert it into the desired location of the document tree via any node's appendChild( ) or insertBefore( ) method. Only partially implemented in IE 5/Mac.

Returned Value

Comment node object reference.

Parameters

commentText

String containing the comment data.

createDocumentFragment( ) NN 6 IE 5(Mac)/6(Win) DOM 1
Generates in memory an instance of an empty document fragment node (DocumentFragment object). This node becomes an arbitrary holder for assembling a sequence of nodes that ultimately get appended or inserted into a document tree. See the DocumentFragment object for more details.

Returned Value

DocumentFragment node object reference.

Parameters

None.

createElement( ) NN 6 IE 4 DOM 1
createElement("tagName")
Generates in memory an instance of an element object associated with the tag passed as a parameter to the method. The method is limited to area, img, and option elements in IE 4; all elements are permitted in other supporting browsers. A newly created element has no attribute values assigned (except any default values assigned according to the DTD), nor is the element yet part of the document tree. Assign attributes (such as the type for an input element or id for any element), and append or insert the element into the document tree. This sequence is the W3C DOM approach to generating new content (in place of the innerHTML convenience properties implemented in IE and Netscape 6 browsers).

Returned Value

Element object reference.

Parameters

tagName

A string of the tag name of the new element: document.createElement("option"). IE also allows a complete start tag string, complete with angle brackets and attribute name/value pairs. Only the straight tag name is supported by the W3C DOM specification.

createElementNS( ) NN 6 IE n/a DOM 2
createElementNS("namespaceURI", "qualifiedName")
Generates in memory an instance of an element object associated with namespace, label, and tag passed as parts of the method's parameters. A newly created element has no attribute values assigned (except any default values assigned according to the DTD), nor is the element yet part of the document tree. Assign attributes (such as the type for an input element or id for any element), and append or insert the element into the document tree.

Returned Value

Element object reference.

Parameters

namespaceURI

URI string that will match a URI assigned to a label earlier in the document into which the attribute is eventually added.

qualifiedName

The full name for the attribute, consisting of the local name prefix (if any), a colon, and the local name.

createEntityReference( ) NN 6 IE 5(Mac) DOM 1
createEntityReference("entityName")
Generates in memory an instance of an entity reference node object in an XML document. Only partial support provided in IE 5/Mac and Netscape as of Version 7.

Returned Value

Entity reference node object reference.

Parameters

entityName

String value.

createEvent( ) NN 6 IE n/a DOM 2
createEvent("eventType")
Generates in memory an instance of a W3C DOM Event object of a particular event category. After the generic event is created, it must be initialized (via one of several initialization methods) as a particular event type, along with other properties appropriate for the event category. The following sequence creates a mousedown event and sends it to an element:
var evt = document.createEvent("MouseEvents"); evt.initEvent("mousedown", true, true); document.getElementById("myElement").dispatchEvent(evt);
Such an event might then be handed to an element (via the element's dispatchEvent( ) method) so that the element's event listener can process the event as if it had been generated by a user clicking the mouse button.

Returned Value

Event object object reference.

Parameters

eventType

String constant for one of the support event categories: HTMLEvents, KeyEvents (supported by Netscape 6, but not specified until DOM Level 3), MouseEvents, MutationEvents, or UIEvents.

createEventObject( ) NN n/a IE 5.5(Win) DOM n/a
createEventObject([existingEventObject])
Generates in memory an instance of an empty IE DOM event object. After the generic event is created, its properties can be stuffed with pertinent values to help the event be processed. Then the event acts as a parameter to an element's fireEvent( ) method, at which point the event type is associated with the event. The following sequence creates a mousedown event and sends it to an element:
var evt = document.createEventObject( ); document.getElementById("myElement").fireEvent("onmousedown", evt);
You can also use an existing event object as a model for a script-generated event. Pass the current event object as a parameter to the createEventObject( ) method, and modify the properties of the new object as you see fit.

Returned Value

event object reference.

Parameters

existingEventObject

Reference to an event object either generated by the user or script. The new event assumes all properties of the existing event object.

createNodeIterator( ) NN n/a IE n/a DOM 2
createNodeIterator(rootNode, whatToShow, filterFunction, entityRefExpansion)
Generates in memory an instance of a NodeIterator object. This method has the same set of parameters as the createTreeWalker( ) method, which is implemented in Netscape 7.

Returned Value

NodeIterator object reference.

Parameters

rootNode

Reference to a node in the document tree that becomes the first node in the NodeIterator object's list of nodes.

whatToShow

Integer value corresponding to one of several built-in filters that allow nodes of a single type to be included in the NodeIterator object returned by the method. The NodeFilter object contains constants that should be used as plain-language substitutes for this value:

NodeFilter.SHOW_ALL

NodeFilter.SHOW_ATTRIBUTE

NodeFilter.SHOW_CDATA_SECTION

NodeFilter.SHOW_COMMENT

NodeFilter.SHOW_DOCUMENT

NodeFilter.SHOW_DOCUMENT_FRAGMENT

NodeFilter.SHOW_DOCUMENT_TYPE

NodeFilter.SHOW_ELEMENT

NodeFilter.SHOW_ENTITY

NodeFilter.SHOW_ENTITY_REFERENCE

NodeFilter.SHOW_NOTATION

NodeFilter.SHOW_PROCESSING_INSTRUCTION

NodeFilter.SHOW_TEXT

filterFunction

Reference to a user function that can further filter nodes that are included in the NodeIterator object. The function has a single parameter (a reference to a node to test, invoked automatically by the NodeIterator object). The value returned by the function determines whether the node being tested is to be included in the list of nodes. Returned values are integers, but the NodeFilter object provides three constants you should use as plain-language substitutes:

NodeFilter.FILTER_ACCEPT

NodeFilter.FILTER_REJECT

NodeFilter.FILTER_SKIP

Because a NodeIterator object does not maintain its list of nodes as a hierarchy, the values NodeFilter.FILTER_REJECT and NodeFilter.FILTER_SKIP pass over a node without any effect on child nodes. See the TreeWalker object for an example of this kind of function.

entityRefExpansion

Boolean value that controls whether the content of entity reference nodes (found predominantly in XML documents) should be treated as hierarchical nodes (true) or not (false).

createProcessingInstruction( ) NN 6 IE 5(Mac) DOM 1
createProcessingInstruction("target", "data")
Generates in memory an instance of a processing instruction node object in an XML document. Only partial support provided in IE 5/Mac and Netscape as of Version 7.

Returned Value

Processing instruction node object reference.

Parameters

target

String value.

data

String value.

createRange( ) NN 6 IE n/a DOM 2
Creates a blank Range object, whose boundary points are collapsed to the point before the first character of the rendered body text. The method returns a reference to that Range object, which you then use to adjust its boundary points, invoke its methods, and so on. See the Range object for details of its language features.

Returned Value

W3C DOM Range object reference.

Parameters

None.

createStyleSheet( ) NN n/a IE 4 DOM n/a
createStyleSheet(["url"[, index]])
This method performs the same actions in IE for Windows and Macintosh, but their returned values differ. Moreover, the specific actions in the document tree depend upon the parameters passed with the method. When no parameters are included, the method inserts a blank style element into the document tree. This style element, however, is not reflected in the document.styleSheets collection until you add one or more style rules to the object. But if you specify a URL to an external .css file as the first parameter, the method creates and inserts a link element into the document's head section, bringing the external style rules to life immediately.
IE for Windows always returns a reference to a styleSheet object; IE for Macintosh returns a reference to the newly inserted element, which will be a style or link element, depending on the parameter makeup. The inserted style element reference is of little help for adding a rule because you can't reference the styleSheet object. For cross-operating-system compatibility, it's best to use this method only for external style sheets.

Returned Value

styleSheet object reference (Windows); style or link element object reference (IE 5 and later for Macintosh).

Parameters

url

A string of the URL of an external .css style sheet definition file.

index

Optional zero-based integer that indicates where among the styleSheets[] collection this new style sheet should be inserted. Default behavior is to append to the end of the collection, but this may affect cascading rules for your document. See Chapter 3.

createTextNode( ) NN 6 IE 5 DOM 1
createTextNode("text")
Generates in memory an instance of a text node (W3C DOM Text object) whose nodeValue consists of the untagged text content passed as a parameter. A newly created text node is not yet part of the document tree. Append or insert the node into the document tree or document fragment being assembled for later document insertion. This sequence is the W3C DOM approach to generating new content (in place of the innerText convenience property implemented in IE browsers).

Returned Value

Text node object reference.

Parameters

text

A string of characters to be rendered as content when inserted into the document tree.

createTreeWalker( ) NN 7 IE n/a DOM 2
createTreeWalker(rootNode, whatToShow, filterFunction, entityRefExpansion)
Generates in memory an instance of a TreeWalker object.

Returned Value

TreeWalker object reference.

Parameters

rootNode

Reference to a node in the document tree that becomes the first node in the TreeWalker object's list of nodes.

whatToShow

Integer value corresponding to one of several built-in filters that allow nodes of a single type to be included in the TreeWalker object returned by the method. The NodeFilter object contains constants that should be used as plain-language substitutes for this value:

NodeFilter.SHOW_ALL

NodeFilter.SHOW_ATTRIBUTE

NodeFilter.SHOW_CDATA_SECTION

NodeFilter.SHOW_COMMENT

NodeFilter.SHOW_DOCUMENT

NodeFilter.SHOW_DOCUMENT_FRAGMENT

NodeFilter.SHOW_DOCUMENT_TYPE

NodeFilter.SHOW_ELEMENT

NodeFilter.SHOW_ENTITY

NodeFilter.SHOW_ENTITY_REFERENCE

NodeFilter.SHOW_NOTATION

NodeFilter.SHOW_PROCESSING_INSTRUCTION

NodeFilter.SHOW_TEXT

filterFunction

Reference to a user function that can further filter nodes that are included in the TreeWalker object. The function has a single parameter (a reference to a node to test, invoked automatically by the TreeWalker object). The value returned by the function determines whether the node being tested is to be included in the list of nodes. Returned values are integers, but the NodeFilter object provides three constants you should use as plain-language substitutes:

NodeFilter.FILTER_ACCEPT

NodeFilter.FILTER_REJECT

NodeFilter.FILTER_SKIP

With a return value of NodeFilter.FILTER_SKIP, descendant nodes of the skipped node may still qualify as members of the TreeWalker node list (provided they survive other filtering). A return value of NodeFilter.FILTER_REJECT removes both the node under test and its descendants from consideration as members of the TreeWalker object. See the TreeWalker object for an example of this kind of function.

entityRefExpansion

Boolean value that controls whether the content of entity reference nodes (found predominantly in XML documents) should be treated as hierarchical nodes (true) or not (false).

elementFromPoint( ) NN n/a IE 4 DOM n/a
elementFromPoint(x, y)
Returns a reference to the object directly underneath the pixel coordinates specified by the x (horizontal) and y (vertical) parameters. For an element to be recognized, it must be capable of responding to mouse events. Also, if more than one element is positioned in the same location, the element with the highest zIndex value or, given equal zIndex values, the element that comes last in the source code order is the one returned.

Returned Value

Element object reference.

Parameters

x

Horizontal pixel measure relative to the left edge of the window or frame.

y

Vertical pixel measure relative to the top edge of the window or frame.

execCommand( ) NN n/a IE 4(Win) DOM n/a
execCommand("commandName"[, UIFlag[, value]])
Available only in the Win32 platforms for IE, the execCommand( ) method executes the named command. Most commands require that a TextRange object be created first for an insertion point. See Appendix D for a list of commands.

Returned Value

Boolean value: true if command was successful; false if unsuccessful.

Parameters

commandName

A case-insensitive string value of the command name. See Appendix D.

UIFlag

Optional Boolean value: true to display any user interface triggered by the command (if any); false to prevent such display.

value

A parameter value for the command.

getAnonymousElementByAttribute( )

See addBinding( ).

getAnonymousNodes
See addBinding( ).

getBindingParent
See addBinding( ).

getElementById( ) NN 6 IE 5 DOM 1
getElementById("elementID")
Returns a reference to an element node from the document tree whose id attribute value matches the parameter value. If there is no match, the method returns null. This method, although a chore to type while observing its case-sensitive name, is the gateway for scripts in W3C DOM-capable browsers to communicate with element objects.

Returned Value

Reference to element node object.

Parameters

elementID

String of the desired element's ID.

getElementsByName( ) NN 6 IE 5 DOM 1
getElementsByName("elementName")
Returns an array of references to all element nodes from the document tree whose name attribute value matches the parameter value. If there is no match, the method returns null. When an element supports both the name and id attribute, IE for Windows includes an element in the returned array even if only the id attribute is set to the parameter value. IE for Macintosh and Netscape 6 match only elements that have name attributes explicitly set to the parameter value.

Returned Value

Array of references to element node object.

Parameters

elementName

String of the desired element's name.

getSelection( ) NN 4 IE n/a DOM n/a
In Navigator 4, this method captures the current text selection in the document. The method is deprecated in Netscape 6 in favor of the window.getSelection( ) method (which returns a sophisticated selection object, rather than just text). Invoking from the document object displays a warning in the JavaScript Console window, but does not throw a full-fledged exception. The IE equivalent is reading the selection property.

Returned Value

String.

Parameters

None.

handleEvent( ) NN |4| IE n/a DOM n/a
handleEvent(event)
Instructs the document object to accept and process the Navigator 4-only event whose specifications are passed as the parameter to the method. The object must have an event handler for the event type to process the event.

Returned Value

None.

Parameters

event

A Navigator 4 event object.

hasFocus( ) NN n/a IE 6 DOM n/a
Returns Boolean true if the document or any element in the document has focus. A background process, such as a function invoked through setTimeout( ) can find out if the document's window is currently the front window on the Desktop.

Returned Value

Boolean value: true | false.

Parameters

None.

importNode( ) NN 6 IE n/a DOM 2
importNode(nodeReference, deepBoolean)
Imports a node object from another loaded document into the current document, but not yet into the document tree. In many ways, importNode( ) works like cloneNode( ), but it assumes that the source node may exist in an entirely different document tree context (especially in an XML document). W3C DOM rules for this method govern what properties and attributes of the source node make the journey and what happens to them upon their arrival. For example, an Attr node loses its ownerElement (i.e., its value becomes null) when imported from an element in one document into a fragment-like state in the new document—until the attribute gets added to an element in the new document. Nodes of Document and DocumentType types are not importable.
The importNode( ) method does not assume the responsibility of persistence between documents. That's where, for instance, a JavaScript variable comes into play. As with cloneNode( ), the importNode( ) method does not disturb the source node.

Returned Value

Reference to the imported copy of the node object.

Parameters

nodeReference

Reference to a node in a different loaded document (including a nonrendered document loaded into the browser by way of the document.implementation.createDocument( ) method).

deepBoolean

Boolean value that controls whether the copy includes all nested nodes (true) or only the current node (false). Required, but applicable primarily to element nodes.

loadBindingDocument
See addBinding( ).

open( ) NN 2 IE 3 DOM 1
open(["MIMEType"][, "replace"])
Opens the output stream for writing to the current window or frame. If document.clear( ) has not already been invoked, it is automatically invoked in response to the document.open( ) method. Early version bugs may lead you to use document.write( ) and document.writeln( ) to take care of this method more reliably for you.

Returned Value

None.

Parameters

MIMEType

Advises the browser of the MIME type of the data to be written in subsequent statements. Navigator supports "text/html" | "text/plain" | "image/gif" | "image/jpeg" | "image/xbm" | "plugIn". Only "text/html" is supported in Internet Explorer.

replace

The presence of this parameter directs the browser to replace the entry in the history list for the current document with the document about to be written.

queryCommandEnabled( ) NN n/a IE 4(Win) DOM n/a
queryCommandEnabled("commandName")
Specifies whether the command can be invoked in light of the current state of the document or selection. Available only in the Win32 platform for IE 4.

Returned Value

Boolean value: true if enabled; false if not.

Parameters

commandName

A case-insensitive string value of the command name. See Appendix D.

queryCommandIndeterm( ) NN n/a IE 4(Win) DOM n/a
queryCommandIndeterm("commandName")
Specifies whether the command is in an indeterminate state. Available only in the Win32 platform for IE 4.

Returned Value

Boolean value: true | false.

Parameters

commandName

A case-insensitive string value of the command name. See Appendix D.

queryCommandState( ) NN n/a IE 4(Win) DOM n/a
queryCommandState("commandName")
Determines the current state of the named command. Available only in the Win32 platform for IE 4.

Returned Value

true if the command has been completed; false if the command has not completed; null if the state cannot be accurately determined.

Parameters

commandName

A case-insensitive string value of the command name. See Appendix D.

queryCommandSupported( ) NN n/a IE 4(Win) DOM n/a
queryCommandSupported("commandName")
Determines whether the named command is supported by the document object. Available only in the Win32 platform for IE 4.

Returned Value

Boolean value: true | false.

Parameters

commandName

A case-insensitive string value of the command name. See Appendix D.

queryCommandText( ) NN n/a IE 4(Win) DOM n/a
queryCommandText("commandName")
Returns text associated with the command. Available only in the Win32 platform for IE 4.

Returned Value

String.

Parameters

commandName

A case-insensitive string value of the command name. See Appendix D.

queryCommandValue( ) NN n/a IE 4(Win) DOM n/a
queryCommandValue("commandName")
Returns the value associated with the command, such as the name font of the selection. Available only in the Win32 platform for IE 4.

Returned Value

Depends on the command.

Parameters

commandName

A case-insensitive string value of the command name. See Appendix D.

recalc( ) NN n/a IE 5(Win) DOM n/a
recalc([allBoolean])
Forces the recalculation of expressions assigned to element attributes via the setExpression( ) method. Needed only when automatic recalculation isn't triggered by user action, but affected values might have changed.

Returned Value

None.

Parameters

allBoolean

When set to true, forces all dynamic attribute expressions in the document to recalculate. The default false lets browser decide which expressions are affected by changes since the last manual or automatic recalculation.

releaseEvents( ) NN 4 IE n/a DOM n/a
releaseEvents(eventTypeList)
The opposite of document.captureEvents( ), this method turns off event capture at the document level for one or more specific events named in the parameter list. In Netscape 6, it performs the same action as the W3C DOM removeEventListener( ) method on the document object. See Chapter 6.

Returned Value

None.

Parameters

eventTypeList

A comma-separated list of case-sensitive event types as derived from the available Event object constants, such as Event.CLICK or Event.MOUSEMOVE.

removeBinding
See addBinding( ).

routeEvent( ) NN 4 IE n/a DOM n/a
routeEvent(event)
Used inside an event handler function, this method directs Navigator 4 to let the event pass to its intended target object. The method does not cause an error in Netscape 6, but it does not perform any action.

Returned Value

None.

Parameters

event

A Navigator 4 event object

write( ), writeln( ) NN 2 IE 3 DOM n/a
write("string1"[, ..."stringN"]) writeln("string1"[, ..."stringN"])
When invoked as the page loads, these methods can dynamically add content to the page. When invoked after the page has loaded, a single method invocation clears the current document, opens a new output stream, and writes the content to the window or frame. A document.close( ) method is required afterward. Because the first document.write( ) or document.writeln( ) method destroys the current document, do not use two or more writing statements to create a new document. Instead, load the content into one variable and pass that variable as the parameter to a single document.write( ) or document.writeln( ) method.
Using document.write( ) for <script> tags is tricky in Navigator because it typically interprets the writing of the end script tag as meaning the end of the script doing the writing. You should have success, however, if you split the end script tag into string sections:
document.write("<" + "/script>");
If you include the "hide script" comment trick, write it this way:
document.write("//--" + ">");
The difference between the two methods is that document.writeln( ) adds a carriage return to the source code it writes to the document. This is not reflected in the rendered content, but can make reading the dynamic source code easier in browser versions that support dynamic content source viewing (Navigator 4 does so as a wysiwyg: URL in the source view window).

Returned Value

None.

Parameters

string

Any string value, including HTML tags.

Document NN 6 IE n/a DOM 1

The document object described earlier is, in the W3C DOM structure, more specifically an HTMLDocument node, a member of the HTML module of the standard. The HTMLDocument node inherits the properties and methods of the Document node (with an uppercase "D" described here, and defined in the W3C DOM Core module. This is the pure, abstract Document node, and all that is needed to contain an unrendered XML document.

Netscape 6 extends this node with a load( ) method that allows scripts to load XML documents into a plain (and unseen) Document node. Such a node is created via the document.implementation.createDocument( ) method. Scripts can then access the XML data in that document through regular W3C DOM document tree properties and methods.

To help reinforce in your mind the heritage of the document object you normally script (that is, the instance of the HTMLDocument node represented in each window's document), I show the lists of properties and methods for the core Document object. For descriptions of all these properties and methods—except for the uninherited Netscape 6-specific load( ) method—see the document object, earlier in this chapter.

Object Model Reference

documentNodeReference

Object-Specific Properties

doctype

documentElement

implementation

Object-Specific Methods

`createAttribute( )`	`createAttributeNS( )`	`createCDATASection( )`
`createComment( )`	`createDocumentFragment( )`	`createElement( )`
`createElementNS( )`	`createEntityReference( )`	`createProcessingInstruction( )`
`createTextNode( )`	`getElementById( )`	`getElementsByTagName( )`
`getElementsByTagNameNS( )`	`importNode( )`	`load( )`

Object-Specific Event Handler Properties

None.

load( ) NN 6 IE n/a DOM n/a
load("URI")
Loads an XML file into the current Document object. Attempting to load other types of files (such as HTML) throws an exception. The server must be configured to send the file as the text/html content type.

Returned Value

None.

Parameters

URI

A string of the URI to an external XML file.

DocumentType NN 6 IE 5(Mac) DOM 1

Reflects the DOCTYPE element, if one arrives to the browser as part of the document flow. The DocumentType object is its own node type in the W3C DOM, and, just as indicated in its position in a document's source code, exists outside of the content portion of the document tree. Access to this object in supported browsers is via the document.doctype property. If no DOCTYPE element exists in the file, the property returns null.

Properties of the DocumentType object expose individual pieces of the data within the DOCTYPE tag, whose structure is determined by SGML standards. The W3C DOM Level 2 specification provides placeholder properties for these pieces, and Netscape 6 implements most of them to one degree or other. But it is clear from the DOM specification that work on aligning the two worlds is not complete.

Object Model Reference

documentTypeNodeReference

Object-Specific Properties

entities

internalSubset

name

notations

publicId

systemId

Object-Specific Methods

None.

Object-Specific Event Handler Properties

None.

entities NN 6 IE n/a DOM 1
Read-only
Returns an array of nested Entity nodes within the DOCTYPE element. An Entity is formatted according to the following syntax (which would appear inside the DOCTYPE element's angle brackets):
[<!ENTITY publicID "systemID">]
Primarily applicable to XML documents.

Value

Array (technically, a NamedNodeMap data type) of Entity node object references.

Default

null

internalSubset NN 6 IE n/a DOM 2
Read-only
Returns a string value of the internal subset portion of the element.

Value

String.

Default

Empty string.

name NN 6 IE 5(Mac) DOM 1
Read-only
Returns a string value of the name portion of the element. The name is the first word that follows the DOCTYPE element's tag name. In the context of this book's subject, all HTML and XHTML documents show this value to be html. Note that although this object and property are implemented in IE 5/Macintosh, that browser returns the entire inner string value of the DOCTYPE element, starting with the html name.

Value

String.

Default

html

notations NN 6 IE n/a DOM 1
Read-only
Returns an array of references to Notation nodes within the DOCTYPE element.

Value

Array (technically, a NamedNodeMap data type) of Notation node object references.

Default

null

publicId NN 6 IE n/a DOM 2
Read-only
Returns a string value of the public identifier portion of the element. This data reveals the type of DTD, as in "-//W3C//DTD XHTML 1.0 Strict//EN".

Value

String.

Default

Empty string.

systemId NN 6 IE n/a DOM 2
Read-only
Returns a string value of the system identifier portion of the element. This data typically reveals the URI of DTD, as in "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd".

Value

String.

Default

Empty string.

DOMException NN 6 IE n/a DOM 1

Some operations on W3C DOM objects can trigger errors, or, in the vernacular of JavaScript 1.5, throw exceptions, if something goes wrong. The W3C DOM defines an object that conveys a code number corresponding to a well-defined (if limited) list of exceptions. For example, if you attempt to append one text node as a child of another text node, the appendChild( ) method of such an operation throws an exception whose code number is 3. This number corresponds to the exception that signals an attempt to perform an illegal or logically impossible action on a DOM hierarchy (a text node can't have any child nodes).

The job of conveying the DOM exception information to a scripter falls to the hosting environment, rather than the DOM. Because JavaScript 1.5 already has an exception handling mechanism, the task of blending the DOMException system with JavaScript exception handling fell first to Netscape, as implemented in Netscape 6. The new mechanism permits different kinds of error objects to circulate through the exception handling operations, thus leaving the original system intact, while extending the mechanism to accommodate not only the W3C DOM DOMException object, but some Netscape-specific errors, as well. Processing of exceptions of all kinds continues to take place in the catch block of a try/catch construction, and all information about the exception is still passed as an object through a single parameter to the catch block.

Netscape's DOM exception object (which embodies the W3C DOMException object) arrives at the catch block with a longer list of properties and methods associated with it than does an exception arising from other causes (e.g., trying to use a JavaScript variable that has not been initialized). The distinguishing property of a DOMException object, missing from the other types, is the code property. Moreover, any code value between 1 and 15 indicates an exception type known to the formal DOM specification through Level 2. Others will certainly be added to the list in the future. Netscape uses code numbers starting with 1000 for its list of browser-specific exceptions.

If you wish to process true W3C DOM exceptions along their own execution path, you can use a construction similar to the following (which allows for the DOMException list to grow to 999 in future iterations):

try {
    // your DOM-related statement goes here
}
catch(e) {
    if (typeof e.code == "number") {
        if (e.code < 1000) {
            // process DOMException object here
        } else {
            // process Netscape DOM exception object here
        }
    } else {
        // process language or other exceptions here
    }
}

Of course, it is highly unlikely that exception details will be of benefit to users, but they are invaluable to you during development. For more on exception handling, see the error object in Chapter 12.

Object Model Reference

errorObjectReference

Object-Specific Properties

code

Object-Specific Methods

None.

Object-Specific Event Handler Properties

None.

code NN 6 IE n/a DOM 1
Read-only
Provides an integer corresponding to one of the defined DOM error types. The following table lists all code values, their constant equivalents, and examples of what kinds of problems throw the exception.

Code

Constant

Most likely cause

1

INDEX_SIZE_ERR

An integer offset parameter is out of the range of the target object

2

DOMSTRING_SIZE_ERR

Property string value is too large for the hosting language

3

HIERARCHY_REQUEST_ERR

Appending a child to a node not capable of children

4

WRONG_DOCUMENT_ERR

Inserting a node created from a different document (without passing through the import process)

5

INVALID_CHARACTER_ERR

Assigning an identifier with an illegal character

6

NO_DATA_ALLOWED_ERR

Assigning data to a node that doesn't allow data

7

NO_MODIFICATION_ALLOWED_ERR

Assigning a value to a read-only property

8

NOT_FOUND_ERR

Method parameter reference to a nonexistent node in the object's scope

9

NOT_SUPPORTED_ERR

Invoking an XML-only method in an HTML document

10

INUSE_ATTRIBUTE_ERR

Method parameter to an Attr node that already belongs to another element (without cloning the Attr first)

11

INVALID_STATE_ERR

Referencing a node that is not readable or writable

12

SYNTAX_ERR

A slippery keyboard

13

INVALID_MODIFICATION_ERR

Modifying the type of a node

14

NAMESPACE_ERR

Namespace mismatch or malformed name

15

INVALID_ACCESS_ERR

You can't go there

Example

if (e.code == e.INVALID_CHARACTER_ERR) { // process for an illegal identifier character }

Value

Integer

Default

Determined by error.

dt	`NN 6` IE 4 DOM 1

The dt object reflects the dt element.

HTML Equivalent

<dt>

Object Model Reference

[window.]document.getElementById("elementID")

Object-Specific Properties

noWrap

Object-Specific Methods

None.

Object-Specific Event Handler Properties

None.

noWrap NN n/a IE 4 DOM n/a
Read/Write
Specifies whether the browser should render the element as wide as is necessary to display a line of nonbreaking text on one line. Abuse of this attribute can force the user into a great deal of inconvenient horizontal scrolling of the page to view all of the content.

Example

document.getElementById("wideItem").noWrap = "true";

Value

Boolean value: true | false.

Default

false

elements NN 2 IE 3 DOM 1

A collection of all elements contained within a form. Collection members are sorted in source code order. Because each form element includes a type property (starting with Navigator 3 and Internet Explorer 4), scripts can loop through all elements in search of elements of a specific type (e.g., all checkbox elements).

Object Model Reference

document.forms[i].elements
document.formName.elements

Object-Specific Properties

length

Object-Specific Methods

None.

Object-Specific Event Handler Properties

None.

length NN 2 IE 3 DOM 1
Read-only
Returns the number of elements in the collection.

Example

var howMany = document.forms[0].elements.length;

Value

Integer.

embed NN 3 IE 4 DOM n/a

The embed object reflects the embed element. Although the embed object is losing favor to the object element in recent browser generations, scripts in browsers such as Navigator 3, Navigator 4, and IE 4/Windows can control media players that load into a page in response to the embed element's pointer to a media file on the server. Properties and methods exposed by the player pass through the embed object so that scripts treat the embed object as if its list of scriptable powers is extended. Properties listed here are the properties that the element object, rather than an external controller, exposes to scripts.

Note that IE 5 for the Macintosh treats the embed object more like the object object, and exposes properties more closely aligned with an object or applet than an embed object. It's of little consequence, however, because through Version 5.1, IE/Mac does not let scripts communicate with external players or controllers.

HTML Equivalent

<embed>

Object Model Reference

[window.]document.getElementById("elementID")
[window.]document.embeds[i]

Object-Specific Properties

`align`	`height`	`hidden`	`name`	`palette`
`pluginspage`	`src`	`type`	`units`	`width`

Object-Specific Methods

None.

Object-Specific Event Handler Properties

None.

align NN 6 IE 5(Mac) DOM n/a
Read/Write
Defines the alignment of the element within its surrounding container. See the Section 8.1.5 at the beginning of Chapter 8 for the various meanings that different values bring to this property.

Example
document.getElementById("audioPlayer").align = "center";
Value

Any of the alignment constants: absbottom | absmiddle | baseline | bottom | left | middle | right | texttop | top.

Default

left

height, width NN 6 IE 4 DOM n/a
Read/Write
Provide the height and width in pixels of the element as set by the tag attributes. Changing the values does not necessarily change the actual rectangle of the applet after it has loaded.

Example

var controllerHeight = document.embeds["audioPlayer"].height;

Value

Integer.

Default

0

hidden NN n/a IE 4(Win) DOM n/a
Read/Write
Specifies whether the embedded data's plugin control panel appears on the screen. Changes to this property force the page to reflow its content to make room for the plugin control panel or close up space around a newly hidden panel.

Example

document.embeds["jukebox"].hidden = true;

Value

Boolean value: true | false.

Default

false

name NN 6 IE 4 DOM n/a
Read/Write (IE)
Reflects the name attribute value of the element's tag.

Example

document.embeds["myEmbed"].name = "tunes";

Value

Case-sensitive identifier that follows the rules of identifier naming: it may contain no whitespace, cannot begin with a numeral, and should avoid punctuation except for the underscore character.

Default

None.

palette NN n/a IE 4(Win) DOM n/a
Read-only
Returns the setting of the palette attribute of the embed object.

Value

String.

Default

None.

pluginspage NN n/a IE 4(Win) DOM n/a
Read-only
Indicates the URL for downloading and installing the plugin necessary to run the current object's embedded data.

Value

A complete or relative URL as a string.

Default

None returned, but Internet Explorer has its own default URL for plugin information.

src NN n/a IE 4(Win) DOM n/a
Read/Write
Indicates URL of the external content file associated with the object. Although some controllers may respond to changes of this attribute, it is more reliable to load a different file into the controller via its own loading method or property.

Example

document.embeds["myEmbed"].src = "tunes/dannyboy.wav";

Value

Complete or relative URL as a string.

Default

None.

type NN 6 IE n/a DOM n/a
Read-only
Indicates the MIME type of the external data assigned to the element's type attribute.

Example

var dataMIME = document.embeds["myEmbed"].type;

Value

Any valid MIME type name as a quoted string, including the type and subtype portions delimited by a forward slash.

Default

None.

units NN n/a IE 4(Win) DOM n/a
Read/Write
Specifies the unit of measure for the height and width dimensions of the element. Internet Explorer appears to treat all settings as pixels.

Example

document.getElementById("myEmbed").units = "ems";

Value

Any of the following case-insensitive constants (as a string): pixels | px | em.

Default

pixels

width
See height.

embeds NN 3 IE 4 DOM n/a

A collection of all embed elements contained in the current element. Collection members are sorted in source code order. Internet Explorer lets you use array notation or parentheses to access a single element in the collection.

Object Model Reference

document.embeds

Object-Specific Properties

length

length NN 3 IE 4 DOM n/a
Read-only
Returns the number of elements in the collection.

Example

var howMany = document.embeds.length;

Value

Integer.

Entity, EntityReference NN n/a IE n/a DOM 1

The Entity object (one of the node types) is an abstract representation in the W3C DOM of an element that is treated in an XML document as a storage unit. Some entities define a name that can be used by other elements (including other entities) as a shortcut reference to the information stored in the entity. This latter reference is represented in the W3C DOM as an EntityReference node type. You can see many examples of Entity elements in DTD documents. For more details on the application of Entity elements, see the XML specification at http://www.w3.org/TR/REC-xml.

event NN 4 IE 4 DOM 2

The event object contains information about a user- or system-generated event. But there are three different kinds of event objects, one for each of the event object models deployed in browsers: IE for Windows, Navigator 4, and Netscape 6 (from the W3C DOM). IE 5 for Macintosh implements a hybrid of the IE for Windows and Netscape 6 version. See Chapter 6 for examples of processing events in a cross-browser environment. It is rare that an event object property applies to more than one of the event models, so pay special attention to the browser compatibility listings for each of the following properties.

The Netscape 6 event object is more complex in some ways due to the object-oriented nature of the underlying W3C DOM Event object structure. Rather than being an all-encompassing object (as the IE event object is), the Netscape 6 event object exposes different sets of properties and methods depending on the classification of event. All event classes share the properties and methods of the W3C DOM root Event object. But actual event object instances belong to one of the Event object's subclasses (and sometimes, sub-subclasses). These subclasses are known as UIEvent (so-called user interface events such as DOMFocusIn), MouseEvent (including the well-known mouse events), MutationEvent (events that signal a scripted change to the node structure of the document), and, coming in DOM Level 3, TextEvent (keyboard-related events). Netscape 6 implements its own, temporary keyboard events classification under the name KeyEvent, which is a subclass of UIEvent, although it borrows some MouseEvent properties for scripting convenience.

By and large, this functional division of objects won't impact your Netscape 6 event processing because an event listener function for a particular kind of event will be looking for properties associated with that event. The event class is of little concern. Still, it is instructive to see the way event object properties and methods cascade through this object-oriented structure. The following table illustrates the distribution of properties among Netscape 6 and W3C DOM event classes.

	Event	UIEvent	MouseEvent	KeyEvent[19]	TextEvent[20]	MutationEvent
Event properties
`bubbles`	•	•	•	•	•	•
`cancelable`	•	•	•	•	•	•
`cancelBubble[21]`	•	•	•	•		•
`currentTarget`	•	•	•	•	•	•
`eventPhase`	•	•	•	•	•	•
`originalTarget19`	•	•	•	•		•
`target`	•	•	•	•	•	•
`timeStamp`	•	•	•	•	•	•
`type`	•	•	•	•	•	•
UIEvent properties
`detail`		•	•	•	•
`view`		•	•	•	•
MouseEvent properties
`altKey`			•	•
`button`			•
`clientX`			•	•
`clientY`			•	•
`ctrlKey`			•	•
`metaKey`			•	•
`relatedTarget`			•
`screenX`			•	•
`screenY`			•	•
`shiftKey`			•	•
KeyEvent properties
`charCode19`				•
`isChar19`				•
`keyCode19`				•
`rangeOffset19`				•
`rangeParent19`				•
TextEvent properties
`keyVal20`					•
`numPad20`					•
`outputString20`					•
`virtKeyVal20`					•
`visibleOutputGenerated20`					•
MutationEvent properties
`attrChange`						•
`attrName`						•
`newValue`						•
`prevValue`						•
`relatedNode`						•

[19] Implemented in in Netscape 6 for additional functionality or in lieu of unfinished DOM Level 3 keyboard event model. Borrows some MouseEvent properties for scripting convenience.

[20]Proposed for DOM Level 3, but not implemented in Netscape 6.

[21]IE property implemented in Netscape 6 for cross-browser convenience.

And the following table illustrates the distribution of methods among Netscape 6 and W3C DOM event classes.

Event

UIEvent

MouseEvent

KeyEvent[22]

TextEvent[23]

MutationEvent

Event methods

initEvent( ) • • • • • •

getPreventDefault( )22 • • • • •

preventDefault( ) • • • • • •

stopPropagation( ) • • • • • •

UIEvent methods

initUIEvent( ) •

MouseEvent methods

initMouseEvent( ) •

KeyEvent methods

initKeyEvent( ) •

TextEvent methods

checkModifier( )23 •

initModifier( )23 •

initTextEvent( )23 •

MutationEvent methods

initMutationEvent( ) •

[22] Implemented in Netscape 6 for additional functionality or in lieu of unfinished DOM Level 3 keyboard event model. Borrows some MouseEvent properties for scripting convenience.

[23]Proposed for DOM Level 3, but not implemented in Netscape 6.

The event object in Netscape 6 also implements the properties of the Navigator 4 static Event object, and it inherits an enormous list of W3C DOM TextEvent object constants that represent nonalphanumeric keyboard key codes (which have constant names like eventObject.DOM_VK_PAGE_UP). These keyboard constants are defined in the forthcoming W3C DOM Level 3 events module, but are already implemented in Netscape 6 (although the values don't exactly line up yet). A list of properties for the Navigator 4 static Event object appears in the Event object discussion following the current foray through an instance of an event.

As described in detail throughout Chapter 6, you must use different script techniques to obtain a reference to an event object in the IE and Navigator event models. Once you have that reference, you are well on your way to equalizing event processing across browsers. The example fragments that follow assume that previous script statements have obtained a reference to the browser-specific event object (usually shown in the example as stored in a variable called evt).

Object Model Reference

NN: eventObj
IE: [window.]event

Object-Specific Properties

`altLeft`	`attrChange`	`attrName`
`behaviorCookie`	`behaviorPart`	`bookmarks`	`boundElements`
`bubbles`	`button`	`cancelable`	`cancelBubble`
`charCode`	`clientX`	`clientY`	`contentOverflow`
`ctrlKey`	`ctrlLeft`	`currentTarget`	`data`
`dataFld`	`dataTransfer`	`detail`	`eventPhase`
`fromElement`	`isChar`	`keyCode`	`layerX`
`layerY`	`metaKey`	`modifiers`	`newValue`
`nextPage`	`offsetX`	`offsetY`	`originalTarget`
`pageX`	`pageY`	`prevValue`	`propertyName`
`qualifier`	`rangeOffset`	`rangeParent`	`reason`
`recordset`	`relatedNode`	`relatedTarget`	`repeat`
`returnValue`	`screenX`	`screenY`	`shiftKey`
`shiftLeft`	`srcElement`	`srcFilter`	`srcUrn`
`target`	`timeStamp`	`toElement`	`type`
`view`	`wheelDelta`	`which`	`x`
`y`

Object-Specific Methods

`getPreventDefault( )`	`initEvent( )`	`initKeyEvent( )`	`initMouseEvent( )`
`initMutationEvent( )`	`initUIEvent( )`	`preventDefault( )`	`stopPropagation( )`

Object-Specific Event Handler Properties

None.

altKey NN 6 IE 4 DOM 2
Read-only
Returns true if the left or right Alt key is down at the time the event fired.

Example

if (evt.altKey) { //handle case of Alt key down }

Value

Boolean value: true | false.

Default

false

altLeft NN n/a IE 5.5(Win) DOM n/a
Read-only
Returns true if the left Alt key is down at the time the event fired.

Example

if (evt.altLeft) { //handle case of left Alt key down }

Value

Boolean value: true | false.

Default

false

attrChange NN 6 IE n/a DOM 2
Read-only
Returns an integer code corresponding to the type of change made to an Attr node as the result of a DOMAttrModified event type of W3C DOM mutation event. Every mutation event object has three constants that also correspond to the integer values, which you can use to make more verbose, but easier-to-read script comparisons for DOMAttrModified event processing. The values and constants are shown in the following table.

Value

Constant

Description

1

evtObj.MODIFICATION

Changed value of existing Attr node

2

evtObj.ADDITION

The Attr node was added to the document tree

3

evtObj.REMOVAL

The Attr node was removed from the document tree

Example

if (evt.attrChange == evt.MODIFICATION) { // do post-processing of attribute value change }

Value

Integer value: 1 | 2 | 3.

Default

None.

attrName NN 6 IE n/a DOM 2
Read-only
Returns a string version of the name of an Attr node affected by a DOMAttrModified event type of W3C DOM mutation event.

Example

var changedAttr = evt.attrName;

Value

String value.

Default

Empty string.

behaviorCookie, behaviorPart, bookmarks, boundElements NN n/a IE 6(Win) DOM n/a
Read-only
These properties are returned by the event object in IE 6 for Windows (with values 0, 0, null, and the empty array, respectively), but Microsoft does not document them. Perhaps they will be supported and implemented in a future version.

bubbles NN 6 IE n/a DOM 2
Read-only
Returns Boolean true if the default behavior of the event is to allow the event to bubble through the element hierarchy.

Example

if (evt.bubbles) { // handle case of the event bubbling }

Value

Boolean value: true | false.

Default

Event type-specific.

button NN 6 IE 4 DOM 2
Read-only
Inidicates which mouse button was pressed to trigger the mouse event. Be aware that the typical Macintosh has only a one-button mouse. Also, if you want to intercept the right-click context menu in IE/Windows, use the oncontextmenu event handler.
A significant discrepancy exists among DOM specifications and implementations with respect to the numbers returned for this property. The W3C DOM, as implemented in Netscape 6, specifies a value of zero to indicate the left (primary) button. IE for Windows supports additional values for mouse button combinations.

Example

if (evt.button == 2) { // handle event for right button }

Value

Integer value according to the following table.

Button(s)

IE

NN 6

W3C DOM

No button

0

null

null

Left (primary)

1

0

0

Middle

4

1

1

Right

2

2

2

Left + Right

3

n/a

n/a

Left + Middle

5

n/a

n/a

Right + Middle

6

n/a

n/a

Left + Middle + Right

7

n/a

n/a

Default

0

cancelable NN 6 IE n/a DOM 2
Read-only
Returns Boolean true if the event is of the type that can have its default behavior on the target element cancelled via the preventDefault( ) method.

Example

if (evt.cancelable ) { evt.preventDefault( ); }

Value

Boolean: true | false.

Default

Event type-specific.

cancelBubble NN 6 IE 4 DOM n/a
Read/Write
Specifies whether the event should propagate (bubble) up the element container hierarchy. You usually only need to set this property to true to override the default behavior and prevent the event from going any further. Netscape 6 implements this IE property for convenience. The W3C DOM equivalent is the stopPropagation( ) method of the event object.

Example

evt.cancelBubble = true;

Value

Boolean: true | false.

Default

false

charCode NN 6 IE n/a DOM n/a
Read-only
Returns an integer corresponding to the Unicode value of the character generated by the key that fired the event. The character code is different from the key code, as the character code distinguishes between upper- and lowercase letters (for example, 97 for "a" and 65 for "A"), whereas the keyCode value is the same for that key, regardless of the character created from it. This property generally contains a value only for onkeypress events; the value is zero for onkeydown and onkeyup events. For the IE equivalent, see the keyCode property.
When the keyboard events module is completed for W3C DOM Level 3, this property will probably have a different name.

Example

if (evt.charCode > 96 && evt.charCode < 123) { evt.target.value += String.fromCharCode(evt.charCode - 32); evt.preventDefault( ); }

Value

Integer.

Default

Event-specific.

clientX, clientY NN 6 IE 4 DOM 2
Read-only
Indicate the horizontal (x) and vertical (y) coordinate of the mouse at the moment the current event fired. These coordinates are relative to the viewable document area of the browser window or frame. To convert these coordinates to the document's in IE, be sure to add the body element's scroll values (or html element's scroll values in IE 6 standards-compatible mode). For Netscape 6, the pageX and pageY properties provide coordinates in the document's space.

Example

if ((evt.clientX >= 10 && evt.clientX <= 20) && (evt.clientY >= 50 && evt.clientY <= 100)) { // process code for click in hot zone bounded by 10,50 and 20,100 }

Value

Integer of pixel values.

Default

None.

contentOverflow NN n/a IE 5.5(Win) DOM n/a
Read-only
Returns Boolean true if as-yet unrendered content requires a new layout rectangle to handle the overflow content. The property applies only to the onlayoutcomplete event if you deploy custom print or print preview templates. For more on the C++ programming required for such templates, visit http://msdn.microsoft.com/library/default.asp?url=/workshop/browser/hosting/printpreview/reference/reference.asp.

Value

Boolean: true | false.

Default

false

ctrlKey NN 6 IE 4 DOM 2
Read-only
Returns true if the left or right Control key was pressed at the instant the event fired. See Chapter 6 for testing for this key in cross-browser event handling code.

Example
if (evt.ctrlKey) {
    // process for Control key being down
}
Value

Boolean value: true | false.

Default

false

ctrlLeft NN n/a IE 5.5(Win) DOM n/a
Read-only
Returns true if the left Control key was pressed at the instant the event fired.

Example

if (evt.ctrlLeft) { // process for left Control key being down }

Value

Boolean value: true | false.

Default

false

currentTarget NN 6 IE n/a DOM 2
Read-only
Returns a reference to the node whose event listener is currently processing the event. Allows a function to know whether it is invoked from the actual target node or a different node during event propagation.

Example

if (evt.currentTarget.nodeType == 1) { // process at element level for possible text node target }

Value

Reference to a node in event propagation hierarchy.

Default

Reference to event target.

data NN |4| IE n/a DOM n/a
Read-only
Provides accessory data associated with the Navigator 4-only dragdrop event. The data property returns the URL of the item being dropped onto the window or frame.

Example

var srcDoc = evtObj.data;

Value

String.

Default

None.

dataFld NN n/a IE 5(Win) DOM n/a
Read/Write
Used with IE data binding, the dataFld property holds the name of the data source object's field associated with the column of the HTML table. This property contains a value after an oncellchange event in a table generated via data binding.

Value

String.

Default

Empty string.

dataTransfer NN n/a IE 5(Win) DOM n/a
Read-only
Returns a reference to the dataTransfer object to facilitate moving customized data between source and destination elements during a drag-and-drop operation. See the dataTransfer object for details of its usage.

Value

Reference to dataTransfer object.

Default

None.

detail NN 6 IE n/a DOM 2
Read-only
Returns an integer conveying event type-specific additional information. For mouse button events, the number indicates how many times the user clicked the mouse on the same coordinate position as the previous click without moving the cursor away from the location. Moving the cursor resets the counter to zero in preparation for the next press and release of the mouse button. For a DOMActivate event type, the detail property returns 1 for activation by a simple user action (click or tab), and 2 for a more complex action (a double-click).

Example

if (evt.type == "click" && evt.detail > 5) { alert("Relax, dude!"); }

Value

Integer.

Default

Event-type specific.

eventPhase NN 6 IE n/a DOM 2
Read-only
Returns an integer conveying whether the event listener is processing the event while in the capture phase, at the event target, or in the bubbling phase. W3C DOM event objects also implement plain-language constants corresponding to the three values.

Example

if (evt.eventPhase == evt.AT_TARGET) { // process event listener from the event target }

Value

Integer value from the following table.

Value

Constant

1

eventObjectReference.CAPTURING_PHASE

2

eventObjectReference.AT_TARGET

3

eventObjectReference.BUBBLING_PHASE

Default

2

fromElement NN n/a IE 4 DOM n/a
Read-only
Returns a reference to the object where the cursor was located just prior to the onMouseOver or onMouseOut event.

Example

if (evt.fromElement.id == "lowerLevel") { ... }

Value

Element object reference.

Default

None.

isChar NN 6 IE n/a DOM n/a
Read-only
Returns true if the keyboard event is from a character key. In practice Netscape 6 returns true for all keys, including function keys. Use onkeydown or onkeyup event handlers to process noncharacter keys.

Value

Boolean value: true | false.

Default

true

keyCode NN 6 IE 4 DOM n/a
Read/Write
Slightly different characteristics for IE and Netscape 6, but the two browser classes treat the keyCode property the same way for onkeydown and onkeyup events. For these events, the keyCode property returns the code associated with the keyboard key, irrespective of the character that might be generated by that key. On a typical Latin character set keyboard, the A key generates the code 65. Modifier keys generate their own events and codes as they are pressed and released.
For the onkeypress event, only IE returns a significant value, corresponding to the Unicode value of the actual character displayed in a text box by typing the character (e.g., 65 for "A" and 97 for "a"). The equivalent property in Netscape 6 for the onkeypress event is charCode. See Chapter 6 about processing keyboard events.

Example
if (evt.keyCode == 65) {
    ...
}
Value

Integer.

Default

None.

layerX, layerY NN 4 IE n/a DOM n/a
Read-only
Provide the horizontal (x) and vertical (y) coordinate of the mouse at the moment the current event fired. These coordinates are relative to the containing layer. If no layers or positionable elements have been defined, the default layer of the base document is used as a reference point, thus equivalent to the pageX and pageY properties. In Netscape 6 and later, these properties are measured relative to the element's own rectangular space for text and password input elements, textarea elements, and select elements.

Example

if ((evt.layerX >= 10 && evt.layerX <= 20) && (evt.layerY >= 50 && evt.layerY <= 100)) { // process code for click in hot zone bounded by 10,50 and 20,100 }

Value

Integer of pixel values.

Default

None

metaKey NN 6 IE n/a DOM n/a
Read-only
Returns true if the keyboard's Meta key (Command key on the Macintosh keyboard) was pressed at the instant the event fired.

Example

if (evt.metaKey) { // process for meta key being down }

Value

Boolean value: true | false.

Default

false

modifiers NN |4| IE n/a DOM n/a
Read-only
Provides an integer that represents the keyboard modifier key(s) being held down at the time the Navigator 4-only event fired. You can use the & operator with a series of static Event object constants to find out whether a particular modifier key was pressed. See Chapter 6.

Example
var altKeyPressed = evt.modifiers & Event.ALT_MASK;
Value

Integer.

Default

0

newValue, prevValue NN 6 IE n/a DOM 2
Read-only
Return a string with the new and previous values (respectively) of data associated with DOMAttrModified and DOMCharacterDataModified event types of the W3C DOM mutation events class. This information could be useful for creating an undo buffer for changes to an element's attribute or the content of a CharacterData node.

Example

undoAttrBuffer = {attrNode:evt.relatedNode, oldVal:evt.prevValue};

Value

String value.

Default

Empty string.

nextPage NN n/a IE 5.5(Win) DOM n/a
Read-only
Returns a string indicating whether the next page of a custom print template will appear on a left- or right-facing page. For more on the C++ programming required for templates, visit http://msdn.microsoft.com/library/default.asp?url=/workshop/browser/hosting/printpreview/reference/reference.asp.

Value

String constant: left | right | (empty string).

Default

Empty string.

offsetX, offsetY NN n/a IE 4 DOM n/a
Read-only
Provide the left and top coordinates of the mouse pointer relative to the containing element (exclusive of padding, borders, or margins) when the event fired. You can determine the containing element via the offsetParent property. See the Section 9.2 at the beginning of this chapter for information on offset measurement anomalies in Internet Explorer.

Example
if (evt.offsetX <= 20 && evt.offsetY <=40) {
 ...
}
Value

Integer pixel count.

Default

None.

originalTarget NN 6 IE n/a DOM n/a
Read-only
Returns a reference to a node that Netscape 6 internally treats as the genuine first target of the event. By and large, this information isn't helpful to DHTML scripting, because it dives into the internal construction of certain elements (e.g., an input element of type text has a div element nested inside of it, but the DOM node tree does not see the div element as a child node of the input element). For many events and event targets, the target and originalTarget properties reference the identical node.

Value

Node object reference

Default

Element-specific.

pageX, pageY NN 4 IE n/a DOM n/a
Read-only
Provide the left and top coordinates of the element's content relative to the top-left corner of the page area when the event fired. The measurements ignore any scrolling of the page.

Example

if (evt.pageX <= 20 && evt.pageY <=40) { ... }

Value

Integer pixel count.

Default

None.
prevValue changed during an onpropertychange event. For other event types, the value is an empty string. If the changed property is a property of a property (e.g., a property of an element's style property), the returned value shows the "dot" version, such as style.color.

Example

if (evt.propertyName.indexOf("style") == 0) { // perform further processing on a changed style }

Value

String property name.

Default

Empty string.

qualifier NN n/a IE 5(Win) DOM n/a
Read/Write
For use with IE data binding events (such as ondatasetcomplete). Returns a string value signifying a data source member, which may then be used as a parameter to access a data source's named recordset. Consult the Microsoft documentation for the Data Source Object you use to see if it provides qualifier data.

Value

String.

Default

Empty string.

rangeOffset NN 6 IE n/a DOM n/a
Read-only
Returns an integer of the character offset within a node that the Netscape 6 DOM considers a potential Range end point. The reference to the node is found in the associated rangeParent property of the event object. These two values can be passed as parameters to W3C DOM Range object methods for setting a start or end point. Thus, a mousedown event listener could establish the start point of a range, while a mouseup event listener function could set the end point—both functions feeding rangeParent and rangeOffset values to the Range object methods.

Example

var rng; function processMouseDown(evt) { rng = document.createRange( ); rng.setStart(evt.rangeParent, evt.rangeOffset); }

Value

Integer.

Default

0

rangeParent NN 6 IE n/a DOM n/a
Read-only
Returns a reference to a document tree node that would be a suitable start or end point for a W3C text range. Use in concert with the rangeOffset property.

Example

function processMouseUp(evt) { rng.setEnd(evt.rangeParent, evt.rangeOffset); }

Value

Reference to a node.

Default

None.

reason NN n/a IE 4 DOM n/a
Read/Write
Returns a code associated with an ondatasetcomplete event signifying whether the IE data binding data transfer was successful or, if incomplete, whether the transfer stopped due to an error or a stoppage by the client or user. This property must be examined in an event handler for the ondatasetcomplete event. In IE 4, the property is read-only. Although IE 5/Mac includes this property of the event object, it does not implement the associated event.

Example

if (evt.reason == 2) { alert("An error occurred during the most recent update."); }

Value

One of three possible integer values:

0

Transfer was successful

1

Transfer aborted

2

An error halted the transfer

Default

None.

recordset NN n/a IE 5(Win) DOM n/a
Read/Write
Returns a reference to an IE data binding recordset object associated with a data-related event.

Value

Object reference.

Default

None.

relatedNode NN 6 IE n/a DOM 2
Read-only
Returns a reference to a node that is affected by the action that triggers some W3C DOM mutation events. This provides a more direct route to a node that is impacted by the event, according to the following table.

Mutation event type

eventObj.relatedNode reference

DOMNodeInserted

Parent node of inserted node

DOMNodeRemoved

Original parent node of removed node

DOMAttrModified

Attr node

For other mutation event types, the property returns null; for other event classes, the property returns undefined.

Example

var newParent = evt.relatedNode;

Value

Reference to a node, null, or undefined.

Default

None.

relatedTarget NN 6 IE n/a DOM 2
Read-only
Returns a reference to a rendered node in the document tree that was the previous or next target for events, depending on the event type. For a mouseover event type, the relatedTarget property refers to the node from which the cursor arrived; for a mouseout event, the relatedTarget property refers to the node to which the cursor departed. The corresponding IE functionality is in the fromElement and toElement properties of the IE event object.

Example

var beenThere = evt.relatedTarget;

Value

Reference to a node.

Default

None.

repeat NN n/a IE 5(Win) DOM n/a
Read/Write
For an onkeydown event only, returns Boolean true if the key has been down long enough to enter auto-repeat mode. You can prevent auto-repeated keys from being entered into a field with the following example.

Example

function handleKeyDown( ) { if (evt.repeat) { evt.returnValue = false; } }

Value

Boolean value: true | false.

Default

false

returnValue NN n/a IE 4 DOM n/a
Read/Write
Provides the value to be returned to the event's source element to allow or prohibit the element's default action connected with the event. If you set event.returnValue to false, the element does not carry out its normal operation, such as navigating to a link or submitting the form. This property does not influence an actual value you may wish to return from an event handler function.

Example

evt.returnValue = false;

Value

Boolean value: true | false.

Default

true

screenX, screenY NN 4 IE 4 DOM 2
Read-only
Provide the horizontal and vertical pixel coordinate points where the cursor was located on the video screen when the event occurred. The top-left corner of the screen is point 0,0. There is no particular coordination with the browser window or document, unless you have positioned the window and know where the active window area is in relation to the screen.

Example

if (evt.screenX < 5 || evt.screenY < 5) { alert("You\'re too close to the edge!"); }

Value

Any positive integer or zero.

Default

0

shiftKey NN 6 IE 4 DOM 2
Read-only
Returns true if the left or right Shift key was pressed at the instant the event fired.

Example

if (evt.shiftKey) { // process for Shift key being down }

Value

Boolean value: true | false.

Default

false

shiftLeft NN n/a IE 5.5(Win) DOM n/a
Read-only
Returns true if the left Shift key was pressed at the instant the event fired.

Example

if (evt.shiftLeft) { // process for left Shift key being down }

Value

Boolean value: true | false.

Default

false

srcElement NN n/a IE 4 DOM n/a
Read-only
Refers to the element object that initially received the current event. This property is convenient in switch constructions for an event handler function that handles the same event type for a number of different elements. The corresponding property for Netscape 6 is target.

Example

switch (evt.srcElement.id) { case "myDIV": ... ... }

Value

Element object reference.

Default

None.

srcFilter NN n/a IE 4(Win) DOM n/a
Read-only
Refers to the filter object that fired an onfilterchange event.

Value

Filter object reference.

Default

None.

srcUrn NN n/a IE 5(Win) DOM n/a
Read-only
String of the URN of an attached behavior that fired an event.

Value

String.

Default

null

target NN 4 IE n/a DOM 2
Read-only
Refers to the node object that is the intended destination of the current event. Unlike the corresponding IE srcElement property, the target property in Netscape 6 can refer to a text node, even if the event handler is defined for the element that surrounds the text node. Your event processing for such a scenario must take the nodeType into account to equalize the reference to the surrounding element for both IE and Navigator. See Chapter 6 for examples of cross-browser event handling code.

Example
var elem = (evt.target) ? evt.target : evt.srcElement;
Value

Node object reference.

Default

None.

timeStamp NN 6 IE n/a DOM 2
Read-only
Provides an integer signifying a milliseconds value you can use as a relative indicator of when an event occurred. Although the W3C DOM suggests the value should be the time since 1 January 1970 (the Java and JavaScript epoch), you cannot rely on that value. But you can compare the timeStamp property value for two events to derive the elapsed time between events.

Example

var clickTime = evt.timeStamp;

Value

Integer.

Default

Current timestamp.

toElement NN n/a IE 4 DOM n/a
Read-only
Returns a reference to the element object to which the cursor has moved that triggered the onmouseout event.

Example

if (evt.toElement.id == "upperLevel") { ... }

Value

Element object reference.

Default

None.

type NN 4 IE 4 DOM 2
Read-only
Indicates the type of the current event (without the "on" prefix). Values are all lowercase.

Example

if (evt.type == "change") { ... }

Value

Any event name (without the "on" prefix) as a string.

Default

None.

view NN 6 IE n/a DOM 2
Read-only
Returns a reference to the W3C DOM view (i.e., the window or frame object in Netscape's implementation) in which the event occurred.

Example

var whichWin = evt.view;

Value

Reference to a window type of object.

Default

Current window.

wheelDelta NN n/a IE 5.5(Win) DOM n/a
Read-only
Returns an integer indicating which direction the user rolled the mouse wheel (for a mouse equipped with a wheel) during an onmousewheel event. A positive value means the user rolled the wheel toward the screen; a negative value means the opposite direction.

Example

if (evt.wheelDelta > 0) { ... }

Value

Integer, typically 120 or -120.

Default

None.

which NN 4 IE n/a DOM n/a
Read-only
Returns a value relevant to the type of event. For mouse events, the property value is an integer indicating which mouse button was used (1 is the left button; 3 is the right button). For keyboard events, the property value is an integer of the keyboard character ASCII code. This property survives in Netscape 6 as a carryover from the Navigator 4 event model. Use the button, charCode, and keyCode properties if you no longer need to support Navigator 4.

Example

if (evt.which == 65) { ... }

Value

Integer.

Default

None.

x, y NN n/a IE 4 DOM n/a
Read-only
Return the horizontal and vertical pixel coordinates of the mouse pointer at the time the event occurred. For all but relative-positioned elements, the coordinate system is the body element (or html element in IE 6 standards-compatible mode). If the event occurs inside a relative-positioned element's rectangle, the coordinate system is limited to that element's space (the element's top left corner being 0,0). A value of -1 is returned if the pointer was outside of the document area of the browser window.

Example

if (evt.x < 20 && evt.y < 30) { ... }

Value

Integer.

Default

None.

getPreventDefault( ) NN 6 IE n/a DOM n/a
Returns Boolean true if the preventDefault( ) method has been invoked for the current event object. Essentially lets a script inquire about the prevent-default state. This property is a Netscape 6 extension to the W3C DOM events module.

Returned Value

Boolean value: true | false.

Parameters

None.

initEvent( ) NN 6 IE n/a DOM 2
initEvent("eventType", bubblesFlag, cancelableFlag)
Indicates the minimum initialization required on an event object that is generated by document.createEvent( ). After a script-generated event is initialized, it may be used as a parameter to a node's dispatchEvent( ) method.

Returned Value

None.

Parameters

eventType

String identifier for the event's type, such as click, mousedown, keypress, DOMAttrModified, and so on.

bubblesFlag

Boolean value (true | false) determining whether the event's default propagation behavior is to bubble.

cancelableFlag

Boolean value (true | false) determining whether the event's default action may be prevented via the preventDefault( ) method.

initKeyEvent( ) NN 6 IE n/a DOM n/a
initKeyEvent("eventType", bubblesFlag, cancelableFlag, view, ctrlKeyFlag, altKeyFlag, shiftKeyFlag, metaKeyFlag, keyCode, charCode)
Initializes a newly created event object with a complete set of property values associated with any keyboard event. This method's name and parameter makeup may change for the formal DOM Level 3 events module, where keyboard events (tentatively called text events) will be published. All parameters must be present, and must be set to default values (such as false for Boolean key flags or zero for integer code numbers) if the values are not significant for the event type.

Returned Value

None.

Parameters

eventType

String identifier for the event's type: keydown, keypress, keyup.

bubblesFlag

Boolean value (true | false) determining whether the event's default propagation behavior is to bubble.

cancelableFlag

Boolean value (true | false) determining whether the event's default action may be prevented via the preventDefault( ) method.

view

Reference to the window or frame object in which the dynamically-generated event is supposed to have occurred.

ctrlKeyFlag

Boolean value (true | false) of the Control key state for this event.

altKeyFlag

Boolean value (true | false) of the Alt key state for this event.

shiftKeyFlag

Boolean value (true | false) of the Shift key state for this event.

metaKeyFlag

Boolean value (true | false) of the Meta key(e.g., Macintosh Command key) state for this event.

keyCode

Integer key code for this event.

charCode

Integer character code for this event.

initMouseEvent( ) NN 6 IE n/a DOM 2

initMouseEvent("eventType", bubblesFlag, cancelableFlag, view, detailVal, screenX, screenY, clientX, clientY, ctrlKeyFlag, altKeyFlag, shiftKeyFlag, metaKeyFlag, buttonCode, relatedTargetNodeRef)
Initializes a newly created event object with a complete set of property values associated with any mouse event. All parameters must be present, and must be set to default values (such as false for Boolean key flags, zero for integer values, or null for a node reference) if the values are not significant for the event type.

Returned Value

None.

Parameters

eventType

String identifier for the event's type, such as click, mousedown, mousemove, mouseout, mouseover, mouseup.

bubblesFlag

Boolean value (true | false) that determines whether the event's default propagation behavior is to bubble.

cancelableFlag

Boolean value (true | false) that determines whether the event's default action may be prevented via the preventDefault( ) method.

view

Reference to the window or frame object in which the dynamically-generated event is supposed to have occurred.

detailVal

Integer code for detail data associated with the event.

screenX

Integer for horizontal screen coordinate.

screenY

Integer for vertical screen coordinate.

clientX

Integer for horizontal browser window coordinate.

clientY

Integer for vertical browser window coordinate.

ctrlKeyFlag

Boolean value (true | false) of the Control key state for this event.

altKeyFlag

Boolean value (true | false) of the Alt key state for this event.

shiftKeyFlag

Boolean value (true | false) of the Shift key state for this event.

metaKeyFlag

Boolean value (true | false) of the Meta key(e.g., Macintosh Command key) state for this event.

buttonCode

Integer button code for this event.

relatedTargetNodeRef

Reference to node receiving the previous or next mouse event.

initMutationEvent( ) NN 6 IE n/a DOM 2
initMutationEvent("eventType", bubblesFlag, cancelableFlag, relatedNodeRef, prevValue, newValue, attrName, attrChangeCode)
Initializes a newly created event object with a complete set of property values associated with any mutation event. All parameters must be present, and must be set to default values (such as false for Boolean key flags or zero for integer code numbers) if the values are not significant for the event type.

Returned Value

None.

Parameters

eventType

String identifier for the event's type: DOMAttrModified, DOMCharacterDataModified, DOMNodeInserted, DOMNodeInsertedIntoDocument, DOMNodeRemoved, DOMNodeRemovedFrom-Document, DOMSubtreeModified.

bubblesFlag

Boolean value (true | false) determining whether the event's default propagation behavior is to bubble.

cancelableFlag

Boolean value (true | false) determining whether the event's default action may be prevented via the preventDefault( ) method.

relatedNode

Reference to a node associated with the event. Applicable only to DOMNodeInserted, DOMNodeRemoved, DOMAttrModified event types.

prevValue

String of previous value for an Attr or CharacterData node. Applicable only to DOMAttrModified and DOMCharacterDataModified event types.

newValue

String of new value for an Attr or CharacterData node. Applicable only to DOMAttrModified and DOMCharacterDataModified event types.

attrName

String of the name of an Attr node. Applicable only to the DOMAttrModified event type.

attrChangeCode

Integer for the code corresponding to the type of change the event simulates. Applicable only to the DOMAttrModified event type.

initUIEvent( ) NN 6 IE n/a DOM 2

initUIEvent("eventType", bubblesFlag, cancelableFlag, view, detailVal)
Initializes a newly created event object with a complete set of property values associated with any UI event. All parameters must be present, and must be set to default values (such as false for Boolean key flags or zero for integer values) if the values are not significant for the event type.

Returned Value

None.

Parameters

eventType

String identifier for the event's type, such as DOMFocusIn, DOMFocusOut, DOMActivate.

bubblesFlag

Boolean value (true | false) determining whether the event's default propagation behavior is to bubble.

cancelableFlag

Boolean value (true | false) determining whether the event's default action may be prevented via the preventDefault( ) method.

view

Reference to the window or frame object in which the dynamically generated event is supposed to have occurred.

detailVal

Integer code for detail data associated with the event.

preventDefault( ) NN 6 IE n/a DOM 2
Instructs the current event to bypass the normal operation it performs on the node. Once set, the mode cannot be undone for the current event. The following Netscape 6 event listener function for an keypress event allows only numbers to be entered into a text field:
function numsOnly(evt) { if (evt.charCode < 48 || evt.charCode > 57) { evt.preventDefault( ); } }
This method is the equivalent of assigning false to the IE event.returnValue property, or having an event handler evaluate to return false.

Returned Value

None.

Parameters

None.

stopPropagation( ) NN 6 IE n/a DOM 2
Prevents the current event from propagating through the capture or bubbling hierarchy beyond the node currently processing the event. This method performs the same action as assigning false to the event object's cancelBubble property (for bubbling propagation only).

Returned Value

None.

Parameters

None.

Event NN 4 IE n/a DOM n/a

The Event object is a static object in Navigator 4 and later that contains a large set of case-sensitive constant values you can use to test user- or system-generated events for keyboard modifiers and event types (see the modifiers and type properties of the event object). These constant values evaluate to mathematically related integers. Not all event types assigned a constant value are implemented as events in Navigator 4. This same object continues to be supported in Netscape 6, but only for backward compatibility with the Navigator 4 event capture syntax.

Object Model Reference

Event

Object-Specific Properties

`ABORT`	`ALT_MASK`	`BACK`	`BLUR`	`CHANGE`
`CLICK`	`CONTROL_MASK`	`DBLCLICK`	`DRAGDROP`	`ERROR`
`FOCUS`	`FORWARD`	`HELP`	`KEYDOWN`	`KEYPRESS`
`KEYUP`	`LOAD`	`LOCATE`	`META_MASK`	`MOUSEDOWN`
`MOUSEDRAG`	`MOUSEMOVE`	`MOUSEOUT`	`MOUSEOVER`	`MOUSEUP`
`MOVE`	`RESET`	`RESIZE`	`SCROLL`	`SELECT`
`SHIFT_MASK`	`SUBMIT`	`UNLOAD`	`XFER_DONE`

external NN n/a IE 4(Win) DOM n/a

The external object is used primarily by developers who use Internet Explorer as a component for their applications and require access to custom extensions to the document object model. But you might add one or two of this object's methods into your work for an IE/Windows audience.

The following syntax example asks a user for permission to insert a script-controlled bookmark into the browser's Favorites list:

external.AddFavorite("URL", "Favorites List Label");

The following syntax example loads another URL into the a target window or frame (or the current window if the third parameter is an empty string), and then performs a text find for the third parameter string:

external.NavigateAndFind("URL", "searchString", "targetFrameName");

For more details, visit http://msdn.microsoft.com/workshop/browser/overview/overview.asp.

fieldset NN 6 IE 4 DOM 1

The fieldset object reflects the fieldset element. IE 5 for Macintosh implements the client and scroll measurement properties for this object.

HTML Equivalent

<fieldset>

Object Model Reference

[window.]document.getElementById("elementID")

Object-Specific Properties

align

form

margin

Object-Specific Methods

None.

Object-Specific Event Handler Properties

None.

align NN n/a IE 4 DOM n/a
Read/Write
Defines the horizontal alignment of the element within its surrounding container. In practice, this property has little effect on the fieldset object or its contents in IE 4. It behaves erratically in IE 6 for Windows, but responds as expected in IE 5 for Macintosh.

Example

document.getElementById("myFieldset").align = "center";

Value

Any of the three horizontal alignment constants: center | left | right.

Default

left

form NN 6 IE 5(Mac)/6(Win) DOM 1
Read-only
Returns a reference to the next outermost form element object in the document tree. Multiple fieldset element objects within the same form element reference the same form element object.

Example

var theForm = document.getElementById("myFieldset").form;

Value

Reference to a form element object.

Default

None.

margin NN n/a IE 5(Mac) DOM n/a
Read-only
Returns an integer value, presumably of a margin setting. But the element does not feature a corresponding attribute. Ignore this property.

Value

Integer.

Default

7

filters[] NN n/a IE 4(Win) DOM n/a

Provides a collection of all filters associated with the current element. Internet Explorer lets you use array notation or parentheses to access a single element in the collection. Filters are not available in IE for the Macintosh through Version 5.1.

Object Model Reference

document.getElementById("elementID").filters

Object-Specific Properties

length

Object-Specific Methods

item( )

namedItem( )

length NN n/a IE 4(Win) DOM n/a
Read-only
Returns the number of elements in the collection.

Example

var howMany = document.body.filters.length;

Value

Integer.

item( ) NN n/a IE 4(Win) DOM n/a
item(index)
Returns a filter object corresponding to the filter that matches the index value in source code order.

Returned Value

Reference to a filter object. If there are no matches to the parameter, the returned value is null.

Parameters

index

A zero-based integer corresponding to the specified item in source code order.

namedItem( ) NN n/a IE 6(Win) DOM n/a
namedItem(IDOrName)
Returns a filter object or collection of objects corresponding to the filter matching the parameter string value.

Returned Value

One filter object or collection (array) of filter objects. If there are no matches to the parameters, the returned value is null.

Parameters

IDOrName

The string that contains the same value as the desired filter's name.

font NN 6 IE 4 DOM 1

The font object reflects the font element.

HTML Equivalent

<font>

Object Model Reference

[window.]document.getElementById("elementID")

Object-Specific Properties

color

face

size

Object-Specific Methods

None.

Object-Specific Event Handler Properties

None.

color NN 6 IE 4 DOM 1
Read/Write
Sets the font color of all text contained by the font element.

Example

document.getElementById("myFont").color = "red";

Value

Case-insensitive hexadecimal triplet or plain-language color name as a string. See Appendix A for acceptable plain-language color names.

Default

Browser default.

face NN 6 IE 4 DOM 1
Read/Write
Provides a hierarchy of font faces to use for the content surrounded by the current font object. The browser looks for the first font face in the comma-delimited list of font face names until it either finds a match in the client system or runs out of choices, at which point the browser default font face is used. Font face names must match the system font face names exactly.

Example

document.getElementById("myFont").face = "Bookman, Times Roman, serif";

Value

One or more font face names in a comma-delimited list within a string. You may use real font names or the recognized generic faces: serif | sans-serif | monospace.

Default

Browser default.

size NN 6 IE 4 DOM 1
Read/Write
The size of the font in the 1-7 browser relative scale. For more accurate font size settings, see the style.fontSize property later in this chapter.

Example

document.getElementById("fontSpec2").size = "+1";

Value

Either an integer (as a quoted string) or a quoted relative value consisting of a + or - symbol and an integer value.

Default

3

form NN 2 IE 3 DOM 1

The form object reflects the form element. The form object can be referenced in all scriptable browsers via the value assigned to its tag name attribute or by the index of the forms array contained by every document. For browsers that support the id attribute (IE 4 and later and Netscape 6), you may also use the element object reference formats that employ the element's ID. To assemble a reference to a nested form control object (such as input and textarea element objects), you have a choice again of using backward compatible references that include the form object as part of the reference (as in document.formName.controlName); or in more modern browsers, you can reference the control element directly via its unique ID.

HTML Equivalent

<form>

Object Model Reference

[window.]document.formName
[window.]document.forms[i]
[window.]document.form["formName"]
[window.]document.getElementById("elementID")

Object-Specific Properties

`acceptCharset`	`action`	`elements[]`	`encoding`	`enctype`
`length`	`method`	`name`	`target`

Object-Specific Methods

handleEvent( )

reset( )

submit( )

Object-Specific Event Handler Properties

Events	IE Windows	IE Mac	NN	W3C DOM
`onreset`	3	3.01	3	2
`onsubmit`	3	3.01	3	2

acceptCharset NN 6 IE 5 DOM 1
Read/Write
A server advisory (for servers that are equipped to interpret the information) about which character sets it must receive from a client form.

Example

document.entryForm.acceptCharset= "it, es";

Value

Case-insensitive string from the character set registry (ftp://ftp.isi.edu/in-notes/iana/assignments/character-sets). Multiple character sets may be delimited by commas.

Default

Empty string, except in IE/Windows, with a default of UNKNOWN.

action NN 2 IE 3 DOM 1
Read/Write
Provides the URL to be accessed when a form is being submitted. Script control of this property lets one form be submitted to different server processes based on user interaction with the rest of the form. This property is read-only in IE 3.

Example

document.entryForm.action = "http://www.megacorp.com/cgi-bin/altEntry";

Value

Complete or relative URL.

Default

None.

elements[] NN 2 IE 3 DOM 1
Read-only
Returns an array of all form control objects contained by the current form.

Example

for (var i = 0; i < document.entryForm.elements.length; i++) { if (document.entryForm.elements[i].type == "text") { document.entryForm.elements[i].value = ""; } }

Value

Array of element object references.

Default

Array of length zero.

encoding NN 2 IE 3 DOM n/a
Read/Write
Specifies the MIME type for the data being submitted to the server with the form. For typical form submissions (where the method attribute is set to post), the default value is the proper content type. But if you change the action property for a form by script, consider whether you require a custom encoding for the purpose. This property is read-only in IE 3. See also the encType property.

Example

document.orderForm.encoding = "text/plain";

Value

Case-insensitive MIME type (content type) value as a string. For multiple items, a comma-delimited list is allowed in a single string.

Default

"application/x-www-form-urlencoded" in IE; empty string in Netscape 6.

enctype NN 6 IE 5(Mac)/6(Win) DOM 1
Read/Write
Provides the W3C DOM property name for what had been the encoding property of earlier DOM implementations. Current browsers support both property names. See the encoding property.

Example

document.orderForm.enctype = "text/plain";

Value

Case-insensitive MIME type (content type) value as a string. For multiple items, a comma-delimited list is allowed in a single string.

Default

"application/x-www-form-urlencoded"; empty string in Netscape 6.

length NN 2 IE 3 DOM 1
Read-only
Specifies the number of form control elements in the form. You can use this property in lieu of the length of the form's elements array.

Example

for (var i = 0; i < document.forms[0].length; i++) ... }

Value

Integer.

Default

0

method NN 2 IE 3 DOM 1
Read/Write
Forms may be submitted via two possible HTTP methods: get and post. These methods determine whether the form element data is sent to the server appended to the action attribute URL (get) or as a transaction message body (post). In practice, when the action and method attributes are not assigned in a form element, the form performs an unconditional reload of the same document, restoring form controls to their default values. Note that the method property is read-only in Internet Explorer 3.

Example

document.entryForm.method = "post";

Value

Either of the following constant values as a string: get | post.

Default

get

name NN 2 IE 3 DOM 1
Read/Write
This is the identifier associated with the form. This information is not submitted with the form, but a form's name is used in references to the form and nested form elements. Despite the modern standards' preference for the id attribute, many browsers still require that a form be assigned a name attribute to allow the form to be submitted.

Example

var firstFormName = document.forms[0].name;

Value

Case-sensitive identifier that follows the rules of identifier naming: it may contain no whitespace, cannot begin with a numeral, and should avoid punctuation except for the underscore character.

Default

None.

target NN 2 IE 3 DOM 1
Read/Write
The name of the window or frame that is to receive content returned by the server after the form is submitted. Such names are assigned to frames by the frame element's name attribute; for subwindows, the name is assigned via the second parameter of the window.open( ) method. Because the corresponding target attribute is not recognized by strict HTML or XHTML validators, you can omit the attribute to survive validation, yet still direct form results to another window by assigning a value to the form's target property in script.

Example

document.getElementById("myForm").target = "_blank";

Value

String value of the window or frame name, or any of the following constants (as a string): _parent | _self | _top | _blank. The _parent value targets the frameset to which the current document belongs; the _self value targets the current window; the _top value targets the main browser window, thereby eliminating all frames; and the _blank value (or any unused identifier, for that matter) creates a new window of default size.

Default

None (which implies the current window or frame).

handleEvent( ) NN |4| IE n/a DOM n/a
handleEvent(event)
Instructs the object to accept and process the event whose specifications are passed as the parameter to the method. The object must have an event handler for the event type to process the event.

Returned Value

None.

Parameters

event

A Navigator 4 event object.

reset( ) NN 3 IE 4 DOM 1
Performs the same action as a click of a reset-type input element. All form controls revert to their default values.

Returned Value

None.

Parameters

None.

submit( ) NN 2 IE 3 DOM 1
Performs the same action as a click of a submit-type input element. This method does not fire the onSubmit event handler in Navigator or recent versions of IE.

Returned Value

None.

Parameters

None.

forms NN 2 IE 3 DOM n/a

A collection of all form objects in the document.

Object Model Reference

document.forms

Object-Specific Properties

length

Object-Specific Methods

item( )

namedItem( )

tags( )

urns( )

Object-Specific Event Handler Properties

None.

length NN 2 IE 3 DOM 1
Read-only
Returns the number of elements in the collection.

Example

var howMany = document.forms.length;

Value

Integer.

item( ) NN 6 IE 4 DOM 1
item(index[, subindex]) item(index)
Returns a single object or collection of objects corresponding to the element matching the index value (or, optionally in IE/Windows, the index and subindex values).

Returned Value

One object or collection (array) of objects. If there are no matches to the parameters, the returned value is null.

Parameters

index

When the parameter is a zero-based integer (as required for Netscape 6), the returned value is a single element corresponding to the said numbered item in source code order (nested within the current element). When the parameter is a string (allowed by IE/Windows), the returned value is a collection of elements with id or name properties that match that string.

subindex

If you specify a string value for the first parameter (in IE/Windows), you may use the second parameter to specify a zero-based integer to retrieve a specific element from the collection with id or name properties that match the first parameter's string value.

namedItem( ) NN 6 IE 6 DOM 1
namedItem(IDOrName)
Returns a single object (in Netscape 6) or collection of objects corresponding to the element matching the parameter string value.

Returned Value

One object (in Netscape 6) or collection (array) of objects. If there are no matches to the parameters, the returned value is null.

Parameters

IDOrName

The string that contains the same value as the desired element's id or name attribute.

tags( ) NN n/a IE 4 DOM n/a
tags(tagName)
Returns a collection of objects (among all objects within the current collection) with tags that match the tagName parameter. Redundant here, because all elements have the same form tag.

Returned Value

A collection (array) of objects. If there are no matches to the parameters, the returned value is an array of zero length.

Parameters

tagName

A string that contains the element tag, as in document.forms.tags("form").

urns( ) NN n/a IE 5(Win) DOM n/a
urns(URN)
Returns a collection of nested element objects that have behaviors attached to them and URNs that match the URN parameter.

Returned Value

A collection (array) of objects. If there are no matches to the parameters, the returned value is an array of zero length.

Parameters

URN

A string with a local or external behavior file URN.

frame NN 6 IE 4 DOM 1

The frame object reflects the frame element, which can only be generated inside a frameset element. Be sure to distinguish the difference between the frame element object (described here) and the window object that a frame makes possible. Properties and methods of a frame element object tend to reflect the aspects associated with the HTML element and its attributes. The content of the frame is a window (a view in the W3C DOM terminology), which has been scriptable from the beginning, and contains a document. Reference a frame element object via its ID, even if you assign the same identifier to a frame element's id and name attributes. For example, from a script residing in one frame's document, reach the frame element object via:

parent.document.getElementById("TOCFrame")

But to reach the same frame in its capacity as a window (and thus access its scripts and document), the reference from the same script would be either of the following:

parent.TOCFrame
parent.frames["TOCFrame"]

If a script is processing a reference to the frame element object, you can jump the fence between the element object and its content via the contentDocument or contentWindow properties described below.

Be aware that references to frame objects shown in this section may not work properly in the Windows 95 version of Internet Explorer 4. Also, the windowRef placeholder may be filled with parent or top if the reference is in a script contained by a child frame.

HTML Equivalent

<frame>

Object Model Reference

[windowRef.]document.getElementById("frameID")

Object-Specific Properties

`allowTransparency`	`borderColor`	`contentDocument`	`contentWindow`
`dataFld`	`dataSrc`	`frameBorder`	`height`
`longDesc`	`marginHeight`	`marginWidth`	`name`
`noResize`	`scrolling`	`src`	`width`

Object-Specific Methods

None.

Object-Specific Event Handler Properties

None.

allowTransparency NN n/a IE 6 DOM n/a
Read/Write
Specifies whether the frame background can be transparent. Because an underlying frameset does not have a background color or image, this property is not helpful for a frame. It does apply, however, to the related iframe element object.

Value

Boolean value: true | false.

Default

false

borderColor NN n/a IE 4 DOM n/a
Read/Write
Color of the frame's border. Each browser and operating system may resolve conflicts between different colored borders differently, so test any changes your scripts make to the color of individual frame borders.

Example

parent.document.getElementById("myFrame").borderColor = "salmon";

Value

A hexadecimal triplet or plain-language color name. A setting of empty is interpreted as "#000000" (black). See Appendix A for acceptable plain-language color names.

Default

Varies with operating system.

contentDocument NN 6 IE n/a DOM 2
Read-only
Returns a reference to the document object loaded into the frame element object. Through that document object, you can access one of the document's elements via the getElementById( ) method, or access the containing window object via the document's defaultView property. For IE/Windows, use the contentWindow property to jump from frame element object to its content.

Example

var frameElem = parent.document.getElementById("myFrame"); var doc = frameElem.contentDocument;

Value

Reference to a document node.

Default

Current document node.

contentWindow NN 7 IE 5.5(Win) DOM n/a
Read-only
Returns a reference to the window object generated by the frame element. Through that window object, you can access the document object and then any one of the document's elements. For Netscape 6, use the contentDocument property to jump from frame element object to its content. But if you are trying to reach script variables or functions in the frame, the contentWindow (or W3C DOM-friendly and Netscape 6-compatible contentDocument.defaultView) provides access to the script context.

Example

var frameElem = parent.document.getElementById("myFrame"); var win = frameElem.contentWindow;

Value

Reference to a window node.

Default

Current window node.

dataFld NN n/a IE 4 DOM n/a
Read/Write
Used with IE data binding to associate a remote data source column name to the frame's src attribute. A datasrc attribute must also be set for the element. Setting both the dataFld and dataSrc properties to empty strings breaks the binding between element and data source. Works only with text file data sources in IE 5/Mac.

Example

parent.document.getElementById("myFrame").dataFld = "srcURL";

Value

Case-sensitive identifier of the data source column.

Default

None.

dataSrc NN n/a IE 4 DOM n/a
Read/Write
Used with IE data binding to specify the ID of the page's object element that loads the data source object for remote data access. Setting both the dataFld and dataSrc properties to empty strings breaks the binding between element and data source. Works only with text file data sources in IE 5/Mac.

Example

parent.document.getElementById("myFrame").dataSrc = "DBSRC3";

Value

Case-sensitive identifier of the data source.

Default

None.

frameBorder NN 6 IE 4 DOM 1
Read/Write
Controls whether an individual frame within a frameset displays a border. Controlling individual frame borders appears to be a problem for most browsers in most operating system versions. Turning off the border of one frame may have no effect if all adjacent frames have their borders on. Feel free to experiment with the effects of turning some borders on and some borders off, but be sure to test the final effect on all browsers and operating systems used by your audience. Rely more comfortably on the frameborder attribute or frameBorder property of the entire frameset.

Example

parent.document.getElementById("frame2").frameBorder = "no";

Value

String values of 1 (on) and 0 (off) as well as yes and no.

Default

yes

height, width NN n/a IE 4 DOM n/a
Read-only
Return the height and width in pixels of the frame. Dimensions include frame chrome (scrollbars). Adjust a frame's size via the frameset object's rows or cols properties.

Example

var frHeight = parent.document.getElementById("myFrame").height;

Value

Integer.

Default

Current height and width.

longDesc NN 6 IE 5(Mac)/6(Win) DOM 1
Read/Write
Reflects the longDesc attribute of the frame element. Version 6 browsers provide no significant functionality for this attribute or property.

Value

URL String.

Default

Empty string.

marginHeight, marginWidth NN 6 IE 4 DOM 1
Read/Write
Indicate the number of pixels between the inner edge of a frame and the content rendered inside the frame. The marginHeight property controls space along the top and (when scrolled) bottom edges of a frame; the marginWidth attribute controls space on the left and right edges of a frame.
Without any prompting, browsers automatically insert a small margin inside a frame (generally between 8 and 14 pixels depending on browser and operating system). But if you attempt to override the default behavior, be aware that setting any one of these two attributes causes the value of the other to go to zero. Therefore, unless you want the content to be absolutely flush with various frame edges, you need to assign values to both attributes.

Example

parent.document.getElementById("myFrame").marginHeight = 14; parent.document.getElementById("myFrame").marginWidth = 5;

Value

Positive integer value or zero.

Default

Varies with browser and operating system.

name NN 6 IE 4 DOM 1
Read/Write
This is the identifier associated with a frame for use as the value assigned to target attributes or as script references to the frame. The value is usually assigned via the name attribute, but it can be modified by script if necessary.

Example

parent.document.getElementById("myFrame").name = "results";

Value

Case-sensitive identifier that follows the rules of identifier naming: it may contain no whitespace, cannot begin with a numeral, and should avoid punctuation except for the underscore character.

Default

None.

noResize NN 6 IE 4 DOM 1
Read/Write
Indicates whether the frame can be resized by the user. All border edges of the affected frame element become locked, meaning all edges that extend to other frames in the frameset remain locked as well.

Example

parent.document.getElementById("myFrame").noResize = "true";

Value

Boolean value: true | false.

Default

false

scrolling NN 6 IE 4 DOM 1
Read/Write
Controls the treatment of scrollbars for a frame when the content exceeds the visible area of the frame. You can force a frame to display scrollbars at all times or never. Or you can let the browser determine the need for scrolling. In many supporting browsers, changing the value of this property has no effect.

Example

parent.document.getElementById("mainFrame").scrolling = "yes";

Value

String values of 1 (on) and 0 (off) as well as yes, no, and auto.

Default

auto

src NN 6 IE 4 DOM 1
Read/Write
Provides the URL of the external content file loaded into the frame. To change the content, assign a new URL to the property. For cross-platform applications, you can also set the location.href property of the frame to load a different document into the frame using window-related references (parent.frameName.location.href = "newDoc.html").

Example

parent.document.getElementById("myFrame").src = "images/altNavBar.jpg";

Value

Complete or relative URL as a string.

Default

None.

width
See height.

frames NN 2 IE 3 DOM n/a

A collection of all frame objects defined in the window or frame. Only the first-level frames are exposed to the frameset object. To find further nested frames requires digging into the frames collections of nested frameset objects. The collection also includes iframe elements defined in the window's document. Be aware that the frames object does not work as expected in some sub-versions of Netscape 6.

Object Model Reference

[windowRef.]frames

Object-Specific Properties

length

Object-Specific Methods

item( )

namedItem( )

length NN 2 IE 3 DOM n/a
Read-only
Returns the number of child frames defined in the frameset whose window starts the reference. Broken in some sub-versions of Netscape 6.

Example

var howMany = parent.frames.length;

Value

Integer.

item( ) NN n/a IE 4 DOM n/a
item(index)
Returns a single window object corresponding to the element matching the index value in source code order.

Returned Value

window object.

Parameters

index

A zero-based integer.

namedItem( ) NN n/a IE 6 DOM n/a
namedItem(IDOrName)
Returns a single object or collection of objects corresponding to the element matching the parameter string value.

Returned Value

One object or collection (array) of objects. If there are no matches to the parameters, the returned value is null.

Parameters

IDOrName

The string that contains the same value as the desired element's id or name attribute.

frameset NN 6 IE 4 DOM 1

The frameset object reflects the frameset element. Be sure to distinguish the difference between the frameset element object (described here) and the window object that a frameset makes possible. Properties and methods of a frameset element object tend to reflect the aspects associated with the HTML element and its attributes. The content of the frameset element is a window (a view in the W3C DOM terminology), which has been scriptable from the beginning, and contains a document (although with no renderable elements beyond the nested frame elements). Reference a frameset element object via its ID. For example, from a script residing in one frame's document, reach the frameset element object via:

parent.document.getElementById("myFrameset")

But to reach the frameset's window (and thus access its scripts and document), the reference from the same script would be either of the following:

parent
top

If a script is processing a reference to the frameset element object, you can jump the fence between the element object and its content via the ownerDocument property of the element (described among the shared properties earlier in this chapter).

Be aware that references to frameset objects shown in this section may not work properly in the Windows 95 version of Internet Explorer 4. Also, the windowRef placeholder may be filled with parent or top if the reference is in a script contained by a child frame.

HTML Equivalent

<frameset>

Object Model Reference

[windowRef.]document.getElementById("framesetID")

Object-Specific Properties

border

borderColor

cols

frameBorder

frameSpacing

rows

Object-Specific Methods

None.

Object-Specific Event Handler Properties

Handler	IE Windows	IE Mac	NN	W3C DOM
`onafterprint`	5	n/a	n/a	n/a
`onbeforeprint`	5	n/a	n/a	n/a
`onbeforeunload`	4	n/a	n/a	n/a
`onload`	3	3.01	2	2
onresize	4	4	4	n/a
`onunload`	3	3.01	2	2

border NN n/a IE 4 DOM n/a
Read/Write
Thickness of the spaces between frames in a frameset in pixels. Only the outermost frameset element of a system of nested framesets responds to the border property setting. Internet Explorer treats the default thicknesses for Windows and Macintosh differently, so be aware that the same value may look different on each operating system platform.

Example

top.document.getElementById("myFrameset").border = 4;

Value

An integer value. A setting of zero eliminates the border entirely. While the value is supposed to represent the precise pixel thickness of borders in the frameset, this is not entirely true for all operating systems or browsers.

Default

6 (IE Windows); 1 (IE Mac).

borderColor NN n/a IE 4 DOM n/a
Read/Write
Color of borders between frames of the frameset. The borderColor property of an individual frame overrides the frameset object's setting.

Example

parent.document.getElementById("myFrameset").borderColor = "salmon";

Value

A hexadecimal triplet or plain-language color name. A setting of empty is interpreted as "#000000" (black). See Appendix A for acceptable plain-language color names.

Default

Varies with operating system.

cols NN 6 IE 4 DOM 1
Read/Write
Defines the sizes or proportions of the column arrangement of frames in a frameset. Column size is defined in one of three ways:

An absolute pixel size

A percentage of the width available for the entire frameset

A wildcard (*) to represent all available remaining space after other pixels and percentages have been accounted for

Exercise extreme care when scripting a change to this property. Altering the composition of a frameset on the fly might disrupt scripts that communicate across frames. Reducing the number of columns may destroy documents whose scripts or objects support scripts in other frames or the parent. It is safest to maintain the same number of columns, but use this property to adjust the widths of existing frame columns. Early versions of Netscape 6 may not render changes correctly. Also, if your scripts rely on the frameset's onresize event handler, be sure to test on as many platforms as possible that the event is firing in response to script changes of these properties.

Example

parent.document.getElementById("framesetter").cols = "40%,60%";

Value

Comma-separated list (as a string) of pixel, percentage, or wildcard (*) values. Internet Explorer 4 for the Macintosh exhibits incorrect behavior with some combinations that include a wildcard value.

Default

100%

frameBorder NN n/a IE 4 DOM n/a
Read/Write
Controls whether the frameset displays borders between frames. Adjusting this property does not dynamically change the border visibility in Internet Explorer for Windows.

Example

parent.document.getElementById("framesetter").frameBorder = "no";

Value

Internet Explorer 4 accepts the string values of 1 (on) and 0 (off) as well as yes and no.

Default

yes

frameSpacing NN n/a IE 4 DOM n/a
Read/Write
The amount of spacing in pixels between frames within a frameset. Adjusting this property does not dynamically change the frame spacing in Internet Explorer for Windows.

Example

parent.document.getElementById("framesetter").frameSpacing = 5;

Value

Integer.

Default

2

rows NN 6 IE 4 DOM 1
Read/Write
The sizes or proportions of the row arrangement of frames in a frameset. See the cols property for additional details of selecting values for the rows property.

Example

document.getElementById("myFrameset").rows = "20%, 300, *";

Value

String of comma-delimited list of pixel or percentage values, or the * wildcard character.

Default

None.

h1, h2, h3, h4, h5, h6 NN 6 IE 4 DOM 1

These objects reflect the HTML header elements of the same names. See the description of the elements in Chapter 8 for examples of how various browsers render each of the header sizes.

HTML Equivalent

<h1>
<h2>
<h3>
<h4>
<h5>
<h6>

Object Model Reference

[window.]document.getElementById("elementID")

Object-Specific Properties

align

Object-Specific Methods

None.

Object-Specific Event Handler Properties

None.

align NN 6 IE 4 DOM 1
Read/Write
Defines the horizontal alignment of the element within its surrounding container.

Example

document.getElementById("myHeader").align = "center";

Value

Any of the three horizontal alignment constants: center | left | right.

Default

left

head NN 6 IE 4 DOM 1

The head object reflects the head element. Accessing this object via its ID reference may not work in the Windows version of IE 4. You should use the document.all.tags[] collection instead. For IE 5 and later and Netscape 6, you can reference the element via its ID or the document.getElementsByTagName("head")[0] array reference.

HTML Equivalent

<head>

Object Model Reference

[window.]document.getElementById("elementID")
[window.]document.getElementsByTagName("head")[0]

Object-Specific Properties

profile

Object-Specific Methods

None.

Object-Specific Event Handler Properties

None.

profile NN 6 IE 4 DOM 1
Read-only
Returns the URL string assigned to the optional profile attribute. As of Version 6 browsers, nothing special occurs as a result of assigning this attribute.

Value

URL string.

Default

Empty string.

history NN 2 IE 3 DOM n/a

During a browser session, the browser uses the history object to maintain a list of URLs visited by the user. This list (stored as an array) is used by the browser to assist with navigation via the Back and Forward buttons. Due to the sensitive nature of the private information stored in the history object, not many of the details are exposed to scripts that could capture such information and surreptitiously submit it to a server. In more recent browser versions, each window maintains its own history object.

To answer a frequently-asked question: no, you cannot block or disable the Back button's action. At most, you can prevent the current page from being entered into the browser's history when a user clicks on a link from the page. Accomplish this by scripting the links with the location.replace( ) navigation method. Navigator 4 and later (with signed scripts and the user's explicit approval) can remove the toolbar from the browser window (see the locationbar object discussion). Or, you can open a new window without the toolbar (see the window.open( ) method).

Object Model Reference

[window.]history

Object-Specific Properties

current

length

next

previous

Object-Specific Methods

back( )

forward( )

go( )

item( )

Object-Specific Event Handler Properties

None.

current, next, previous NN 4 IE n/a DOM n/a
Read-only
The URL of the current, next, and previous URLs in the history array. This information is private and can be retrieved in Navigator 4 or later only with signed scripts and the user's approval. Signed scripts are beyond the scope of this book, but a good JavaScript book should show you how to create and program signed scripts.

Example

netscape.security.PrivilegeManager.enablePrivilege("UniversalBrowserRead"); var prevURL = parent.otherFrame.history.previous; netscape.security.PrivilegeManager.revertPrivilege("UniversalBrowserRead");

Value

URL string.

Default

None.

length NN 2 IE 3 DOM n/a
Read-only
The number of items in the history list. Even with this information, you are not allowed to extract a specific history entry except with signed scripts and the user's permission in Navigator 4 or later.

Example

if (history.length > 4) { ... }

Value

Integer.

Default

None.

back( ) NN 2 IE 3 DOM n/a
The basic action is to navigate to the previously viewed document, similar to the click of the browser's Back button. In Navigator 4 or later, however, you can direct the back( ) method to a specific window or frame, thus bypassing the default behavior of the Back button. For example, repeated calls to parent.otherFrame.history.back( ) eventually run out of history for the frame and then cease to do anything further. On the other hand, repeated calls to top.history.back( ) are the same as clicking the Back button, conceivably backing out of the frameset entirely if it wasn't the first document loaded in the current browser session.

Returned Value

None.

Parameters

None.

forward( ) NN 2 IE 3 DOM n/a
The basic action is to navigate to the same URL that the browser's Forward button leads to (if it is active). Similar cautions about the window's history from the history.back( ) method apply here, as well.

Returned Value

None.

Parameters

None.

go( ) NN 2 IE 3 DOM n/a
go(stepCount | "URL")
Navigates to a specific position in the history listing.

Returned Value

None.

Parameters

stepCount

An integer representing how many items away from the current listing the browser should use to navigate. A value of zero causes the current page to reload; a value of -1 is the same as back( ); a value of -2 is the URL two steps back from the current item in history. A bug in IE 3 causes all values other than 0 to be treated as -1.

URL

A URL or (in Navigator) document title stored in the history listing.

item( ) NN 4 IE n/a DOM n/a
item(itemNumber)
Returns the URL at a specific location in the history list. Requires Netscape signed scripts and the user's explicit permission to retrieve this private information.

Returned Value

URL String.

Parameters

itemNumber

An integer representing the number of item within the history list. The range of acceptable values is 0 through the history.length minus 1.

hr	`NN 6` IE 4 DOM 1

The hr object reflects the hr element.

HTML Equivalent

<hr>

Object Model Reference

[window.]document.getElementById("elementID")

Object-Specific Properties

align

color

noShade

size

width

Object-Specific Methods

None.

Object-Specific Event Handler Properties

None.

align NN 6 IE 4 DOM 1
Read/Write
Defines the horizontal alignment of the element within its surrounding container.

Example

document.getElementById("myHR").align = "center";

Value

Any of the three horizontal alignment constant strings: center | left | right.

Default

center

color NN n/a IE 4 DOM n/a
Read/Write
Sets the color scheme of the horizontal rule. If the rule is rendered in 3-D, complementary colors are automatically assigned to the shaded area.

Example

document.getElementById("myHR").color = "red";

Value

Case-insensitive hexadecimal triplet or plain-language color name as a string. See Appendix A for acceptable plain-language color names.

Default

Browser default.

noShade NN 6 IE 4 DOM 1
Read/Write
Indicates whether the browser should render the rule as a flat (not 3-D) line. In Internet Explorer only, if you set the color property, the browser changes the default line style to a no-shade style. In IE, once noShade is set to true, shading cannot later be restored.

Example

document.getElementById("bar2").noShade = "true";

Value

Boolean value: true | false.

Default

false

size NN 6 IE 4 DOM 1
Read/Write
Provides the thickness in pixels of the horizontal rule.

Example

document.getElementById("rule2").size = 3;

Value

Positive integer.

Default

2

width NN 6 IE 4 DOM 1
Read/Write
Provides the width of the rule either in pixels (as an integer) or a percentage (as a string) of the next outermost block-level container.

Example

document.getElementById("bar3").width = "70%";

Value

Integer (for pixels) or string (for pixels or percentage).

Default

100%

html NN 6 IE 4 DOM 1

The html object reflects the html element.

HTML Equivalent

<html>

Object Model Reference

[window.]document.getElementById("elementID")
[window.]document.body.parentNode
[window.]document.documentElement

Object-Specific Properties

version

Object-Specific Methods

None.

Object-Specific Event Handler Properties

None.

version NN 6 IE 5(Mac)/6(Win) DOM 1
Read/Write
Reflects the deprecated version attribute of the html element. Present in modern browsers, but not functional. See the DocumentType object.

Value

String.

Default

Empty string.

HTMLCollection NN 6 IE 5(Mac)/6(Win) DOM 1

The HTMLCollection object is an abstract representation in the W3C DOM of any collection of HTML element objects, all of which exist in the same document tree and have the same tag. For example, in the eyes of the W3C DOM, the document.images array is an HTMLCollection object. All entries are img element object references. JavaScript treats such collections as arrays for access to individual entries via array notation, along with the help of the HTMLCollection's sole property, length. Alternatively, you can use the two methods (item( ) and namedItem( )) to reference a single entry in the collection. All instances of the HTMLCollection object (such as document.images) inherit the property and methods listed below from the abstract HTMLCollection object. See descriptions of each instance in this chapter (anchors, applets, areas, cells, elements, forms, images, links, options, rows, tBodies, and non-W3C DOM element collections all, children, embeds, and frames).

Object-Specific Properties

length

Object-Specific Methods

item( )

namedItem( )

Object-Specific Event Handler Properties

None.

length NN 6 IE 5(Mac)/6(Win) DOM 1
Read-only
Returns the number of elements in the collection.

Example

var howMany = document.myForm.elements.length;

Value

Integer.

item( ) NN 6 IE 5(Mac)/6(Win) DOM 1
item(index)
Returns one object from the collection corresponding to the object matching the index value in source code order. IE implements another variation of this method for some (but not all) of its collections with an optional secondary parameter.

Returned Value

Reference to an element object. If there are no matches to the parameter, the returned value is null.

Parameters

index

A zero-based integer corresponding to the specified item in source code order.

namedItem( ) NN 6 IE 5(Mac)/6(Win) DOM 1
namedItem(IDOrName)
Returns one object from the collection corresponding to the object matching the parameter string value.

Returned Value

Reference to an element object. If there are no matches to the parameters, the returned value is null.

Parameters

IDOrName

The string that contains the same value as the desired filter's name.

iframe NN 6 IE 4 DOM 1

The iframe object reflects the iframe element. Be aware that, in Internet Explorer, a number of properties defined for this object have no effect on the object nor any default value, but are implemented because the element shares its internal structure with other elements that use those properties.

HTML Equivalent

<iframe>

Object Model Reference

[window.]document.getElementById("elementID")

Object-Specific Properties

`align`	`allowTransparency`	`border`	`borderColor`	`contentDocument`
`contentWindow`	`dataFld`	`dataSrc`	`frameBorder`	`frameSpacing`
`height`	`hspace`	`longDesc`	`marginHeight`	`marginWidth`
`name`	`noResize`	`scrolling`	`src`	`vspace`
`width`

Object-Specific Methods

None.

Object-Specific Event Handler Properties

None.

align NN 6 IE 4 DOM 1
Read/Write
Defines how the element is aligned relative to surrounding text content. Most values set the vertical relationship between the element and surrounding text. For example, to align the bottom of the element with the baseline of the surrounding text, the align property value would be baseline. An element can be "floated" along the left or right margin to let surrounding text wrap around the element.

Example

document.getElementById("myIframe").align = "absmiddle";

Value

Any of the following alignment constant values (as a string): absbottom | absmiddle | baseline | bottom | right | left | none | texttop | top.

Default

bottom

allowTransparency NN n/a IE 6 DOM n/a
Read/Write
Specifies whether the iframe background can be transparent. For the background of the main document to show through both the iframe and its document, the document's background-color style attribute must be set to transparent.

Example

document.getElementById("myIframe").allowTransparency = true;

Value

Boolean value: true | false.

Default

false

border NN n/a IE 4(Win) DOM n/a
Read/Write
Although defined for the iframe element object in IE/Windows, the border property has no value nor does assigning a value affect the appearance of the element.

borderColor NN n/a IE 4 DOM n/a
Read/Write
Although defined for the iframe element object in IE, the borderColor property has no value. Assigning a color value does draw a thin border around the iframe's rectangle on the Macintosh, but has no effect in Windows.

contentDocument NN 6 IE n/a DOM 2
Read-only
Returns a reference to the document object loaded into the iframe element object. Through that document object, you can access one of the document's elements via the getElementById( ) method, or access the containing window object via the document's defaultView property. For IE/Windows, use the contentWindow property to jump from iframe element object to its content.

Example

var iframeElem = parent.document.getElementById("myIframe"); var doc = iframeElem.contentDocument;

Value

Reference to a document node.

Default

Current document node.

contentWindow NN 7 IE 5.5(Win) DOM n/a
Read-only
Returns a reference to the window object generated by the iframe element. Through the window object, you can access the document object and then any one of the document's elements. For Netscape 6, use the contentDocument property to jump from iframe element object to its content. If you are trying to reach script variables or functions in the frame, the contentWindow (or W3C DOM-friendly and Netscape 6-compatible contentDocument.defaultView) provides access to the script context.

Example

var iframeElem = parent.document.getElementById("myIframe"); var win = iframeElem.contentWindow;

Value

Reference to a window node.

Default

Current window node.

dataFld NN n/a IE 4 DOM n/a
Read/Write
Used with IE data binding to associate a remote data source column name with the value of the src property. A datasrc attribute must also be set for the element. Setting both the dataFld and dataSrc properties to empty strings breaks the binding between element and data source. Works only with text file data sources in IE 5/Mac.

Example

document.getElementById("myIframe").dataFld = "frameURL";

Value

Case-sensitive identifier of the data source column.

Default

None.

dataSrc NN n/a IE 4 DOM n/a
Read/Write
Used with IE data binding to specify the ID of the page's object element that loads the data source object for remote data access. Setting both the dataFld and dataSrc properties to empty strings breaks the binding between element and data source. Works only with text file data sources in IE 5/Mac.

Example

document.getElementById("myIframe").dataSrc = "DBSRC3";

Value

Case-sensitive identifier of the data source.

Default

None.

frameBorder NN n/a IE 4 DOM n/a
Read/Write
This property should control whether the frame displays a border. In practice, the property has no effect on the visual appearance of an inline frame.

frameSpacing NN n/a IE 4 DOM n/a
Read/Write
The amount of spacing in pixels between frames within a frameset. This property has no effect on an inline frame in Internet Explorer.

height, width NN 6 IE 4 DOM 1
Read/Write
Provide the pixel or percentage measure of the iframe element's height and width.

Example

document.getElementById("myIframe").height = "200"; document.getElementById("myIframe").width = "500";

Value

Length string.

Default

300 (width); 150 (height).

hspace, vspace NN n/a IE 4 DOM n/a
Read/Write
Provide the pixel measure of horizontal and vertical margins surrounding an inline frame. The hspace property affects the left and right edges of the element equally; the vspace property affects the top and bottom edges of the element equally. These margins are not the same as margins set by style sheets, but they have the same visual effect.

Example

document.getElementById("myIframe").hspace = 5; document.getElementById("myIframe").vspace = 8;

Value

Integer of pixel count.

Default

0

longDesc NN 6 IE 5(Mac)/6(Win) DOM 1
Read/Write
Reflects the longDesc attribute of the iframe element. Version 6 browsers provide no significant functionality for this attribute or property.

Value

URL string.

Default

Empty string.

marginHeight, marginWidth NN 6 IE 4 DOM 1
Read/Write
Control the number of pixels between the inner edge of a frame and the content rendered inside the frame. An adjustment to either property sets the other property to zero, eliminating the default margin provided by the browser. Not reliable in IE 4 for Windows, but operable in all other supported versions.

Value

Positive integer value or zero.

Default

Varies with browser and operating system.

name NN 6 IE 4 DOM 1
Read/Write
This is the identifier associated with an iframe for use as the value assigned to target attributes or as script references to the frame. The value is usually assigned via the name attribute, but it can be modified by script if necessary.

Value

Case-sensitive string identifier that follows the rules of identifier naming: it may contain no whitespace, cannot begin with a numeral, and should avoid punctuation except for the underscore character.

Default

None.

noResize NN n/a IE 4 DOM n/a
Read/Write
Specifies whether the frame can be resized by the user. Not applicable to an iframe element.

scrolling NN 6 IE 4 DOM 1
Read/Write
Specifies the treatment of scrollbars for an iframe when the content exceeds the visible area of the iframe. You can force an iframe to display scrollbars at all times or never. Or you can let the browser determine the need for scrolling. It is not uncommon for browsers to ignore scripted changes to this property. Make your choice in the element's scrolling attribute.

Example

document.getElementById("myIframe").scrolling = "no";

Value

One of three constants (as a string): auto | no | yes.

Default

auto

src NN 6 IE 4 DOM 1
Read/Write
Indicates the URL of the external content file loaded into the current element. To change the content, assign a new URL to the property.

Example

document.getElementById("myIframe").src = "section2.html";

Value

Complete or relative URL as a string.

Default

None.

ellievspace
See hspace.

width
See height.

images NN 3 IE 4 DOM 1

A collection (array) of all img objects contained by the document. This object is implemented only in browser versions that treat images as objects. Therefore, you can use the existence of this array object as a conditional switch surrounding statements that swap or preload images:

if (document.images) {
    // process img element objects here
}

Internet Explorer 3.01 for the Macintosh provided support for images as objects.

Object Model Reference

document.images

Object-Specific Properties

length

Object-Specific Methods

item( )

namedItem( )

tags( )

urns( )

length NN 3 IE 4 DOM 1
Read-only
Returns the number of elements in the collection.

Example

var howMany = document.images.length;

Value

Integer.

item( ) NN 6 IE 4 DOM 1
item(index[, subindex]) item(index)
Returns a single image object or collection of image objects corresponding to the element matching the index value (or, optionally in IE, the index and subindex values).

Returned Value

One object or collection (array) of objects. If there are no matches to the parameters, the returned value is null.

Parameters

index

When the parameter is a zero-based integer (required in Netscape 6), the returned value is a single element corresponding to the said numbered item in source code order (nested within the current element). When the parameter is a string, the returned value is a collection of elements with id or name properties that match that string.

subindex

If you specify a string value for the first parameter (IE only), you may use the second parameter to specify a zero-based integer to retrieve a specific element from the collection with id or name properties that match the first parameter's string value.

namedItem( ) NN 6 IE 6 DOM 2
namedItem(IDOrName)
Returns a single object corresponding to the element matching the parameter string value.

Returned Value

One object reference. If there are no matches to the parameters, the returned value is null.

Parameters

IDOrName

The string that contains the same value as the desired element's id or name attribute.

tags( ) NN n/a IE 4 DOM n/a
tags(tagName)
Returns a collection of objects (among all objects within the current collection) with tags that match the tagName parameter. Redundant here, because all elements have the same img tag.

Returned Value

A collection (array) of objects. If there are no matches to the parameters, the returned value is an array of zero length.

Parameters

tagName

A string that contains the element tag, as in document.images.tags("img").

urns( ) NN n/a IE 5(Win) DOM n/a
urns(URN)
Returns a collection of nested element objects that have behaviors attached to them and URNs that match the URN parameter.

Returned Value

A collection (array) of objects. If there are no matches to the parameters, the returned value is an array of zero length.

Parameters

URN

A string with a local or external behavior file URN.

img NN 3 IE 4 DOM 1

The img object reflects the img element. This object shares the same properties as the static Image object, which you can use to pre-cache images without rendering them on the page.

HTML Equivalent

<img>

Object Model Reference

[window.]document.imageName
[window.]document.images[i]
[window.]document.images["imageName"]
[window.]document.getElementById("elementID")

Object-Specific Properties

`align`	`alt`	`border`	`complete`
`dataFld`	`dataFormatAs`	`dataSrc`	`dynsrc`
`fileCreatedDate`	`fileModifiedDate`	`fileSize`	`fileUpdatedDate`
`height`	`href`	`hspace`	`isMap`
`longDesc`	`loop`	`lowsrc`	`lowSrc`
`mimeType`	`name`	`nameProp`	`naturalHeight`
`naturalWidth`	`protocol`	`prototype`	`src`
`start`	`useMap`	`vspace`	`width`
`x`	`y`

Object-Specific Methods

None.

Object-Specific Event Handler Properties

Events	IE Windows	IE Mac	NN	W3C DOM
`onabort`	4	4	3	2
`onerror`	4	4	3	2
`onload`	4	4	3	n/a

align NN 6 IE 4 DOM 1
Read/Write
Defines how the element is aligned relative to surrounding text content. Most values set the vertical relationship between the element and surrounding text. For example, to align the bottom of the element with the baseline of the surrounding text, the align property value would be baseline. An element can be "floated" along the left or right margin to let surrounding text wrap around the element.

Example

document.logoImg.align = "absmiddle";

Value

Any of the following alignment constant values (as a string): absbottom | absmiddle | baseline | bottom | right | left | none | texttop | top.

Default

bottom

alt NN 6 IE 4 DOM 1
Read/Write
Indicates the text to be displayed (or spoken) where the img element appears on the page when a browser does not download graphics (or is waiting for the image to download). The text is usually a brief description of what the image is. Be aware that the size of the image area on the page may limit the amount of assigned text visible on the page. Make sure the description is readable.

Example

document.corpLogo.alt = "MegaCorp Logo";

Value

String value.

Default

None.

border NN 3 IE 4 DOM 1
Read/Write (IE and Netscape 6)
Provides the thickness of the border around an element (in pixels). This property is read-only in Navigator 4.

Example

document.logoImage.border = 4;

Value

An integer value. A setting of zero removes the border entirely.

Default

0

complete NN 3 IE 4 DOM n/a
Read-only
Reveals whether the img element's src or lowsrc image file has fully loaded. Note that Navigator 4 provides an incorrect true reading before the image has completely loaded.

Example

if (document.logo.complete) { // safe to process the image object }

Value

Boolean value: true | false.

Default

false

dataFld NN n/a IE 4 DOM n/a
Read/Write
Used with IE data binding to associate a remote data source column name with the src property of the img object. A datasrc attribute must also be set for the element. Setting both the dataFld and dataSrc properties to empty strings breaks the binding between element and data source. Works only with text file data sources in IE 5/Mac.

Example

document.myImage.dataFld = "logoURL";

Value

Case-sensitive identifier of the data source column.

Default

None.

dataFormatAs NN n/a IE 4 DOM n/a
Read/Write
This property is a member of the img element object in IE, but does not apply to img because data binding values are linked to the src attribute, rather than rendered content.

dataSrc NN n/a IE 4 DOM n/a
Read/Write
Used with IE data binding to specify the ID of the page's object element that loads the data source object for remote data access. Setting both the dataFld and dataSrc properties to empty strings breaks the binding between element and data source. Works only with text file data sources in IE 5/Mac.

Example

document.myImage.dataSrc = "DBSRC3";

Value

Case-sensitive identifier of the data source.

Default

None.

dynsrc NN n/a IE 4 DOM n/a
Read/Write
URL of a video clip to be displayed through the img element. Changing this property loads a new video clip into the image object. See also the loop property for controlling the frequency of video clip play.

Example

document.images[3].dynsrc = "snowman.avi";

Value

Complete or relative URL as a string.

Default

None.

fileCreatedDate NN n/a IE 4(Win)/5(Mac) DOM n/a
Read-only
Returns a string of the date (but not the time) that the server (or local filesystem) reports the currently-loaded file was created. By loading an image into a nonrendered Image object, a script can determine the date of the image (but more accurately from the fileUpdatedDate property). IE 4's value is a long date format, but starting with IE 5, the date information is formatted as mm/dd/yyyy. The value may be corrupted if the server supplies the data in a format that IE does not expect. Implemented in IE 5/Mac, but the value is empty.

Example

var dateObj = new Date(document.logoImg.fileCreatedDate);

Value

Date string.

Default

None.

fileModifiedDate NN n/a IE 4(Win)/5(Mac) DOM n/a
Read-only
Returns a string of the date (but not the time) that the server (or local filesystem) reports the currently-loaded file was most recently modified. IE 4's value is a long date format, but starting with IE 5, the date information is formatted as mm/dd/yyyy. The value may be corrupted or incorrect if the server supplies the data in a format that IE does not expect. Implemented in IE 5/Mac, but the value is empty.

Example

var dateObj = new Date(document.logoImg.fileModifiedDate);

Value

Date string.

Default

None.

fileSize NN n/a IE 4(Win)/5(Mac) DOM n/a
Read-only
Returns the number of bytes for the size of the currently-loaded image. IE for Windows returns this value as a string, while IE for Macintosh returns a number value (although its value is 0).

Example

var byteCount = parseInt(document.fileSize, 10);

Value

Integer as string (Windows) or number (Mac).

Default

None.

fileUpdatedDate NN n/a IE 5(Mac)/5.5(Win) DOM n/a
Read-only
For an image file retrieved from a server, this property may more accurately reflect the date the file was last uploaded to the server than the other date-related properties. Local files commonly return an empty string. Implemented in IE 5/Mac, but the value is empty.

Example

var dateObj = new Date(document.logoImg.fileUpdatedDate);

Value

Date string.

Default

None.

height, width NN 3 IE 4 DOM 1
Read/Write (IE and Netscape 6)
Provide the height and width in pixels of the image rendered in the img element. Changes to these values are immediately reflected in reflowed content on the page in Internet Explorer 4 (or later) and Netscape 6. Be aware that images scale to fit the new dimension.

Example

document.prettyPicture.height = 250;

Value

Integer.

Default

None.

href NN n/a IE 4 DOM n/a
Read/Write
The URL specified by the element's src attribute. Identical to, and deprecated in favor of, the src property.

Example

document.logoImage.href = "images/fancyLogo.gif";

Value

String of complete or relative URL.

Default

None.

hspace, vspace NN 3 IE 4 DOM 1
Read/Write (IE and Netscape 6)
Provide the pixel measure of horizontal and vertical margins surrounding an image object. The hspace property affects the left and right edges of the element equally; the vspace affects the top and bottom edges of the element equally. These margins are not the same as margins set by style sheets, but they have the same visual effect.

Example

document.logo.hspace = 5; document.logo.vspace = 8;

Value

Integer of pixel count.

Default

0 (IE), -1 (Netscape 6).

isMap NN 6 IE 4 DOM 1
Read/Write
Indicates whether the img element is acting as a server-side image map. For an image to be a server-side image map, it must be wrapped with an a element whose href attribute points to the URL of the CGI program that knows how to interpret the click coordinate information. The browser appends coordinate information about the click to the URL as a get form method appends form element data to the action attribute URL.
More recent browsers allow client-side image maps (see the useMap property), which operate more quickly for the user, because there is no communication with the server to carry out the examination of the click coordinate point.

Example

document.navMap.isMap = true;

Value

Boolean value: true | false.

Default

false

longDesc NN 6 IE 5(Mac)/6(Win) DOM 1
Read/Write
Reflects the longDesc attribute of the img element. Version 6 browsers provide no significant functionality for this attribute or property.

Value

URL string.

Default

Empty string.

loop NN n/a IE 4 DOM n/a
Read/Write
If you specify a video clip with the dynsrc attribute, the loop property controls how many times the clip should play (loop). Changing to a value of -1 is equal to a continuous loop.

Example

document.movieImg.loop = 3;

Value

Integer.

Default

1

lowsrc NN 3 IE 4 DOM n/a
Read/Write (IE and Netscape 6)
Indicates the URL of a lower-resolution (or alternate) image to download into the document space if the image of the src attribute will take a long time to download. The lowsrc image should be the same pixel size as the primary src image. It makes sense to change the lowsrc property only if you are also going to change the src property. In this case, make sure you change the lowsrc property first so that the browser knows how to handle the long download for the src image.
Note that Netscape 6 also implements a second variation of this property with a different capitalization: lowSrc. Neither version is indicated in the W3C DOM.

Example

document.productImage.lowsrc = "images/widget43LoRes.jpg";

Value

Any complete or relative URL as a string.

Default

None.

mimeType NN n/a IE 6(Win) DOM n/a
Read-only
Returns a plain-language description of the MIME type for the image. This property may not be officially supported by Microsoft, but it correctly reports values for typical image types served from both local disks and servers.

Example

if (document.productImage.mimeType.indexOf("JPEG") != -1) { // process condition for jpeg image }

Value

String value such as JPEG Image or GIF Image.

Default

None.

name NN 2 IE 3 DOM 1
Read/Write
This is the identifier associated with the image object for use in scripted references to the object.

Example

var imgName = document.images[3].name;

Value

Case-sensitive string identifier that follows the rules of identifier naming: it may contain no whitespace, cannot begin with a numeral, and should avoid punctuation except for the underscore character.

Default

None.

nameProp NN n/a IE 5(Win) DOM n/a
Read-only
Returns the filename (without the rest of the URL path) of the current image. Simplifies examination of current image content.

Example

if (document.images[3].nameProp == "menuOn.jpg") { document.image[3].src = "../images/menuOff.jpg"; }

Value

Case-sensitive string filename and extension.

Default

None.

naturalHeight, naturalWidth NN 6 IE n/a DOM n/a
Read-only
Return the unscaled height and width of the image, in pixels. Allows scripts to find the true dimensions of the original image in case scripts or incorrect element attributes have scaled the image.

Example

document.logoImg.height = document.logoImg.naturalHeight; document.logoImg.width = document.logoImg.naturalWidth;

Value

Integer.

Default

None.

protocol NN n/a IE 4(Win)/5(Mac) DOM n/a
Read-only
Returns the protocol component of the URL associated with the element. Windows and Macintosh versions return values in different formats. For the Windows version, the values are in expanded plain language (e.g., File Protocol or HyperText Transfer Protocol); for the Mac version, values resemble location.protocol values (e.g., file: or http:). Unreliable in IE 4 for Windows.

Value

String.

Default

None.

prototype NN n/a IE 4(Mac) DOM n/a
Read-only
Returns a reference to the static Image object from which all instances of image objects are created. This mechanism is more commonly used in JavaScript core language objects (see Chapter 12). The fact that this property is available only in Internet Explorer 4 for the Macintosh calls its legitimacy into question.

Value

Object reference.

Default

object Image

src NN 3 IE 4 DOM 1
Read/Write
Provides the relative or complete URL of the image file currently loaded or to be loaded into the img element. Loading an image of a different size into an existing img element forces the element to resize to the new image's dimensions except in the following browsers: Netscape 3, Netscape 4, and IE 3 for the Macintosh. Reading this property returns the complete URL, regardless of how the URL form assigned the value originally.

Example

document.image[3].src = "../images/menuOff.jpg";

Value

URL string.

Default

None.

start NN n/a IE 4 DOM n/a
Read/Write
If you specify a video clip with the dynsrc attribute, the start property controls the action that causes the clip to start running.

Example

document.movieImg.start = "mouseover";

Value

String constant: fileopen | mouseover.

Default

fileopen

useMap NN 6 IE 4 DOM 1
Read/Write
Provides the URL of the map element in the same document that contains client-side image map hot areas and links. The value includes the hashmark assigned with the map name in the usemap attribute of the img element.

Example

document.images[0].useMap = "#altMap";

Value

A string starting with a hashmark and the name of the map element.

Default

None.

vspace
See hspace.

width
See height.

x, y NN 4 IE n/a DOM n/a
Read-only
Provide the horizontal and vertical pixel coordinates of the top-left corner of the image relative to the page. These are Navigator-only properties, corresponding to the offsetLeft and offsetTop properties of Internet Explorer.

Example

var imageFromTop = document.logoImg.y;

Value

Integer.

Default

None.

implementation NN 6 IE 5(Mac)/6(Win) DOM 1

The implementation object (the JavaScript reference for the W3C DOMImplementation object) represents, to a limited degree, the environment that makes up the document container—the browser for our purposes. You can reach this object via the document.implementation property.

Methods of the object let you see which DOM modules the browser reports supporting. In Netscape 6, this object is also a gateway to creating virtual W3C Document and DocumentType objects outside of the current document tree. Thus, in Netscape 6 you can use the document.implementation property as a start to generating a nonrendered document for external XML documents.

Object Model Reference

document.implementation

Object-Specific Properties

None.

Object-Specific Methods

createDocument( )

createDocumentType( )

hasFeature( )

Object-Specific Event Handler Properties

None.

createDocument( ) NN 6 IE n/a DOM 2
createDocument("namespaceURI", "qualifiedName", docTypeReference)
Returns a reference to a newly created virtual W3C DOM Document (not the document node of an HTML document) object. Netscape 6 extends this Document object with a load( ) method that permits the loading of XML documents into the browser, although they are invisible to the user. Scripts may then access the document tree of the XML document as a data source for rendering information in the HTML document. If you are loading an external XML document, you can create the Document object with blank values for the three parameters:
var myXDoc = document.implementation.createDocument("", "", null);
When the external document loads, any namespace and DOCTYPE concerns will be controlled by the document's content. For an example, see Section 5.9.2 in Chapter 5.

Returned Value

Reference to an empty Document object.

Parameters

namespaceURI

String of the namespace URI for a new XML document element.

qualifiedName

String identifier for the qualified name for the new document element.

docTypeReference

Reference to a DocumentType node (which may be generated from the DocumentImplementation.createDocumentType( ) method).

createDocumentType( ) NN 6 IE n/a DOM 2
createDocumentType("qualifiedName", "publicID", "systemID")
Returns a reference to a newly created virtual W3C DOM DocumentType object. You can feed the object returned from this method to the DocumentImplementation.createDocument( ) method.

Returned Value

Reference to a DocumentType object not yet associated with a Document object.

Parameters

qualifiedName

String identifier for the qualified name for the new document element.

publicID

String of the public identifier for the DOCTYPE.

systemID

String of the system identifier (typically, the URI of the DTD file) for the DOCTYPE.

hasFeature( ) NN 6 IE 5(Mac)/6(Win) DOM 1
hasFeature("feature", "version")
Returns a Boolean true if the browser application supports (i.e., conforms to the required specifications of) a stated W3C DOM module and version. The closely related isSupported( ) method performs the same test on an individual node, allowing you to verify feature support for the current node type. Parameter values for the two methods are identical.
It is up to the browser maker to validate that the DOM implemented in the browser conforms with each module before allowing the browser to return true for the module. That doesn't necessarily mean that the implementation is bug-free or consistent with other implementations. Caveat scriptor.
In theory, you could use this method to verify module support prior to accessing a property or invoking a method. The following script fragment from the head portion of a document dynamically links a different external style sheet file for "true" CSS2 support:
var cssFile; if (document.implementation.hasFeature("CSS", "2.0")) { cssFile = "styles/corpStyle2.css"; } else { cssFile = "styles/corpStyle1.css"; } document.write("<link rel='stylesheet' type='text/css' href='" + cssFile + "'>");
More browsers support this browser-wide method than the element-specific method, which may help more developers deploy it sooner.

Returned Value

Boolean value: true | false.

Parameters

feature

As of W3C DOM Level 2, permissible case-sensitive module name strings are: Core, XML, HTML, Views, StyleSheets, CSS, CSS2, Events, UIEvents, MouseEvents, MutationEvents, HTMLEvents, Range, and Traversal.

version

String representation of the major and minor version of the DOM module cited in the first parameter. For the W3C DOM Level 2, the version is 2.0, even when the DOM module supports another W3C standard that has its own numbering system. Thus, the test for HTML DOM module support is for Version 2.0, even though HTML is at 4.x.

imports NN n/a IE 4 DOM n/a

A collection (array) of styleSheet objects imported into an explicit styleSheet object via the @import rule. In other words, a styleSheet object that employs an @import treats that imported style sheet as a nested object, but one that is, itself, a full-fledged styleSheet object. Thus, you can access the rule objects within each imported style sheet. The following example iterates through all of the document's styleSheet objects in search of imported style sheets:

for (var i = 0; i < document.styleSheets.length; i++) {
    for (var j = 0; j < document.styleSheets[i].imports.length; j++) {
        // process each imported style sheet, referenced
        // here as document.styleSheets[i].imports[j]
    }
}

Object Model Reference

document.styleSheets[i].imports

Object-Specific Properties

length

Object-Specific Methods

item( )

length NN n/a IE 4 DOM n/a
Read-only
Returns the number of objects in the collection.

Example

var howMany = document.styleSheets[i].imports.length;

Value

Integer.

item( ) NN n/a IE 4 DOM n/a
item(index)
Returns a single imported styleSheet object corresponding to the index value in source code order of @import rules. IE 5 for Macintosh erroneously returns null.

Returned Value

Reference to an imported styleSheet object. If there are no matches to the parameters, the returned value is null.

Parameters

index

Zero-based integer.

input (type="button") NN 2 IE 3 DOM 1

The button object is a form control generated with an input element whose type attribute is set to "button". The button's text label comes from its value attribute and property. This element is similar to, but differs from, the button element. For details on the distinctions, see the button HTML element description in Chapter 8.

HTML Equivalent

<input type="button">

Object Model Reference

[window.]document.formName.elementName
[window.]document.forms[i].elements[i]
[window.]document.getElementById("elementID")

Object-Specific Properties

dataFld

dataSrc

form

name

type

value

Object-Specific Methods

createTextRange( )

handleEvent( )

Object-Specific Event Handler Properties

Handler	NN	IE	DOM
`onblur`	6	4	2
`onclick`	2	3	2
`onfocus`	6	4	2
`onmousedown`	4	4	2
`onmousemove`	6	4	2
`onmouseout`	6	4	2
`onmouseover`	6	4	2
`onmouseup`	4	4	2

dataFld NN n/a IE 4 DOM n/a
Read/Write
Used with IE data binding to associate a remote data source column name to a button object's value property. A datasrc attribute must also be set for the element. Setting both the dataFld and dataSrc properties to empty strings breaks the binding between element and data source. Works only with text file data sources in IE 5/Mac.

Example

document.myForm.myButton.dataFld = "linkURL";

Value

Case-sensitive identifier of the data source column.

Default

None.

dataSrc NN n/a IE 4 DOM n/a
Read/Write
Used with IE data binding to specify the ID of the page's object element that loads the data source object for remote data access. Content from the data source is specified via the datafld attribute. Setting both the dataFld and dataSrc properties to empty strings breaks the binding between element and data source. Works only with text file data sources in IE 5/Mac.

Example

document.myForm.myButton.dataSrc = "DBSRC3";

Value

Case-sensitive identifier of the data source.

Default

None.

form NN 2 IE 3 DOM 1
Read-only
Returns a reference to the form element that contains the current element. When processing an event from this element, the event handler function automatically has access to the input element (as the event object's target or srcElement property). By reading the form property, the script can easily access other controls within the same form.

Example

var theForm = evt.srcElement.form;

Value

form element object reference.

Default

None.

name NN 2 IE 3 DOM 1
Read/Write
This is the identifier associated with the form control. The value of this property is submitted as one-half of the name/value pair when the form is submitted to the server. Names are hidden from user view, since control labels are assigned via other means, depending on the control type. Form control names may also be used by script references to the objects. Despite the modern standards' preference for the id attribute, many browsers still require that a form control be assigned a name attribute to allow the control's value to be submitted.

Example

document.orderForm.myButton.name = "Win32";

Value

Case-sensitive string identifier that follows the rules of identifier naming: it may contain no whitespace, cannot begin with a numeral, and should avoid punctuation except for the underscore character.

Default

None.

type NN 3 IE 4 DOM 1
Read-only
Returns the type of form control element. The value is returned in all lowercase letters. It may be necessary to cycle through all form elements in search of specific types to do some processing on (e.g., emptying all form controls of type "text" while leaving other controls untouched).

Example

if (document.forms[0].elements[3].type == "button") { // process button input type here }

Value

Any of the following constants (as a string): button | checkbox | file | hidden | image | password | radio | reset | select-multiple | select-one | submit | text | textarea.

Default

checkbox

value NN 2 IE 3 DOM 1
Read/Write
This is one of the rare times that the value property controls the label of a form control: the text that appears on the button. A button input element is not submitted with the form.

Example

document.forms[0].myButton.value = "Undo";

Value

String.

Default

None.

createTextRange( ) NN n/a IE 4(Win) DOM n/a
Creates a TextRange object containing the button's label text. See the TextRange object for details.

Returned Value

TextRange object.

Parameters

None.

handleEvent( ) NN |4| IE n/a DOM n/a
handleEvent(event)
Instructs the object to accept and process the event whose specifications are passed as the parameter to the method. The object must have an event handler for the event type to process the event. Navigator 4 only.

Returned Value

None.

Parameters

event

A Navigator 4 event object.

input (type="checkbox") NN 2 IE 3 DOM 1

The checkbox object is a form control generated with an input element whose type attribute is set to "checkbox". Employ this element only as a user interface element for user on-off choices, not as a navigation button. In IE 5 and later for Windows and in Netscape 6, you can adjust the size of the checkbox via style sheet height and width attributes, but only Netscape 6 automatically scales the size of the checkmark optimized for the checkbox rectangle's size and keeps the baselines of surrounding text aligned with the rectangle's bottom.

HTML Equivalent

<input type="checkbox">

Object Model Reference

[window.]document.formName.elementName
[window.]document.forms[i].elements[i]
[window.]document.getElementById("elementID")

Object-Specific Properties

`checked`	`dataFld`	`dataSrc`	`defaultChecked`	`form`
`indeterminate`	`name`	`status`	`type`	`value`

Object-Specific Methods

handleEvent( )

Object-Specific Event Handler Properties

Handler	NN	IE	DOM
`onblur`	6	4	2
`onclick`	3	4	2
`onfocus`	6	4	2
`onmousedown`	4	4	2
`onmousemove`	6	4	2
`onmouseout`	6	4	2
`onmouseover`	6	4	2
`onmouseup`	4	4	2

checked NN 2 IE 3 DOM 1
Read/Write
Specifies whether the checkbox is selected or turned on by the user (or script). Checkboxes operate independently of each other. Only checkbox objects with the checked property set to true have their name/value pair submitted with the form. To find out whether the form element is set to be checked when the page loads, see the defaultChecked property. Scripts can change this property even if the element is disabled.

Example

if (document.choiceForm.monitors.checked) { //process for the "monitors" checkbox being checked }

Value

Boolean: true | false.

Default

false

dataFld NN n/a IE 4 DOM n/a
Read/Write
Used with IE 4 data binding to associate a remote data source column name to a checkbox object's value attribute. A datasrc attribute must also be set for the element. Setting both the dataFld and dataSrc properties to empty strings breaks the binding between element and data source. Works only with text file data sources in IE 5/Mac.

Example

document.myForm.myCheckbox.dataFld = "homeAddrFlag";

Value

Case-sensitive identifier of the data source column.

Default

None.

dataSrc NN n/a IE 4 DOM n/a
Read/Write
Used with IE data binding to specify the ID of the page's object element that loads the data source object for remote data access. Content from the data source is specified via the datafld attribute. Setting both the dataFld and dataSrc properties to empty strings breaks the binding between element and data source. Works only with text file data sources in IE 5/Mac.

Example

document.myForm.myCheckbox.dataSrc = "DBSRC3";

Value

Case-sensitive identifier of the data source.

Default

None.

defaultChecked NN 2 IE 3 DOM 1
Read/Write
Specifies whether the element has the checked attribute set in the tag. You can compare the current checked property against defaultChecked to see whether the state of the control has changed since the document loaded. Changing this property does not affect the current checked status.

Example

var cBox = document.forms[0].checkbox1 if (cBox.checked != cBox.defaultChecked) { // process for changed state }

Value

Boolean value: true | false.

Default

Determined by HTML tag attribute.

form NN 2 IE 3 DOM 1
Read-only
Returns a reference to the form element that contains the current element (if any). When processing an event from this element, the event handler function automatically has access to the input element (as the event object's target or srcElement property). By reading the form property, the script can easily access other controls within the same form.

Example

var theForm = evt.srcElement.form;

Value

form element object reference.

Default

None.

indeterminate NN n/a IE 4 DOM n/a
Read/Write
Indicates whether a checkbox is visually represented as being neither checked nor unchecked, yet still active. This middle ground is rendered differently for different operating systems. In Windows, the checkbox is grayed out (with the checkmark still visible if it was there originally) but still active. On the Macintosh, the checkbox displays a hyphen inside the box. The indeterminate state usually means some change elsewhere on the page has likely affected the setting of the checkbox, requiring the user to verify the checkbox's setting for accuracy. An "indeterminate" checkbox is submitted with the form.

Example

document.orderForm.2DayAir.indeterminate = true;

Value

Boolean value: true | false.

Default

false

name NN 2 IE 3 DOM 1
Read/Write
This is the identifier associated with the form control. The value of this property is submitted as one-half of the name/value pair when the form is submitted to the server. Names are hidden from user view, since control labels are assigned via other means, depending on the control type. Form control names may also be used by script references to the objects. Despite the modern standards' preference for the id attribute, many browsers still require that a form control be assigned a name attribute to allow the control's value to be submitted.

Example

document.orderForm.myCheckbox.name = "Win32";

Value

Case-sensitive string identifier that follows the rules of identifier naming: it may contain no whitespace, cannot begin with a numeral, and should avoid punctuation except for the underscore character.

Default

None.

status NN n/a IE 4 DOM n/a
Read/Write
Specifies whether the element is highlighted/checked. This property is identical to the checked property.

Example

if (document.forms[0].56KbpsBox.status) { ... }

Value

Boolean value: true | false.

Default

None.

type NN 3 IE 4 DOM 1
Read-only
Returns the type of form control element. The value is returned in all lowercase letters. It may be necessary to cycle through all form elements in search of specific types to do some processing on (e.g., emptying all form controls of type "text" while leaving other controls untouched).

Example

if (document.forms[0].elements[3].type == "checkbox") { // process checkbox input type here }

Value

Any of the following constants (as a string): button | checkbox | file | hidden | image | password | radio | reset | select-multiple | select-one | submit | text | textarea.

Default

checkbox

value NN 2 IE 3 DOM 1
Read/Write
Provides the current value associated with the form control that is submitted with the name/value pair for the element (if the checkbox is checked). All values are strings, but they may represent other kinds of data, including Boolean and numeric values.

Example

document.forms[0].extraPhone.value = "cellPhone";

Value

String.

Default

None.

handleEvent( ) NN |4| IE n/a DOM n/a
handleEvent(event)
Instructs the object to accept and process the event whose specifications are passed as the parameter to the method. The object must have an event handler for the event type to process the event. Navigator 4 only.

Returned Value

None.

Parameters

event

A Navigator 4 event object.

input (type="file") NN 3 IE 4 DOM 1

The fileUpload object is a form control generated with an input element whose type attribute is set to "file". The "fileUpload" term does not appear in scripts, but it is the way Netscape casually referred to this object when it was first scriptable.

To submit a file, the form element should have its method attribute set to POST and its enctype attribute set to multipart/form-data. But you also need some server programming to process the incoming data correctly.

HTML Equivalent

<input type="file">

Object Model Reference

[window.]document.formName.elementName
[window.]document.forms[i].elements[i]
[window.]document.getElementById("elementID")

Object-Specific Properties

accept

defaultValue

form

name

size

type

value

Object-Specific Methods

handleEvent( )

select( )

Object-Specific Event Handler Properties

Handler	NN	IE	DOM
`onblur`	3	4	2
`onchange`	3	4	2
`onclick`	6	4	2
`onfocus`	3	4	2
`onkeydown`	6	4	n/a
`onkeypress`	6	4	n/a
`onkeyup`	6	4	n/a
`onmousedown`	6	4	2
`onmousemove`	6	4	2
`onmouseout`	6	4	2
`onmouseover`	6	4	2
`onmouseup`	6	4	2
`onselect`	3	4	2

accept NN 6 IE 4 DOM 1
Read/Write
Provides an optional advisory property consisting of a string of one or more comma-delimited MIME types of files that are being uploaded. Values have no impact on this element in current browsers.

Example

document.entryForm.myFileUpload.accept = "image/gif";

Value

String.

Default

None.

defaultValue NN 4 IE 4 DOM n/a
Read/Write
Returns the string assigned to the value attribute of the element in the source code (except in IE for Windows, which returns an empty string). A user must manually select a file for uploading, so pre-setting or attempting to alter this value is a waste of time.

Example

var initVal = document.entryForm.myFileUpload.defaultValue;

Value

String.

Default

None.

form NN 3 IE 4 DOM 1
Read-only
Returns a reference to the form element that contains the current element (if any). When processing an event from this element, the event handler function automatically has access to the input element (as the event object's target or srcElement property). By reading the form property, the script can easily access other controls within the same form.

Example

var theForm = evt.srcElement.form;

Value

form element object reference.

Default

None.

name NN 2 IE 3 DOM 1
Read/Write
This is the identifier associated with the form control. The value of this property is submitted as one-half of the name/value pair when the form is submitted to the server. Names are hidden from user view, since control labels are assigned via other means, depending on the control type. Form control names may also be used by script references to the objects. Despite the modern standards' preference for the id attribute, many browsers still require that a form control be assigned a name attribute to allow the control's value to be submitted.

Example

document.orderForm.myFileChoice.name = "Win32File";

Value

Case-sensitive string identifier that follows the rules of identifier naming: it may contain no whitespace, cannot begin with a numeral, and should avoid punctuation except for the underscore character.

Default

None.

size NN 6 IE 4 DOM 1
Read/Write
Roughly speaking, indicates the width in characters that the input text box portion of the file input element should be sized to accommodate. In practice, the browser does not always accurately predict the proper width when the font used is a proportional one. See details in the size attribute discussion for the input element in Chapter 8. This property is not available for IE 4 on the Macintosh.

Example
document.forms[0].myFileUpload.size = 60;
Value

Integer.

Default

20

type NN 3 IE 4 DOM 1
Read-only
Returns the type of form control element. The value is returned in all lowercase letters. It may be necessary to cycle through all form elements in search of specific types to do some processing on (e.g., emptying all form controls of type "text" while leaving other controls untouched).

Example

if (document.forms[0].elements[3].type == "file") { // process file input type here }

Value

Any of the following constants (as a string): button | checkbox | file | hidden | image | password | radio | reset | select-multiple | select-one | submit | text | textarea.

Default

file

value NN 2 IE 3 DOM 1
Read-only
Indicates the current value associated with the form control that is submitted with the name/value pair for the element. For a fileUpload object, this value is the URL-encoded full pathname to the local file. This is true even for the Macintosh browser versions, which tend to display only the file's name in the form element display. While the property accepts new value assignments in some browsers, only values assigned as a result of a user's explicit file menu choice get submitted.

Value

String.

Default

None.

handleEvent( ) NN |4| IE n/a DOM n/a
handleEvent(event)
Instructs the object to accept and process the event whose specifications are passed as the parameter to the method. The object must have an event handler for the event type to process the event. Navigator 4 only.

Returned Value

None.

Parameters

event

A Navigator 4 event object.

select( ) NN 3 IE 4 DOM n/a
Selects all the text displayed in the form element.

Returned Value

None.

Parameters

None.

input (type="hidden") NN 3 IE 4 DOM 1

The hidden object is a form control generated with an input element that has its type attribute is set to "hidden". This element has no event handlers, because users do not interact directly with the element. Be aware that any values assigned to a hidden object are removed if the user reloads the page. In other words, it does not function as a persistent store. Internet Explorer for Windows and Netscape 6 expose many more properties than are listed below. Most of these are included in the internal object definition for consistency across other text-oriented form controls, but have no practical significance for a hidden object.

HTML Equivalent

<input type="hidden">

Object Model Reference

[window.]document.formName.elementName
[window.]document.forms[i].elements[i]
[window.]document.getElementById("elementID")

Object-Specific Properties

dataFld

dataSrc

defaultValue

form

name

type

value

Object-Specific Methods

createTextRange( )

Object-Specific Event Handler Properties

None.

dataFld NN n/a IE 4 DOM n/a
Read/Write
Used with IE data binding to associate a remote data source column name with the element's value. A datasrc attribute must also be set for the element. Setting both the dataFld and dataSrc properties to empty strings breaks the binding between element and data source. Works only with text file data sources in IE 5/Mac.

Example

document.myForm.price.dataFld = "price";

Value

Case-sensitive identifier of the data source column.

Default

None.

dataSrc NN n/a IE 4 DOM n/a
Read/Write
Used with IE data binding to specify the ID of the page's object element that loads the data source object for remote data access. Setting both the dataFld and dataSrc properties to empty strings breaks the binding between element and data source. Works only with text file data sources in IE 5/Mac.

Example

document.myForm.price.dataSrc = "DBSRC3";

Value

Case-sensitive identifier of the data source.

Default

None.

defaultValue NN 2 IE 3 DOM n/a
Read-only
Returns the string assigned to the value attribute of the element in the source code. You can use this value to reassign the original value to the element if scripts have altered the value property during other processing.

Example

document.entryForm.sessionID.value = document.entryForm.sessionID.defaultValue;

Value

String.

Default

None.

form NN 2 IE 3 DOM 1
Read-only
Returns a reference to the form element that contains the current element (if any). When processing an event from this element, the event handler function automatically has access to the input element (as the event object's target or srcElement property). By reading the form property, the script can easily access other controls within the same form.

Example

var theForm = evt.srcElement.form;

Value

form element object reference.

Default

None.

name NN 2 IE 3 DOM 1
Read/Write
This is the identifier associated with the form control. The value of this property is submitted as one-half of the name/value pair when the form is submitted to the server. Names are hidden from user view, since control labels are assigned via other means, depending on the control type. Form control names may also be used by script references to the objects. Despite the modern standards' preference for the id attribute, many browsers still require that a form control be assigned a name attribute to allow the control's value to be submitted.

Example

document.orderForm.compName.name = "company";

Value

Case-sensitive string identifier that follows the rules of identifier naming: it may contain no whitespace, cannot begin with a numeral, and should avoid punctuation except for the underscore character.

Default

None.

type NN 3 IE 4 DOM 1
Read-only
Returns the type of form control element. The value is returned in all lowercase letters. It may be necessary to cycle through all form elements in search of specific types to do some processing on (e.g., emptying all form controls of type "text" while leaving other controls untouched).

Example

if (document.forms[0].elements[3].type == "hidden") { // process hidden input type here }

Value

Any of the following constants (as a string): button | checkbox | file | hidden | image | password | radio | reset | select-multiple | select-one | submit | text | textarea.

Default

hidden

value NN 2 IE 3 DOM 1
Read/Write
Indicates the current value associated with the form control that is submitted with the name/value pair for the element. All values are strings, but they may represent other kinds of data, including Boolean and numeric values.

Example

document.forms[0].price.value = "33.95";

Value

String.

Default

None.

createTextRange( ) NN n/a IE 4(Win) DOM n/a
Creates a TextRange object containing the hidden field's string value. See the TextRange object for details.

Returned Value

TextRange object.

Parameters

None.

input (type="image") NN 6 IE 4 DOM 1

The image-type input object is first and foremost a button-like form control element, but with several characteristics of an img element, as well. Its default behavior is that of a submit-type button. The coordinates of the mouse click within the image's rectangle are passed as form data (in the format elemName.x=65&elemName.y=44) when the form is submitted. Note that unlike most other input element types, this input type was not scriptable in early browsers. IE for Windows may not recognize a reference to this element via the enclosing form. Accessing the form via its ID is completely reliable, however.

HTML Equivalent

<input type="image">

Object Model Reference

[window.]document.formName.elementName
[window.]document.forms[i].elements[i]
[window.]document.getElementById("elementID")

Object-Specific Properties

`alt`	`complete`	`dynsrc`	`form`	`height`
`hspace`	`loop`	`lowsrc`	`name`	`src`
`start`	`type`	`useMap`	`vspace`	`width`

Object-Specific Methods

handleEvent( )

Object-Specific Event Handler Properties

Handler	NN	IE	DOM
`onblur`	n/a	4	n/a
`onclick`	2	3	2
`onfocus`	n/a	4	n/a
`onmousedown`	4	4	2
`onmousemove`	6	4	2
`onmouseout`	6	4	2
`onmouseover`	6	4	2
`onmouseup`	4	4	2

alt NN 6 IE 4 DOM 1
Read/Write
Provides text to be displayed (or spoken) where the image-type input element appears on the page when a browser does not download graphics (or is waiting for the image to download). See the alt property of the img object for more details.

complete NN n/a IE 4 DOM n/a
Read-only
Reveals whether the image-type input element's src or lowsrc image file has fully loaded. See the complete property of the img object for more details.

dynsrc NN n/a IE 4 DOM n/a
Read/Write
Provides the URL of a video clip to be displayed through the image-type input element's image. See the dynsrc property of the img object for more details.

form NN 6 IE 4 DOM 1
Read-only
Returns a reference to the form element that contains the current element. When processing an event from this element, the event handler function automatically has access to the input element (as the event object's target or srcElement property). By reading the form property, the script can easily access other controls within the same form.

Example

var theForm = evt.srcElement.form;

Value

form element object reference.

Default

None.

height, width NN n/a IE 4 DOM n/a
Read/Write
Indicate the height and width in pixels of the image rendered in the input element. See the height and width properties of the img object for more details.

hspace, vspace NN n/a IE 4 DOM n/a
Read/Write
Indicate the pixel measure of horizontal and vertical margins surrounding an image-type input object. See the hspace and vspace properties of the img object for more details.

loop NN n/a IE 4 DOM n/a
Read/Write
If you specify a video clip with the dynsrc attribute, the loop property controls how many times the clip should play (loop). See the loop property of the img object for more details.

lowsrc NN n/a IE 4 DOM n/a
Read/Write
Provides the URL of a lower-resolution (or alternate) image to download into the document space if the image of the src attribute will take a long time to download. See the lowsrc property of the img object for more details.

name NN 2 IE 3 DOM 1
Read/Write
This is the identifier associated with the form control. The value of this property is submitted associated with click coordinate values (within the image's rectangle) when the form is submitted in the format elemName.x=65&elemName.y=44. These coordinates take the place of the value attribute and property of other types of input elements. Despite the modern standards' preference for the id attribute, many browsers still require that a form control be assigned a name attribute to allow the control's value to be submitted.

Example

document.orderForm.myButton.name = "Win32";

Value

Case-sensitive string identifier that follows the rules of identifier naming: it may contain no whitespace, cannot begin with a numeral, and should avoid punctuation except for the underscore character.

Default

None.

src NN 6 IE 4 DOM 1
Read/Write
Provides the relative or complete URL of the image file currently loaded or to be loaded into the image-type input element. See the src property of the img object for more details.

start NN n/a IE 4 DOM n/a
Read/Write
If you specify a video clip with the dynsrc attribute, the start property controls the action that causes the clip to start running. See the start property of the img object for more details.

type NN 6 IE 4 DOM 1
Read-only
Returns the type of form control element. The value is returned in lowercase letters. It may be necessary to cycle through all form elements in search of specific types to do some processing on (e.g., emptying all form controls of type "text" while leaving other controls untouched).

Example

if (document.forms[0].elements[3].type == "image") { // process image input type here }

Value

Any of the following constants (as a string): button | checkbox | file | hidden | image | password | radio | reset | select-multiple | select-one | submit | text | textarea.

Default

image

useMap NN 6 IE 4 DOM 1
Read/Write
Provides the URL of the map element in the same document that contains client-side image map hot areas and links to be applied to the image. See the useMap property of the img object for more details.

vspace
See hspace.

width
See height.

handleEvent( ) NN |4| IE n/a DOM n/a
handleEvent(event)
Instructs the object to accept and process the event whose specifications are passed as the parameter to the method. The object must have an event handler for the event type to process the event. Navigator 4 only.

Returned Value

None.

Parameters

event

A Navigator 4 event object.

input (type="password") NN 2 IE 3 DOM 1

The password object is a form control generated with an input element that has a type attribute set to "password". This object is similar to the text input object, except that the characters typed into the text box by the user are converted to asterisk or bullet symbols for privacy.

HTML Equivalent

<input type="password">

Object Model Reference

[window.]document.formName.elementName
[window.]document.forms[i].elements[i]
[window.]document.getElementById("elementID")

Object-Specific Properties

`dataFld`	`dataSrc`	`defaultValue`	`form`	`maxLength`
`name`	`readOnly`	`selectionEnd`	`selectionStart`	`size`
`textLength`	`type`	`value`

Object-Specific Methods

createTextRange( )

handleEvent( )

select( )

Object-Specific Event Handler Properties

Handler	NN	IE	DOM
`onblur`	2	3	2
`onchange`	2	3	2
`onfocus`	2	3	2
`onkeydown`	4	4	n/a
`onkeypress`	4	4	n/a
`onkeyup`	4	4	n/a
`onselect`	2	3	2

dataFld NN n/a IE 4 DOM n/a
Read/Write
Used with IE data binding to associate a remote data source column name to a password object's value property. A datasrc attribute must also be set for the element. Setting both the dataFld and dataSrc properties to empty strings breaks the binding between element and data source. Works only with text file data sources in IE 5/Mac.

Example

document.myForm.myPassword.dataFld = "userWurd";

Value

Case-sensitive identifier of the data source column.

Default

None.

dataSrc NN n/a IE 4 DOM n/a
Read/Write
Used with IE data binding to specify the ID of the page's object element that loads the data source object for remote data access. Content from the data source is specified via the datafld attribute. Setting both the dataFld and dataSrc properties to empty strings breaks the binding between element and data source. Works only with text file data sources in IE 5/Mac.

Example

document.myForm.myPassword.dataSrc = "#DBSRC3";

Value

Case-sensitive identifier of the data source.

Default

None.

defaultValue NN 2 IE 3 DOM 1
Read-only
Indicates the default text for the password input element, as established by the value attribute.

Example

var pwObj = document.forms[0].myPassword; if (pwObj.value != pwObj.defaultValue ) { // process user-entered password }

Value

String value.

Default

None.

form NN 2 IE 3 DOM 1
Read-only
Returns a reference to the form element that contains the current element (if any). When processing an event from this element, the event handler function automatically has access to the input element (as the event object's target or srcElement property). By reading the form property, the script can easily access other controls within the same form.

Example

var theForm = evt.srcElement.form;

Value

form element object reference.

Default

None.

maxLength NN 6 IE 4 DOM 1
Read/Write
Specifies the maximum number of characters that may be typed into a password field input element. In practice, browsers beep or otherwise alert users when a typed character would exceed the maxLength value. There is no innate correlation between the maxLength and size properties. If the maxLength allows for more characters than fit within the specified width of the element, the browser provides horizontal scrolling (albeit awkward for many users) to allow entry and editing of the field.

Example

document.entryForm.myPassword.maxLength = 35;

Value

Integer value.

Default

Unlimited.

name NN 2 IE 3 DOM 1
Read/Write
This is the identifier associated with the form control. The value of this property is submitted as one-half of the name/value pair when the form is submitted to the server. Names are hidden from user view, since control labels are assigned via other means, depending on the control type. Form control names may also be used by script references to the objects. Despite the modern standards' preference for the id attribute, many browsers still require that a form control be assigned a name attribute to allow the control's value to be submitted.

Example

document.orderForm.myPassword.name = "pw";

Value

Case-sensitive string identifier that follows the rules of identifier naming: it may contain no whitespace, cannot begin with a numeral, and should avoid punctuation except for the underscore character.

Default

None.

readOnly NN 6 IE 4 DOM 1
Read-only
Specifies whether the form element can be edited on the page by the user. A form control whose readOnly property is true may still be modified by scripts, even though the user may not alter the content.

Example

if (document.forms[0].myPassword.readOnly ) { ... };

Value

Boolean value: true | false.

Default

false

selectionEnd, selectionStart NN 6 IE n/a DOM n/a
Read/Write
The selectionEnd and selectionStart properties are convenience properties introduced with Netscape 6. They allow scripts to get and set the end positions of a text selection within a text-oriented input element. Values are zero-based integer counters of positions between characters in the text entered into the field. When both properties have the same value, the visual result is the same as a text insertion pointer. For example, to place the cursor at the end of a text box, set the two values to the element's text length (see the textLength property). The equivalent IE functionality requires creating an IE text range in the element, adjusting the range's endpoints, and selecting the range (see the TextRange object).

Example

var elem = document.forms[0].myPassword; elem.selectionEnd = elem.textLength; elem.selectionStart = elem.textLength;

Value

Positive integer.

Default

None.

size NN 6 IE 4 DOM 1
Read/Write
Roughly speaking, the width in characters that the input box should be sized to accommodate. In practice, the browser does not always accurately predict the proper width even when all characters are the same, as they are in the password object. See details in the size attribute discussion for the input element in Chapter 8. There is no interaction between the size and maxLength properties for this object.

Example
document.forms[0].myPassword.size = 12;
Value

Integer.

Default

20

textLength NN 6 IE n/a DOM n/a
Read-only
The textLength convenience property (introduced with Netscape 6) returns the length of text entered into the text field. The value is same as the length of the value property.

Example

var elem = document.forms[0].myPassword; elem.selectionEnd = elem.textLength; elem.selectionStart = elem.textLength;

Value

Positive integer.

Default

None.

type NN 3 IE 4 DOM 1
Read-only
Returns the type of form control element. The value is returned in all lowercase letters. It may be necessary to cycle through all form elements in search of specific types to do some processing on (e.g., emptying all form controls of type "text" while leaving other controls untouched).

Example

if (document.forms[0].elements[3].type == "password") { // process password input type here }

Value

Any of the following constants (as a string): button | checkbox | file | hidden | image | password | radio | reset | select-multiple | select-one | submit | text | textarea.

Default

password

value NN 2 IE 3 DOM 1
Read/Write
Indicates the current value associated with the form control that is submitted with the name/value pair for the element. All values are strings. Browsers return the actual characters typed by the user (except in Navigator 2), so you can retrieve an entered password for further processing before submission (or perhaps for storage in the cookie).

Example

document.forms[0].myPassword.value = "franken";

Value

String.

Default

None.

createTextRange( ) NN n/a IE 4(Win) DOM n/a
Creates a TextRange object containing the field's value text. See the TextRange object for details.

Returned Value

TextRange object.

Parameters

None.

handleEvent( ) NN |4| IE n/a DOM n/a
handleEvent(event)
Instructs the object to accept and process the event whose specifications are passed as the parameter to the method. The object must have an event handler for the event type to process the event. Navigator 4 only

Returned Value

None.

Parameters

event

A Navigator 4 event object.

select( ) NN 2 IE 3 DOM 1
Selects all the text displayed in the form element. Usually requires that the element have focus prior to invoking this method.

Returned Value

None.

Parameters

None.

input (type="radio") NN 2 IE 3 DOM 1

The radio object is a form control generated with an input element that has a type attribute set to "radio". radio objects related to each other are assigned the same name. This means all like-named radio objects become a collection (array) of radio objects. It may be necessary, therefore, to reference an individual radio button as an item in an array. The entire array, of course, has a length property you can use to assist in looping through all radio objects within the group, if necessary, to find which one is checked, and retrieve that object's value:

var radioGrp = document.forms[0].myRadio;
for (var i = 0; i < radioGrp.length; i++) {
    if (radioGrp[i].checked) {
        alert("The value of the chosen button is " + radioGrp [i].value);
    }
}

Properties and methods listed as follows are for individual radio buttons.

HTML Equivalent

<input type="radio">

Object Model Reference

[window.]document.formName.elementName
[window.]document.forms[i].elements[i]
[window.]document.getElementById("elementID")

Object-Specific Properties

`checked`	`dataFld`	`dataSrc`	`defaultChecked`	`form`
`name`	`status`	`type`	`value`

Object-Specific Methods

handleEvent( )

Object-Specific Event Handler Properties

Handler	NN	IE	DOM
`onblur`	6	4	2
`onclick`	3	4	2
`onfocus`	6	4	2
`onmousedown`	4	4	2
`onmousemove`	6	4	2
`onmouseout`	6	4	2
`onmouseover`	6	4	2
`onmouseup`	4	4	2

checked NN 2 IE 3 DOM 1
Read/Write
Determines whether the radio button is selected or turned on by the user or script. Only radio objects with the checked property set to true have their name/value pair submitted with the form. To find out whether the form element is set to be checked when the page loads, see the defaultChecked property. Scripts can change this property even if the element is disabled.

Example

if (document.choiceForm.myRadio[0].checked) { //process first radio button }

Value

Boolean: true | false.

Default

false

dataFld NN n/a IE 4 DOM n/a
Read/Write
Used with IE data binding to associate a remote data source column name to a radio button element value attribute determined by properties set in the object. A datasrc attribute must also be set for the element. Setting both the dataFld and dataSrc properties to empty strings breaks the binding between element and data source. Works only with text file data sources in IE 5/Mac.

Example

document.myForm.myRadio[0].dataFld = "cableModem";

Value

Case-sensitive string identifier of the data source column.

Default

None.

dataSrc NN n/a IE 4 DOM n/a
Read/Write
Used with IE data binding to specify the ID of the page's object element that loads the data source object for remote data access. Content from the data source is specified via the datafld attribute. Setting both the dataFld and dataSrc properties to empty strings breaks the binding between element and data source. Works only with text file data sources in IE 5/Mac.

Example

document.myForm.myRadio[0].dataSrc = "DBSRC3";

Value

Case-sensitive string identifier of the data source.

Default

None.

defaultChecked NN 2 IE 3 DOM 1
Read/Write
Specifies whether element has the checked attribute set in the tag. You can compare the current checked property against defaultChecked to see if the state of the control has changed since the document loaded. Changing this property doesn't affect the current checked status.

Example

var rBut = document.forms[0].myRadio[0]; if (rBut.checked != rBut.defaultChecked) { // process for changed state }

Value

Boolean value: true | false.

Default

Determined by HTML tag attribute.

form NN 2 IE 3 DOM 1
Read-only
Returns a reference to the form element that contains the current element (if any). When processing an event from this element, the event handler function automatically has access to the input element (as the event object's target or srcElement property). By reading the form property, the script can easily access other controls within the same form.

Example

var theForm = evt.srcElement.form;

Value

form element object reference.

Default

None.

name NN 2 IE 3 DOM 1
Read/Write
This is the identifier associated with the form control. The value of this property is submitted as one-half of the name/value pair when the form is submitted to the server (the value property of the highlighted radio button supplies the value portion). Names are hidden from user view, since control labels are assigned via other means, depending on the control type. Form control names may also be used by script references to the objects. Assign the same name to every radio button in a group whose highlight/unhighlight characteristics are related. Despite the modern standards' preference for the id attribute, many browsers still require that a form control be assigned a name attribute to allow the control's value to be submitted, but no two elements should have the same id attribute value. Therefore, if scripts need to reference elements by id, devise two separate naming schemes for the common name attributes and unique id attributes.

Example

document.orderForm.myRadio[0].name = "connectivity";

Value

Case-sensitive string identifier that follows the rules of identifier naming: it may contain no whitespace, can't begin with a numeral, and should avoid punctuation except for the underscore character.

Default

None.

status NN n/a IE 4 DOM n/a
Read/Write
Specifies whether the element is highlighted/checked. This property is identical to the checked property.

Example

if (document.forms[0].myRadio[0].status) { ... }

Value

Boolean value: true | false.

Default

None.

type NN 3 IE 4 DOM 1
Read-only
Returns the type of form control element. The value is returned in all lowercase letters. It may be necessary to cycle through all form elements in search of specific types to do some processing on (e.g., emptying all form controls of type "text" while leaving other controls untouched).

Example

if (document.forms[0].elements[3].type == "radio") { // process radio input type here }

Value

Any of the following constants (as a string): button | checkbox | file | hidden | image | password | radio | reset | select-multiple | select-one | submit | text | textarea.

Default

radio

value NN 2 IE 3 DOM 1
Read/Write
Indicates the current value associated with the form control that is submitted with the name/value pair for the group of like-named elements (if the particular radio button is selected). All values are strings, but they may represent other kinds of data, including Boolean and numeric values.

Example

document.forms[0].myRadio[0].value = "56kbps";

Value

String.

Default

None.

handleEvent( ) NN |4| IE n/a DOM n/a
handleEvent(event)
Instructs the object to accept and process the event whose specifications are passed as the parameter to the method. The object must have an event handler for the event type to process the event. Navigator 4 only

Returned Value

None.

Parameters

event

A Navigator 4 event object.

input (type="reset") NN 2 IE 3 DOM 1

The reset object is a form control generated with an input element whose type attribute is set to reset. This element is similar to the button object. No script action is necessary for the reset object to do its job of restoring form controls to their default settings.

HTML Equivalent

<input type="reset">

Object Model Reference

[window.]document.formName.elementName
[window.]document.forms[i].elements[i]
[window.]document.getElementById("elementID")

Object-Specific Properties

form

name

type

value

Object-Specific Methods

createTextRange( )

handleEvent( )

Object-Specific Event Handler Properties

Handler	NN	IE	DOM
`onblur`	6	4	2
`onclick`	3	4	2
`onfocus`	6	4	2
`onmousedown`	4	4	2
`onmousemove`	6	4	2
`onmouseout`	6	4	2
`onmouseover`	6	4	2
`onmouseup`	4	4	2

form NN 2 IE 3 DOM 1
Read-only
Returns a reference to the form element that contains the current element (if any). When processing an event from this element, the event handler function automatically has access to the input element (as the event object's target or srcElement property). By reading the form property, the script can easily access other controls within the same form.

Example

var theForm = evt.srcElement.form;

Value

form element object reference.

Default

None.

name NN 2 IE 3 DOM 1
Read/Write
This is the identifier associated with the form control. Names are hidden from user view, since control labels are assigned via other means, depending on the control type. Form control names may also be used by script references to the objects.

Example

document.orderForm.myReset.name = "resetter";

Value

Case-sensitive string identifier that follows the rules of identifier naming: it may contain no whitespace, cannot begin with a numeral, and should avoid punctuation except for the underscore character.

Default

None.

type NN 3 IE 4 DOM 1
Read-only
Returns the type of form control element. The value is returned in all lowercase letters. It may be necessary to cycle through all form elements in search of specific types to do some processing on (e.g., emptying all form controls of type "text" while leaving other controls untouched).

Example

if (document.forms[0].elements[3].type == "reset") { // process reset input type here }

Value

Any of the following constants (as a string): button | checkbox | file | hidden | image | password | radio | reset | select-multiple | select-one | submit | text | textarea.

Default

reset

value NN 2 IE 3 DOM 1
Read/Write
This is one of the rare times that the value property controls the label of a form control: the text that appears on the reset button.

Example

document.forms[0].myReset.value = "Undo";

Value

String.

Default

Reset

createTextRange( ) NN n/a IE 4(Win) DOM n/a
Creates a TextRange object containing the button's label text. See the TextRange object for details.

Returned Value

TextRange object.

Parameters

None.

handleEvent( ) NN |4| IE n/a DOM n/a
handleEvent(event)
Instructs the object to accept and process the event whose specifications are passed as the parameter to the method. The object must have an event handler for the event type to process the event. Navigator 4 only.

Returned Value

None.

Parameters

event

A Navigator 4 event object.

input (type="submit") NN 2 IE 3 DOM 1

The submit object is a form control generated with an input element that has a type attribute set to "submit". This object is similar to the button object, but a submit object has more implied power. No script action is necessary for the submit object to do its job of submitting the containing form to the server. If you require a button to perform a script action, but not an actual form submission, use the button or button-type input object instead. Otherwise, the submit object automatically reloads the current document (i.e., obeying the form's default action, which is the page's URL), perhaps destroying important script variables. To initiate form validation, use the onsubmit event handler of the form object rather than the onclick event handler of the submit button. If the event handler evaluates to true, the form is submitted; if it evaluates to false, the submission is cancelled. The scripted equivalent of a submit-type input object is the form object's submit( ) method.

HTML Equivalent

<input type="submit">

Object Model Reference

[window.]document.formName.elementName
[window.]document.forms[i].elements[i]
[window.]document.getElementById("elementID")

Object-Specific Properties

form

name

type

value

Object-Specific Methods

createTextRange( )

handleEvent( )

Object-Specific Event Handler Properties

Handler	NN	IE	DOM
`onblur`	6	4	2
`onclick`	3	4	2
`onfocus`	6	4	2
`onmousedown`	4	4	2
`onmousemove`	6	4	2
`onmouseout`	6	4	2
`onmouseover`	6	4	2
`onmouseup`	4	4	2

form NN 2 IE 3 DOM 1
Read-only
Returns a reference to the form element that contains the current element. When processing an event from this element, the event handler function automatically has access to the input element (as the event object's target or srcElement property). By reading the form property, the script can easily access other controls within the same form.

Example

var theForm = evt.srcElement.form;

Value

form element object reference.

Default

None.

name NN 2 IE 3 DOM 1
Read/Write
This is the identifier associated with the form control. Names are hidden from user view, since control labels are assigned via other means, depending on the control type. Form control names may also be used by script references to the objects.

Example

document.orderForm.mySubmit.name = "sender";

Value

Case-sensitive string identifier that follows the rules of identifier naming: it may contain no whitespace, cannot begin with a numeral, and should avoid punctuation except for the underscore character.

Default

None.

type NN 3 IE 4 DOM 1
Read-only
Returns the type of form control element. The value is returned in lowercase letters. You may have to cycle through all form elements in search of specific types to do some processing on (e.g., emptying all form controls of type "text", leaving other controls untouched).

Example

if (document.forms[0].elements[3].type == "submit") { // process submit input type here }

Value

Any of the following constants (as a string): button | checkbox | file | hidden | image | password | radio | reset | select-multiple | select-one | submit | text | textarea.

Default

submit

value NN 2 IE 3 DOM 1
Read/Write
This is one of the rare times that the value property controls the label of a form control: the text that appears on the submit button.

Example

document.forms[0].mySubmit.value = "Send";

Value

String.

Default

Submit

createTextRange( ) NN n/a IE 4(Win) DOM n/a
Creates a TextRange object containing the button's label text. See the TextRange object for details.

Returned Value

TextRange object.

Parameters

None.

handleEvent( ) NN |4| IE n/a DOM n/a
handleEvent(event)
Instructs the object to accept and process the event whose specifications are passed as the parameter to the method. The object must have an event handler for the event type to process the event. Navigator 4 only

Returned Value

None.

Parameters

event

A Navigator 4 event object.

input (type="text") NN 2 IE 3 DOM 1

The text object is a form control generated with an input element that has a type attribute set to "text". This object is the primary way of getting a user to enter single lines of text for submission to the server.

HTML Equivalent

<input type="text">

Object Model Reference

[window.]document.formName.elementName
[window.]document.forms[i].elements[i]
[window.]document.getElementById("elementID")

Object-Specific Properties

`dataFld`	`dataSrc`	`defaultValue`	`form`	`maxLength`
`name`	`readOnly`	`size`	`type`	`value`

Object-Specific Methods

createTextRange( )

handleEvent( )

select( )

Object-Specific Event Handler Properties

Handler	NN	IE	DOM
`onblur`	2	3	2
`onchange`	2	3	2
`onfocus`	2	3	2
`onkeydown`	4	4	n/a
`onkeypress`	4	4	n/a
`onkeyup`	4	4	n/a
`onselect`	2	4	2

dataFld NN n/a IE 4 DOM n/a
Read/Write
Used with IE 4 data binding to associate a remote data source column name to a text object's value property. A datasrc attribute must also be set for the element. Setting both the dataFld and dataSrc properties to empty strings breaks the binding between element and data source. Works only with text file data sources in IE 5/Mac.

Example

document.myForm.myText.dataFld = "price";

Value

Case-sensitive string identifier of the data source column.

Default

None.

dataSrc NN n/a IE 4 DOM n/a
Read/Write
Used with IE data binding to specify the ID of the page's object element that loads the data source object for remote data access. Content from the data source is specified via the datafld attribute. Setting both the dataFld and dataSrc properties to empty strings breaks the binding between element and data source. Works only with text file data sources in IE 5/Mac.

Example

document.myForm.myText.dataSrc = "DBSRC3";

Value

Case-sensitive string identifier of the data source.

Default

None.

defaultValue NN 2 IE 3 DOM 1
Read-only
The default text for the text input element, as established by the value attribute.

Example

var txtObj = document.forms[0].myText; if (txtObj.value != txtObj.defaultValue ) { ... }

Value

String value.

Default

None.

form NN 2 IE 3 DOM 1
Read-only
Returns a reference to the form element that contains the current element.When processing an event from this element, the event handler function automatically has access to the input element (as the event object's target or srcElement property). By reading the form property, the script can easily access other controls within the same form.

Example

var theForm = evt.srcElement.form;

Value

form element object reference.

Default

None.

maxLength NN 6 IE 4 DOM 1
Read/Write
Indicates the maximum number of characters that may be typed into a text input element. In practice, browsers beep or otherwise alert users when a typed character would exceed the maxLength value. There is no innate correlation between the maxLength and size properties. If the maxLength allows for more characters than fit within the specified width of the element, the browser provides horizontal scrolling (albeit awkward for many users) to allow entry and editing of the field.

Example

document.entryForm.myText.maxLength = 35;

Value

Integer value.

Default

Unlimited.

name NN 2 IE 3 DOM 1
Read/Write
This is the identifier associated with the form control. The value of this property is submitted as one-half of the name/value pair when the form is submitted to the server. Names are hidden from user view, since control labels are assigned via other means, depending on the control type. Form control names may also be used by script references to the objects. Despite the modern standards' preference for the id attribute, many browsers still require that a form control be assigned a name attribute to allow the control's value to be submitted.

Example

document.orderForm.myText.name = "lastName";

Value

Case-sensitive string identifier that follows the rules of identifier naming: it may contain no whitespace, cannot begin with a numeral, and should avoid punctuation except for the underscore character.

Default

None.

readOnly NN 6 IE 4 DOM 1
Read-only
Specifies whether the form element can be edited on the page by the user. A form control that has a readOnly property set to true may still be modified by scripts, even though the user may not alter the content.

Example

if (document.forms[0].myText.readOnly) { ... }

Value

Boolean value: true | false.

Default

false

size NN 6 IE 4 DOM 1
Read/Write
Roughly speaking, indicates the width in characters that the input box should be sized to accommodate. In practice, the browser does not always accurately predict the proper width. See details in the size attribute discussion for the input element in Chapter 8. There is no interaction between the size and maxLength properties for this object.

Example
document.forms[0].myText.size = 12;
Value

Integer.

Default

20

type NN 3 IE 4 DOM 1
Read-only
Returns the type of form control element. The value is returned in all lowercase letters. It may be necessary to cycle through all form elements in search of specific types to do some processing on (e.g., emptying all form controls of type "text" while leaving other controls untouched).

Example

if (document.forms[0].elements[3].type == "text") { // process text input type here }

Value

Any of the following constants (as a string): button | checkbox | file | hidden | image | password | radio | reset | select-multiple | select-one | submit | text | textarea.

Default

text

value NN 2 IE 3 DOM 1
Read/Write
Indicates the current value associated with the form control that is submitted with the name/value pair for the element. All values are strings, which means that scripts using text field values for some math operations (especially addition) have to convert the strings to numbers via the parseInt( ) or parseFloat( ) functions before performing the math. If you assign a number to a text field's value property, the browser automatically converts its data type to a string.

Example

document.forms[0].myText.value = "franken";

Value

String.

Default

None.

createTextRange( ) NN n/a IE 4(Win) DOM n/a
Creates a TextRange object from the content of the text object. See the TextRange object for details.

Returned Value

TextRange object.

Parameters

None.

handleEvent( ) NN |4| IE n/a DOM n/a
handleEvent(event)
Instructs the object to accept and process the event whose specifications are passed as the parameter to the method. The object must have an event handler for the event type to process the event. Navigator 4 only.

Returned Value

None.

Parameters

event

A Navigator 4 event object.

select( ) NN 2 IE 3 DOM 1
Selects all the text displayed in the form element. You should invoke the focus( ) method on the element prior to the select( ) method. Moreover, to ease potential timing problems in IE for Windows, place the focus( ) and select( ) method statements in a separate function, and invoke that function through setTimeout( ), usually with a delay of 0 to 50 milliseconds. This lets the browser catch up with window refreshing tasks before selecting the contents.

Returned Value

None.

Parameters

None.

ins NN 6 IE 4 DOM 1

The ins object reflects the ins element.

HTML Equivalent

<ins>

Object Model Reference

[window.]document.getElementById("elementID")

Object-Specific Properties

cite

dateTime

Object-Specific Methods

None.

Object-Specific Event Handler Properties

None.

cite, dateTime NN 6 IE 5(Mac)/6(Win) DOM 1
Read/Write
These two properties are listed among the shared properties earlier in this chapter due to an IE 6 implementation oddity. IE 5/Macintosh and Netscape 6 correctly implement these properties only for the del and ins objects, as specified in the W3C DOM, but in no mainstream browser do they convey any special powers. See the shared cite and dateTime properties.

isindex NN 6 IE 5 DOM 1

The isindex object reflects the ancient HTML isindex element. IE arbitrarily converts this element into a text-type input object in its DOM, and even creates a form element around it. Avoid using this element.

HTML Equivalent

<isindex>

Object-Specific Properties

prompt

prompt NN 6 IE 5(Mac) DOM 1
Read/Write
Provides the prompt message for the text entry field.

Value

String.

Default

None.

label NN 6 IE 4 DOM 1

The label object reflects the label element.

HTML Equivalent

<label>

Object Model Reference

[window.]document.getElementById("elementID")

Object-Specific Properties

dataFld

dataFormatAs

dataSrc

form

htmlFor

Object-Specific Methods

None.

Object-Specific Event Handler Properties

None.

dataFld NN n/a IE 4 DOM n/a
Read/Write
Used with IE data binding to associate a remote data source column name with the displayed text of the input element label. A datasrc attribute must also be set for the element. Setting both the dataFld and dataSrc properties to empty strings breaks the binding between element and data source. Works only for text data sources in IE 5 for the Macintosh.

Example

document.getElementById("myLabel").dataFld = "labelText";

Value

Case-sensitive string identifier of the data source column.

Default

None.

dataFormatAs NN n/a IE 4 DOM n/a
Read/Write
Used with IE data binding, this property advises the browser whether the source material arriving from the data source is to be treated as plain text or as tagged HTML. Works only for text data sources in IE 5 for the Macintosh.

Example

document.forms[0].myLabel.dataFormatAs = "html";

Value

IE 4 recognizes two possible settings: text | html.

Default

text

dataSrc NN n/a IE 4 DOM n/a
Read/Write
Used with IE data binding to specify the ID of the page's object element that loads the data source object for remote data access. Setting both the dataFld and dataSrc properties to empty strings breaks the binding between element and data source. Works only for text data sources in IE 5 for the Macintosh.

Example

document.getElementById("myLabel").dataSrc = "DBSRC3";

Value

Case-sensitive identifier of the data source.

Default

None.

form NN 6 IE 5(Mac)/6(Win) DOM 1
Read-only
Returns a reference to the next outermost form element object in the document tree. Multiple label element objects within the same form element reference the same form element object.

Example

var theForm = document.getElementById("myLabel").form;

Value

Reference to a form element object.

Default

None.

htmlFor NN 6 IE 4 DOM 1
Read/Write
Provides the element id of the input element to which the label is associated (the value of the for attribute). Binds the label element to a particular input element.

Example

document.getElementById("label3").htmlFor = "chkbox3";

Value

String.

Default

None.

layer NN |4| IE n/a DOM n/a

The layer object reflects the layer and ilayer elements. Found in Navigator 4 only. Other elements (such as div and span) that have style sheet position attributes set to absolute or relative are arbitrarily converted to layer objects in Navigator 4.

HTML Equivalent

<ilayer>
<layer>

Object Model Reference

[window.]document.layerName

Object-Specific Properties

`above`	`background`	`below`	`bgColor`	`clip`
`hidden`	`left`	`name`	`pageX`	`pageY`
`parentLayer`	`siblingAbove`	`siblingBelow`	`src`	`top`
`visibility`	`zIndex`

Object-Specific Methods

`captureEvents( )`	`handleEvent( )`	`load( )`	`moveAbove( )`
`moveBelow( )`	`moveBy( )`	`moveTo( )`	`moveToAbsolute( )`
`releaseEvents( )`	`resizeBy( )`	`resizeTo( )`	`routeEvent( )`

Object-Specific Event Handler Properties

Handler	NN	IE	DOM
`onblur`	4	n/a	n/a
`onfocus`	4	n/a	n/a
`onload`	4	n/a	n/a
`onmouseout`	4	n/a	n/a
`onmouseover`	4	n/a	n/a
`onmouseup`	4	n/a	n/a

above, below NN |4| IE n/a DOM n/a
Read-only
Return a reference to the positionable element whose stacking z-order is above or below the current element. These properties operate in the context of all positionable elements in a document. If the current element is the highest element, the above property returns null. To restrict the examination of next higher or lower elements within a single layer context, see siblingAbove and siblingBelow. To adjust the stacking order with respect to specific objects, see the moveAbove( ) and moveBelow( ) methods.

Example

var nextHigher = document.myILayer.above;

Value

Object reference or null.

Default

None.

background NN |4| IE n/a DOM n/a
Read/Write
This property holds an image object that has a src property that can be set to change the image used for the layer's background. In other words, you must set the src property of the layer's background object to change the image.

Example

document.myIlayer.background.src = "images/newlogo.gif";

Value

An image object property, such as src.

Default

None.

bgColor NN |4| IE n/a DOM n/a
Read/Write
Provides the background color of the element. While you may set the value with either a hexadecimal triplet or plain-language color value, values returned from the property are for some reason the decimal equivalent of the hexadecimal RGB version. The default behavior is a transparent background created with a bgColor property value of null.

Example

document.myIlayer.bgColor = "yellow";

Value

A hexadecimal triplet or plain-language color name. See Appendix A for acceptable plain-language color names. Returned values are the decimal equivalent of the hexadecimal value. A value of null sets the background to transparent.

Default

null (transparent).

clip NN |4| IE n/a DOM n/a
Read/Write
Defines a clipping region of a positionable element. This property is treated more like an object in itself, in that you adjust its values through six properties: clip.top, clip.left, clip.bottom, clip.right, clip.width, and clip.height. Adjust the side(s) or dimension(s) of your choice. All values represent pixel values.

Example

document.myIlayer.clip.width = 150;

Value

Integer.

Default

None.

hidden NN |4| IE n/a DOM n/a
Read/Write
Specifies whether the object is visible on the page. When the object is hidden, its surrounding content does not close the gap left by the element.

Example

document.myIlayer.hidden = false;

Value

Boolean value: true | false.

Default

false

left NN |4| IE n/a DOM n/a
Read/Write
For positionable elements, defines the position (in pixels) of the left edge of an element's box (content plus left padding, border, and/or margin) relative to the left edge of the next outermost block content container. For the relative-positioned layer, the offset is based on the left edge of the inline location of where the element would normally appear in the content.

Example

document.myIlayer.left = 45;

Value

Integer.

Default

0

name NN |4| IE n/a DOM n/a
Read-only
This is the identifier associated with a layer for use as the value assigned to target attributes or as script references to the frame. If no value is explicitly assigned to the id attribute, Navigator automatically assigns the name attribute value to the id attribute.

Example

if (document.layers[2].name == "main") { ... }

Value

Case-sensitive identifier that follows the rules of identifier naming: it may contain no whitespace, cannot begin with a numeral, and should avoid punctuation except for the underscore character.

Default

None.

pageX, pageY NN |4| IE n/a DOM n/a
Read/Write
Provide the horizontal (x) and vertical (y) position of the object relative to the top and left edges of the entire document.

Example

document.myIlayer.pageX = 400;

Value

Integer.

Default

None.

parentLayer NN |4| IE n/a DOM n/a
Read-only
Returns a reference to the next outermost layer in the containment hierarchy. For a single layer in a document, its parentLayer is the window object.

Example

if (parentLayer != window) { ... }

Value

Object reference (a layer or window).

Default

window

siblingAbove, siblingBelow NN |4| IE n/a DOM n/a
Read-only
Return a reference to the positionable element whose stacking z-order is above or below the current element, but only within the context of the shared parentLayer. If the current element is the highest element, the siblingAbove property returns null. To widen the examination of next higher or lower elements to a document-wide context, see above and below. To adjust the stacking order with respect to specific objects, see the moveAbove( ) and moveBelow( ) methods.

Example

var nextHigher = document.myILayer.siblingAbove;

Value

Object reference or null.

Default

None.

src NN |4| IE n/a DOM n/a
Read/Write
Indicates the URL of the external content file loaded into the current element. To change the content, assign a new URL to the property.
Assigning a new URL to this property does not work with inline layers (ilayer elements) in Navigator 4. Instead the current source document is removed, and other page elements can be obscured. Avoid setting this property for inline layers. The same goes for the load( ) method.

Example

document.myIlayer.src = "swap2.html";

Value

Complete or relative URL as a string.

Default

None.

top NN |4| IE n/a DOM n/a
Read/Write
For positionable elements, defines the position of the top edge of an element's box (content plus top padding, border, and/or margin) relative to the top edge of the next outermost block content container. All measures are in pixels. When the element is a relative-positioned inline layer, the offset is based on the top edge of the inline location of where the element would normally appear in the content.

Example

document.myIlayer.top = 50;

Value

Integer.

Default

0

visibility NN |4| IE n/a DOM n/a
Read/Write
Indicates the state of the positioned element's visibility. Surrounding content does not close the space left by an element whose visibility property is set to hide (or the CSS version, hidden). If you set the property to the CSS syntax values (hidden | visible), they are converted internally to the JavaScript versions and returned from the property in that format.

Example

document.myIlayer.visibility = "hide";

Value

One of the constant values (as a string): hide | inherit | show.

Default

inherit

zIndex NN |4| IE n/a DOM n/a
Read/Write
For a positioned element, determines the stacking order relative to other elements within the same parent container. See Chapter 4 for details on relationships of element layering amid multiple containers.

Example
document.myIlayer.zIndex = 3;
Value

Integer.

Default

0

captureEvents( ) NN |4| IE n/a DOM n/a
captureEvents(eventTypeList)
Instructs the browser to grab events of a specific type before they reach their intended target objects. The object invoking this method must then have event handlers defined for the given event types to process the event.

Returned Value

None.

Parameters

eventTypeList

A comma-separated list of case-sensitive event types as derived from the available Event object constants, such as Event.CLICK or Event.MOUSEMOVE.

handleEvent( ) NN |4| IE n/a DOM n/a
handleEvent(event)
Instructs the object to accept and process the event whose specifications are passed as the parameter to the method. The object must have an event handler for the event type to process the event.

Returned Value

None.

Parameters

event

A Navigator 4 event object.

load( ) NN |4| IE n/a DOM n/a
load("URL", newLayerWidth)
This method lets you load a new document into a layer object. It does not work properly in Navigator 4 for ilayer elements. The existing document is unloaded from the layer, but the new one does not load as you'd expect. There is no satisfactory workaround except to transform the element into a layer.

Returned Value

Boolean value: true if the document loading was successful.

Parameters

URL

String value of the complete or relative URL of the document to be loaded into the layer.

newLayerWidth

Integer value in pixels of a resized width of the element to accommodate the new content.

moveAbove( ), moveBelow( ) NN |4| IE n/a DOM n/a
moveAbove(layerObject) moveBelow(layerObject)
These methods shift the z-order of the current layer to a specific location relative to another, sibling layer. This is helpful if your script is not sure of the precise zIndex value of a layer you want to use as a reference point for the current layer's stacking order. Use moveAbove( ) to position the current layer immediately above the layer object referenced as a parameter.

Returned Value

None.

Parameters

layerObject

Reference to another layer object that shares the same parent as the current layer.

moveBy( ) NN |4| IE n/a DOM n/a
moveBy(deltaX, deltaY)
A convenience method that shifts the location of the current element by specified pixel amounts along both axes. To shift along only one axis, set the other value to zero. Positive values for deltaX shift the element to the right; negative values to the left. Positive values for deltaY shift the element downward; negative values upward. This method comes in handy for path animation under the control of a setInterval( ) or setTimeout( ) method that moves the element in a linear path over time.

Returned Value

None.

Parameters

deltaX

Positive or negative pixel count of the change in horizontal direction of the element.

deltaY

Positive or negative pixel count of the change in vertical direction of the element.

moveTo( ), moveToAbsolute( ) NN |4| IE n/a DOM n/a
moveTo(x, y) moveToAbsolute(x, y)
Convenience methods that shift the location of the current element to a specific coordinate point. The differences between the two methods show when the element to be moved is nested inside another positioned container (e.g., a layer inside a layer). The moveTo( ) method uses the coordinate system of the parent container; the moveToAbsolute( ) method uses the coordinate system of the page. For a single layer on a page, the two methods yield the same result.

Returned Value

None.

Parameters

x

Positive or negative pixel count relative to the top of the reference container, whether it is the next outermost layer (moveTo( )) or the page (moveToAbsolute( )).

y

Positive or negative pixel count relative to the left edge of the reference container, whether it is the next outermost layer (moveTo( )) or the page (moveToAbsolute( )).

releaseEvents( ) NN |4| IE n/a DOM n/a
releaseEvents(eventTypeList)
The opposite of layerObj.captureEvents( ), this method turns off event capture at the layer level for one or more specific events named in the parameter list. See Chapter 6.

Returned Value

None.

Parameters

eventTypeList

A comma-separated list of case-sensitive event types as derived from the available Event object constants, such as Event.CLICK or Event.MOUSEMOVE.

resizeBy( ) NN |4| IE n/a DOM n/a
resizeBy(deltaX, deltaY)
A convenience method that shifts the width and height of the current element by specified pixel amounts. To adjust along only one axis, set the other value to zero. Positive values for deltaX make the element wider; negative values make the element narrower. Positive values for deltaY make the element taller; negative values make the element shorter. The top and left edges remain fixed; only the right and bottom edges are moved.

Returned Value

None.

Parameters

deltaX

Positive or negative pixel count of the change in horizontal dimension of the element.

deltaY

Positive or negative pixel count of the change in vertical dimension of the element.

resizeTo( ) NN |4| IE n/a DOM n/a
resizeTo(x, y)
Convenience method that adjusts the height and width of the current element to specific pixel sizes. The top and left edges of the element remain fixed, while the bottom and right edges move in response to this method.

Returned Value

None.

Parameters

x

Width in pixels of the element.

y

Height in pixels of the element.

routeEvent( ) NN |4| IE n/a DOM n/a
routeEvent(event)
Used inside an event handler function, this method directs Navigator to let the event pass to its intended target object.

Returned Value

None.

Parameters

event

A Navigator 4 event object.

legend NN 6 IE 4 DOM 1

The legend object reflects the legend element. A legend element must be nested inside and immediately after the fieldset element associated with a form or group of form controls.

HTML Equivalent

<legend>

Object Model Reference

[window.]document.getElementById("elementID")

Object-Specific Properties

align

form

Object-Specific Methods

None.

Object-Specific Event Handler Properties

None.

align NN 6 IE 4 DOM 1
Read/Write
Controls the alignment of the legend element with respect to the containing fieldset element. The permissible values do not always work as planned in Internet Explorer 4. Be sure to check your desired setting on all operating system platforms of your intended audience.

Example

document.getElementById("myLegend").align = "center";

Value

Any one of the following constant values (as a string): bottom | center | left | right | top.

Default

left

form NN 6 IE 5(Mac)/6(Win) DOM 1
Read-only
Returns a reference to the next outermost form element object in the document tree. Multiple legend element objects within the same form element reference the same form element object.

Example

var theForm = document.getElementById("myLegend").form;

Value

Reference to a form element object.

Default

None.

li	`NN 6` IE 4 DOM 1

The li object reflects the li element nested inside an ol or ul element.

HTML Equivalent

<li>

Object Model Reference

[window.]document.getElementById("elementID")

Object-Specific Properties

type

value

Object-Specific Methods

None.

Object-Specific Event Handler Properties

None.

type NN 6 IE 4 DOM 1
Read/Write
Indicates the manner in which the leading bullets, numbers, or letters of items in the list are displayed. Bullet styles are displayed when the li element is nested inside a ul element; numbers and letters are displayed for an ol element. If your script changes the type for a single li object, be aware that the change affects all subsequent li elements in the same list.

Example

document.getElementById("instruxListItem3").type = "a"; document.getElementById("point4").type = "square";

Value

For an ol style list, possible values are: A | a | I | i | 1. Sequencing is performed automatically as shown in the following table.

Type

Example

A
A, B, C, ...

a
a, b, c, ...

I
I, II, III, ...

i
i, ii, iii, ...

1
1, 2, 3, ...

For a ul- style list, possible values are: circle | disc | square.

Default

1 and disc (although values are empty unless the corresponding attribute is explicitly assigned).

value NN 6 IE 4 DOM 1
Read/Write
Indicates the number of the item within an ordered list. This property applies to an li element only when it is nested inside an ol element, and only when the corresponding attribute is explicitly assigned in the HTML code. The default value for unadjusted numbering is always 0 in IE and -1 in Netscape 6. If you set the value property of one item in the list, the following items continue the sequence from the new value. Modifying the property value does not adjust the rendered numbering.

Example

if (document.getElementById("step5").value > 0) { ... }

Value

Integer.

Default

0 or -1.

link NN 6 IE 4 DOM 1

The link object reflects the link element. Note that many of the properties listed here are not available for scripting in the object unless their corresponding attributes are set initially in the HTML tag. Moreover, because the element's attributes act as directives while the document loads, assigning new values to the corresponding properties generally has no effect (even though the properties are read/write). This includes: href, rel, rev, and type. The media property is not available in the Macintosh version of IE 4. As a reminder, the disabled property (described among the shared properties earlier in this chapter) lets all supporting browsers turn on and off a linked style sheet.

HTML Equivalent

<link>

Object Model Reference

[window.]document.getElementById("elementID")

Object-Specific Properties

`charset`	`href`	`hreflang`	`media`	`rel`
`rev`	`sheet`	`styleSheet`	`target`	`type`

Object-Specific Methods

None.

Object-Specific Event Handler Properties

Handler	NN	IE/Windows	IE/Mac	DOM
`onerror`	n/a	4	n/a	n/a
`onload`	n/a	4	n/a	n/a

charset NN 6 IE 4 DOM 1
Read/Write
Indicates the character encoding of the content at the other end of the link.

Example

var charCoding = document.getElementById("myLink").charset;

Value

Case-insensitive alias from the character set registry (ftp://ftp.isi.edu/in-notes/iana/assignments/character-sets).

Default

None.

href NN 6 IE 4 DOM 1
Read/Write
Provides the URL specified by the element's href attribute. In IE/Windows, you can assign a new URL to this property to load in an alternate style sheet after the fact.

Example

document.getElementById("styleLink").href = "altStyles.css";

Value

String of complete or relative URL.

Default

None.

hreflang NN 6 IE 6 DOM 1
Read/Write
Specifies the language code of the content at the destination of a link. Requires that the href attribute or property also be set.

Example

document.getElementById("myLink").hreflang = "DE";

Value

Case-insensitive language code.

Default

None.

media NN 6 IE 4 DOM 1
Read/Write
Specifies the intended output device for the content of the destination document pointed to by the href attribute. The media property looks forward to the day when browsers are able to tailor content to specific kinds of devices such as pocket computers, text-to-speech digitizers, or fuzzy television sets. This property is not available in IE 4/Macintosh.

Example

if (document.getElementById("link3").media == "print") { // process for print output }

Value

Any one of the following constant values as a string: all | print | screen.

Default

all

rel NN 6 IE 4 DOM 1
Read/Write
Defines the relationship between the current element and the external item pointed to by the link. Also known as a forward link, not to be confused in any way with the destination document whose address is defined by the href attribute. This property is not fully exploited in mainstream browsers, but you can treat the attribute as a kind of parameter to be checked and/or modified under script control. See the discussion of the a element's rel attribute in Chapter 8 for a glimpse of how this property may be used in the future.

Example
if (document.getElementById("link3").rel == "alternate stylesheet") {
    // process for alternate style sheet
}
Value

Case-insensitive, space-delimited list of HTML 4 standard link types (as a single string) applicable to the element. Sanctioned link types are:

alternate

appendix

bookmark

chapter

contents

copyright

glossary

help

index

next

prev

section

start

stylesheet

subsection

Default

None.

rev NN 6 IE 4 DOM 1
Read/Write
Defines the relationship between the current element and the destination of the link. Also known as a reverse link. This property is not fully exploited in mainstream browsers, but you can treat the attribute as a kind of parameter to be checked and/or modified under script control. See the discussion of the a element's rev attribute in Chapter 8 for a glimpse of how this property may be used in the future.

Value

Case-insensitive, space-delimited list of HTML 4 standard link types (as a single string) applicable to the element. See the rel property for sanctioned link types.

Default

None.

sheet NN 6 IE n/a DOM 1
Read-only
Returns a reference to the styleSheet object (CSSStyleSheet object in W3C DOM terminology) linked into the current document when a style sheet is specified as the target of the link element. IE for Windows provides a similar property: styleSheet.

Example

var extSS = document.getElementById("link3").sheet;

Value

styleSheet object reference.

Default

None.

styleSheet NN n/a IE 5(Win) DOM n/a
Read-only
This nonstandard convenience property returns a reference to the styleSheet object linked into the current document when a style sheet is specified as the target of the link element. Netscape 6 provides a similar property: sheet.

Example

var extSS = document.getElementById("link3").styleSheet;

Value

styleSheet object reference.

Default

None.

target NN 6 IE 4 DOM 1
Read/Write
Indicates the window or frame name to be the recipient of linked content. Default value (equivalent of _self) is the desired setting for linked style sheets.

Example

document.getElementById("link4").target = "frame2";

Value

String value of the window or frame name, or any of the following constants (as a string): _parent | _self | _top | _blank.

Default

None.

type NN 6 IE 4 DOM 1
Read/Write
Indicates an advisory MIME type declaration about the data being loaded from an external source. For example, an external style sheet would be text/css. This information is usually set in the element tag's type attribute.

Example

if (document.getElementById("myStyle").type == "text/css") { ... }

Value

MIME type string.

Default

None.

links NN 2 IE 3 DOM 1

A collection of all a and area elements that have assigned href attributes that make them behave as links (instead of only anchors). Collection members are sorted in source code order. Navigator and Internet Explorer let you use array notation to access a single link in the collection (document.links[0] or document.links["section3"], for example). If you wish to use the link's name as an index value (always as a string identifier), be sure to use the value of the name attribute, rather than the id attribute. To use the id attribute in a reference to an anchor, access the object via a document.all.elementID (in IE only) or document.getElementById("elementID") reference.

Object Model Reference

document.links

Object-Specific Properties

length

Object-Specific Methods

item( )

namedItem( )

tags( )

urns( )

Object-Specific Event Handler Properties

None.

length NN 2 IE 3 DOM n/a
Read-only
Returns the number of elements in the collection.

Example

var howMany = document.links.length;

Value

Integer.

item( ) NN 6 IE 4 DOM 1
item(index) item(index[, subindex])
Returns a single object or collection of objects corresponding to the element matching the index value (or, optionally in IE/Windows, the index and subindex values).

Returned Value

One object or collection (array) of objects. If there are no matches to the parameters, the returned value is null.

Parameters

index

When the parameter is a zero-based integer (as required for Netscape 6), the returned value is a single element corresponding to the said numbered item in source code order (nested within the current element). When the parameter is a string (allowed by IE/Windows), the returned value is a collection of elements with id or name properties that match that string.

subindex

If you specify a string value for the first parameter (in IE/Windows), you may use the second parameter to specify a zero-based integer to retrieve a specific element from the collection with id or name properties that match the first parameter's string value.

namedItem( ) NN 6 IE 6 DOM 1
namedItem(IDOrName)
Returns a single object (in Netscape 6) or collection of objects corresponding to the element matching the parameter string value.

Returned Value

One object (in Netscape 6) or collection (array) of objects. If there are no matches to the parameters, the returned value is null.

Parameters

IDOrName

The string that contains the same value as the desired element's id or name attribute.

tags( ) NN n/a IE 4 DOM n/a
tags(tagName)
Returns a collection of objects (among all objects within the current collection) with tags that match the tagName parameter. Lets you distinguish among collections of a and area elements.

Returned Value

A collection (array) of objects. If there are no matches to the parameters, the returned value is an array of zero length.

Parameters

tagName

A string that contains the element tag, as in document.links.tags("a").

urns( ) NN n/a IE 5(Win) DOM n/a
urns(URN)
Returns a collection of nested element objects that have behaviors attached to them and URNs that match the URN parameter.

Returned Value

A collection (array) of objects. If there are no matches to the parameters, the returned value is an array of zero length.

Parameters

URN

A string with a local or external behavior file URN.

LinkStyle NN 6 IE n/a DOM 2

The LinkStyle object is a W3C DOM abstract object that gets blended into the link element object. Through this blending, the Netscape 6 link element object gains the sheet property, which provides a reference to the styleSheet object linked into the current document through a link element.

Object Model Reference

document.getElementById("linkElementID")

Object-Specific Properties

sheet

Object-Specific Methods

None.

Object-Specific Event Handler Properties

None.

sheet NN 6 IE n/a DOM 1
Read-only
Returns a reference to the styleSheet object (CSSStyleSheet object in W3C DOM terminology) linked into the current document when a style sheet is specified as the target of the link element. IE for Windows provides a similar property for a link element object: styleSheet.

Example

var extSS = document.getElementById("link3").sheet;

Value

styleSheet object reference.

Default

None.

location NN 2 IE 3 DOM n/a

There is one location object in each window or frame. The object stores all information about the URL of the document currently loaded into that window or frame. By assigning a new URL to the href property of the location object, you instruct the browser to load a new page into the window or frame. This is the primary way of scripting the loading of a new page:

location.href = "newPage.html";

A script in one frame can reference the location object in another frame to load a new document into that other frame:

parent.otherFrameName.location.href = "newPage.html";

Security restrictions prevent a script in one frame from accessing location object information in another frame if the document in the second frame does not come from the same domain (and the same server, unless the document.domain properties of the two documents are set to match) as the document with the nosy script. This prevents a rogue script from monitoring navigation in another frame to external web sites. In Navigator 4 and later, you can overcome the security restriction with the help of signed scripts, but the user still has to give explicit permission for a script to access location object information outside the script's domain.

As a window-related object, the location object is not part of the formal W3C DOM Level 1 or 2 specifications (which leave windows for future versions). But the location object and its properties are well-entrenched in scripting vernacular, and should continue to be supported for a long time coming.

Object Model Reference

[windowRef.]location

Object-Specific Properties

hash

host

hostname

href

pathname

port

protocol

search

Object-Specific Methods

assign( )

reload( )

replace( )

Object-Specific Event Handler Properties

None.

hash NN 2 IE 3 DOM n/a
Read/Write
Indicates that portion of a URL following the # symbol, referring to an anchor location in a document. This property contains its data only if the user has explicitly navigated to an anchor, and is not just scrolling to it. Do not include the # symbol when setting the property.

Example

location.hash = "section3";

Value

String.

Default

None.

host NN 2 IE 3 DOM n/a
Read/Write
Provides the combination of the hostname and port (if any) of the server that serves up the current document. If the port is explicitly part of the URL, the hostname and port are separated by a colon, just as they are in the URL.

Example

if (location.host == "www.megacorp.com:80") { ... }

Value

String of hostname, optionally followed by a colon and port number.

Default

Depends on server.

hostname NN 2 IE 3 DOM n/a
Read/Write
Provides the combination of the hostname of the server (i.e., a two-dot address consisting of server name and domain) that serves up the current document. The hostname property does not include the port number.

Example

if (location.hostname == "www.megacorp.com") { ... }

Value

String of hostname (server and domain).

Default

Depends on server.

href NN 2 IE 3 DOM n/a
Read/Write
Provides the complete URL of the document loaded in the window or frame. Assigning a URL to this property is how you script navigation to load a new document into the window or frame (although Internet Explorer also offers the equivalent window.navigate( ) method).

Example

location.href = "http://www.megacorp.com";

Value

String of complete or relative URL.

Default

None.

pathname NN 2 IE 3 DOM n/a
Read/Write
Provides the pathname component of the URL. This consists of all URL information following the last character of the domain name, including the initial forward slash symbol.

Example

location.pathname = "/images/logoHiRes.gif";

Value

String.

Default

None.

port NN 2 IE 3 DOM n/a
Read/Write
Provides the port component of the URL, if one exists. This consists of all URL information following the colon after the last character of the domain name. The colon is not part of the port property value.

Example

location.port = "80";

Value

String (a numeric value as string).

Default

None.

protocol NN 2 IE 3 DOM n/a
Read/Write
Provides the protocol component of the URL. This consists of all URL information up to and including the first colon of a URL. Typical values are: "http:", "file:", "ftp:", and "mailto:".

Example

if (location.protocol == "file:") { // statements for treating document as local file }

Value

String.

Default

None.

search NN 2 IE 3 DOM n/a
Read/Write
Provides the URL-encoded portion of a URL that begins with the ? symbol. A document that is served up as the result of the search also may have the search portion available as part of the window.location property. You can modify this property by script. Doing so sends the URL and search criteria to the server. You must know the format of data (usually name/value pairs) expected by the server to perform this properly. You can also pass string data between separate pages by appending a search string to the next page's URL. While the search string appendage does not affect retrieval of the page, the string arrives with the new page in the new page's location object. A script in the new page can read and dissect the location.search property to place the passed values in variables that scripts in the page may use for their processing.

Example

location.search="?p=Tony+Blair&d=y&g=0&s=a&w=s&m=25";

Value

String starting with the ? symbol.

Default

None.

assign( ) NN 2 IE 3 DOM n/a
assign("URL")
This method was intended to be hidden from view of scripters, but remains available for now. It performs the same action as assigning a URL to the location.href property. The assign( ) method is listed here for completeness and should not be used.

Returned Value

None.

Parameters

URL

A string version of a complete or relative URL of a document to be loaded into a window or frame.

reload( ) NN 3 IE 4 DOM n/a
reload([unconditional])
Performs a hard reload of the document associated with the location object. This kind of reload resets form elements to their default values (for a soft reload, use history.go(0)). By default, the reload( ) method performs a conditional-get action, which retrieves the file from the browser cache if the file is still in the cache (and the cache is turned on). To force a reload from the server, force an unconditional-get by adding the true Boolean parameter.

Returned Value

None.

Parameters

unconditional

An optional Boolean value. If true, the browser performs an unconditional-get to force a reload of the document from the server, rather than the browser cache.

replace( ) NN 3 IE 4 DOM n/a
replace("URL")
Loads a new document into the reference window and replaces the browser's history listing entry of the current document with the entry of the new document. Thus, some interim page that you don't want appearing in history (to prevent the Back button from ever returning to the page) can be removed from the history and replaced with the entry of the newly loaded document.

Returned Value

None.

Parameters

URL

A string version of a complete or relative URL of a document to be loaded into a window or frame.

map NN 6 IE 4 DOM 1

The map object reflects the map element.

HTML Equivalent

<map>

Object Model Reference

[window.]document.getElementById("elementID")

Object-Specific Properties

areas[]

name

Object-Specific Methods

None.

Object-Specific Event Handler Properties

None.

areas[ ] NN 6 IE 4 DOM 1
Read-only
Indicates a collection of all area element objects nested inside the map element.

Example

for (var i = 0; i < document.getElementById("myMap").areas.length; i++) { oneMap = document.getElementById("myMap").areas[i]; ... }

Value

Array of area element objects.

Default

Array of length zero.

name NN 6 IE 4 DOM 1
Read/Write
This is the identifier associated with the client-side image map specification. A map element contains all the area elements that define the hotspots of an image and their link destinations. The name assigned to the map element is the one cited by the usemap attribute of the img element. This binds the map definitions to the image.

Example

document.getElementById("myMap").name = "altMap";

Value

Case-sensitive string identifier that follows the rules of identifier naming: it may contain no whitespace, cannot begin with a numeral, and should avoid punctuation except for the underscore character.

Default

None.

marquee NN n/a IE 4 DOM n/a

The marquee object reflects the marquee element.

HTML Equivalent

<marquee>

Object Model Reference

[window.]document.getElementById("elementID")

Object-Specific Properties

`behavior`	`bgColor`	`dataFld`	`dataFormatAs`	`dataSrc`
`direction`	`height`	`hspace`	`loop`	`scrollAmount`
`scrollDelay`	`trueSpeed`	`vspace`	`width`

Object-Specific Methods

start( )

stop( )

Object-Specific Event Handler Properties

Handler	NN	IE	DOM
`onbounce`	n/a	4	n/a
`onfinish`	n/a	4	n/a
`onstart`	n/a	4	n/a

behavior NN n/a IE 4 DOM n/a
Read/Write
Specifies the motion of the content within the rectangular space set aside for the marquee element. You have a choice of three motion types.

Example

document.getElementById("newsBanner").behavior = "slide";

Value

Case-insensitive marquee element motion types:

alternate

Content alternates between marching left and right.

scroll

Content scrolls (according to the direction attribute or property) into view and out of view before starting again.

slide

Content scrolls (according to the direction attribute or property) into view, stops at the end of its run, blanks, and then starts again.

Default

scroll

bgColor NN n/a IE 4 DOM n/a
Read/Write
Background color of the element. This color setting is not reflected in the style sheet backgroundColor property. Even if the bgcolor attribute or bgColor property is set with a plain-language color name, the returned value is always a hexadecimal triplet.

Example

document.getElementById("myBanner").bgColor = "yellow";

Value

A hexadecimal triplet or plain-language color name. See Appendix A for acceptable plain-language color names.

Default

Inherits body background color.

dataFld NN n/a IE 4 DOM n/a
Read/Write
Used with IE data binding to associate a remote data source column name with the content of the marquee element. A datasrc attribute must also be set for the element. Setting both the dataFld and dataSrc properties to empty strings breaks the binding between element and data source. Works only with text file data sources in IE 5/Mac.

Example

document.getElementById("myBanner").dataFld = "hotNews";

Value

Case-sensitive string identifier of the data source column.

Default

None.

dataFormatAs NN n/a IE 4 DOM n/a
Read/Write
Used with IE data binding, this property advises the browser whether the source material arriving from the data source is to be treated as plain text or as tagged HTML.

Example

document.getElementById("myBanner").dataFormatAs = "text";

Value

IE recognizes two possible settings: text | html.

Default

text

dataSrc NN n/a IE 4 DOM n/a
Read/Write
Used with IE data binding to specify the ID of the page's object element that loads the data source object for remote data access. Setting both the dataFld and dataSrc properties to empty strings breaks the binding between element and data source. Works only with text file data sources in IE 5/Mac.

Example

document.getElementById("myBanner").dataSrc = "DBSRC3";

Value

Case-sensitive string identifier of the data source.

Default

None.

direction NN n/a IE 4 DOM n/a
Read/Write
Specifies the direction of the scroll within the element space.

Example

document.getElementById("myBanner").direction = "down";

Value

Four possible case-insensitive directions: down | left | right | up.

Default

left

height, width NN n/a IE 4 DOM n/a
Read/Write
Provide the height and width in pixels of the element. Changes to these values are immediately reflected in reflowed content on the page.

Example

document.getElementById("myBanner").height = 250;

Value

Integer.

Default

None.

hspace, vspace NN n/a IE 4 DOM n/a
Read/Write
Provide the pixel measure of horizontal and vertical margins surrounding the element. The hspace property affects the left and right edges of the element equally; the vspace affects the top and bottom edges of the element equally. These margins are not the same as margins set by style sheets, but they have the same visual effect.

Example

document.getElementById("myBanner").hspace = 5; document.getElementById("myBanner").vspace = 8;

Value

Integer of pixel count.

Default

0

loop NN n/a IE 4 DOM n/a
Read/Write
Sets the number of times the element scrolls its content. After the final scroll, the content remains in a fixed position. Constant animation can sometimes be distracting to page visitors, so if you have the marquee turn itself off after a few scrolls, you may be doing your visitors a favor.

Example

document.getElementById("myBanner").loop = 3;

Value

Any positive integer if you want the scrolling to stop after that number of times. Otherwise, set the value to -1.

Default

-1

scrollAmount NN n/a IE 4 DOM n/a
Read/Write
Specifies the amount of space between positions of each drawing of the content. The greater the space, the faster the text appears to scroll. See also scrollDelay.

Example

document.getElementById("myBanner").scrollAmount = 4;

Value

Positive integer.

Default

6

scrollDelay NN n/a IE 4 DOM n/a
Read/Write
Specifies the amount of time in milliseconds between each drawing of the content. The greater the delay, the slower the text appears to scroll. See also scrollAmount.

Example

document.getElementById("myBanner").scrollDelay = 100;

Value

Positive integer.

Default

85 (Windows 95); 90 (Macintosh).

trueSpeed NN n/a IE 4 DOM n/a
Read/Write
Specifies whether the browser should honor scrolldelay attribute settings below 60 milliseconds. The default setting (false) prevents accidental settings that scroll too fast for most readers.

Example

document.getElementById("myBanner").trueSpeed = "true";

Value

Boolean value: true | false.

Default

false

vspace
See hspace.

width
See height.

start( ) NN n/a IE 4 DOM n/a
Starts the marquee element scrolling if it has been stopped. If the method is invoked on a stopped element, the onstart event handler also fires in response.

Returned Value

None.

Parameters

None.

stop( ) NN n/a IE 4 DOM n/a
Stops the scrolling of the marquee element. The content remains on the screen in the precise position it was in when the method was invoked. Restart via the start( ) method.

Returned Value

None.

Parameters

None.

MediaList NN 6 IE n/a DOM 2

The MediaList object is an abstract representation in the W3C DOM of a collection of string names for media specified for a particular styleSheet object. The media property of a styleSheet object returns a value that is a MediaList object (IE 6 for Windows incorrectly returns a string value). Media types (such as print, screen, aural, and so on) are specified for the style sheet either via the media attribute of a link element or an @media rule in a style element. As of Version 6 browsers, media support beyond print and screen types (and the default all type) is rather limited, so the details of this object are not yet important.

Object-Specific Properties

length

mediaText

Object-Specific Methods

appendMedium( )

deleteMedium( )

item( )

Object-Specific Event Handler Properties

None.

length NN 6 IE n/a DOM 2
Read-only
Returns the number of items in the collection.

Example

var howMany = document.styleSheets[0].media.length;

Value

Integer.

mediaText NN 6 IE n/a DOM 2
Read-only
Returns the entire string of comma-delimited media names.

Example

var allMedia = document.styleSheets[0].media.mediaText;

Value

String.

appendMedium( ), deleteMedium( ) NN 7 IE n/a DOM 2
appendMedium("mediumType") deleteMedium("mediumType")
Adds or removes a medium type from the list. In Netscape 6.2, the methods are incorrectly named append( ) and delete( ).

Returned Value

None.

Parameters

mediumType

String of recognized media type (e.g., print, screen).

item( ) NN 6 IE n/a DOM 2
item(index)
Returns one media name string from the collection corresponding to the item matching the index value in source code order.

Returned Value

String.

Parameters

index

A zero-based integer corresponding to the specified item in source code order.

menu NN 6 IE 4 DOM 1

The menu object reflects the menu element.

HTML Equivalent

<menu>

Object Model Reference

[window.]document.getElementById("elementID")

Object-Specific Properties

compact

type

Object-Specific Methods

None.

Object-Specific Event Handler Properties

None.

compact NN 6 IE 5(Mac)/6(Win) DOM 1
Read/Write
Provided for this element for the sake of compatibility with the W3C DOM standard. However, mainstream browsers do not act upon this property or its corresponding attribute.

Value

Boolean value: true | false.

Default

false

type NN n/a IE 6(Win) DOM n/a
Read/Write
Implemented in IE 6 for Windows due to internal element relationships with the ol and ul element objects. Ignore for the menu element object.

meta NN 6 IE 4 DOM 1

The meta object reflects the meta element.

HTML Equivalent

<meta>

Object Model Reference

[window.]document.getElementById("elementID")

Object-Specific Properties

charset

content

httpEquiv

name

scheme

url

Object-Specific Methods

None.

Object-Specific Event Handler Properties

None.

charset NN n/a IE 4 DOM n/a
Read/Write
Indicates the character encoding of the content in the file associated with the href attribute. This property does not change the setting of the charset attribute of a name/value pair contained by the content attribute or property. For now the charset property has little or no effect on a document.

Example

if (document.all.myMeta.charset == "csISO5427Cyrillic") { // process for Cyrillic charset }

Value

Case-insensitive alias from the character set registry (ftp://ftp.isi.edu/in-notes/iana/assignments/character-sets).

Default

Determined by browser.

content NN 6 IE 4 DOM 1
Read/Write
This is the equivalent of the value of a name/value pair. The property's corresponding content attribute is usually accompanied by either a name or http-equiv attribute, either of which acts as the name portion of the name/value pair. Specific values of the content attribute vary with the value of the name or http-equiv attribute. Sometimes the content attribute value contains multiple values. In such cases, the values are delimited by a semicolon. Some of these multiple values may be name/value pairs in their own right, such as the content for a refresh meta element. The first value is a number representing the number of seconds of delay before loading another document; the second value is a name/value pair indicating a URL of the document to load after the delay expires.
Despite the following example, changing the content property on a loaded document may not produce the desired effect if the browser relies on the incoming value as the document loads.

Example

document.getElementById("refreshMeta").content = "5,http://www.giantco.com/basicindex.html";

Value

String.

Default

None.

httpEquiv NN 6 IE 4 DOM 1
Read/Write
This is the equivalent of the name of a name/value pair. The property's corresponding http-equiv attribute is usually accompanied by a content attribute, which acts as the "value" portion of the name/value pair. The author may elect to use the name attribute instead of the http-equiv attribute, but only one may be set. Adjust only the property corresponding to the attribute used in the meta element's tag. Then be sure to set the content property with a value that makes sense with the httpEquiv or name property.

Example

document.getElementById("refreshMeta").httpEquiv = "expires";

Value

String.

Default

None.

name NN 6 IE 4 DOM 1
Read/Write
This is an identifier for the name/value pair that constitutes the meta element. The value is typically a plain-language term that denotes the purpose of the meta element, such as "author" or "keywords". Either the name or httpEquiv properties can have a value, but not both, in the same meta element.

Example

document.getElementById("detailMeta").name = "keywords";

Value

String.

Default

None.

scheme NN 6 IE 5(Mac)/6(Win) DOM 1
Read/Write
Reflects the scheme attribute, but as yet has no particular functionality in current browsers. See the scheme attribute of the meta element in Chapter 8 for information about the intended purpose of this property.

Value

String.

Default

None.

url NN n/a IE 4 DOM n/a
Read/Write
Although implemented in IE browsers, this property no longer appears to be officially supported.

mimeType NN 3 IE 5(Mac) DOM n/a

The mimeType object belongs to the navigator object. The object represents a MIME type specification. Its properties let scripts find out if the browser is equipped to handle a specific MIME type of external content before it is loaded from the server. All these properties are mirrored in the internal document displayed when you choose Navigator's About Plug-ins menu option. Internet Explorer 5 for the Macintosh implements this scheme, but Explorer for Windows uses an entirely different system for determining support for external media via the object element.

Object Model Reference

navigator.mimeTypes[i]

Object-Specific Properties

description

enabledPlugin

suffixes

type

Object-Specific Methods

None.

Object-Specific Event Handler Properties

None.

description NN 3 IE 5(Mac) DOM n/a
Read-only
Returns the brief description of the plugin. This information is embedded in the plugin by its developer. Be aware that the precise wording of this description may vary for the same plugin written for different operating systems.

Example

var descr = navigator.mimeTypes["video/mpeg"].description;

Value

String.

Default

None.

enabledPlugin NN 3 IE 5(Mac) DOM n/a
Read-only
Returns a plugin object reference corresponding to the plugin currently set to play any incoming data formatted according to the current MIME type. You can then dig deeper into properties of the returned plugin object to retrieve, say, its name.

Example

var plugName = navigator.mimeTypes["video/mpeg"].enabledPlugin.name;

Value

plugin object reference.

Default

None.

suffixes NN 3 IE 5(Mac) DOM n/a
Read-only
Returns a comma-delimited string list of file suffixes associated with the mimeType object, as supported by the plugin enabled for that MIME type. For example, the suffixes that the QuickTime plugin acknowledges for the type video/avi are:
avi, vfw
If you loop through all mimeType objects registered in the browser to find a match for a specific suffix, you can then find out whether the matching mimeType object has a plugin installed for it (via the enabledPlugin property).

Example

var suff = navigator.mimeTypes["audio/mpeg"].suffixes;

Value

String.

Default

None.

type NN 3 IE 5(Mac) DOM n/a
Read-only
Returns a string version of the MIME type associated with the mimeType object. You could, for example, loop through all the mimeType objects in search of the one that matches a specific MIME type (application/x-midi) and examine that mimeType object further to see whether it is currently supported and enabled.

Example

var MType = navigator.mimeTypes[3].type;

Value

String.

Default

None.

navigator NN 2 IE 3 DOM n/a

The navigator object in many ways represents the browser application. As such, the browser is outside the scope of the document object model. Even so, the navigator object plays an important role in scripting, because it allows scripts to see what browser and browser version is running the script. In addition to several key properties that both Navigator and Internet Explorer have in common, each browser also extends the property listing of this object in ways that would generally benefit all browsers. IE duplicates this object under the clientInformation object name, but for cross-browser compatibility, you can use the navigator object reference in all browsers.

Object Model Reference

NN: navigator
IE: [window.]navigator

Object-Specific Properties

`appCodeName`	`appMinorVersion`	`appName`	`appVersion`
`browserLanguage`	`cookieEnabled`	`cpuClass`	`language`
`mimeTypes[]`	`onLine`	`oscpu`	`platform`
`plugins[]`	`product`	`productSub`	`securityPolicy`
`systemLanguage`	`userAgent`	`userLanguage`	`userProfile`
`vendor`	`vendorSub`

Object-Specific Methods

javaEnabled( )

preference( )

taintEnabled( )

Object-Specific Event Handler Properties

None.

appCodeName NN 2 IE 3 DOM n/a
Read-only
Reveals the code name of the browser. Both Navigator and Internet Explorer return Mozilla, which was the code name for an early version of Navigator (a combination of the early freeware name of the Mosaic browser and Godzilla). The Mozilla character is Netscape's corporate mascot, but all browsers that license the original Mosaic technology (including IE) return Mozilla.

Example

var codeName = navigator.appCodeName;

Value

Mozilla

Default

Mozilla

appMinorVersion NN n/a IE 4 DOM n/a
Read-only
With succeeding generations of Internet Explorer, this property returns a dizzying range of values, most of which are not useful for typical version detection. IE 5.x for Windows returns an appVersion value of 4.0, with the appMinorVersion reporting the first digit to the right of the decimal. In IE 6 for Windows, the appMinorVersion returns a string signifying a build or patch code number, such as ;Q313675;. Use with extreme caution.

Example

var subVer = navigator.appMinorVersion;

Value

String.

Default

Depends on browser version.

appName NN 2 IE 3 DOM n/a
Read-only
Reveals the model name of the browser.

Example

var isNav = navigator.appName == "Netscape";

Value

String values. NN: "Netscape"; IE: "Microsoft Internet Explorer". Some other browsers return these values to appear to be compatible with one of the mainstream browsers.

Default

Depends on browser.

appVersion NN 2 IE 3 DOM n/a
Read-only
Reveals a version number of the browser engine, along with minimal operating system platform information (a subset of the information returned by userAgent). Sample returned values are as follows.
Internet Explorer:
4.0 (compatible; MSIE 6.0; Windows 98; Q312461) 4.0 (compatible; MSIE 5.0; Macintosh; I; PPC)
Navigator:
4.04 [en] (Win95; I) 5.0 (Macintosh; en-US)
Note that the version number at the start of the value (up to the first whitespace) is not indicative of the actual browser application version, but rather of the fundamental engine. Thus, IE application Versions 4 through 6 (and perhaps later) all report engine Version 4.0; Netscape 6 is based on what it terms engine generation 5.0. Browser application version information is found elsewhere either in the appVersion, userAgent, or other navigator object properties. Do not use the first word of the appVersion value for any kind of browser version detection that influences which DOM or JavaScript language features are supported by the browser. In browsers leading up to Version 4, this property correctly reflected the application version, but that is no longer the case.
While it may appear that the precise Internet Explorer version is embedded in this property's value (as MSIE X.XX), there are occasional mismatches in some versions. To inspect this portion of the version string, the navigator.userAgent property is more reliable.

Example

var isVer4Min = parseInt(navigator.appVersion) >= 4;

Value

String.

Default

Depends on browser.

browserLanguage NN n/a IE 4 DOM n/a
Read-only
Provides the default written language of the browser. The Navigator equivalent is the navigator.language property.

Example

var browLangCode = navigator.browserLanguage;

Value

Case-insensitive language code as a string.

Default

Browser default.

cookieEnabled NN 6 IE 4 DOM n/a
Read-only
Returns whether the browser allows reading and writing of cookie data.

Example

if (cookieEnabled) { setCookieData(data); }

Value

Boolean value: true | false.

Default

Depends on browser preference setting.

cpuClass NN n/a IE 4 DOM n/a
Read-only
Returns a string reference of the CPU of the client computer. Common Intel microprocessors (including Pentium-class CPUs and Macintoshes running Windows emulators) return x86, while PowerPC Macintoshes return PPC. This value tells you only about the basic hardware class, not the operating system or specific CPU speed or model number.

Example

if (navigator.cpuClass == "PPC") { // statements specific to PowerPC clients }

Value

String.

Default

Depends on client hardware.

language NN 4 IE n/a DOM n/a
Read-only
Indicates the written language for which the browser version was created. The language is specified in the ISO 639 language code scheme (such as en-us). Internet Explorer provides this information via the navigator.browserLanguage property.

Example

var mainLang = navigator.language;

Value

Case-insensitive language code as a string.

Default

Browser default.

mimeTypes NN 4 IE 5(Mac) DOM n/a
Read-only
Returns an array of mimeType objects supported by installed plugins in the browser. IE for Windows provides this property for syntactical compatibility, but it always returns an array of zero length. See the mimeType object.

Example

var videoPlugin = navigator.mimeTypes["video/mpeg"].enabledPlugin;

Value

Array of mimeType objects.

Default

Browser default.

onLine NN n/a IE 4 DOM n/a
Read-only
Specifies whether the browser is set for online or offline browsing (in Internet Explorer's File menu). Pages may wish to invoke live server actions when they load in online mode, but avoid these calls when in offline mode. Use this Boolean property to build such conditional statements.

Example

if (navigator.onLine) { document.write("<applet ...>"); ... }

Value

Boolean value: true | false.

Default

true

oscpu NN 6 IE n/a DOM n/a
Read-only
Returns a string containing operating system or central processing unit information about the client machine. Values vary widely across systems. Windows clients are divided roughly into two categories: non-NT and NT. The former includes Windows 95, 98, and ME (oscpu values of Win95, Win98, and Win 9x 4.90, respectively). The NT category includes Windows NT 4 (WinNT4.0) and Windows XP (Windows NT x.x). Macintosh systems all report the CPU type and the absence or presence of Mac OS X (PPC or PPC Mac OS X). Unix systems report both the operating system and CPU type. The oscpu value is also a part of the userAgent value. Formatting for this information is not the same in Internet Explorer's corresponding cpuClass or userAgent properties.

Example

if (navigator.oscpu.indexOf("Win") != -1) { document.write("You are running a Windows computer."); }

Value

String.

Default

System dependent.

platform NN 4 IE 4 DOM n/a
Read-only
Returns the name of the operating system or hardware platform of the browser. For Windows 95/NT, the value is Win32; for a Macintosh running a PowerPC CPU, the value is MacPPC. At least for the major platforms I've been able to test, Navigator and Internet Explorer agree on the returned values. Using this property to determine the baseline facilities of the client in a conditional expression can help the page optimize its output for the device.

Example

if (navigator.platform == "Win32") { document.write("<link rel='stylesheet' type='text/css' href='css/stylePC.css'>"); }

Value

String.

Default

System dependent.

plugins[ ] NN 3 IE 5(Mac) DOM n/a
Read-only
Returns a collection of plugin objects recognized by the browser to facilitate script determination of the browser's support for a particular external media type. IE 4 and later for Windows implement this property, but only as a dummy placeholder that always returns an array of length zero. See the mimeType and plugin objects.

Example

var plugInCount = navigator.plugins.length;

Value

Array of plugin object references.

Default

None.

product, productSub NN 6 IE n/a DOM n/a
Read-only
Return a string identifying the software engine behind the browser. In Netscape 6, the product property returns Gecko, while the productSub property returns a development build number (in string form).

Example

var prod = navigator.product;

Value

String.

Default

Browser dependent.

securityPolicy NN 4 IE n/a DOM n/a
Read-only
Returns a string in Navigator 4 revealing the browser's encryption level (that is, the domestic or export encryption policy to which the browser adheres). With the loosening of U.S. encryption export laws, Netscape 6 implements one encryption type across all versions. In Netscape 6, this property returns an empty string.

Value

String.

Default

None.

systemLanguage NN n/a IE 4 DOM n/a
Read-only
Specifies the code for the default written language used by the operating system. If you have multi-lingual content available, you can use this property to insert content in specific languages.

Example

if (navigator.systemLanguage == "nl") { // document.write( ) some Dutch content }

Value

Case-insensitive language code.

Default

Usually the browser default (en for English-language Internet Explorer available in the United States).

userAgent NN 2 IE 3 DOM n/a
Read-only
Provides information about the browser software, including version, operating system platform, and brand. This is the most complete set of information about the browser, whereas appVersion and appName properties provide subset (and not always correct) data. Typical data for the userAgent property looks like the following examples from IE and Navigator:
Mozilla/4.0 (compatible; MSIE 6.0; Windows 98; Q312461) Mozilla/5.0 (Macintosh; U; PPC; en-US; rv:0.9.4) Gecko/20011022 Netscape6/6.2
Do not rely on the length or position of any part of this data, as it may vary with the browser, version, and proxy server used at the client end. Instead, use the indexOf( ) method to check for the presence of a desired string. To extract only the actual application version number for IE, use the following function:
function readIEVersion( ) { var ua = navigator.userAgent; var IEOffset = ua.indexOf("MSIE "); return parseFloat(ua.substring(IEOffset + 5, ua.indexOf(";", IEOffset))); }

Example

if (navigator.userAgent.indexOf("MSIE") != -1) { var isIE = true; }

Value

String.

Default

Browser dependent.

userLanguage NN n/a IE 4 DOM n/a
Read-only
The default written language of the browser, based on the operating system user profile setting (if one exists). The property defaults to the browserLanguage property.

Example

var userLangCode = navigator.userLanguage;

Value

Case-insensitive language code as a string.

Default

Browser default.

userProfile NN n/a IE 4 DOM n/a
Read-only
The userProfile property is, itself, an object that lets scripts request permission to access personal information stored in the visitor's user profile (for Win32 versions of Internet Explorer). See the userProfile object.

Example

navigator.userProfile.addReadRequest("vcard.displayname"); navigator.userProfile.doReadRequest("3", "MegaCorp Customer Service"); var custName = navigator.userProfile.getAttribute("vcard.displayname"); navigator.userProfile.clearRequest( ); if (custName) { ... }

Value

userProfile object reference.

Default

Browser default.

vendor, vendorSub NN 6 IE n/a DOM n/a
Read-only
Return a string identifying the browser product that employs the Mozilla engine. In Netscape 6, the vendor property returns Netscape6, while Netscape 7 returns simply Netscape. The vendorSub property returns the version release in detail (in string form). If you want to test for a minimum version, convert the navigator.vendorSub value to a decimal floating-point number before performing a comparison against your minimum requirement.

Example

if (parseFloat(navigator.vendorSub, 10) >= 6.2) { // OK, meets minimum NN requirement }

Value

String.

Default

Browser dependent.

javaEnabled( ) NN 3 IE 4 DOM n/a
Returns whether Java is turned on in the browser. This method obviously won't help you in a nonscriptable browser (or scriptable browser that doesn't support the property), but if scripting is enabled, it does tell you whether the user has Java turned off in the browser preferences.

Returned Value

Boolean value: true | false.

Parameters

None.

preference( ) NN 4 IE n/a DOM n/a
preference(name[, value])
By way of signed scripts in Navigator 4, you can access a wide variety of user preferences settings. These include even the most detailed items, such as whether the user has elected to download images or whether style sheets are enabled. Most of these settings are intended for scripts used by network administrators to install and control the user settings of enterprise-wide deployment of Navigator. Consult the Netscape developer web site for further information about these preferences settings (http://developer.netscape.com/docs/manuals/communicator/preferences/). Netscape 6 throws a security exception when invoking this method (even with signed scripts), but the method works with signed scripts in Netscape 7.

Returned Value

Preference value in a variety of data types.

Parameters

name

The preference name as a string, such as general.always_load_images.

value

An optional value to set the named preference.

taintEnabled( ) NN 3 IE 4 DOM n/a
Returns whether data tainting is turned on in the browser. This security mechanism was never fully implemented in Navigator, but the method that checks for it is still included in newer versions of Navigator for backward compatibility. Internet Explorer also includes it for compatibility, even though it always returns false.

Returned Value

Boolean value: true | false.

Parameters

None.

NodeFilter NN 7 IE n/a DOM 2

The NodeFilter object provides a mechanism for the NodeIterator and TreeWalker objects to determine which nodes or classes of nodes are to be accepted or rejected for inclusion into one of the special node lists. The lone accept( ) method is invoked silently by the NodeInterator and TreeWalker objects whenever the objects are asked to point to the next node in sequence. The NodeFilter object is also the holder of two sets of constants that are used in a variety of creation method calls and user-defined filter functions. See the TreeWalker object for an example, and the document.createTreeWalker( ) method for application of the constants.

Object Model Reference

NodeFilter

Object-Specific Properties

`FILTER_ACCEPT`	`FILTER_REJECT`	`FILTER_SKIP`
`SHOW_ALL`	`SHOW_ATTRIBUTE`	`SHOW_CDATA_SECTION`
`SHOW_COMMENT`	`SHOW_DOCUMENT`	`SHOW_DOCUMENT_FRAGMENT`
`SHOW_DOCUMENT_TYPE`	`SHOW_ELEMENT`	`SHOW_ENTITY`
`SHOW_NOTATION`	`SHOW_PROCESSING_INSTRUCTION`	`SHOW_TEXT`

Object-Specific Methods

accept( )

Object-Specific Event Handler Properties

None.

accept( ) NN 7 IE n/a DOM 2
accept(nodeReference)
Returns an integer signifying whether a node is to be included in the NodeIterator or TreeWalker object's list. This method is invoked automatically by the objects whenever one of their pointer-moving methods is invoked.

Returned Value

Integer value, each of which has a corresponding constant value associated with the NodeFilter object: 1 (NodeFilter.FILTER_ACCEPT); 2 (NodeFilter.FILTER_REJECT); 3 (NodeFilter.FILTER_SKIP).

Parameters

nodeReference

Reference to the document tree node under test. Passed automatically to the method when invoked by the NodeInterator and TreeWalker objects.

NodeIterator NN n/a IE n/a DOM 2

The NodeIterator object is a "live" list of nodes that meet the criteria defined by the document.createNodeIterator( ) method. The list is a simple list of node references in source code order, but the list items do not bear any parent or descendant relationships to each other. The createNodeIterator( ) method describes the node where the list begins and which nodes (or classes of nodes) are exempt from the list by way of filtering (see the TreeWalker object for an example of this kind of filtering).

The NodeIterator object maintains a kind of pointer inside the list (so that your scripts don't have to). Methods of this object let scripts access the next or previous node in the list, while moving the pointer one position in either direction. If scripts modify the document tree after the NodeIterator is created, changes to the document tree are automatically reflected in the sequence of nodes in the NodeIterator.

Object Model Reference

NodeIteratorReference

Object-Specific Properties

expandEntityReference

filter

root

whatToShow

Object-Specific Methods

detach( )

nextNode( )

previousNode( )

Object-Specific Event Handler Properties

None.

expandEntityReference, filter, root, whatToShow NN n/a IE n/a DOM 2
Read-only
See these properties of the TreeWalker object.

detach( ) NN n/a IE n/a DOM 2
Disconnects the current NodeIterator object from the document tree. Items in the list are no longer accessible once the method is invoked.

Returned Value

None.

Parameters

None.

nextNode( ), previousNode( ) NN n/a IE n/a DOM 2
Moves the internal NodeIterator pointer one position forward (nextNode( )) or backward (previousNode( )), while returning a reference to the node through which the pointer passed en route.

Returned Value

Reference to a node in the document tree.

Parameters

None.

object NN 6 IE 4 DOM 1

The object object reflects the object element. This is an updated way of embedding other media and external data into a document (through a plugin or, in IE for Windows, an ActiveX control). The depth and quality of implementation of this object (vis-à-vis the W3C specifications) is uneven across browser brands and versions. The most consistent implementation is in IE for Windows for loading ActiveX controls.

HTML Equivalent

<object>

Object Model Reference

[window.]document.getElementById("elementID")

Object-Specific Properties

`align`	`alt`	`altHtml`	`archive`	`BaseHref`
`border`	`classid`	`code`	`codeBase`	`codeType`
`contentDocument`	`data`	`dataFld`	`dataSrc`	`declare`
`form`	`height`	`hspace`	`name`	`object`
`standby`	`type`	`useMap`	`vspace`	`width`

Object-Specific Methods

None.

Object-Specific Event Handler Properties

Handler	NN	IE	DOM
`onabort`	n/a	n/a	2
`onerror`	n/a	4	2
`onload`	n/a	n/a	2

align NN n/a IE 4 DOM 1
Read/Write
Defines how the element is aligned relative to surrounding text content. Most values set the vertical relationship between the element and surrounding text. For example, to align the bottom of the element with the baseline of the surrounding text, the align property value would be baseline. An element can be "floated" along the left or right margin to let surrounding text wrap around the element.

Example

document.getElementById("myObject").align = "absmiddle";

Value

Any of the following alignment constant values (as a string): absbottom | absmiddle | baseline | bottom | right | left | none | texttop | top.

Default

bottom

alt NN n/a IE 6(Win) DOM n/a
Read/Write
Indicates the text to be displayed (or spoken) where the object element appears on the page when a browser doesn't download graphics (or is waiting for the image to download). Presumably, Microsoft implemented this nonstandard property for occasions when the object element is used for the display of images, rather than the more common img element.

Example

document.getElementById("logoDisplay").alt = "MegaCorp Logo";

Value

String value.

Default

None.

altHtml NN n/a IE 4 DOM n/a
Read/Write
Provides HTML content to be displayed if the object or applet fails to load. This can be a message, static image, or any other HTML that best fits the scenario. There are inconsistencies in Internet Explorer with regard to this property name's case. The Win32 version requires altHtml; the Mac version requires altHTML.

Example

document.getElementById("myObject").altHtml = "<img src='objectAlt.gif'>";

Value

Any quoted string of characters, including HTML tags.

Default

None.

archive NN 6 IE 6(Win) DOM 1
Read/Write
Reflects the archive attribute of the object element, but Version 6 browsers assign no functionality to either the attribute or property.

Value

String value.

Default

None.

BaseHref NN n/a IE 4(Win) DOM n/a
Read-only
Returns the URL of the document containing the object element. Most commonly, the value is the same as the location.href of the current window. Note the unusual letter case.

Example

var where = document.getElementById("myObject").BaseHref;

Value

URL string.

Default

Current document's URL.

border NN 6 IE 6(Win) DOM 1
Read/Write
Controls the thickness of the border in pixels. For cross-browser compatibility use string values.

Example

document.getElementById("myObject").border = "5";

Value

Number as string.

Default

0

classid NN n/a IE 4 DOM n/a
Read-only
Provides the URL of the object's implementation. In Internet Explorer, the URL can point to the client computer's CLSID directory (with a clsid: URL) that stores all the IDs for registered ActiveX controls, such as DirectX or Media Player. IE 4 for Macintosh names this property classID, but the name was repaired to all lowercase in IE 4.5. The W3C DOM omits this property, even though HTML 4 includes the corresponding attribute.

Example

if (document.getElementById("soundObject").classid == "clsid:83A38BF0-B33A-A4FF-C619A82E891D"){ // process for the desired sound object }

Value

String (including the clsid: protocol for local ActiveX controls).

Default

None.

code NN 6 IE 4 DOM 1
Read-only
Provides the name of the Java applet class file set to the code attribute of the object element (when using an object element in lieu of an applet element—if supported by your browsers).

Example

if (document.getElementById("clock").code == "Y2Kcounter.class") { // process for the found class file }

Value

Case-sensitive applet class filename as a string.

Default

None.

codeBase NN 6 IE 4 DOM 1
Read-only
This is the path to the directory holding the class file designated in either the code or classid attribute. The codebase attribute does not name the class file, just the path.

Example

if (document.getElementById("clock").codeBase == "classes") { // process for the found class file directory }

Value

Case-sensitive pathname, usually relative to the directory storing the current HTML document.

Default

None.

codeType NN 6 IE 4 DOM 1
Read/Write
Provides an advisory about the content type of the object referred to by the classid attribute. A browser might use this information to assist in preparing support for a resource requiring a multimedia player or plugin. If the codetype property is set to an empty string, the browser looks next for the type attribute setting (although it is normally associated with content linked by the data attribute URL). If both attributes have no (or empty) values set, the browser gets the content type information from the resource as it downloads.

Example

document.getElementById("gameTime").codeType = "application/x-crossword";

Value

Case-insensitive MIME type. A catalog of registered MIME types is available from ftp://ftp.isi.edu/in-notes/iana/assignments/media-types/.

Default

None.

contentDocument NN 6 IE n/a DOM 2
Read-only
Refers to a document node created by the object element, if any.

Value

Document node reference or null.

Default

null

data NN 6 IE 4 DOM 1
Read-only
URL of a file containing data for the object element (as distinguished from the object itself). Relative URLs are calculated relative to the codebase attribute if one is assigned; otherwise, the URL is relative to the document's URL.

Example

var objDataURL = document.getElementById("soundEffect").data;

Value

A complete or relative URL as a string.

Default

None.

dataFld NN n/a IE 4 DOM n/a
Read/Write
Used with IE data binding to associate a remote data source column name to an object element attribute determined by properties set in the object. A datasrc attribute must also be set for the element. Setting both the dataFld and dataSrc properties to empty strings breaks the binding between element and data source.

Example

document.getElementById("myObject").dataFld = "streamURL";

Value

Case-sensitive identifier of the data source column.

Default

None.

dataSrc NN n/a IE 4 DOM n/a
Read/Write
Used with IE data binding to specify the ID of the page's object element that loads the data source object for remote data access (an object element other than the current one). Setting both the dataFld and dataSrc properties to empty strings breaks the binding between element and data source.

Example

document.getElementById("myObject").dataSrc = "DBSRC3";

Value

Case-sensitive identifier of the data source.

Default

None.

declare NN 6 IE 6 DOM 1
Read/Write
Reflects the declare attribute. As of Version 6 browsers, has no effect on the content.

Value

Boolean value: true | false.

Default

false

form NN 6 IE 4 DOM 1
Read-only
Returns a reference to the form element that contains the current element (if any). This property is appropriate only if the object is acting as a form control. Not available in IE 4.0 for the Macintosh.

Value

Object reference or null.

Default

None.

height, width NN 6 IE 4 DOM 1
Read/Write
Provide the height and width of the element, in pixels. Changes to these values are immediately reflected in reflowed content on the page.

Example

document.getElementById("myObject").height = 250;

Value

Integer.

Default

None.

hspace, vspace NN 6 IE 4 DOM 1
Read/Write
Provide the pixel measure of horizontal and vertical margins surrounding an object element. The hspace property affects the left and right edges of the element equally; the vspace affects the top and bottom edges of the element equally. These margins are not the same as margins set by style sheets, but they have the same visual effect.

Example

document.getElementById("myObject").hspace = 5; document.getElementById("myObject").vspace = 8;

Value

Integer of pixel count as string.

Default

0

name NN 6 IE 4 DOM 1
Read/Write
This is the identifier associated with the object element. If the object should be one that goes inside a form, the name property is submitted as one-half of the name/value pair when the form is submitted to the server.

Example

document.getElementById("myObject").name = "company";

Value

Case-sensitive string identifier that follows the rules of identifier naming: it may contain no whitespace, cannot begin with a numeral, and should avoid punctuation except for the underscore character.

Default

None.

object NN n/a IE 4 DOM n/a
Read-only
Provides a reference to a wrapper around an object to allow access to document object model properties of the object element when the names may be confused with internal property naming of the object. For example, if the code loaded into an object element had a property named hspace, the script reference document.getElementById("reader").object.hspace would retrieve that internal property, rather than the hspace property of the HTML element. The object property wrapper tells the JavaScript interpreter to get the property from the HTML element without diving into the external object's code.

Example

var objCode = document.getElementById("reader").object.code;

Value

Object reference.

Default

None.

standby NN 6 IE 5(Mac)/6(Win) DOM 1
Read-only
This will eventually assume the duty of the alt attribute for displaying a message during loading. Currently has no effect on the element.

Value

String.

Default

None.

type NN 6 IE 4 DOM 1
Read/Write
Provides an advisory about the MIME type of the external data to be loaded into the object. The browser looks to the type property value if the codeType property is null.

Example

if (document.getElementById("myObject").type == "image/jpeg") { ... }

Value

Case-insensitive MIME type. A catalog of registered MIME types is available from ftp://ftp.isi.edu/in-notes/iana/assignments/media-types/.

Default

None.

useMap NN 6 IE 6 DOM 1
Read/Write
Provides the URL of the map element in the same document that contains client-side image map hot areas and links. The value includes the hash mark assigned with the map name in the usemap attribute of the object element.

Example

document.getElementById("logoViewer").useMap = "#altMap";

Value

A string starting with a hash mark and the name of the map element.

Default

None.

vspace
See hspace.

width
See height.

ol	`NN 6 IE 4 DOM 1`

The ol object reflects the ol element.

HTML Equivalent

<ol>

Object Model Reference

[window.]document.getElementById("elementID")

Object-Specific Properties

compact

start

type

Object-Specific Methods

None.

Object-Specific Event Handler Properties

None.

compact NN 6 IE 4 DOM 1
Read/Write
When set to true, the compact property should instruct the browser to render items in the list in a more compact format. This property has no effect in mainstream browsers.

Example

document.getElementById("myOL").compact = true;

Value

Boolean value: true | false.

Default

false

start NN 6 IE 4 DOM 1
Read/Write
Indicates the starting number for the sequence of items in the ol element. This is convenient when a sequence of items must be disturbed by running body text. While the value is a number, the corresponding Arabic numeral, Roman numeral, or alphabet letter renders the value. When no value is set as an attribute, Netscape 6 defaults the property value to -1.

Example

document.getElementById("sublist2").start = 6;

Value

Integer.

Default

1 (IE); -1 (Netscape 6).

type NN 6 IE 4 DOM 1
Read/Write
Indicates the manner in which the leading numbers or letters of items in the list are displayed.

Example

document.getElementById("instruxList").type = "a";

Value

Possible values are: A | a | I | i | 1. Sequencing is performed automatically as shown in the following table.

Type

Example

A

A, B, C, ...

a

a, b, c, ...

I

I, II, III, ...

i

i, ii, iii, ...

1

1, 2, 3, ...

Default

None specified, although behavior is that of 1.

optgroup NN 6 IE 5(Mac)/6)Win) DOM 1

The optgroup object reflects the optgroup element, which must be nested inside a select element and surround option elements. See the optgroup element in Chapter 8 for browser support details of this element. The disabled property (described among the shared properties earlier in this chapter) is available for this object, and it influences the disabled status of nested option elements.

HTML Equivalent

<optgroup>

Object Model Reference

[window.]document.getElementById("elementID")

Object-Specific Properties

label

Object-Specific Methods

None.

Object-Specific Event Handler Properties

None.

label NN 6 IE 5(Mac)/6(Win) DOM 1
Read/Write
Reflects the label attribute of the optgroup element.

Value

String.

Default

None.

option NN 2 IE 3 DOM 1

The option object reflects the option element, which must be nested inside a select element. References to option objects most often use its parent select object, with the option object treated as one member of an array of options belonging to that select object. With modern browsers, you can also reference an option object directly via its ID. The disabled property (described among the shared properties earlier in this chapter) is available for IE 4 and later and Netscape 6.

You can modify the set of options in a select object in browsers starting with Netscape 3 and Explorer 4 with backward-compatible code that continues to work in the newest browsers. If the modification entails replacing existing options with a different list of the same length, you can simply assign new values to text, value, and selected properties of each option in the select object's options array. But if the list has a different number of options, you are better served by removing all existing option objects and inserting new ones. A constructor function for a new Option object lets you create objects one at a time, and then assign them to positions within the options array. Syntax for the constructor is as follows:

var newOpt = new Option("text", "value", isDefaultSelectedFlag, 
isSelectedFlag);

The following function demonstrates the typical steps involved in rewriting a select object's list of options:

function setSelect(selectElemObj) {
    // remove existing options
    selectElemObj.options.length = 0;
    // create and assign options, one by one
    selectElemObj.options[0] = new Option("Hercule Poirot", "poirot", false, false);
    selectElemObj.options[1] = new Option("Miss Marple", "marple", false, false);
    ...
}

In a production environment, the values for the constructor parameters would most likely be delivered to the page as an array of objects, allowing the stuffing of new options to be carried out inside a for loop. For additional approaches to this task, see the options.add( ) method (for IE only) and the select.add( ) method (for IE 5 or later and Netscape 6 only).

HTML Equivalent

<option>

Object Model Reference

[window.]document.formName.selectName.options[i]
[window.]document.forms[i].elements[i].options[i]
[window.]document.getElementById("elementID")

Object-Specific Properties

defaultSelected

form

index

label

selected

text

value

Object-Specific Methods

None.

Object-Specific Event Handler Properties

None.

defaultSelected NN 2 IE 3 DOM 1
Read/Write
Determines whether an element has the selected attribute set in the tag. You can compare the current selected property against defaultSelected to see whether the state of the select control has changed since the document loaded. Changing this property does not affect the current selected status.

Example

var listItem = document.forms[0].selector.options[2]; if (listItem.selected != listItem.defaultSelected) { // process for changed state }

Value

Boolean value: true | false.

Default

Determined by HTML tag attribute.

form NN 6 IE 4 DOM 1
Read-only
Returns a reference to the form object that contains the select element and its options.

Example

var theForm = document.getElementById("myOption3").form;

Value

form object reference.

Default

None.

index NN 6 IE 3 DOM 1
Read-only
Returns the zero-based index integer value of the current option object within the collection of options of the select element. The select object's selectedIndex property returns the index value of the option that is currently selected.

Example

var whichItem = document.getElementById("myOption3").index;

Value

Integer.

Default

None.

label NN 6 IE 5(Mac)/6(Win) DOM 1
Read/Write
Reflects the label attribute of the option element. This property is intended for use with hierarchical menus, but it is not operational in browsers except for IE 5/Mac, where it returns the same value as the text property.

Value

String.

Default

None.

selected NN 2 IE 3 DOM 1
Read/Write
Determines whether the list option has been selected by the user, meaning that its value is submitted with the form. Scripts can modify the value to select an item algorithmically. To find out which option is selected, it is more efficient to use the select object's selectedIndex property, rather than looping through all options in search of those whose selected properties are true. The exception to this is when the select element is set to allow multiple selections, in which case you need to cycle through them all to find the chosen items.

Example

document.forms[0].selectList.options[3].selected = true;

Value

Boolean value: true | false.

Default

false

text NN 2 IE 3 DOM 1
Read/Write
Provides the text associated with the option element. This text is located between the start and end tags; it is what appears in the select element on screen. A hidden value associated with the list item can be stored, retrieved, and changed via the value property.

Example

var list = document.forms[0].selectList; var listItemText = list.options[list.selectedIndex].text;

Value

String.

Default

None.

value NN 4 IE 4 DOM 1
Read/Write
Provides the value associated with the option element. If the option element has a value attribute or value property set, this is the value returned for the value property; otherwise, the property returns an empty string.

Example

var itemValue = document.forms[0].selectList.options[2]value;

Value

String.

Default

None.

options NN 2 IE 3 DOM 1

An array of option elements nested within a select object.

Object Model Reference

[window.]document.formName.selectName.options
[window.]document.forms[i].elements[i].options
[window.]document.getElementById("selectElementID").options

Object-Specific Properties

length

Object-Specific Methods

add( )

item( )

namedItem( )

remove( )

tags( )

urns( )

length NN 2 IE 3 DOM 1
Read-only
Returns the number of elements in the collection.

Example

var howMany = document.forms[0].mySelect.options.length;

Value

Integer.

add( ) NN n/a IE 4 DOM n/a
add(elementRef[, index])
Adds an already-created element (from the createElement( ) method) to the current collection. The element must be of the option type. By default, the new element is added as the last item of the collection unless you specify an index value as a second parameter (in which case all existing items from that index position get pushed down by one). The following example sequence appends a new item to a select object:
var newElem = document.createElement("option"); newElem.text = "Freddy"; newElem.value = "Freddy Mercury"; document.forms[1].rockers.options.add(newElem);
Notice that a generic object is created first. Then its properties are stuffed with values, and the new element is added to the select element.
For an example of a cross-browser and backward-compatible approach to this task, see the option object discussion. Also see the select.add( ) method for a W3C DOM approach that works with Netscape 6.

Returned Value

None.

Parameters

elementRef

A fully-formed element object reference, usually generated by the createElement( ) method.

index

An optional integer indicating where in the collection the new element should be placed.

item( ) NN 6 IE 4 DOM 1
item(index[, subindex]) item(index)
Returns a single object or collection of objects corresponding to the element matching the index value (or, optionally, the index and subindex values).

Returned Value

One object or collection (array) of objects. If there are no matches to the parameters, the returned value is null.

Parameters

index

When the parameter is a zero-based integer, the returned value is a single element corresponding to the specified item in source code order (nested within the current element); when the parameter is a string (IE only), the returned value is a collection of elements with id properties that match that string.

subindex

In IE only, if you specify a string value for the first parameter, you can use the second parameter to specify a zero-based index that retrieves the specified element from the collection with id properties that match the first parameter's string value.

namedItem( ) NN 6 IE 6 DOM 1
namedItem("ID")
Returns a single option object corresponding to the element matching the parameter string value.

Returned Value

One option object. If there are no matches to the parameters, the returned value is null.

Parameters

ID

The string that contains the same value as the desired element's id attribute.

remove( ) NN n/a IE 4 DOM n/a
remove(index)
Deletes an element from the current collection. Simply specify the zero-based index value of the option element you wish to remove from the collection belonging to a select element. The following example deletes the first item from a select object:
document.forms[1].rockers.options.remove(0);
The process for removing an option element is entirely different in Navigator. To delete an item, assign null to the item in the collection. For example, the Navigator version of the preceding IE example is as follows:
document.forms[1].rockers.options[0] = null;
Regardless of the browser-specific process of removing an option from the select object, the length of the options array collapses to fill the space.

Returned Value

None.

Parameters

index

A zero-based integer indicating which item in the collection should be deleted.

tags( ) NN n/a IE 4 DOM n/a
tags("tagName")
Returns a collection of objects (among all objects nested within the current collection) with tags that match the tagName parameter. Implemented in all IE collections (see the all.tags( ) method), but redundant for collections of the same element type.

urns( ) NN n/a IE 5(Win) DOM n/a
urns(URN)
See the all.urns( ) method.

p	`NN 6 IE 4 DOM 1`

The p object reflects the p element.

HTML Equivalent

<p>

Object Model Reference

[window.]document.getElementById("elementID")

Object-Specific Properties

align

Object-Specific Methods

None.

Object-Specific Event Handler Properties

None.

align NN 6 IE 4 DOM 1
Read/Write
Determines how the paragraph text is justified within the p element's box.

Example

document.getElementById("myP").align = "center";

Value

Any of the three horizontal alignment string constants: center | left | right.

Default

left

page NN n/a IE 5.5(Win) DOM 2

The page object is a special type of style rule created via an @page CSS rule. In the W3C DOM, this object (known as the CSSPageRule object) inherits properties of the CSSRule object. But as of IE 6 for Windows, the page object does not adhere to this inheritance structure. This object lays the foundation for a more fully implemented notion of page boxes expected in future browser versions.

HTML Equivalent

<style type="text/css">
@page {specifications}
</style.

Object Model Reference

[window.]document.styleSheets.pages[i]

Object-Specific Properties

pseudoClass

selectorText

style

Object-Specific Methods

None.

Object-Specific Event Handler Properties

None.

pseudoClass NN n/a IE 5.5(Win) DOM n/a
Read-only
Returns the name of the pseudo-class associated with the @page rule (if any).

Example

var pClass = document.styleSheets[2].pages[0].pseudoClass;

Value

String pseudo-class names (including leading colon): :first | :left | :right.

Default

None.

selectorText NN n/a IE 5.5(Win) DOM n/a
Read/Write
Provides the selector of the @page rule (if any).

Example

document.styleSheets[2].pages[0].selectorText = ":right";

Value

String.

Default

None.

style NN n/a IE n/a DOM 2
Read-only
Returns the style object (of type CSSStyleDeclaration in the W3C DOM) reflecting the style attributes and properties of the @page rule.

Value

style object reference.

Default

None.

pages NN n/a IE 5.5(Win) DOM n/a

Provides an array of page objects (@page rules) nested within a styleSheet object.

Object Model Reference

[window.]document.styleSheets.pages

Object-Specific Properties

length

Object-Specific Methods

item( )

Object-Specific Event Handler Properties

None.

length NN n/a IE 5.5(Win) DOM 2
Read-only
Returns the number of objects in the collection.

Example

var howMany = document.styleSheets.pages.length;

Value

Integer.

item( ) NN n/a IE 5.5(Win) DOM 2
item(index)
Returns a single object corresponding to the element matching the index value.

Returned Value

Reference to a page object. If there are no matches to the parameters, the returned value is null.

Parameters

index

A zero-based integer corresponding to the specified item in source code order.

param NN 6 IE 5 DOM 1

The param object reflects the param element, which passes variable values to ActiveX objects (IE/Windows only), Java applets, and some plugins. Such programs are written to read parameter name/value pairs during initialization so the values are ready to go when the program starts (e.g., the URL of a sound file). IE for Windows commonly assigns a full suite of parameters to some ActiveX controls, even though only a handful might be explicitly defined in the source code. Although properties are read/write, assigning new values after the page has loaded does not convey the new values to the external program.

HTML Equivalent

<param>

Object Model Reference

[window.]document.getElementById("elementID")

Object-Specific Properties

name

type

value

valueType

Object-Specific Methods

None.

Object-Specific Event Handler Properties

None.

name NN 6 IE 5 DOM 1
Read/Write
This is the name of the external program's parameter to which a value in the param element applies.

Example

var pName = document.getElementById("audioParam2").name;

Value

String.

Default

None.

type NN 6 IE 5 DOM 1
Read/Write
Provides the MIME type for a param element with a valuetype attribute set to "ref".

Example

if (document.getElementById("myParam").valueType == "ref") { var pType = document.getElementById("myParam").type; }

Value

Case-insensitive MIME type as string. A catalog of registered MIME types is available from ftp://ftp.isi.edu/in-notes/iana/assignments/media-types/.

Default

None.

value NN 6 IE 5(Mac)/6(Win) DOM 1
Read/Write
Indicates the string value assigned to a named parameter for the external program.

Example

var pVal = document.getElementById("volumeParam").value;

Value

String.

Default

None.

valueType NN 6 IE 5(Mac)/6(Win) DOM 1
Read/Write
Indicates the string classification of the parameter set by the element.

Example

var pValType = document.getElementById("volumeParam").valueType;

Value

String constant: data | object | ref.

Default

data

plugin NN 3 IE 5(Mac) DOM n/a

A plugin object represents a single plugin that is registered with the browser at launch time. Access to a single plugin is normally via the navigator.plugins array. It is also common to use the navigator.mimeTypes array and associated properties to uncover whether the browser has the desired plugin installed before loading external content. Most of the properties provide scripted access to information normally found in the About Plug-ins window available from Navigator's Help menu and IE/Macintosh File Helper preferences. IE for Windows uses a different technique (involving the object element loading ActiveX controls) to determine support for playing external media.

Object Model Reference

navigator.plugins[i]

Object-Specific Properties

description

filename

length

name

Object-Specific Methods

refresh( )

description NN 3 IE 5(Mac) DOM n/a
Read-only
Provides a brief plain-language description of the plugin supplied by the plugin manufacturer.

Example

var descr = navigator.plugins[2].description;

Value

String.

Default

None.

filename NN 3 IE 5(Mac) DOM n/a
Read-only
Returns the filename of the plugin binary. In Win32 versions of Navigator, the full pathname is returned; for the Mac (both Navigator and IE), only the filename is returned.

Example

var file = navigator.plugins[2].filename;

Value

String.

Default

None.

length NN 3 IE 5(Mac) DOM n/a
Read-only
Returns the number of MIME types supported by the plugin. Don't confuse this property with the length property of the entire navigator.plugins array, which measures how many plugin objects are known to the browser.

Example

var howManyMIMEs = navigator.plugins[2].length;

Value

Integer.

Default

None.

name NN 3 IE 5(Mac) DOM n/a
Read-only
Returns the name of the plugin assigned to it by its manufacturer. You cannot, however, be guaranteed that a plugin designed for multiple operating systems has the same name across all versions.

Example

var pName = navigator.plugins[2].name;

Value

Integer.

Default

None.

refresh( ) NN 3 IE 5(Mac) DOM n/a
Instructs the browser to reregister plugins installed in the plugins directory. This allows a browser to summon a newly installed plugin without forcing the user to quit and relaunch the browser.

Returned Value

None.

Parameters

None.

plugins NN 3 IE 4 DOM n/a

Navigator and Internet Explorer both have a plugins array, but they are quite different collections of objects. Navigator's and IE/Macintosh's plugins array is a property of the navigator object. Each item in the navigator.plugins array represents a plugin that is installed in the browser (actually just registered with the browser when the browser last loaded). See the plugin object.

On the Windows side, Internet Explorer's plugins collection belongs to the document object and essentially mirrors the embeds collection: a collection of all embed elements in the document. An embed element may well, indeed, launch a plugin, but not necessarily. Nor does Internet Explorer for Windows provide JavaScript access to the installed plugins in the same way that Navigator does (IE for Macintosh provides no such access).

Object Model Reference

NN: navigator.plugins
IE: document.plugins

Object-Specific Properties

length

Object-Specific Methods

item( )

namedItem( )

length NN 3 IE 4 DOM n/a
Read-only
Returns the number of elements in the collection.

Example

var IEhowMany = document.plugins.length; var NNhowMany = navigator.plugins.length;

Value

Integer.

item( ) NN 6 IE 4(Win) DOM n/a
item(index[, subindex]) item(index)
Returns a single object or collection of objects corresponding to the item matching the index value (or, optionally, the index and subindex values).

Returned Value

One object or collection (array) of objects. If there are no matches to the parameters, the returned value is null.

Parameters

index

When the parameter is a zero-based integer, the returned value is a single element corresponding to the specified item in source code order (nested within the current element). When the parameter is a string (IE only), the returned value is a collection of elements with name properties that match that string.

subindex

In IE only, if you specify a string value for the first parameter, you can use the second parameter to specify a zero-based index that retrieves the specified element from the collection with name properties that match the first parameter's string value.

namedItem( ) NN 6 IE 6 DOM n/a
namedItem("name")
Returns a single plugin (NN) or embed (IE) object corresponding to the element matching the parameter string value.

Returned Value

One plugin (NN) or embed (IE) object. If there are no matches to the parameters, the returned value is null.

Parameters

name

The string that contains the same value as the desired object's name attribute.

popup NN n/a IE 5.5(Win) DOM n/a

A popup object is a featureless rectangular space that has none of the typical browser window chrome (borders, scrollbars, title bar, etc.) nor any reference path back to the main document. Scripts must create the popup object to a specific size and location, and populate the window with content by assigning an HTML string to the popup's document.body.innerHTML property. Your scripts must also help this region stand out from the document by assigning background colors and borders to either the popup's document.body.style property or the styles of elements inside the popup.

While this popup object holds what is essentially a document object, it is not related to the window object in any way, and therefore may not load external documents. It does, however, have the helpful characteristic of transcending frame and even browser window borders, giving the appearance of an operating-system level HTML content holder. Thus, you could use it for a drop-down menu or an annotation that needs to flow across frame borders or extend beyond the browser window edge.

A popup is a transient visual element. A click anywhere outside of the popup causes the popup to disappear. But you can assign the full range of mouse events to the elements in the popup's document, for effects such as rollovers and menu item clicks. The HTML content may also contain images.

To create a popup object, use the window.createPopup( ) method. Here is a simple example of the typical creation, population, and display sequence:

var popup = window.createPopup( );
var bod = popup.document.body;
bod.style.border = "3px solid #ff8800";
bod.style.padding = "2px";
bod.style.backgroundColor = "lightyellow";
bod.innerHTML = 
  "<p style='font-family:Arial, sans-serif; font-size:10px'>Some popup text.</p>";
popup.show(100, 100, 100, 26, document.body);

Object Model Reference

popupObjectRef

Object-Specific Properties

document

isOpen

Object-Specific Methods

hide( )

show( )

Object-Specific Event Handler Properties

None.

document NN n/a IE 5.5(Win) DOM n/a
Read-only
Returns a reference to the document object inside the popup object. Most (but not all) regular document object properties apply to the popup's document object. It is the primary gateway to assigning HTML content to the popup. This property is read-only, but the document object's properties are read/write to allow you to assign values to its content.

Example

popupRef.document.body.innerHTML = "Howdy, pardner!";

Value

document object reference.

Default

The current document object.

isOpen NN n/a IE 5.5(Win) DOM n/a
Read-only
Returns a Boolean value revealing whether the popup object is visible. Even after the popup object is hidden, its content is still accessible to scripts.

Example

if (popupRef.isOpen) { popupRef.hide( ); }

Value

Boolean value: true | false.

Default

false

hide( ) NN n/a IE 5.5(Win) DOM n/a
Hides the popup object. Generally invoked from scripts triggered by user actions on the popup's content.

Returned Value

Nothing.

Parameters

None.

show( ) NN n/a IE 5.5(Win) DOM n/a
show(left, top, width, height[, positioningElemRef])
Shows the popup object, usually after its content has been assigned. All dimensions and position are set via parameters. The position may optionally be established relative to an element in the main document. Position and positioning element parameters may come from event object properties (event.clientX, event.clientY, and event.srcElement).

Returned Value

None.

Parameters

left

Horizontal pixel coordinate relative to the left edge of the screen or, if specified by the optional parameter, an HTML element.

top

Vertical pixel coordinate relative to the top edge of the screen or, if specified by the optional parameter, an HTML element.

width

Outer pixel width of the popup space.

height

Outer pixel height of the popup space.

positioningElemRef

An optional reference to any element accessible to the script invoking the method. Establishes a coordinate context for the left and top parameters.

pre NN 6 IE 4 DOM 1

The pre object reflects the pre element for preformatted text.

HTML Equivalent

<pre>

Object Model Reference

[window.]document.getElementById("elementID")

Object-Specific Properties

width

Object-Specific Methods

None.

Object-Specific Event Handler Properties

None.

width NN 6 IE 6(Win) DOM 1
Read/Write
Provides the character column count for the monospaced content of the element. Only Netscape 6 reflows the content in response to changes of this property.

Example

document.getElementById("codeExample2").width = 40;

Value

Integer.

Default

-1 (Netscape 6); None (IE).

Range NN 6 IE n/a DOM 2

The W3C DOM Range object—similar in concept to the IE TextRange object—represents a sequence of zero or more rendered text characters in a document. When a text range consists of zero characters, it represents an insertion point between two characters (or before the first or after the last character of the document). The Range object automatically keeps track of the node and character offset references for the start and end points of the range, so its methods can copy existing content, delete the range's contents, or insert new contents (in node form) into the existing range while maintaining the integrity of the document tree at every step. Nodeness is important to the Range object, but most of those concerns are handled for you.

A Range object is created via the document.createTextRange( ) method or by turning a user selection into a range via window.getSelection().getRangeAt(0). Once a text range is created, use its methods to adjust its start and end point to encompass a desired segment of the text. The choose from a set of additional methods to act on the range. See Chapter 5 for details and examples of using the Range object and how its syntax varies from that of the IE TextRange object.

Object Model Reference

document.createRange( )

Object-Specific Properties

`collapsed`	`commonAncestorContainer`	`endContainer`
`endOffset`	`startContainer`	`startOffset`

Object-Specific Methods

`cloneContents( )`	`cloneRange( )`	`collapse( )`
`compareBoundaryPoints( )`	`compareNode( )`	`comparePoint( )`
`createContextualFragment( )`	`deleteContents( )`	`detach( )`
`extractContents( )`	`insertNode( )`	`intersectsNode( )`
`isPointInRange( )`	`selectNode( )`	`selectNodeContents( )`
`setEnd( )`	`setEndAfter( )`	`setEndBefore( )`
`setStart( )`	`setStartAfter( )`	`setStartBefore( )`
`surroundContents( )`	`toString( )`

Object-Specific Event Handler Properties

None.

collapsed NN 6 IE n/a DOM 2
Read-only
Returns Boolean true if the range's start and end points are at the same location, encompassing zero characters. A collapsed range can be located anywhere within the document.

Example

if (rng.collapsed) { // act on collapsed text range }

Value

Boolean value: true | false.

Default

None.

commonAncestorContainer NN 6 IE n/a DOM 2
Read-only
Returns a reference to a document tree node that is the next outermost container that encompasses the current range's start and end points. If the start and end points are, themselves, in the same node (for example, the same text node), the commonAncestorContainer property returns a reference to that node's parent node. IE TextRange equivalent is parentElement( ).

Example

var containingElem = rng.commonAncestorContainer;

Value

Reference to a node object (commonly an element node type).

Default

None.

endContainer NN 6 IE n/a DOM 2
Read-only
Returns a reference to a document tree node that contains the current range's end point.

Example

var containingElemRight = rng.endContainer;

Value

Reference to a node object.

Default

None.

endOffset NN 6 IE n/a DOM 2
Read-only
Returns an integer count of characters or nodes for the end point's location within the node reported by the endContainer property. If the endContainer is a text node, the endOffset property counts the number of characters to the right of the first character of that text node. If the endContainer is an element node, the endOffset property counts the number of nodes between the start of the containing node's content and the end point.
As an example, consider the following document segment that shows a text range in boldface characters, with the start and end points signified by pipe characters:
One paragraph with |a nested| element inside.
Note that the start point is within a text node, while the end point sits just outside the span element end tag. The Range object's properties report values as shown in the following table.

Property

Value

Description

commonAncestorContainer

[object HTMLParagraphElement]

The p element embraces both the start and end points.

startContainer

[object Text]

Start point is within a text node.

startOffset

19

Start point is at the 20th (zero-based index of 19) character from the start of its container, the text node.

endContainer

[object HTMLParagraphElement]

End point is designated as the end of the span element, which makes the next outer p element the end point's container.

endOffset

2

End point is at the 3rd (zero-based index of 2) node in the context of its endContainer p element (first node is a text node; second node is the span element; end point is at the start of the third node of the p element).

Example

var rngEndOff = rng.endOffset;

Value

Integer.

Default

None.

startContainer NN 6 IE n/a DOM 2
Read-only
Returns a reference to a document tree node that contains the current range's start point.

Example

var containingElemLeft = rng.startContainer;

Value

Reference to a node object.

Default

None.

startOffset NN 6 IE n/a DOM 2
Read-only
Returns an integer count of characters or nodes for the start point's location within the node reported by the startContainer property. If the startContainer is a text node, the startOffset property counts the number of characters to the right of the first character of that text node. If the startContainer is an element node, the startOffset property counts the number of nodes between the start of the containing node's content and the start point. See endOffset for more details.

Example

var rngStartOff = rng.startOffset;

Value

Integer.

Default

None.

cloneContents( ) NN 7 IE n/a DOM 2
Returns a DocumentFragment node containing a copy of the contents from the current range. Any dangling nodes are resolved as part of the cloning process.

Returned Value

Reference to a node of a document fragment type.

Parameters

None.

cloneRange( ) NN 6 IE n/a DOM 2
Returns a Range object that is a carbon copy of the current range, including references to associated containers. This method lets you preserve a copy of a Range object's specifications while creating a new Range object. Similar to the IE TextRange object's duplicate( ) method.

Returned Value

Reference to a Range object.

Parameters

None.

collapse( ) NN 6 IE n/a DOM 2
collapse(toStartFlag)
Shrinks the current range to an insertion point (start and end points are in the same node at the same offset). The Boolean parameter controls whether the range collapses to the start point (true) or end point (false) of the current range. A script working its way through a document (e.g., using the String.indexOf( ) method to search for the next instance of a string) usually collapses to the end point before shifting the end point to the end of the body to perform the next String.indexOf( ) search.

Returned Value

None.

Parameters

toStartFlag

Boolean value that controls whether collapse occurs at the start point (true) or end point (false) of the current range.

compareBoundaryPoints( ) NN 6 IE n/a DOM 2
compareBoundaryPoints(compareType, sourceRangeRef)
Returns an integer code indicating the relative positioning of one boundary point of the current range's against a boundary point of a different text range. In the simplest case, the two end points (one from each range) share the same ancestor container. In such a case, the first parameter determines which end points from the two ranges get compared. Use the constants supplied with every Range object, as shown in the following table.

Comparison type

Description

rng.START_TO_START

Comparing the start position of the current range against the start position of the source range

rng.START_TO_END

Comparing the start position of the current range against the end position of the source range

rng.END_TO_END

Comparing the end position of the current range against the end position of the source range

rng.END_TO_START

Comparing the end poisition of the current range against the start position of the source range

If the first boundary in the comparison occurs earlier in the document than the second boundary, the returned value is -1; if the first boundary comes after the second boundary, the returned value is 1; if the two boundaries are in the identical position, the returned value is 0. Similar to the IE TextRange object's compareEndPoints( ) method.
But the situation can be more complex if the boundary points being compared have different ancestor container nodes. The offset values with respect to container nodes influence the comparison results. Due to the variety of results that can occur with numerous relationships between the compared end points, your scripts will need to perform an intricate analysis of boundaries to assure comparisons report the desired sequence. On the other hand, simply looking for unanimity of boundary points is a much simpler prospect. You may prefer to limit your comparisons to looking only for return values of zero (or any other value) for a more binary determination of boundary comparisons.

Returned Value

Integer values -1, 0, or 1.

Parameters

compareType

Integer values from 0 to 3 corresponding to comparison types. Integer values are not aligned with the W3C DOM standard in Netscape 6 or 7, but the plain-language constants (such as rng.START_TO_START, shown in the table above) produce the correct comparisons.

sourceRangeRef

Reference to a second, previously defined Range object, perhaps preserved through the cloneRange( ) method.

compareNode( ) NN 6 IE n/a DOM n/a
compareNode(nodeReference)
A Netscape-only method that returns an integer code indicating the relative position of some other node with respect to the current range. Four plain-language constants are members of every Netscape Range object, and can be used for comparisons of values returned by the compareNode( ) method. Note that the returned values are from the point of view of the node passed as a parameter, rather than from that of the current range.
Returned values and constants are as follows.

Constant

Value

Description

rng.NODE_BEFORE

0

Entire node comes before the range.

rng.NODE_AFTER

1

Entire node comes after the range.

rng.NODE_BEFORE_AND_AFTER

2

Node starts before the current range and ends after it.

rng.NODE_INSIDE

3

Node is contained in its entirety within the scope of the range.

By way of example:
if (rng.compareNode(document.getElementById("myElem")) == rng.NODE_INSIDE) { // process for myElem node being contained by the range }

Returned Value

Integer values 0, 1, 2, or 3.

Parameters

nodeReference

Reference to any node in the document tree.

comparePoint( ) NN 6 IE n/a DOM n/a
compareNode(nodeReference, offset)
A Netscape-only method that returns an integer code indicating the relative position of some other node and offset within that node with respect to the current range. Note that the returned values are from the point of view of the node (more specifically, the point signified by the offset within the node) passed as parameters, rather than from that of the current range.
Returned values are as follows.

Value

Description

-1

Point comes before the start of the range.

0

Point is located within the range.

1

Point comes after the end of the range.

By way of example:
if (rng.comparePoint(document.getElementById("myElem"), 2) == 0) { // process for offset of 2 within myElem node being contained by the range }

Returned Value

Integer values -1, 0, 1.

Parameters

nodeReference

Reference to any node in the document tree.

offset

Integer offset, counting either nested nodes within an element or characters within a text node.

createContextualFragment( ) NN 6 IE n/a DOM n/a
createContextualFragment(contentString)
The createContextualFragment( ) method was initially designed as an alternative to the innerHTML convenience property (because the W3C DOM provides little in the way of support for content strings consisting of tags). This method accepts any string—including tagged content—as a parameter, and returns a DocumentFragment type of node, ready for appending or inserting into the document tree. Subsequent adoption of the innerHTML property by the Mozilla browser makes this method redundant, except that it is more consistent with the overall nodeness of the W3C DOM.

Returned Value

Reference to a document fragment type of node outside of the document tree. This node can then be applied to the document tree.

Parameters

contentString

Document content in string form, including tags and attributes.

deleteContents( ) NN 6 IE n/a DOM 2
Removes the contents of the current text range from the document tree. If the range is an element node (e.g., with boundaries established via the selectNode( ) method), invoking deleteContents( ) on the range removes the node from the document tree and collapses the range. The Range object remains in memory, but without any content. If you want to capture the content prior to its deletion, do so with other Range object methods (such as cloneRange( ) and, when it works correctly, cloneContents( )).

Returned Value

None.

Parameters

None.

detach( ) NN 6 IE n/a DOM 2
Destroys the current Range object to the extent that invoking most methods on the object or accessing its properties throw a RangeException of type INVALID_STATE_ERR.

Returned Value

None.

Parameters

None.

extractContents( ) NN 6 IE n/a DOM 2
Returns a DocumentFragment node containing the contents of the current range, after removing the contents from the document tree. Not working in Netscape as of Version 6.2 except when the range boundaries are set via the selectNodeContents( ) method.

Returned Value

Reference to a node of a document fragment type.

Parameters

None.

insertNode( ) NN 6 IE n/a DOM 2
insertNode(nodeReference)
Inserts a node at the start of the current text range. Most useful when the range is already collapsed as a text insertion pointer. The node being inserted can be created fresh (via document.createElement( )) or fetched from elsewhere in the document tree, in which case it is removed from its old position and inserted into the current range. If you insert a text node adjacent to a spot that also happens to be an existing text node, you can wind up with two adjacent text nodes. Invoke the normalize( ) method on the parent to consolidate the text nodes.

Returned Value

Nothing

Parameters

nodeReference

Reference to any text, element, or document fragment node to be inserted into the range.

intersectsNode( ) NN 6 IE n/a DOM n/a
intersectsNode(nodeReference)
Returns Boolean true if any part of the current range overlaps with the text or element node that is passed as a parameter. If your script detects an intersection, it can use the compareNode( ) method to obtain more detail about the intersection.

Returned Value

Boolean value: true | false.

Parameters

nodeReference

Reference to any text or element in the document tree.

isPointInRange( ) NN 6 IE n/a DOM n/a
isPointInRange(nodeReference, offset)
Returns Boolean true if the location denoted by the parameter values (a node in the document tree and an offset location within that node) is within the current range.

Returned Value

Boolean value: true | false.

Parameters

nodeReference

Reference to any text or element in the document tree.

offset

Integer offset, counting either nested nodes within an element or characters within a text node.

selectNode( ), selectNodeContents( ) NN 6 IE n/a DOM 2
selectNode(nodeReference) selectNodeContents(nodeReference)
Sets the range's boundary points to encompass a node or just the node's contents. Despite the methods' names, no body text in the rendered document is highlighted.
Your choice of method impacts the way the range's startContainer and endContainer properties are filled. In the following sequence, you see what happens to the range and its properties when an element node and a text node are parameters to these methods. The initial HTML segment is:
One paragraph with a nested element inside.
Selecting the span element (with the rng.selectNode(document.getElementById("myspan")) method) sets the range to:
One paragraph with a |nested| element inside.
The Range object's properties report values as follows.

Property

Value

Description

startContainer

[object HTMLParagraphElement]

Start point is right before the span element.

startOffset

1

Start point is at the 2nd (zero-based index of 1) node inside the p element.

endContainer

[object HTMLParagraphElement]

End point is immediately after the span element.

endOffset

2

End point is at the 3rd (zero-based index of 2) node in the context of its endContainer p element.

Using the rng.selectNodeContents(document.getElementById("myspan")) method to select the span element's contents sets the range to:
One paragraph with a |nested| element inside.
The Range object's properties report values as follows.

Property

Value

Description

startContainer

[object HTMLSpanElement]

Start point is just inside the span element.

startOffset

0

Start point is at the 1st (zero-based index of 0) node inside the span element.

endContainer

[object HTMLSpanElement]

End point is immediately after the span element's content.

endOffset

1

End point is at a position where the 2nd (zero-based index of 1) node, if present, would be in the context of its endContainer span element.

Using the rng.selectNode(document.getElementById("myspan").firstChild) method to select the text node inside the span element sets the range to:
One paragraph with a |nested| element inside.
Even though the node passed as a parameter is different (and a different node type), the new range selection looks the same as the previous one. In fact, due to the way the node tree is structured, the Range object's properties report identical values as follows.

Property

Value

Description

startContainer

[object HTMLSpanElement]

Start point is just inside the span element.

startOffset

0

Start point is at the 1st (zero-based index of 0) node inside the span element.

endContainer

[object HTMLSpanElement]

End point is immediately after the span element's content.

endOffset

1

End point is at a position where the 2nd (zero-based index of 1) node, if present, would be in the context of its endContainer span element.

Using the rng.selectNodeContents(document.getElementById("myspan")) method to select the contents of the text node inside the span element sets the range to:
One paragraph with a ||nested element inside.
In other words, the range collapses to an insertion point at the start of the text node (this may be a bug in Netscape 6), and the text node becomes the container, as shown in the following property enumeration.

Property

Value

Description

startContainer

[object Text]

Start point is at the beginning of the text node.

startOffset

0

Start point is at the 1st (zero-based index of 0) position of the text node.

endContainer

[object Text]

End point is collapsed.

endOffset

0

End point is collapsed.

Element nodes tend to be the most practical parameter values to pass to either method.

Returned Value

None.

Parameters

nodeReference

Reference to any text or element in the document tree.

setEnd( ), setStart( ) NN 6 IE n/a DOM 2
setEnd(nodeReference, offset) setStart(nodeReference, offset)
Establish the document tree locations for the individual boundary points of an existing Range object. Similar to the IE TextRange object's setEndPoint( ) method. The mapping of a location relies upon a node reference and an offset value relative to that node's starting point and type. Offset values count child nodes when the nodeReference is an element node; they count characters when the nodeReference is a text node. To set a boundary at a node edge, the associated methods (setEndAfter( ) and three others) are more convenient.

Returned Value

None.

Parameters

nodeReference

Reference to any element or text node in the document tree.

offset

Integer offset, counting either nested nodes within an element or characters within a text node.

setEndAfter( ), setEndBefore( ), setStartAfter( ), setStartBefore( ) NN 6 IE n/a DOM 2
setEndAfter(nodeReference) setEndBefore(nodeReference) setStartAfter(nodeReference) setStartBefore(nodeReference)
Establish the document tree locations for the individual boundary points of an existing Range object with respect to a node's edges. These methods assume that you are interested in setting a range's boundaries to places immediately before or after an existing node, and not concerned with other kinds of offsets. Range boundaries do not have to be symmetrical, allowing you to specify the start boundary relative to one node and the end boundary relative to a completely different node later in the document.

Returned Value

None.

Parameters

nodeReference

Reference to any element or text node in the document tree.

surroundContents( ) NN 7 IE n/a DOM 2
surroundContents(parentNodeReference)
Encapsulates the current range with a new container, usually a new element node created via the document.createElement( ) method. End points of the current range should have the same parent container prior to applying this method.

Returned Value

None.

Parameters

parentNodeReference

Reference to a node that becomes the new containing parent for the range.

toString( ) NN 6 IE n/a DOM 2
Returns a string of the body content contained by the range. No tags or attributes accompany the returned value.

Returned Value

String.

Parameters

None.

RangeException NN n/a IE n/a DOM 2

Some operations on W3C DOM Range objects can trigger errors, or, in the vernacular of JavaScript 1.5, throw exceptions if something goes wrong. The W3C DOM defines an object that conveys a code number corresponding to a well-defined, if somewhat limited, list of exceptions specifically related to Range objects. For example, if you attempt to set range boundaries to encompass non-content-related nodes (such as an Attr node), the selectNode( ) method with such a node as a parameter throws an exception whose code number is 2. This number corresponds to the exception that signals an attempt to perform an illegal or logically impossible action on a text range.

When eventually implemented in browsers, the scripting mechanism to work with range exceptions should be the same as described for the DOMException object. Range object property and method access can also throw DOMException s.

Object Model Reference

errorObjectReference

Object-Specific Properties

code

Object-Specific Methods

None.

Object-Specific Event Handler Properties

None.

code NN n/a IE n/a DOM 1
Read-only
Provides the integer corresponding to one of the defined Range object error types, as shown in the following table.

Code

Constant

Most Likely Cause

1

BAD_BOUNDARYPOINTS_ERR

The surroundContents( ) method was applied to a range with a nonapplicable end point

2

INVALID_NODE_TYPE_ERR

The method tried to work in a nonapplicable type of node

Value

Integer

Default

Determined by error.

rows NN 6 IE 4 DOM 1

Provides a collection of all tr element objects contained in a single table, tbody, tfoot, or thead element object. The rows collection of a table element includes all rows of the table, regardless of row groups. Collection members are sorted in source code order. Internet Explorer lets you use array notation or parentheses to access a single row in the collection (e.g., document.getElementById("myTable").rows[0], document.all.myTable.rows (0)).

Object Model Reference

document.getElementById("tableOrSectionID").rows

Object-Specific Properties

length

Object-Specific Methods

item( )

namedItem( )

tags( )

urns( )

Object-Specific Event Handler Properties

None.

length NN 6 IE 4 DOM 1
Read-only
Returns the number of elements in the collection.

Example

var howMany = document.getElementById("myTable").rows.length;

Value

Integer.

item( ) NN 6 IE 4 DOM 1
item(index[, subindex]) item(index)
Returns a single tr object or collection of tr objects corresponding to the element matching the index value (or, optionally in IE, the index and subindex values).

Returned Value

One tr object or collection (array) of tr objects. If there are no matches to the parameters, the returned value is null.

Parameters

index

When the parameter is a zero-based integer, the returned value is a single element corresponding to the specified item in source code order (nested within the current element); when the parameter is a string (IE only), the returned value is a collection of elements with id properties that match that string.

subindex

In IE only, if you specify a string value for the first parameter, you can use the second parameter to specify a zero-based index that retrieves the specified element from the collection with id properties that match the first parameter's string value.

namedItem( ) NN 6 IE 6 DOM 1
namedItem("ID")
Returns a single tr object or collection of tr objects corresponding to the element matching the parameter string value.

Returned Value

One tr object or collection (array) of tr objects. If there are no matches to the parameters, the returned value is null.

Parameters

ID

The string that contains the same value as the desired element's id attribute.

tags( ) NN n/a IE 4 DOM n/a
tags(tagName)
Returns a collection of objects (among all objects within the current collection) with tags that match the tagName parameter. Redundant here, because all elements have the same tr tag.

Returned Value

A collection (array) of objects. If there are no matches to the parameters, the returned value is an array of zero length.

Parameters

tagName

This involves a string of the all-uppercase version of the element tag, for example, document.getElementById("myTable").rows.tags("tr").

urns( ) NN n/a IE 5(Win) DOM n/a
urns(URN)
See the all.urns( ) method.

rb, ruby, rt NN n/a IE 5 DOM n/a

Of these three ruby text-related elements, only ruby and rt are officially supported as objects in the IE DOM. But an rb element (even though it has no structural or rendering powers as of IE 6) is also regarded as an element object. Even Netscape 6 sees these as valid HTML element objects (of unknown type). See the ruby element in Chapter 8 for details on the usage of these elements. As scriptable objects, they have no properties or methods beyond a generic HTML element object.

Object Model Reference

document.getElementById("elementID")

Object-Specific Properties

None.

Object-Specific Methods

None.

Object-Specific Event Handler Properties

None.

screen NN 4 IE 4 DOM n/a

The screen object refers to the video display on which the browser is being viewed. Many video control panel settings influence the property values, but only a handful of properties are shared among browser brands.

Object Model Reference

NN: screen
IE: [window.]screen

Object-Specific Properties

`availHeight`	`availLeft`	`availTop`	`availWidth`
`bufferDepth`	`colorDepth`	`deviceXDPI`	`deviceYDPI`
`fontSmoothingEnabled`	`height`	`logicalXDPI`	`logicalYDPI`
`pixelDepth`	`updateInterval`	`width`

Object-Specific Methods

None.

Object-Specific Event Handler Properties

None.

availHeight, availWidth NN 4 IE 4 DOM n/a
Read-only
Provide the height and width of the content region of the user's video monitor in pixels. This measure does not include the 24-pixel task bar (Windows) or 20-pixel system menubar (Macintosh). IE/Macintosh miscalculates the height of the menu bar as 24 pixels. To use these values in creating a pseudo-maximized window, you also have to adjust the top-left position of the window.

Example

var newWind = window.open("","","height=" + screen.availHeight + ",width=" + screen.availWidth)

Value

Integer of available pixels in vertical and horizontal dimensions.

Default

Depends on the user's monitor size.

availLeft, availTop NN 4 IE n/a DOM n/a
Read-only
Provide the pixel coordinates of the left and top edges of the screen that is available for content. With the standard Windows Taskbar arrangement, both values are zero. But drag the Taskbar to the left or top of the screen, and the corresponding value increases to accommodate the bar's space. Navigator 4 for the Macintosh doesn't start its screen counting until just below the fixed menu bar, but for Netscape 6, the availTop property returns 20 for the menu bar height.

Example

window.moveTo(screen.availLeft, screen.availTop);

Value

Integer.

Default

0 (Windows); 20 (Macintosh)

bufferDepth NN n/a IE 4 DOM n/a
Read/Write
Specifies the setting of the offscreen bitmap buffer. Path animation smoothness may improve on some clients if you match the bufferDepth to the colorDepth values. Setting the bufferDepth to -1 forces IE to buffer at the screen's pixel depth (as set in the control panel), and colorDepth is automatically set to that value, as well (plus if a user changes the bits per pixel, the buffer is adjusted accordingly). A setting to any of the other permitted values (1, 4, 8, 15, 16, 24, or 32) buffers at that pixel depth and sets the colorDepth to that value. The client's display must be set to the higher bits-per-pixel values to take advantage of the higher settings in scripts.

Example

screen.bufferDepth = 4;

Value

Any of the following allowed integers: -1 | 0 | 4 | 8 | 15 | 16 | 24 | 32.

Default

0

colorDepth NN 4 IE 4 DOM n/a
Read-only
Returns the number of bits per pixel used to display color in the video monitor or image buffer. Although this property is read-only, its value can be influenced by settings of the bufferDepth property (IE only). You can determine the color depth of the current video screen and select colors accordingly.

Example

if (screen.colorDepth > 8) { document.getElementById("pretty").color = "cornflowerblue"; } else { document.getElementById("pretty").color = "blue"; }

Value

Integer.

Default

Current video control panel setting.

deviceXDPI, deviceYDPI, logicalXDPI, logicalYDPI NN n/a IE 6(Win) DOM n/a
Read-only
All four properties concern themselves with the dots-per-inch resolution of display screens along the horizontal (x) and vertical (y) axes. A device density property returns the actual pixel density of the current display screen, as detected by the operating system. The logical density is the "normal" pixel density that most users and page authors work with (typically 96 dots per inch horizontally and vertically). These two sets of properties let scripts examine whether the user has a higher-than-usual pixel density display, which could make fixed-size items, such as images and pixel-sized fonts, appear uncomfortably small on the screen. In such cases, scripts can determine a scaling factor between the device and logical densities, and apply that factor to the style.zoom property of critical elements (or the entire document.body, for that matter). Users of high-density display systems may already have their IE application preferences set to automatic scaling, so these calculations aren't necessary.

Example

var normDPI = 96; if ((screen.deviceXDPI == screen.logicalXDPI) && (screen.deviceXDPI > normDPI)) { document.body.style.zoom = normDPI / screen.logicalXDPI; }

Value

Integer.

Default

96

fontSmoothingEnabled NN n/a IE 4(Win) DOM n/a
Read-only
Returns Boolean true if the user has enabled Smooth Edges for fonts in the Windows Display control panel. The setting may influence the font-related style sheet you link into a document.

Example

var styleFile = "css/corpStyle.css"; if (screen.fontSmoothingEnabled) { styleFile = "css/corpStyleFancy.css"; } document.write("<link type='text/css' rel='stylesheet' href='" + styleFile + "'>");

Value

Boolean value: true | false.

Default

false

height, width NN 4 IE 4 DOM n/a
Read-only
Return the number of pixels available vertically and horizontally in the client video monitor. This is the raw dimension. For the amount of screen space not covered by system bars, see availHeight and availWidth.

Example

if (screen.height > 480 && screen.width > 640) { ... }

Value

Integer of pixel counts.

Default

Depends on video monitor.

logicalXDPI, logicalYDPI
See deviceXDPI.

pixelDepth NN 4 IE n/a DOM n/a
Read-only
Returns the number of bits per pixel used to display color in the video monitor. This value is similar to the colorDepth property, but it is not influenced by a potential custom color palette, as colorDepth is.

Example

if (screen.pixelDepth > 8) { document.getElementById("pretty").color = "cornflowerblue"; } else { document.getElementById("pretty").color = "blue"; }

Value

Integer.

Default

Current video control panel setting.

updateInterval NN n/a IE 4 DOM n/a
Read/Write
Provides the time interval (in milliseconds) between screen updates. A value of zero lets the browser select an average that usually works best. The longer the interval, the more animation steps may be buffered and then ignored as the update fires to display the current state.

Example

screen.updateInterval = 0;

Value

Positive integer or zero.

Default

0

width
See height.

script NN 6 IE 4 DOM 1

The script object reflects the script element. Internet Explorer 4 for Windows chokes on accessing or setting the innerHTML or innerText properties, but the equivalent text property is safe. IE 5 for the Macintosh implements the readyState property (shared among all elements in IE for Windows) for this object.

HTML Equivalent

<script>

Object Model Reference

[window.]document.getElementById("elementID")

Object-Specific Properties

charset

defer

event

htmlFor

src

text

type

Object-Specific Methods

None.

Object-Specific Event Handler Properties

Handler	NN	IE	DOM
`onerror`	n/a	4	n/a
`onload`	n/a	4	n/a

charset NN 6 IE 6(Win) DOM 1
Read/Write
Indicates the character encoding of the script content.

Example

if (document.getElementById("myScript").charset == "csISO5427Cyrillic") { // process for Cyrillic charset }

Value

Case-insensitive alias from the character set registry (ftp://ftp.isi.edu/in-notes/iana/assignments/character-sets).

Default

Determined by browser.

defer NN 6 IE 4 DOM 1
Read/Write
Specifies whether the browser should proceed with rendering regular HTML content without looking for the script to generate content as the page loads. This value needs to be set in the script element's tag at runtime. When this property is set to true by the addition of the DEFER attribute to the tag, the browser does not have to hold up rendering further HTML content to parse the content of the script element in search of document.write( ) statements. Changing this property's value after the document loads does not affect the performance of the script or browser. Although Netscape 6 implements the property, it is not functional.

Example

if (document.getElementById("myScript").defer = = "true") { ... }

Value

Boolean value: true | false.

Default

false

event NN 6 IE 4 DOM 1
Read-only
Internet Explorer's event model allows binding of object events to script elements with the help of the event and for attributes (see Chapter 6). The event property returns the setting for the event attribute. Not functional in Netscape 6.

Example
if (document.getElementById("gizmoScript").event == "onresize") {
    ...
}
Value

Case-sensitive event name string.

Default

None.

htmlFor NN 6 IE 4 DOM 1
Read-only
Returns the value (element ID) assigned to the for attribute of a script element. This attribute points to the ID of the element to which the script is bound when a specific event (set by the event attribute) fires for the element. Not functional in Netscape 6.

Example

if (document.getElementById("helpScript").htmlFor == "helpButton") { ... }

Value

String.

Default

None.

src NN 6 IE 4 DOM 1
Read/Write
Provides the URL of the .js script file imported into the current script element. If you assign a new .js file to an existing script element in IE, the previous .js file's scripts do not disappear. But any duplications of variable or functions names are overwritten by the definitions from the new file. While Netscape 6 and later do not complain when you assign a new value to this property, the assignment does not necessarily load the new scripts into the current window or frame.

Example

if (document.getElementsByTagName("script")[1].src == "scripts/textlib.js") { ... }

Value

Complete or relative URL as a string.

Default

None.

text NN 6 IE 4 DOM 1
Read/Write
Indicates the text content of the element. Assigning script statements to this object has different results in various browsers. In late versions of IE for Windows, the new value is added to the existing script, even though the property no longer reports the previous script text; in Netscape 6, the assigned values are ignored; and in IE 5 for Macintosh, the property is treated as read-only.

Example

var scriptText = document.getElementById("script3").text;

Value

String.

Default

None.

type NN 6 IE 4 DOM 1
Read-only
Provides an advisory about the content type of the script statements. The content type should tell the browser which scripting engine to use to interpret the script statements, such as text/javascript. The type attribute may eventually replace the language attribute as the one defining the scripting language in which the element's statements are written.

Example

var scriptMIMEtype = document.getElementById("script3").type;

Value

String.

Default

None.

scripts NN n/a IE 4 DOM n/a

A collection of all scripts defined or imported in a document, including those defined in the head or body portion. Collection members are sorted in source code order.

Object Model Reference

document.scripts

Object-Specific Properties

length

Object-Specific Methods

item( )

namedItem( )

tags( )

urns( )

Object-Specific Event Handler Properties

None.

length NN n/a IE 4 DOM n/a
Read-only
Returns the number of elements in the collection.

Example

var howMany = document.scripts.length;

Value

Integer.

item( ) NN n/a IE 4 DOM n/a
item(index[, subindex])
Returns a single object or collection of objects corresponding to the element matching the index value (or, optionally, the index and subindex values).

Returned Value

One object or collection (array) of objects. If there are no matches to the parameters, the returned value is null.

Parameters

index

When the parameter is a zero-based integer, the returned value is a single element corresponding to the said numbered item in source code order (nested within the current element). When the parameter is a string, the returned value is a collection of elements with id properties that match that string.

subindex

If you specify a string value for the first parameter, you may use the second parameter to specify a zero-based integer to retrieve a specific element from the collection with id properties that match the first parameter's string value.

namedItem( ) NN n/a IE 6 DOM n/a
namedItem("ID")
Returns a single script object or collection of script objects corresponding to the element matching the parameter string value.

Returned Value

One script object or collection (array) of script objects. If there are no matches to the parameters, the returned value is null.

Parameters

ID

The string that contains the same value as the desired element's id attribute.

tags( ) NN n/a IE 4 DOM n/a
tags(tagName)
Returns a collection of objects (among all objects within the current collection) with tags that match the tagName parameter. Redundant here, because all elements have the same script tag.

Returned Value

A collection (array) of objects. If there are no matches to the parameters, the returned value is an array of zero length.

Parameters

tagName

A string of the all-uppercase version of the element tag, as in document.scripts.tags("script").

urns( ) NN n/a IE 5(Win) DOM n/a
urns(URN)
See the all.urns( ) method.

select NN 2 IE 3 DOM 1

The select object reflects the select element. This element is a form control that contains option elements. Note that the innerHTML and innerText properties are not available on the Macintosh version of Internet Explorer 4. The shared disabled property is available for Netscape 6.

HTML Equivalent

<select>

Object Model Reference

[window.]document.formName.selectName
[window.]document.forms[i].elements[i]
[window.]document.getElementById("elementID")

Object-Specific Properties

`dataFld`	`dataSrc`	`form`	`length`	`multiple`	`name`
`options[]`	`selectedIndex`	`size`	`type`	`value`

Object-Specific Methods

add( )

item( )

namedItem( )

remove( )

Object-Specific Event Handler Properties

Handler	NN	IE	DOM
`onblur`	2	4	n/a
`onchange`	2	4	n/a
`onfocus`	2	4	n/a

dataFld NN n/a IE 4 DOM n/a
Read/Write
Used with IE data binding to associate a remote data source column name with the selectedIndex property of the select object. A datasrc attribute must also be set for the element. Setting both the dataFld and dataSrc properties to empty strings breaks the binding between element and data source. Works only with text file data sources in IE 5/Mac.

Example

document.forms[0].mySelect.dataFld = "choice";

Value

Case-sensitive identifier of the data source column.

Default

None.

dataSrc NN n/a IE 4 DOM n/a
Read/Write
Used with IE data binding to specify the ID of the page's object element that loads the data source object for remote data access. Setting both the dataFld and dataSrc properties to empty strings breaks the binding between element and data source. Works only with text file data sources in IE 5/Mac.

Example

document.forms[0].mySelect.dataSrc = "DBSRC3";

Value

Case-sensitive identifier of the data source.

Default

None.

form NN 2 IE 3 DOM 1
Read-only
Returns a reference to the form element that contains the current element. When processing an event from this element, the event handler function automatically has access to the select element (as the event object's target or srcElement property). By reading the form property, the script can easily access other controls within the same form.

Example

var theForm = evt.srcElement.form;

Value

form element object reference.

Default

None.

length NN 2 IE 3 DOM 1
Read/Write
The number of option objects nested inside the select object. The value returned is the same as the select object options.length property, and can be safely used as a for loop maximum counter value to iterate through the nested option objects. The W3C DOM specifies that this property is read-only, but because the property has been read/write for some time in mainstream browsers, you can continue to adjust this value. By and large, the only modification made to this property, if at all, should be setting its value to zero to empty all options from the select object. Better still, if you are authoring for IE 5 and later or Netscape 6, use the select.remove( ) and select.add( ) methods to modify the contingent of option elements nested inside the select element.

Example

document.forms[0].mySelect.length = 0;

Value

Integer.

Default

None.

multiple NN 6 IE 4 DOM 1
Read/Write
Specifies whether the browser should render the select element as a list box and allow users to make multiple selections from the list of options. By default, the size property is set to the number of nested option elements, but the value may be overridden with the size property setting. To change a scrolling pick list to a popup menu, set the multiple property to false and the size property to 1. Users can select contiguous items by Shift-clicking on the first and last items of the group. To make discontiguous selections, Windows users must Ctrl-click on each item; Mac users must Command-click on each item. The multiple property has no effect when size is set to 1 to display a popup menu.

Example

if (document.entryForm.list3.multiple) { ... }

Value

Boolean value: true | false.

Default

false

name NN 2 IE 3 DOM 1
Read/Write
This is the identifier associated with the form control. The value of this property is submitted as one-half of the name/value pair when the form is submitted to the server. Names are hidden from user view, since control labels are assigned via other means, depending on the control type. Form control names may also be used by script references to the objects. Despite the modern standards' preference for the id attribute, many browsers still require that a control be assigned a name attribute to allow the control's value to be submitted.

Example

document.orderForm.payment.name = "credcard";

Value

Case-sensitive string identifier that follows the rules of identifier naming: it may contain no whitespace, cannot begin with a numeral, and should avoid punctuation except for the underscore character.

Default

None.

options[ ] NN 2 IE 3 DOM 1
Read-only
Returns an array of all option objects contained by the current element. Items in this array are indexed (zero-based) in source code order. For details on using this collection in a backward-compatible way for adding and removing option elements from a select element, see the options object. Loop through this collection in select elements set for multiple selections.

Example

var selVals = new Array( ); for (var i = 0; i < document.forms[0].mySelect.length; i++) { if (document.forms[0].mySelect.options[i].selected) { selVals[selVals.length] = document.forms[0].mySelect.options[i].value; } }

Value

Array of option objects.

Default

None.

selectedIndex NN 2 IE 3 DOM 1
Read/Write
This is the zero-based integer of the option selected by the user. If the select element is set to allow multiple selections, the selectedIndex property returns the index of the first selected item (see the selected property). You can use this property to gain access to the value or text of the selected item, as shown in the example.
In recent browsers, if no option is selected, the selectedIndex property returns -1. Setting the value to -1 to deselect all items works as you'd expect in IE 5 and later for Windows. For Netscape 6, setting the property to -1 may not empty the displayed option, but it does effectively deselect all items for a submitted form.

Example

var list = document.forms[0].selectList; var listText = list.options[list.selectedIndex].text;

Value

Integer.

Default

None.

size NN 6 IE 4 DOM 1
Read/Write
Controls the number of rows displayed in a scrolling pick list, reflecting the size attribute of the select element. When set to true, the multiple property overrides a size value set to fewer than the number of options. To change a scrolling pick list to a popup menu, set the multiple property to false and the size property to 1.

Example

document.forms[0].choices.size = 6;

Value

Integer.

Default

None.

type NN 3 IE 4 DOM 1
Read-only
Returns the type of form control element. A select object has two possible values, depending on whether the element is set to be a multiple-choice list. The value is returned in all lowercase letters. It may be necessary to cycle through all form elements in search of specific types to do some processing on (e.g., emptying all form controls of type "text" while leaving other controls untouched).
Note that Navigator 4 incorrectly reports a select object's type as select-multiple if the element's size attribute is set to any value larger than 1, even if the multiple attribute is not set. This is fixed in Netscape 6.

Example

if (document.forms[0].elements[3].type == "select-multiple") { ... }

Value

Any of the following constants (as a string): button | checkbox | file | hidden | image | password | radio | reset | select-multiple | select-one | submit | text | textarea.

Default

Depends on value of multiple.

value NN 6 IE 4 DOM 1
Read/Write
This is the current value associated with the form control that is submitted with the name/value pair for the element. All values are strings, but they may represent other kinds of data, including Boolean and numeric values. For browsers earlier than IE 4 and Netscape 6, scripts must retrieve the selected option's value by using the select object's selectedIndex property as an index into the options array, then inspect each option object's selected property to find the true one(s).

Example

if (document.forms[0].medium.value == "CD-ROM") { ... }

Value

String.

Default

None.

add( ) NN 6 IE 5 DOM 1
add(newOptionElement[, positionIndex]) add(newOptionElement, optionElementReference)
Adds a new option element to the current select element. Unfortunately, IE and Netscape 6 don't agree on the parameter values for this method. While all browsers require a reference to a newly created option element (the value returned from a document.createElement("option") method is appropriate for that), the second parameter varies with browser. In IE, the second parameter is optional and supplies a numeric index to the existing option element; the new option is inserted in front of that element. With no second parameter, the new option is appended to the existing option elements. In Netscape 6 (which implements the W3C DOM recommendation from the unfinished HTML module), the second parameter is required. The parameter is either a reference to an existing option element (the new option is inserted before that referenced option) or null (the new option is appended to the existing options).

Returned Value

None.

Parameters

newOptionElement

Reference to an option element created by script, usually with the document.createElement( ) method.

positionIndex

Optional IE integer parameter signifying the existing nested option element in front of which the new option is to be inserted. Omitting this parameter causes the new option to be appended to the end of the options list.

optionElementReference

Reference to an option element in front of which the new option is to be inserted. You may also use null to append the new option to the end of the option list.

item( ) NN n/a IE 5 DOM n/a
item(index[, subindex])
Returns a single nested option object or collection of nested option objects corresponding to the element matching the index value (or, optionally, the index and subindex values).

Returned Value

One object or collection (array) of objects. If there are no matches to the parameters, the returned value is null.

Parameters

index

When the parameter is a zero-based integer, the returned value is a single element corresponding to the said numbered item in source code order (nested within the current element). When the parameter is a string, the returned value is a collection of elements with id properties that match that string.

subindex

If you specify a string value for the first parameter, you may use the second parameter to specify a zero-based integer to retrieve a specific element from the collection with id properties that match the first parameter's string value.

namedItem( ) NN n/a IE 6 DOM n/a
namedItem("ID")
Returns a single nested option object or collection of nested option objects corresponding to the element matching the parameter string value.

Returned Value

One option object or collection (array) of option objects. If there are no matches to the parameters, the returned value is null.

Parameters

ID

The string that contains the same value as the desired element's id attribute.

remove( ) NN 6 IE 5 DOM 1
remove(positionIndex)
Deletes an option element from the current select element at the zero-based index position signified by the parameter value. In lieu of setting the select object's length property to zero, you can remove all existing options with a simple loop construction:
while (selectElemRef.length > 0) { selectElemRef.remove(0); }
At this point, you can populate the list with new options via the various approaches described in the add( ) method discussion and the options object discussion.

Returned Value

None.

Parameters

positionIndex

Zero-based integer signifying the item from the nested options collection to be deleted.

selection NN 6 IE 4(Win) DOM n/a

The selection object represents zero or more characters that have been explicitly selected in a document by the user or selected under script control. The objects are very different entities in the IE and Navigator browsers (observe compatibility ratings for properties and methods, below), and each has its own ways of providing script access to it.

In IE for Windows, you create a selection object via the document.selection property, which returns a selection object. To perform substantive actions on the content of the selection object, you then generate a TextRange object from the selection object (via the selection object's createRange( ) method). Use TextRange properties and methods to interact with the content. To convert a TextRange object to a visibly selected stretch of text on the page, use the TextRange object's select( ) method. This close linkage with the TextRange object means that the IE selection object is so far limited to Win32 versions. The IE selection object can include selected text inside an input (of type text) and textarea element.

In IE for the Macintosh, you don't have a selection object per se. Instead, it implements the Navigator 4 document.getSelection( ) method, which returns only the string contents of the selected text.

Navigator 4 offers script access to the text selected in a document through the use of the document.getSelection( ) method. This method is deprecated in Netscape 6, and even displays a warning (less harmful than an error) in the JavaScript Console if you use the method. In its place, Netscape 6 implements a robust selection object that offers a long list of properties and methods to interact with the object. Most of this functionality was made available starting with Netscape 6.2, including the way to create a selection object: the window.getSelection( ) method. Notice that many properties and methods of the Netscape 6 selection object have analogs with the Range object specification. In fact, it is through the Range object that scripts can highlight even discontiguous text spans on the page: create and size a Range object; then add that Range to the highlighted text via the selection object's addRange( ) method. Netscape 6 selections (as with the Range object) operate only on body content, and not on text inside editable text boxes.

Be aware that clicking on buttons in earlier browsers (including IE 5 for the Mac) deselects the current text selection. Therefore, all scripted action involving selections in these browsers must be triggered by onselect or onmouseup events, or functions invoked by a timer (see the window.setTimeout( ) method description in Chapter 12). More recent browsers maintain content selections while buttons are pressed.

Object Model Reference

IE (Win): document.selection
NN 6: window.getSelection( )

Object-Specific Properties

`anchorNode`	`anchorOffset`	`focusNode`	`focusOffset`
`isCollapsed`	`rangeCount`	`type`	`typeDetail`

Object-Specific Methods

`addRange( )`	`clear( )`	`collapse( )`
`collapseToEnd( )`	`collapseToStart( )`	`containsNode( )`
`createRange( )`	`createRangeCollection( )`	`deleteFromDocument( )`
`empty( )`	`extend( )`	`getRangeAt( )`
`removeAllRanges( )`	`removeRange( )`	`selectAllChildren( )`
`selectionLanguageChange( )`	`toString( )`

Object-Specific Event Handler Properties

None.

anchorNode, focusNode NN 6 IE n/a DOM n/a
Read-only
Return a reference to the node where the user started (anchor) and ended (focus) the selection. Most typically, these are text node types. If the selection is set or extended via the addRange( ) method, these properties point to the node boundaries of the most recently added range.

Example

var anchor = selectionRef.anchorNode; if (anchor.nodeType == 3 && anchor.parentNode.tagName == "td") { // process selection start inside a table cell }

Value

Reference to a document tree node, or null if no selection.

Default

null

anchorOffset, focusOffset NN 6 IE n/a DOM n/a
Read-only
Return an integer count of characters or nodes from the beginning of the anchor or focus nodes of the selection (see anchorNode and focusNode properties). If the node is a text node, the offset unit is the character; if the node is an element node, the offset unit is the node. This behavior is similar to the offset properties of a Range object. Most typically, these values count characters within text node types. If the selection is set or extended via the addRange( ) method, these properties point to the node boundary offsets of the most recently added range.

Example

var selStartOffset = selectionRef.anchorOffset;

Value

Integer.

Default

0

isCollapsed NN 6 IE n/a DOM n/a
Read-only
Returns Boolean true if the anchor and focus boundaries of a selection are identical.

Example

if (selectionRef.isCollapsed) { // selection is an insertion point }

Value

Boolean value: true | false.

Default

true

rangeCount NN 6 IE n/a DOM n/a
Read-only
Returns an integer count of Range objects (which may be discontiguous in Netscape 6) within the span of the selection. A manual selection by the user always contains one Range, but the addRange( ) method can tack on multiple, discontiguous ranges to the selection. To inspect each highlighted section's properties, use the getRangeAt( ) method.

Example

var howMany = selectionRef.rangeCount;

Value

Integer.

Default

0

type NN n/a IE 4(Win) DOM n/a
Read-only
Specifies whether the current selection object has one or more characters selected or is merely an insertion point.

Example

if (document.selection.type == "Text") { ... }

Value

One of three constant values (as a string): None | Text | Control. The last one is possible only when HTML editing is engaged and control selections are possible.

Default

None

typeDetail NN n/a IE 5.5(Win) DOM n/a
Read-only
This property is supplied as a placeholder for other applications that may use the IE browser component. Such an application can provide additional selection type information as needed.

addRange( ) NN 6 IE n/a DOM n/a
addRange(RangeReference)
Turns a Range into a highlighted selection on the page. You can add as many discontiguous ranges to the selection as your application requires. Each addition increments the selection object's rangeCount property. Ranges may also overlap in a selection.
var selRef = window.getSelection( ); var rng = document.createRange( ); rng.selectNodeContents(document.getElementById("myP")); selRef.addRange(rng);

Returned Value

None.

Parameters

RangeReference

Reference to a Range object with boundaries that have been established by Range object methods.

clear( ) NN n/a IE 4(Win) DOM n/a
Deletes the content of the current selection in a document. For example, the event handler in the following tag deletes any selected text of the p element two seconds after the user starts making the selection:


Returned Value

None.

Parameters

None.

collapse( ) NN 6 IE n/a DOM n/a
collapse(nodeReference, offset)
Collapses the current selection to a location specified by the two parameters. Any previously highlighted selection returns to normal display.

Returned Value

None.

Parameters

nodeReference

Reference to a text or element node in the document tree in which the collapsed selection should move.

offset

Integer count of characters or nodes within the nodeReference node where the collapsed selection should move. The count is relative to the start of the node. Units are character for text nodes, nodes for elements.

collapseToEnd( ), collapseToStart( ) NN 6 IE n/a DOM n/a
Collapses the current selection to a location at the start (collapseToStart( )) or end (collapseToEnd( )) of the selection object. Any previously highlighted selection returns to normal display. If the selection consists of multiple ranges, the start or end boundary used for these collapse methods are at the outermost edges of the combined selection. After the collapse, the selection contains only one range.

Returned Value

None.

Parameters

None.

containsNode( ) NN 6 IE n/a DOM n/a
containsNode(nodeReference, entirelyFlag)
Returns Boolean true if the current selection object contains a node passed as a parameter. The second parameter is supposed to let you loosen or tighten the definition of contains, but the behavior of the method seems backward to the intended purpose of the flag. You can assure accuracy if you pass null as the second parameter, which forces the method to define containment as containing the node in its entirety.

Returned Value

Boolean value: true | false.

Parameters

nodeReference

Reference to any addressable text or element node in the document tree.

entirelyFlag

Boolean value or null. Observed behavior is that a value of true means the selection can contain only a part of the node for the method to return true.

createRange( ) NN n/a IE 4(Win) DOM n/a
Creates a TextRange object from the current selection object. After a statement like the following:
var myRange = document.selection.createRange( );
scripts can act on the content of the selected text.

Returned Value

TextRange object.

Parameters

None.

createRangeCollection( ) NN n/a IE 5.5(Win) DOM n/a
Creates a TextRange collection object. This must be in anticipation of IE supporting multiple, discontiguous selections in the future.

Returned Value

TextRange collection object.

Parameters

None.

deleteFromDocument( ) NN 6 IE n/a DOM n/a
Removes the current selection from the document tree. The node hierarchy adjusts itself by obeying the same rules as Range.deleteContents( ).

Returned Value

None.

Parameters

None.

empty( ) NN n/a IE 4(Win) DOM n/a
Deselects the current selection and sets the selection object's type property to None. There is no change to the content that had been selected.

Returned Value

None.

Parameters

None.

extend( ) NN 6 IE n/a DOM n/a
extend(nodeReference, offset)
Moves the end (focus) boundary of the selection to the designated document tree node and offset within that node. The start (anchor) point does not move with this method.

Returned Value

None.

Parameters

nodeReference

Reference to a text or element node in the document tree in which the selection's focus (end point) should move.

offset

Integer count of characters or nodes within the nodeReference node where the collapsed selection should move. The count is relative to the start of the node. Units are character for text nodes, nodes for elements.

getRangeAt( ) NN 6 IE n/a DOM n/a
getRangeAt(rangeIndex)
Returns a reference to the range within a selection object whose zero-based numeric index matches the passed parameter. For contiguous selections, the parameter should be zero. But for discontiguous selections, the getRangeAt( ) method lets you retrieve each range that had been added to the selection for individual manipulation as a Range object. Use the selection.rangeCount property to derive the number of Range objects contained by the selection object. Invoking the method does not disturb the sequence of ranges within the selection.

Returned Value

Range object reference.

Parameters

rangeIndex

Zero-based integer index value.

removeAllRanges( ) NN 6 IE n/a DOM n/a
Removes all Range objects from the current selection (not from the document tree). The selection collapses, and the rangeCount property value changes to zero.

Returned Value

None.

Parameters

None.

removeRange( ) NN 6 IE n/a DOM n/a
removeRange(rangeReference)
Removes a single Range object from the current selection (not from the document tree). If you have a multiple-range selection, you can iterate through all Range objects, inspect each for some criterion, and delete the one(s) you want with the following sequence:
var oneRange; var sel = window.getSelection( ); for (var i = 0; i < sel.rangeCount; i++) { oneRange = sel.getRangeAt(i); if (oneRange.someProperty == someDiscerningValue) { sel.removeRange(oneRange); } }

Returned Value

None.

Parameters

rangeReference

Reference to one of the Range objects previously added to the current selection.

selectAllChildren( ) NN 6 IE n/a DOM n/a
selectAllChildren(elementNodeReference)
Forces the selection object to encompass the element node passed as a parameter and all of its child nodes. This method is also a shortcut to using a script to select an element node. Using this method on an element node causes the anchor and focus nodes to be that element node. Should you pass a reference to a text node, the resulting selection is collapsed in front of the first character of the text node. Invoking this method on an existing selection replaces all ranges with the new range encompassing the element.

Returned Value

None.

Parameters

elementNodeReference

Reference to an element node in the document tree that becomes the selection.

selectionLanguageChange( ) NN 6 IE n/a DOM n/a
selectionLanguageChange(RTLFlag)
Controls the cursor Bidi (bi-directional) level.

Returned Value

None.

Parameters

RTLFlag

Boolean value: true for right-to-left; false for left-to-right.

toString( ) NN 6 IE n/a DOM n/a
Returns a string containing only body content from the selection. Tags and attributes are ignored.

Returned Value

String value.

Parameters

None.

style (element) NN 6 IE 4 DOM 1

The style element object reflects the style HTML element. This object is separate from the style object that is accessed as a property of virtually every element in a document. The style element object is generated in a document via the <style> tag, which can have a unique ID value assigned to it; the style (property) object contains all the style properties and their current values as set for a particular element.

HTML Equivalent

<style>

Object Model Reference

[window.]document.getElementById("elementID")

Object-Specific Properties

disabled

media

sheet

styleSheet

type

Object-Specific Methods

None.

Object-Specific Event Handler Properties

Handler	NN	IE	DOM
`onerror`	n/a	4	n/a
`onload`	n/a	4	n/a

disabled NN 6 IE 4 DOM 1
Read/Write
Specifies whether rules in the style sheet should be applied to their selected elements. Although the corresponding disabled attribute does not work in Internet Explorer 4, setting the disabled property to true does, in fact, turn off the entire style sheet. During page authoring, you can create a button that toggles style sheets on and off to see how the page looks in all types of browsers.

Example

document.getElementById("mainStyle").disabled = true;

Value

Boolean value: true | false.

Default

false

media NN 6 IE 4 DOM 1
Read/Write
Indicates the intended output device for the rules of the style element. The media property looks forward to the day when browsers are able to tailor content to specific kinds of devices such as pocket computers, text-to-speech digitizers, or fuzzy television sets.

Example

document.getElementById("myStyle").media = "print";

Value

Any one of the following constant values as a string: all | print | screen.

Default

all

sheet NN 6 IE n/a DOM n/a
Read-only
Returns a styleSheet object (W3C DOM type CSSStyleSheet) representing the style sheet defined by the style element. This is an alternate (and nonstandard) way to reference a styleSheet object. The document.styleSheets collection is a better approach.

Example

var oneSheet = document.getElementById("myStyle").sheet;

Value

Reference to a styleSheet object (W3C DOM type CSSStyleSheet).

Default

None.

styleSheet NN n/a IE 6(Win) DOM n/a
Read-only
Returns a styleSheet object representing the style sheet defined by the style element. This is property is present, but doesn't seem to be officially supported. The document.styleSheets collection is a better approach.

Example

var oneSheet = document.getElementById("myStyle").styleSheet;

Value

Reference to a styleSheet object.

Default

None.

type NN 6 IE 4 DOM 1
Read/Write
This is the style sheet MIME type specified by the type attribute of the style element.

Example

if (document.getElementById("myStyle").type == "text/css") { // unlikely to be anything else }

Value

MIME type string.

Default

text/css

style, CSSStyleDeclaration NN 6 IE 4 DOM 2

In its most generic sense, a style object is the access point for scripts to read and write individual style attributes for a given element. This style object exposes (or has the potential to expose) every style sheet attribute supported by the browser (the kinds of CSS attributes described in Chapter 11).

In practice, however, a style object that you access through an HTML element object's style property (one of the shared properties described early in this chapter) is limited in scope: It reflects only the CSS settings explicitly defined in the element's tag via the style attribute or settings assigned to the element's style property via script. But other style sheets associated with the browser (internal style sheets) and the document (explicit style sheet rules defined in the <style> element and rules imported through either a link element or an @import rule) also affect the rendered characteristics of the element. A union of all style sheet attributes affecting an element—the effective style definition—may be read, but through browser-dependent syntax. IE uses the currentStyle property of an element, whereas Netscape 6 uses the W3C DOM window.getComputedStyle( ) method. Both syntaxes return an object that lets scripts inspect the value of each effective style attribute value.

While the three IE style-related objects (style, currentStyle, and runtimeStyle) return a style object with properties that expose CSS style attributes, the situation is a little more complex on the Netscape 6 side. On the one hand, Netscape 6 implements a version of the W3C DOM CSSStyleDeclaration object that exposes all the CSS attributes as properties. This is the version accessed through an element object's style property (just like IE, thus making an element object's style property work cross-browser). But when you read the effective style sheet (via window.getComputedStyle( )), the object that comes back does not expose the CSS attributes directly as properties. Instead, you must use the CSSStyleDeclaration methods (listed below) to inspect a specific attribute value by name. It's a longer way to reach a particular effective style attribute value, but very much in keeping with other attribute-reading syntax deployed throughout the W3C DOM. The only time this cross-browser disconnect affects you is when you need to view the effective style attribute for an unmodified style. Once you set an attribute value via the element object's style property, you can read it from the style property cross-browser.

This section lists the available style object properties plus the Netscape 6 (W3C DOM) formal methods for accessing those attributes. The W3C DOM lists a large percentage of the style object properties under an object umbrella called CSS2Properties. The specification offers the CSS2Properties object as an optional convenience for browsers. Fortunately for cross-browser scripters, Netscape 6 implements CSS2Properties at least for the element object style property.

The properties of the style object listed below correspond to the CSS attributes. For more information on a particular property, see the corresponding listing in Chapter 11.

Object Model Reference

All: [window.]document.getElementById("elementID").style
IE: [window.]document.styleSheets[i].rules[j].style
NN: [window.]document.styleSheets[i].cssRules[j].style

Object-Specific Properties

`accelerator`	`azimuth`	`background`
`backgroundAttachment`	`backgroundColor`	`backgroundImage`
`backgroundPosition`	`backgroundPositionX`	`backgroundPositionY`
`backgroundRepeat`	`behavior`	`blockDirection`
`border`	`borderBottom`	`borderBottomColor`
`borderBottomStyle`	`borderBottomWidth`	`borderCollapse`
`borderColor`	`borderLeft`	`borderLeftColor`
`borderLeftStyle`	`borderLeftWidth`	`borderRight`
`borderRightColor`	`borderRightStyle`	`borderRightWidth`
`borderSpacing`	`borderStyle`	`borderTop`
`borderTopColor`	`borderTopStyle`	`borderTopWidth`
`borderWidth`	`bottom`	`captionSide`
`clear`	`clip`	`clipBottom`
`clipLeft`	`clipRight`	`clipTop`
`color`	`content`	`counterIncrement`
`counterReset`	`cssFloat`	`cssText`
`cue`	`cueAfter`	`cueBefore`
`cursor`	`direction`	`display`
`elevation`	`emptyCells`	`filter`
`font`	`fontFamily`	`fontSize`
`fontSizeAdjust`	`fontStretch`	`fontStyle`
`fontVariant`	`fontWeight`	`height`
`imeMode`	`layoutFlow`	`layoutGrid`
`layoutGridChar`	`layoutGridLine`	`layoutGridMode`
`layoutGridType`	`left`	`letterSpacing`
`lineBreak`	`lineHeight`	`listStyle`
`listStyleImage`	`listStylePosition`	`listStyleType`
`margin`	`marginBottom`	`marginLeft`
`marginRight`	`marginTop`	`markerOffset`
`marks`	`maxHeight`	`maxWidth`
`minHeight`	`minWidth`	`MozBinding`
`MozOpacity`	`orphans`	`outline`
`outlineColor`	`outlineStyle`	`outlineWidth`
`overflow`	`overflowX`	`overflowY`
`padding`	`paddingBottom`	`paddingLeft`
`paddingRight`	`paddingTop`	`page`
`pageBreakAfter`	`pageBreakBefore`	`pageBreakInside`
`pause`	`pauseAfter`	`pauseBefore`
`pitch`	`pitchRange`	`pixelBottom`
`pixelHeight`	`pixelLeft`	`pixelRight`
`pixelTop`	`pixelWidth`	`playDuring`
`posBottom`	`posHeight`	`posLeft`
`posRight`	`posTop`	`posWidth`
`position`	`quotes`	`richness`
`right`	`rubyAlign`	`rubyOverhang`
`rubyPosition`	`scrollbar3dLightColor`	`scrollbarArrowColor`
`scrollbarBaseColor`	`scrollbarDarkShadowColor`	`scrollbarFaceColor`
`scrollbarHighlightColor`	`scrollbarShadowColor`	`scrollbarTrackColor`
`size`	`speak`	`speakHeader`
`speakNumeral`	`speakPunctuation`	`speechRate`
`stress`	`styleFloat`	`tableLayout`
`textAlign`	`textAlignLast`	`textAutospace`
`textDecoration`	`textDecorationBlink`	`textDecorationLineThrough`
`textDecorationNone`	`textDecorationOverline`	`textDecorationUnderline`
`textIndent`	`textJustify`	`textKashidaSpace`
`textOverflow`	`textShadow`	`textTransform`
`textUnderlinePosition`	`top`	`unicodeBidi`
`verticalAlign`	`visibility`	`voiceFamily`
`volume`	`whiteSpace`	`widows`
`width`	`wordBreak`	`wordSpacing`
`wordWrap`	`writingMode`	`zIndex`
`zoom`

Object-Specific Methods

`getPropertyCSSValue( )`	`getPropertyPriority( )`	`getPropertyValue( )`
`item( )`	`removeProperty( )`	`setProperty( )`

Object-Specific Event Handler Properties

None.

accelerator NN n/a IE 5(Win) DOM n/a
See text
For IE 5 and later running under Windows 2000 or newer version of Windows, users can set a preference to highlight an accelerator key for commands (or web page accessKey letters) when the user presses the Alt key. The accelerator key property controls whether the element is treated as a highlightable accelerator key string. Available as a property of the IE currentStyle (read-only) and runtimeStyle (read/write) objects only.

Example

document.getElementById("controlH").style.accelerator = true;

Value

Boolean value: true | false.

Default

false

azimuth, cue, cueAfter, cueBefore, elevation, pause, pauseAfter, pauseBefore, pitch, pitchRange, playDuring, richness, speak, speakHeader, speakNumeral, speakPunctuation, speechRate, stress, voiceFamily, volume NN 6 IE n/a DOM 2
Read/Write
This large group of properties comes from CSS attributes intended for browsers that use speech synthesis techniques to vocalize document content. You don't have to be vision-impaired to benefit from this possibility, but Netscape 6 does not include this feature by default. Conceivably, other specialty browser makers will build a speech synthesized browser from the Mozilla engine. They'll have the hooks ready in the Mozilla DOM to permit scripting of these style properties. In the meantime, they're simply placeholders within Netscape 6. You can read about these CSS attributes in Chapter 11.

Value

All values for these properties are strings.

Default

None.

background NN 6 IE 4 DOM 2
Read/Write
Provides the element's style sheet background attribute. This is a shorthand attribute, so the scripted property consists of a string of space-delimited values for the backgroundAttachment, backgroundColor, backgroundImage, backgroundPosition, and backgroundRepeat property values. One or more values may be in the background value, and the individual values may be in any order. Available in IE as a property of the style and runtimeStyle objects only.

Example

document.getElementById("myDiv").style.background = "url(logo.gif) repeat-y";

Value

String of space-delimited values corresponding to one or more individual background style properties.

Default

None.

backgroundAttachment NN 6 IE 4 DOM 2
Read/Write
Sets how the image is "attached" to the element. The image can either remain fixed within the viewable area of the element (the viewport) or it may scroll with the element as the document is scrolled. During scrolling, the fixed attachment looks like a stationary backdrop to rolling credits of a movie.

Example

document.getElementById("myDiv").style.backgroundAttachment = "fixed";

Value

String of either allowable value: fixed | scroll.

Default

scroll

backgroundColor NN 6 IE 4 DOM 2
Read/Write
Provides the background color of the element. If you also set a backgroundImage, the image overlays the color. Transparent pixels of the image allow the color to show through.

Example

document.getElementById("highlighted").style.backgroundColor = "yellow";

Value

Any valid color specification (see description at beginning of the chapter) or transparent.

Default

transparent

backgroundImage NN 6 IE 4 DOM 2
Read/Write
URL of the background image of the element. If you also set a backgroundColor, the image overlays the color. Transparent pixels of the image allow the color to show through.

Example

document.getElementById("navbar").style.backgroundImage = "url(images/navVisited.jpg)";

Value

Any complete or relative URL to an image file in CSS URL format: url(filePath).

Default

None.

backgroundPosition NN 6 IE 4 DOM 2
Read/Write
Indicates the top and left location of a background image relative to the element's content region (plus padding). Positions may be specified as length values (with numbers and units or percentages) or according to a combination of constants top, right, bottom, left, and center. The property has no effect on a background images set to repeat along both axes. Some value types don't work (or work correctly) in IE 4. Available as a property of the IE style and runtimeStyle objects only.

Example

document.getElementById("div3").style.backgroundPosition = "20% 50%";

Value

A string containing one value (to be applied to both horizontal and vertical axes) or a space-delimited pair of values. Values may be explicit length values (with units, as in 30px 5px), percentages (e.g., 50% 50%) or position constants that have explicit meanings for their combinations.

Constant value pair

Percentage equivalents

Constant value pair

Percentage equivalents

top left 0% 0% center center 50% 50%

left top 0% 0% right 100% 50%

top 50% 0% right center 100% 50%

top center 50% 0% center right 100% 50%

center top 50% 0% bottom left 0% 100%

right top 100% 0% left bottom 0% 100%

top right 100% 0% bottom 50% 100%

left 0% 50% bottom center 50% 100%

left center 0% 50% center bottom 50% 100%

center left 0% 50% bottom right 100% 100%

center 50% 50% right bottom 100% 100%

Percentage values are interpolated logically. For example, a value of 0% means that the image abuts the left or top edge of the element block; a value of 50% centers the image vertically or horizontally; a value of 100% places the image flush right or bottom..

Default

0% 0%

backgroundPositionX, backgroundPositionY NN n/a IE 4 DOM n/a
Read/Write
Indicate the top and left locations of the background image relative to the element's content region (plus padding). Useful if you wish to adjust the background image along only one axis while not disturbing the other. The same IE 4 cautions for backgroundPosition apply to these two properties.

Example

document.getElementById("div3").style.backgroundPositionX = "20px"; document.getElementById("table2").style.backgroundPositionY = "10px;"

Value

You should be able to specify percentage values, which are the percentage of the block-level element's box width and height (respectively) at which point the image (or repeated images) begins. Setting percentage values, however, does not always work in IE 4 for Windows (and it doesn't work at all on the Mac), even though they are returned as the default value units. You are safest with pixel values. None of the allowed constants except top and left are recognized.

Default

0

backgroundRepeat NN 6 IE 4 DOM 2
Read/Write
Specifies whether a background image (specified with the backgroundImage property) should repeat and, if so, along which axes. You can use repeating background images to create horizontal and vertical bands with some settings.

Example

document.getElementById("div3").style.backgroundRepeat = "repeat-y";

Value

With a string setting of no-repeat, one instance of the image appears in the location within the element established by the backgroundPosition property (default is top-left corner). Normal repeats are performed along both axes, but you can have the image repeat down a single column (repeat-y) or across a single row (repeat-x). To reestablish the default, assign the value repeat.

Default

repeat

behavior NN n/a IE 5(Win) DOM n/a
Read/Write
Controls whether an IE Windows external behavior is assigned to the element.

Example

document.getElementById("div3").style.behavior = "url(#default#userData)";

Value

CSS-formatted URL value, with the actual URL pointing to an external .htc file, ID of an object element that loads a behavior ActiveX control into the page, or one of the built-in default behaviors (in the format url(#default#behaviorName)).

Default

None.

blockDirection NN n/a IE 5(Win) DOM n/a
Read-only
Returns the writing script direction of the current element. Available as a property of the IE currentStyle object only.

Example

if (document.getElementById("myDIV").style.blockDirection = "rtl") { // process right-to-left text }

Value

String constant values: ltr | rtl.

Default

ltr

border NN 6 IE 4 DOM 2
Read/Write
Provides a shorthand property for getting or setting the borderColor, borderStyle, and/or borderWidth properties of all four borders around an element in one statement. You must specify a border style (see borderStyle) for changes of this property to affect the display of the element's border (a missing style is interpreted as no style, ergo no border). Numerous other properties allow you to set the width, style, and color of individual edges or groups of edges if you don't want all four edges to be the same. Only those component settings explicitly made in the element's tag attributes are reflected in the property, but you may assign components not part of the original tag. Available in IE as a property of the style and runtimeStyle objects only.

Example

document.getElementById("announce").style.border = "inset red 4px";

Value

Space-delimited string. For the borderStyle and borderWidth component values, see the respective properties in this chapter. For details on the borderColor value, see the section about CSS colors at the beginning of Chapter 11.

Default

None.

borderBottom, borderLeft, borderRight, borderTop NN 6 IE 4 DOM 2
Read/Write
These are shorthand properties for getting or setting the borderColor, borderStyle, and/or borderWidth properties for a single edge of an element in one statement. You must specify a border style (see borderStyle) for changes of these properties to affect the display of the element's border (a missing style is interpreted as no style, ergo no border along the specified edge). If you want all four edges to be the same, see the border attribute. Only those component settings explicitly made in the element's tag attributes are reflected in the property, but you may assign components not part of the original tag. Available in IE as properties of the style and runtimeStyle objects only.

Example

document.getElementById("announce").style.borderBottom = "inset red 4px"; document.getElementById("announce").style.borderLeft = "solid #20ff00 2px"; document.getElementById("announce").style.borderRight = "double 3px"; document.getElementById("announce").style.borderTop = "outset red 8px";

Value

Space-delimited string. For the borderSideStyle and borderSideWidth component values, see the respective properties in this chapter. For details on the borderSideColor value formats, see the section about colors at the beginning of Chapter 11.

Default

None.

borderBottomColor, borderLeftColor, borderRightColor, borderTopColor NN 6 IE 4 DOM 2
Read/Write
Provide the color of a single border edge of an element. It is easy to abuse these properties by mixing colors that don't belong together. See also the borderColor attribute for setting the color for groups of edges in one statement.

Example

document.getElementById("announce").style.borderBottomColor = "red"; document.getElementById("announce").style.borderLeftColor = "#20ff00"; document.getElementById("announce").style.borderRightColor = "rgb(100, 75, 0)"; document.getElementById("announce").style.borderTopColor = "rgb(90%, 0%, 25%)";

Value

For details on CSS color values, see the section about colors at the beginning of Chapter 11.

Default

None.

borderBottomStyle, borderLeftStyle, borderRightStyle, borderTopStyle NN 6 IE 4 DOM 2
Read/Write
Provide the line style of a single border edge of an element. The edge-specific attributes let you override a style that has been applied to all four edges with the border or borderStyle properties. See also the borderStyle property for setting the style for groups of edges in one statement.

Example

document.getElementById("announce").style.borderBottomStyle = "groove"; document.getElementById("announce").style.borderLeftStyle = "double"; document.getElementById("announce").style.borderRightStyle = "solid"; document.getElementById("announce").style.borderTopStyle = "inset";

Value

Style values are case-insensitive constants that are associated with specific ways of rendering border lines. The CSS style constants are: dashed, dotted, double, groove, hidden, inset, none, outset, ridge, and solid. Not all browsers recognize all the values in the CSS recommendation. See the border-style attribute listing in Chapter 11 for complete details on the available border styles.

Default

None.

borderBottomWidth, borderLeftWidth, borderRightWidth, borderTopWidth NN 6 IE 4 DOM 2
Read/Write
Provide the width of a single border edge of an element. See also the borderWidth property for setting the width for groups of edges in one statement.

Example

document.getElementById("announce").style.borderBottomWidth= "thin"; document.getElementById("announce").style.borderLeftWidth = "thick"; document.getElementById("announce").style.borderRightWidth = "2px"; document.getElementById("announce").style.borderTopWidth = "0.5em";

Value

Three case-insensitive constants—thin | medium | thick—allow the browser to define how many pixels are used to show the border. For more precision, you can also assign a length value (see the discussion of CSS length values at the beginning of Chapter 11).

Default

medium

borderCollapse NN 6 IE 5 DOM 2
Read/Write
Controls which table border model the table element should observe.

Example

document.getElementById("myTable").style.borderCollapse = "separate";

Value

Two case-insensitive string constants: collapse | separate. IE 5 for Macintosh and Netscape 6 do not respond to changes to this property.

Default

separate

borderColor NN 6 IE 4 DOM 2
Read/Write
A shortcut attribute that lets you set multiple border edges to the same or different colors. You may supply one to four space-delimited color values. The number of values determines which sides receive the assigned colors.

Example

document.getElementById("announce").style.borderColor = "red"; document.getElementById("announce").style.borderColor = "red green"; document.getElementById("announce").style.borderColor = "black rgb(100, 75, 0) #c0c0c0"; document.getElementById("announce").style.borderColor = "yellow green blue red";

Value

This property accepts one, two, three, or four color values as a string (including transparent as a color), depending on how many and which borders you want to set with specific colors. See the border-color attribute listing in Chapter 11 for complete details on how the number of values affects this property.

Default

The object's color property (if it is set).

borderSpacing NN 6 IE 5 DOM 2
Read/Write
Controls the spacing between table cells when the table is in (the default) separate borders mode, similar to a table object's cellSpacing property. IE 5 for the Macintosh doesn't respond to changes of this property's value. Available in IE as a property of the style object only.

Example

document.getElementById("myTable").style.borderSpacing= "12px";

Value

CSS length value as a string (see the discussion of CSS length values at the beginning of Chapter 11).

Default

None.

borderStyle NN 6 IE 4 DOM 2
Read/Write
This is a shortcut property that lets you set multiple border edges to the same or different style. You may supply one to four space-delimited style values. The number of values determines which sides receive the assigned colors.

Example

document.getElementById("announce").style.borderStyle = "solid"; document.getElementById("announce").style.borderStyle = "solid double"; document.getElementById("announce").style.borderStyle = "double groove groove double";

Value

Style values are case-insensitive constants that are associated with specific ways of rendering border lines. The CSS style constants are: dashed, dotted, double, groove, hidden, inset, none, outset, ridge, and solid. Not all browsers recognize all the values in the CSS recommendation. See the border-style attribute listing in Chapter 11 for complete details on the available border styles.

This property accepts one, two, three, or four style values as a string, depending on how many and which borders you want to set with specific styles. See the border-style attribute listing in Chapter 11 for complete details on how the number of values affects this property.

Default

none

borderWidth NN 6 IE 4 DOM 2
Read/Write
This is a shortcut property that lets you set multiple border edges to the same or different width. You may supply one to four space-delimited width length values. The number of values determines which sides receive the assigned widths.

Example

document.getElementById("founderQuote").style.borderWidth = "3px 5px";

Value

Three case-insensitive constants—thin | medium | thick—allow the browser to define exactly how many pixels are used to show the border. For more precision, you can also assign a length value (see the discussion of length values at the beginning of Chapter 11).

This property accepts one, two, three, or four values, depending on how many and which borders you want to set with specific widths. See the border-width attribute listing in Chapter 11 for complete details on how the number of values affects this property.

Default

medium

bottom NN 6 IE 5 DOM 2
Read/Write
For an absolute-positioned element, defines the position of the bottom edge of an element's box (content plus bottom padding, border, and/or margin) relative to the bottom edge of the next outermost block content container. IE for Windows and Netscape 6 do something unexpected when the positioned element uses the root positioning context. Instead of using the bottom of the document as the comparative edge, these browsers use the bottom of the browser window space (the viewport in CSS terminology). This means that the precise bottom position of the element varies with the user's browser window size. IE 5 for the Macintosh uses the document's bottom as the comparative edge. This discrepancy makes it more practical to use the bottom property for a positioned element nested inside another positioned element. When the element is relative-positioned, the offset is based on the bottom edge of the inline location where the element would normally appear in the content.
For numeric calculations on this value in IE, retrieve the pixelBottom or posBottom style properties, which return genuine numeric values.

Example

document.getElementById("blockD2").style.bottom = "35px";

Value

String consisting of a numeric value and length unit measure, a percentage, or auto.

Default

auto

captionSide NN 6 IE 5(Mac) DOM 2
Read/Write
Controls the location of a caption element (nested inside a table element) relative to the table's box.

Example

document.getElementById("myTable").style.captionSide = "bottom";

Value

Case-insensitive string of any of the following constants: bottom | left | right | top. Some browsers may be limited to only the bottom and top values.

Default

top

clear NN 6 IE 4 DOM 2
Read/Write
Defines whether the element allows itself to be displayed in the same horizontal band as a floating element. Typically, another element in the vicinity has its float style attribute set to left or right. To prevent the current element from being in the same band as the floating block, set the clear property to the same side (left or right). If you aren't sure where the potential overlap might occur, set the clear property to both. An element that has its clear property set to a value other than none is rendered at the beginning of the next available line below the floating element.

Example

document.getElementById("myDiv").style.clear = "both";

Value

Case-insensitive string of any of the following constants: both | left | none | right.

Default

none

clip NN 6 IE 4 DOM 2
Read/Write
Defines a clipping region of a positionable element. The clipping region is the area of the element layer in which content is visible. Clipping may not work properly in Internet Explorer 4 for the Macintosh. Available in IE as a property of the style and runtimeStyle objects only.

Example

document.getElementById("art2").style.clip = "rect(5px 100px 40px 0)";

Value

Case-insensitive string of either the auto constant or the CSS clip attribute setting that specifies the shape (rect only for now) and the position of the four clip edges relative to the original element's top-left corner. When specifying lengths for each side of the clipping rectangle, observe the clockwise order of values: top, right, bottom, left. See the discussion about CSS length values at the beginning of Chapter 11. A value of auto sets the clipping region to the block that contains the content. In Internet Explorer, the width may extend to the width of the next outermost container (such as the body element).

Default

None.

clipBottom, clipLeft, clipRight, clipTop NN n/a IE 5(Win) DOM n/a
Read-only
Return a clipping edge of a positionable element. Available in IE as a property of the currentStyle object only.

Example

var cl = document.getElementById("art2").style.clipLeft;

Value

Case-insensitive length string or auto constant. See the discussion about CSS length values at the beginning of Chapter 11.

Default

None.

color NN 6 IE 4 DOM 2
Read/Write
Sets the foreground (text) color style sheet attribute of the element. For some graphically oriented elements, such as form controls, the color attribute may also be applied to element edges or other features. Such extracurricular behavior is browser specific and may not be the same across browsers.

Example

document.getElementById("specialDiv").style.color = "green";

Value

Case-insensitive CSS color specification (see the discussion at beginning of Chapter 11).

Default

black

content NN 6 IE 5(Mac) DOM 2
Read/Write
Defines extra content that is to be displayed before or after and element (in concert with the :before and :after pseudo-classes. Although the property is available for IE 5 Macintosh and Netscape 6, the values are empty strings and the rendered content (which appears in Netscape 6 only) does not change if you assign it a new value.

Value

See the discussion of the content CSS attribute in Chapter 11.

Default

None.

counterIncrement, counterReset NN 6 IE 5(Mac) DOM 2
Read/Write
These properties are placeholders for future implementations of automatic counter mechanisms specified in the CSS specification. They are not yet functional in the browsers shown above.

Value

See the discussion of the counterIncrement and counterReset CSS attributes in Chapter 11.

Default

None.

cssFloat NN 6 IE 5(Mac) DOM 2
Read/Write
Controls the CSS float attribute for an element, allowing adjacent text content to wrap around block elements, such as images. Changing the value in IE 5 for Macintosh has no effect. The "css" prefix for this property name deflects potential conflicts with the float reserved JavaScript keyword.

Example

document.getElementById("myDiv").style.cssFloat = "right";

Value

String of an allowable constant value: left | right | none.

Default

none

cssText NN 6 IE 4 DOM 2
Read-only
Returns a string of the entire CSS style sheet rule applied to the element. If the rule included shorthand style attribute settings (such as border), browsers return modified versions according to their ideas of what the value means. If you set the style attribute of an element to style="border: groove red 3px", IE for Windows reports the cssText property for that element as:
BORDER-RIGHT: red 3px groove; BORDER-TOP: red 3px groove; BORDER-LEFT: red 3px groove; BORDER-BOTTOM: red 3px groove
IE for Macintosh reports:
{BORDER-TOP: 3px groove red; BORDER-RIGHT: 3px groove red; BORDER-BOTTOM: 3px groove red; BORDER-LEFT: 3px groove red}
And Netscape 6 reports:
border: 3px groove red;
Note how each browser manipulates the sequence of individual values. Even so, you can assign a shorthand value to the property and in any order you like. Available in IE as a property of the style and runtimeStyle objects only.

Example

document.getElementById("block3").style.cssText = "margin: 2px; font-size: 14pt";

Value

String value of semicolon-delimited style attributes.

Default

None.

cue, cueAfter, cueBefore
See azimuth.

cursor NN 6 IE 4 DOM 2
Read/Write
Specifies the shape of the cursor when the screen pointer is atop the element. The precise look of cursors depends on the operating system. Before deploying a modified cursor, be sure you understand the standard ways that the various types of cursors are used within the browser and operating system. Users expect a cursor design to mean the same thing across all applications. Figure 11-3 in Chapter 11 offers a gallery of Windows and Macintosh cursors for each of the cursor constant settings provided by Internet Explorer and the Netscape 6 group.
Setting this property affects the cursor only when it is atop the current element and does not set the cursor immediately on a global basis.

Example
document.getElementById("hotStuff").style.cursor = "pointer";
Value

Any one cursor constant as a string, as supported by various browsers and versions.

Cursor name

IE/Windows

IE/Mac

NN

alias

n/a

n/a

6

all-scroll

6

n/a

n/a

auto

4

4

6

cell

n/a

n/a

6

col-resize

6

n/a

n/a

context-menu

n/a

n/a

6

copy

n/a

n/a

6

count-down

n/a

n/a

6

count-up

n/a

n/a

6

count-up-down

n/a

n/a

6

crosshair

4

4

6

default

4

4

6

e-resize

4

4

6

grab

n/a

n/a

6

grabbing

n/a

n/a

6

hand

4

4

n/a

help

4

4

6

move

4

4

6

n-resize

4

4

6

ne-resize

4

4

6

no-drop

6

n/a

n/a

not-allowed

6

n/a

n/a

nw-resize

4

4

6

pointer

4

4

6

progress

6

n/a

n/a

row-resize

6

n/a

n/a

s-resize

4

4

6

se-resize

4

4

6

spinning

n/a

n/a

6

sw-resize

4

4

6

text

4

4

6

url(uri)

6

n/a

n/a

vertical-text

6

n/a

n/a

w-resize

4

4

6

wait

4

4

6

The IE 6 setting of an external URL requires an address of a cursor file of extension .cur or .ani.

Default

auto

direction NN 6 IE 5 DOM 2
Read/Write
Returns the writing script direction of the current element. Intended primarily for elements inside documents with mixed writing script directions (e.g., French text intermingled among Arabic).

Example

document.getElementById("term3").style.direction = "ltr";

Value

String constant values: ltr | rtl.

Default

ltr

display NN 6 IE 4 DOM 2
Read/Write
Controls the CSS box type used to render the element. The most common settings for body content dictate whether an element is rendered as a block or inline element. When set to none, the element is hidden, and surrounding content cinches up to fill the space. Some box types are specific to tables and lists.

Example

document.getElementById("instructionDiv").style.display = "none";

Value

Any one display type constant as a string, as supported by various browsers and versions.

Display type

IE/Windows

IE/Mac

NN

block

5

4

6

inline

5

4

6

inline-block

5.5

n/a

n/a

none

4

4

6

run-in

n/a

5

6

table-footer-group

5.5

5

6

table-header-group

5

5

6

Default

Element-dependent.

elevation
See azimuth.

emptyCells NN 6 IE 5(Mac) DOM 2
Read/Write
When a table is set to render the separate cell box format (the default), and a border is established for td elements in that table, the emptyCells style property controls whether the table renders borders around cells that have no content.

Example

document.getElementById("myTable").style.emptyCells = "hide";

Value

String of allowable constant values: hide | show.

Default

show

filter NN n/a IE 4(Win) DOM n/a
Read/Write
Sets the visual, reveal, or blend filter used to display or change content of an element. A visual filter can be applied to an element to produce effects such as content flipping, glow, drop shadow, and many others. A reveal filter is applied to an element when its visibility changes. The value of the reveal filter determines what visual effect is to be applied to the transition from hidden to shown (or vice versa). This includes effects such as wipes, blinds, and barn doors. A blend filter sets the speed at which a transition between states occurs. Although the filter property is present in Internet Explorer for Macintosh, it does not operate there.

Example

document.getElementById("fancy").style.filter= "dropshadow( )";

Value

Each filter property may have more than one space-delimited filter type associated with it. Each filter type is followed by a pair of parentheses, which may convey parameters about the behavior of the filter for the current element. A parameter generally consists of a name/value pair, with assignment performed by the equals symbol. Note that Microsoft instituted an entirely new filter syntax starting with IE 5.5 for Windows. The new syntax runs in parallel with the old (for now). See the filter style sheet attribute listing in Chapter 11 for details on filter settings and parameters.

Default

None.

font NN 6 IE 4 DOM 2
Read/Write
This is a shorthand property that lets you set one or more font-related properties—fontFamily, fontSize, lineHeight (which must be preceded by a / symbol in this property), fontStyle, fontVariant, and fontWeight—with one assignment statement. A space-delimited list of values (in any sequence) is applied to the specific font properties for which the value is a valid type. Or, you can short-circuit these individual settings by choosing one of the default (operating-system-dependent) system fonts: caption | icon | menu | message-box | small-caption | status-bar.

Example

document.getElementById("subhead").style.font = "bolder small-caps 16pt";

Value

For syntax and examples of value types for font-related properties, see the respective property listing.

Default

None.

fontFamily NN 6 IE 4 DOM 2
Read/Write
Provides a prioritized list of font families to be used to render the object's content. One or more font family names may be included in a comma-delimited list of property values. If a font family name consists of multiple words, the family name must be inside a set of inner quotes. Available in IE as a property of the style and runtimeStyle objects only, but the individual font properties are available in currentStyle, as well.

Example

document.getElementById("subhead").style.fontFamily = "'Century Schoolbook', Times, serif";

Value

Any number of font family names, comma delimited. Multiword family names must be quoted. Recognized generic family names are: serif | sans-serif | cursive | fantasy | monospace.

Default

Browser default.

fontSize NN 6 IE 4 DOM 2
Read/Write
Indicates the font size of the element. The font size can be set in several ways. A collection of constants (xx-small, x-small, small, medium, large, x-large, xx-large) defines what are known as absolute sizes. In truth, these are absolute only in a single browser in a single operating system, since the reference point for these sizes varies with browser and operating system (analogous to the old HTML font sizes of 1 through 7). But they do let the author have confidence that one element set to large is rendered larger than medium.
Another collection of constants (larger, smaller) is known as relative sizes. Because the font-size style attribute is inherited from the parent element, these relative sizes are applied to the parent element to determine the font size of the current element. It is up to the browser to determine exactly how much larger or smaller the font size is, and a lot depends on how the parent element's font size is set. If it is set with one of the absolute sizes (large, for example), a child's font size of larger means the font is rendered in the browser's x-large size. The increments are not as clear-cut when the parent font size is set with a length or percentage.
If you elect to use a length value for the fontSize property, you will achieve greater consistency across operating systems if units such as pixels (px) or ems (em), instead of points (pt). Em units are calculated with respect to the size of the parent element's font size. Finally, you can set fontSize to a percentage, which is calculated based on the size of the parent element's font size.

Example

document.getElementById("teeny").style.fontSize = "x-small";

Value

Case-insensitive string values from any of the following categories. For an absolute size, one of the following constants: xx-small | x-small | small | medium | large | x-large | xx-large. For a relative size, one of the following constants: larger | smaller. For a length, see the discussion about CSS length values at the beginning of Chapter 11. For a percentage, the percentage value and the % symbol.

Default

Parent element's font size.

fontSizeAdjust NN 6 IE 5(Mac) DOM 2
Read/Write
Provides the font aspect value, usually of the first font family in a font-family attribute sequence, forcing alternative font families to calculate their rendered font size to closely match that of the primary font family. Although this property is a member of the style object in IE 5/Mac and Netscape 6, neither the style attribute nor scripted changes to it affect the font display.

Example

document.getElementById("myDIV").style.fontSizeAdjust = "0.56";

Value

Numeric aspect value as a quoted string, or none.

Default

none

fontStretch NN 6 IE 5(Mac) DOM 2
Read/Write
Provides the character spacing for the element, based on available spacing widths available for the current font family. Although this property is a member of the style object in IE 5/Mac and Netscape 6, neither the style attribute nor scripted changes to it affect the font display.

Example

document.getElementById("myDIV").style.fontStretch= "ultra-condensed";

Value

String of allowable constant values: normal | wider | narrower | ultra-condensed | extra-condensed | condensed | semi-condensed | semi-expanded | expanded | extra-expanded | ultra-expanded, or none.

Default

none

fontStyle NN 6 IE 4 DOM 2
Read/Write
Specifies whether the element is rendered in a normal (roman), italic, or oblique font style. If the fontFamily includes font faces labeled Italic and/or Oblique, the setting of the fontStyle attribute summons those particular font faces from the browser's system. But if the specialized font faces are not available in the system, the normal font face is usually algorithmically slanted to look italic. Output sent to a printer with such font settings relies on the quality of arbitration between the client computer and printer to render an electronically generated italic font style. Personal computer software typically includes other kinds of font rendering under the heading of "Style." See fontVariant and fontWeight for other kinds of font "styles."

Example

document.getElementById("emphasis").style.fontStyle = "italic";

Value

One the following string constant values: normal | italic | oblique.

Default

normal

fontVariant NN 6 IE 4 DOM 2
Read/Write
Specifies whether the element should be rendered in all uppercase letters in such a way that lowercase letters of the source code are rendered in smaller uppercase letters. If a font family contains a small caps variant, the browser should use it automatically. More likely, however, the browser calculates a smaller size for the uppercase letters that take the place of source code lowercase letters. In practice, Internet Explorer 4 renders the entire source code content as uppercase letters of the same size as the parent element's font, regardless of the case of the source code. Later IE versions and Netscape 6 use two different uppercase sizes.

Example

document.getElementById("emphasis").style.fontVariant = "small-caps";

Value

Any of the following constant values as strings: normal | small-caps.

Default

normal

fontWeight NN 6 IE 4 DOM 2
Read/Write
Sets the weight (boldness) of the element's font. CSS provides a weight rating scheme that is more granular than most browsers render on the screen, but the finely tuned weights may come into play when the content is sent to a printer. The scale is a numeric rating from 100 to 900 at 100-unit increments. Therefore, a fontWeight of 100 would be the least bold that would be displayed, while 900 would be the boldest. A setting of normal (the default weight for any font) is equivalent to a fontWeight value of 400; the standard bold setting is equivalent to 700. Other settings (bolder and lighter) let you specify a weight relative to the parent element's weight.

Example

document.getElementById("hotStuff").style.fontWeight = "bold";

Value

Any of the following constant values: bold | bolder | lighter | normal | 100 | 200 | 300 | 400 | 500 | 600 | 700 | 800 | 900.

Default

normal

height, width NN 6 IE 4 DOM 2
Read/Write
Indicate the height and width (and their units) of the element. Because the values are strings containing the assigned units, you cannot use these properties for calculation. Grab copies of the numbers by using parseFloat( ) on the values; or for IE, use pixelHeight, pixelWidth, posHeight, and posWidth properties. Changes to these properties may not be visible unless the element has its position style attribute set.
In IE 6 standards compatibility mode (where document.compatType == "CSS1Compat"), these dimensions apply to only the content portion of an element, irrespective of borders, padding, or margins. For example, if a positioned element that is equipped with padding and borders must be sized to a precise rectangular size, you must subtract the thicknesses of the padding and borders from the height and width values so that the overall element is the desired size.

Example

document.getElementById("viewArea").style.height = "450px";

Value

String consisting of a numeric value and length measure or percentage.

Default

None.

imeMode NN n/a IE 5(Win) DOM n/a
Read/Write
Controls the presence of the Input Method Editor in IE for Windows for browser and system versions that support languages such as Chinese, Japanese, and Korean.

Example

document.getElementById("nameEntry").style.imeMode = "active";

Value

String of allowable constant values: active | auto | disabled | inactive.

Default

auto

layoutFlow NN n/a IE 5(Win) DOM n/a
Read/Write
Intended primarily for languages that display characters in vertical sentences, controls the progression of content. Replaced starting with IE 5.5 for Windows by the writingMode property.

Value

One of the constant values (as a string): horizontal | vertical-ideographic.

Default

horizontal

layoutGrid NN n/a IE 5(Win) DOM n/a
Read/Write
This is a shorthand property that lets you set one or more layout grid properties (layoutGridChar, layoutGridLine, layoutGridMode, and layoutGridType) with one assignment statement. These attributes are used primarily with Asian language content.

Example

document.getElementById("subhead").style.layoutGrid = "2em strict";

Value

For syntax and examples of value types for layoutGrid-related properties, see the respective property listing.

Default

None.

layoutGridChar NN n/a IE 5(Win) DOM n/a
Read/Write
Dictates the size of Asian language character grid for block-level elements.

Example

document.getElementById("subhead").style.layoutGrid Char= "auto";

Value

String consisting of an explicit CSS length value or auto or none.

Default

none

layoutGridLine NN n/a IE 5(Win) DOM n/a
Read/Write
Dictates the line height of Asian language character grid for block-level elements.

Example

document.getElementById("subhead").style.layoutGrid Line= "120%";

Value

String consisting of an explicit CSS length value or auto or none.

Default

none

layoutGridMode NN n/a IE 5(Win) DOM n/a
Read/Write
Specifies whether the Asian language character grid should be one- or two-dimensional.

Example

document.getElementById("subhead").style.layoutGrid Mode= "both";

Value

String constant values: both | char (for inline elements) | line (for block-level elements) | none.

Default

both

layoutGridType NN n/a IE 5(Win) DOM n/a
Read/Write
Controls how the layout grid responds to characters of varying width..

Example

document.getElementById("subhead").style.layoutGrid Type = "strict";

Value

String constant values: fixed | loose | strict.

Default

loose

left NN 6 IE 4 DOM 2
Read/Write
For positionable elements, defines the position of the left edge of an element's box (content plus left padding, border, and/or margin) relative to the left edge of the next outermost block content container. When the element is relative-positioned, the offset is based on the left edge of the inline location of where the element would normally appear in the content.
For calculations on this value, use parseFloat( ) on the returned value; or, in IE, retrieve the pixelLeft or posLeft properties, which return genuine numeric values.

Example

document.getElementById("blockD2").style.left = "45px";

Value

String consisting of a numeric value and length unit measure, a percentage, or auto.

Default

auto

letterSpacing NN 6 IE 4 DOM 2
Read/Write
Specifies the spacing between characters within an element. Browsers normally define the character spacing based on font definitions and operating system font rendering. Assigning a negative value tightens the spacing, but be sure to test the effect on the selected font for readability on different operating systems.

Example

document.body.style.letterSpacing = "1.1em";

Value

A string of a length value (with unit of measure) or normal. The best results are achieved by using units that are based on the rendered font size (em and ex). A setting of normal is how the browser sets the letters without any intervention.

Default

normal

lineBreak NN n/a IE 5(Win) DOM n/a
Read/Write
Controls line breaking rules for Japanese text.

Example

document.body.style.lineBreak = "strict";

Value

String constant values: normal | strict.

Default

normal

lineHeight NN 6 IE 4 DOM 2
Read/Write
Indicates the height of the inline box (the box holding one physical line of content). See the line-height style attribute in Chapter 11 for details on browser quirks and inheritance traits of different types of values.

Example
document.getElementById("tight").style.lineHeight = "1.1em";
Value

A string of a length value (with unit of measure) or normal.

Default

normal

listStyle NN 6 IE 4 DOM 2
Read/Write
This is a shorthand property for setting up to three list-style properties in one assignment statement. Whichever attributes you don't explicitly set with this attribute assume their default values. These properties define display characteristics for the markers automatically rendered for list items inside ol and ul elements. This is available in IE as a property of the style and runtimeStyle objects only, but individual properties are properties of currentStyle, as well.

Example

document.getElementById("itemList").style.listStyle = "square outside none";

Value

See the individual attribute entries for listStyleType, listStylePosition, and listStyleImage for details on acceptable values for each. You may include one, two, or all three values in the list-style attribute setting in any order you wish.

Default

None.

listStyleImage NN 6 IE 4 DOM 2
Read/Write
Provides the URL for an image that is to be used as the marker for a list item. Because this attribute can be inherited, a setting (including none) for an individual list item can override the same attribute or property setting in its parent.

Example

document.getElementById("itemList").style.listStyleImage = "url(images/3DBullet.gif)";

Value

Use none (as a string) to override an image assigned to a parent element. Otherwise, supply any valid full or relative URL (in the CSS URL format) to an image file with a MIME type that is readable by the browser.

Default

none

listStylePosition NN 6 IE 4 DOM 2
Read/Write
Specifies whether the marker is inside or outside (outdented) the box containing the list item's content. When listStylePosition is set to inside and the content is text, the marker appears to be part of the text block. In this case, the alignment (indent) of the list item is the same as normal, but without the outdented marker.

Example

document.getElementById("itemList").style.listStylePosition = "inside";

Value

Either constant value as a string: inside | outside.

Default

outside

listStyleType NN 6 IE 4 DOM 2
Read/Write
Specifies the kind of item marker to be displayed with each item. This attribute is applied only if listStyleImage is none (or not specified). The constant values available for this attribute are divided into two categories. One set is used with ul elements to present a filled disc, an empty circle, or a filled square (except empty square on IE 4 for Macintosh). The other set is for ol elements, which has list items that can be marked in sequences of arabic numerals, roman numerals (uppercase or lowercase), letters of the alphabet (uppercase or lowercase), and some other character sequences of other languages if the browser and operating system supports those languages.

Example

document.getElementById("itemList").style.listStyleType = "circle";

Value

One constant value as a string that is relevant to the type of list container. For ul: circle | disc | square. For ol: decimal | decimal-leading-zero | lower-roman | upper-roman | lower-greek | lower-alpha | lower-latin | upper-alpha | upper-latin | hebrew | armenian | georgian | cjk-ideographic | hiragana | katakana | hiragana-iroha | katakana-iroha. Commonly-supported ol element sequences are treated as shown in the following table.

Type

Example

decimal

1, 2, 3, ...

decimal-leading-zero

01, 02, 03, ...

lower-alpha

a, b, c, ...

lower-greek

α, β, γ, ...

lower-roman

i, ii, iii, ...

upper-alpha

A, B, C, ...

upper-roman

I, II, III, ...

Default

disc (for ul); decimal (for ol).

margin NN 6 IE 4 DOM 2
Read/Write
This is a shortcut property that can set the margin widths of up to four edges of an element with one statement. A margin is space that extends beyond the border of an element to provide extra empty space between adjacent or nested elements, especially those that have border attributes set. You may supply one to four space-delimited margin values. The number of space-delimited values determines which sides receive the assigned margins.

Example

document.getElementById("logoWrapper").style.margin = "5px 8px";

Value

This property accepts one, two, three, or four space-delimited values inside one string, depending on how many and which margins you want to set. See the margin attribute listing in Chapter 11 for complete details on how the number of values affects this property. Values for the margins can be lengths, percentages of the next outermost element size, or the auto constant.

Default

0

marginBottom, marginLeft, marginRight, marginTop NN 6 IE 4 DOM 6
Read/Write
All four properties set the width of a single margin edge of an element. A margin is space that extends beyond the element's border and is not calculated as part of the element's width or height.

Example

document.getElementById("logoWrapper").style.marginTop = "5px"; document.getElementById("navPanel").style.marginLeft = "10%";

Value

Values for margin widths can be length values, percentages of the next outermost element size, or the auto constant.

Default

0

markerOffset NN 6 IE n/a DOM n/a
Read/Write
Controls the space between list item markers (which occupy their own box in the CSS box model) and the box that contains the list item text. Although the property is available for Netscape 6, the value is an empty string and the rendered content does not change if you assign it a new value.

Value

A string of a length value (with unit of measure) or auto.

Default

None.

marks NN 6 IE 5(Mac) DOM 2
Read/Write
Sets crop mark type for an @page rule. Although the property is available for IE 5 Macintosh and Netscape 6, the values are empty strings and the rendered content does not change if you assign it a new value.

Value

Case-insensitive string of any of the following constants: crop | cross | none.

Default

none

maxHeight, maxWidth, minHeight, minWidth NN 6 IE (See text) DOM 2
Read/Write
Define loose heights and widths for an element so that, for "max" properties, an element is allowed to grow no bigger in the designated dimension, or, for "min" properties, an element can expand in the designated dimension to accommodate more than expected content or rendering situations. Although the property is available for IE 5 Macintosh and Netscape 6, it is either ignored (IE 5 for Mac) or buggy (Netscape 6). IE 6 for Windows supports only the minWidth property, and it can be used only for tr, th, and td elements.

Value

CSS length value (see Chapter 11) as a string.

Default

None.

MozBinding NN 6 IE n/a DOM n/a
Read/Write
Points to the URL of an XML document designed to enhance an existing element or create a new interface element. Based on Mozilla XBL (Extensible Bindings Language). For more details, visit http://www.mozilla.org/unix/customizing.html.

Value

CSS URL value string or none.

Default

None.

MozOpacity NN 6 IE n/a DOM n/a
Read/Write
Defines the level of opacity of the element. The lower the value, the more transparent the element becomes. This is the proprietary Mozilla version of the proprietary Microsoft opaque filter.

Example

document.getElementById("menuWrapper").style.MozOpacity = "40%";

Value

Numeric string value between 0 and 1 or string percentage value between 0% and 100%.

Default

100% (completely opaque)

orphans, widows NN 6 IE 5(Mac) DOM 2
Read/Write
For a block-level element's content that spreads across page boxes, specify the minimum number of lines of the element that must appear at the bottom of the page (orphans) or at the top of the next page (widows). Although these properties are members of the style object in IE 5/Mac and Netscape 6, neither the style attribute nor scripted changes to it affect the printed output.

Example

document.getElementById("sec23").style.orphans = "3";

Value

Integer as a string.

Default

None.

outline NN 6 IE 5(Mac) DOM 2
Read/Write
This is a shorthand property for getting or setting the outlineColor, outlineStyle, and/or outlineWidth properties of an outline around an element in one statement. You must specify an outline style (see outlineStyle) for changes of this property to affect the display. An outline is like a border, but overlays the element without occupying any content space or affecting the element's dimensions. Although this property is a member of the style object in IE 5/Mac and Netscape 6, only IE 5/Mac renders the outline.

Exaple

document.getElementById("announce").style.outline = "solid blue 4px";

Value

Space-delimited string. For the outlineStyle and outlineWidth component values, see the respective properties in this chapter. For details on the outlineColor value, see the section about CSS colors at the beginning of Chapter 11.

Default

None.

outlineColor NN 6 IE 5(Mac) DOM 2
Read/Write
Controls the color of an outline.

Example

document.getElementById("announce").style.outlineColor = "rgb(100, 75, 0)";

Value

CSS color value or constant invert. For details on CSS color values, see the section about colors at the beginning of Chapter 11.

Default

invert

outlineStyle NN 6 IE 5(Mac) DOM 2
Read/Write
Controls the line type of an outline.

Example

document.getElementById("announce").style.outlineStyle = "solid";

Value

Style values are case-insensitive constants that are associated with specific ways of rendering outline (and border) lines. The CSS style constants are: dashed, dotted, double, groove, hidden, inset, none, outset, ridge, and solid.

Default

none

outlineWidth NN 6 IE 5(Mac) DOM 2
Read/Write
Controls the thickness of the outline lines.

Example

document.getElementById("announce").style.outlineWidth = "2px";

Value

Three case-insensitive constants—thin | medium | thick—allow the browser to define exactly how many pixels are used to show the border. For more precision, you can also assign a length value (see the discussion of CSS length values at the beginning of Chapter 11).

Default

medium

overflow NN 6 IE 4 DOM 2
Read/Write
Specifies how a positioned element should treat content that extends beyond the boundaries established in the style sheet rule. See the discussion of the overflow style sheet attribute in Chapter 11 for details.

Example
document.getElementById("myDiv").style.overflow = "scroll";
Value

Any of the following constants as a string: auto | hidden | scroll | visible.

Default

visible

overflowX, overflowY NN n/a IE 5(Win) DOM n/a
Read/Write
Specify how a positioned element should treat content that extends beyond the horizontal (overflowX) or vertical (overflowY) boundaries established in the style sheet rule.

Example

document.getElementById("myDiv").style.overflow X= "scroll";

Value

Any of the following constants as a string: auto | hidden | scroll | visible.

Default

visible

padding NN 6 IE 4 DOM 2
Read/Write
This is a shortcut property that can set the padding widths of up to four edges of an element with one statement. Padding is space that extends around the content box of an element up to but not including any border that may be specified for the element. Padding picks up the background image or color of its element. As you add padding to an element, you increase the size of the visible rectangle of the element without affecting the content block size. You may supply one to four space-delimited padding values. The number of values determines which sides receive the assigned padding.

Example

document.getElementById("logoWrapper").style.padding = "3px 5px";

Value

This property accepts one, two, three, or four space-delimited values inside one string, depending on how many and which edges you want to pad. See the padding attribute listing in Chapter 11 for complete details on how the number of values affects this property. Values for padding widths can be lengths, percentages of the next outermost element size, or the auto constant.

Default

0

paddingBottom, paddingLeft, paddingRight, paddingTop NN 6 IE 4 DOM 2
Read/Write
All four properties set the width of a single padding edge of an element. Padding is space that extends between the element's border and content box. Padding is not calculated as part of the element's width or height.

Example

document.getElementById("logoWrapper").style.paddingTop = "3px"; document.getElementById("navPanel").style.paddingLeft = "10%";

Value

Values for padding widths can be length values, percentages of the next outermost element size, or the auto constant.

Default

0

page NN 6 IE 5(Mac) DOM 2
Read/Write
Points to the name of an existing @page rule (when the rule contains an identifier, such as @page figures {size: landscape}) in order to apply that rule to the current block-level element. Although this property is a member of the style object in IE 5/Mac and Netscape 6, neither the style attribute nor scripted changes to it affect the printed output.

Value

String identifier.

Default

None.

pageBreakAfter, pageBreakBefore NN 6 IE 4 DOM 2
Read/Write
Define how content should treat a page break around an element when the document is sent to a printer. Page breaks are not rendered in the visual browser as they may be in word processing programs; on screen, long content flows in one continuous scroll on the screen. Also see the extensive discussion of page breaks in the listing for the page-break-after and page-break-before style attributes in Chapter 11.

Example
document.getElementById("hardBR").style.pageBreakAfter = "always";
document.getElementById("navPanel").style.paddingLeft = "10%";
Value

All supporting browsers recognize four constant values (as strings): always | auto | left | right. Additionally, IE for Windows supports an empty string, which has the same effect as the W3C CSS avoid constant.

Default

auto

pageBreakInside NN 6 IE 5(Mac) DOM 2
Read/Write
Defines whether the element allows itself to be split across printed pages. Although this property is a member of the style object in IE 5/Mac and Netscape 6, neither the style attribute nor scripted changes to it affect the printed output.

Value

A constant value (as a string): auto | avoid.

Default

auto

pause, pauseAfter, pauseBefore, pitch, pitchRange
See azimuth.

pixelBottom, pixelLeft, pixelRight, pixelTop NN n/a IE 4 DOM n/a
Read/Write
For positionable elements, these properties define the pixel position of the edges of an element's box (content plus padding, border, and/or margin) relative to the corresponding edges of the next outermost block content container. When the element is relative-positioned, the measure is based on the edges of the inline location of where the element would normally appear in the content. Use these properties for calculation (including path animation) instead of the bottom, left, right, and top properties, which store their values as strings with the unit names. Available as a property of the IE style and runtimeStyle objects only.

Example

document.getElementById("myDIV").style.pixelLeft++;

Value

Integer.

Default

None.

pixelHeight, pixelWidth NN n/a IE 4 DOM n/a
Read/Write
Specify the height and width of the element in pixels. Use these properties for calculation instead of properties such as height and width, which return strings including units. Changes to these properties may not be visible unless the element has its position style attribute set. Available as a property of the IE style and runtimeStyle objects only.

Example

var midWidth = document.getElementById("myDIV").style.pixelWidth/2;

Value

Integer

Default

None.

playDuring
See azimuth.

posBottom, posLeft, posRight, posTop NN n/a IE 4 DOM n/a
Read/Write
For positionable elements, these properties define the position of the edges of an element's box (content plus padding, border, and/or margin) relative to the corresponding edges of the next outermost block content container. When the element is relative-positioned, the measure is based on the edges of the inline location where the element would normally appear in the content. Most importantly, these properties' values are numeric and in the unit of measure set in the CSS bottom, left, right, or top attribute. Use these properties for calculation (including path animation) instead of the bottom, left, right, and top properties, which store their values as strings with the unit names. All math is in the specified units. Also contrast these properties with the pixelBottom, pixelLeft, pixelRight, and pixelTop properties, which are integer values for pixel measures only. Available as a property of the IE style and runtimeStyle objects only.

Example

document.getElementById("myDIV").style.posLeft = document.getElementById("myDIV").style.posLeft + 1.5;

Value

Floating-point number.

Default

None.

posHeight, posWidth NN n/a IE 4 DOM n/a
Read/Write
Specify the numeric height and width of the element in the units set by the CSS positioning-related attributes. Use these properties for calculation instead of properties such as height and width, which return strings including units. All math is in the specified units. Also contrast these properties with the pixelHeight and pixelWidth properties, which are integer values for pixel measures only. Available as a property of the IE style and runtimeStyle objects only.

Example

document.getElementById("myDIV").style.posWidth = 10.5;

Value

Floating-point number.

Default

None.

position NN 6 IE 4 DOM 2
Read-only
For positionable elements, returns the value assigned to the style sheet position attribute. This property is actually read/write, but you cannot change a positioned element into a static one or vice-versa.

Example

var posType = document.getElementById("myDIV").style.position;

Value

String constant: absolute | fixed | relative | static. The fixed value is not supported in IE for Windows through Version 6.

Default

None.

quotes NN 6 IE 5(Mac) DOM 2
Read/Write
Assigns pairs of characters to be used as quote marks (especially for the q element). Although the property is available for IE 5 Macintosh and Netscape 6, only Netscape 6 responds to the CSS attributes, and neither responds to reading or writing the quotes property value.

Value

A string consisting of two or four quoted strings (nested quotes). The first pair provides characters for first-level quotes; the second pair supplies characters to nested quotes.

Default

None.

richness
See azimuth.

right NN 6 IE 5 DOM 2
Read/Write
For an absolute-positioned element, defines the position of the right edge of an element's box (content plus right padding, border, and/or margin) relative to the right edge of the next outermost block content container.
For numeric calculations on this value in IE, retrieve the pixelRight or posRight style properties, which return genuine numeric values.

Example

document.getElementById("blockD2").style.right = "25px";

Value

String consisting of a numeric value and length unit measure, a percentage, or auto.

Default

auto

rubyAlign NN n/a IE 5 DOM n/a
Read/Write
Controls alignment of content in a ruby element. Changes to this property affect IE for Windows only. Ruby-related styles are defined in CSS3.

Example

document.getElementById("myRuby").style.rubyAlign = "center";

Value

Case-insensitive string of any of the following constants: auto | center | distribute-letter | distribute-space | left | line-edge | right.

Default

auto

rubyOverhang NN n/a IE 5 DOM n/a
Read/Write
Controls text overhang characteristics of content in a ruby element. Changes to this property affect IE for Windows only. Ruby-related styles are defined in CSS3.

Example

document.getElementById("myRuby").style.rubyOverhang="whitespace";

Value

Case-insensitive string of any of the following constants: auto | none | whitespace.

Default

auto

rubyPosition NN n/a IE 5 DOM n/a
Read/Write
Controls whether ruby (rt element) text renders on the same line or above its related ruby base (rb element) text. Changes to this property affect IE for Windows only. Ruby-related styles are defined in CSS3.

Example

document.getElementById("myRuby").style.rubyPosition = "inline";

Value

Case-insensitive string of any of the following constants: above | inline.

Default

above

scrollbar3dLightColor, scrollbarArrowColor, scrollbarBaseColor, scrollbarDarkShadowColor, scrollbarFaceColor, scrollbarHighlightColor, scrollbarShadowColor, scrollbarTrackColor NN n/a IE 5.5(Win) DOM n/a
Read/Write
Controls the colors for specific components of a scrollbar user interface element associated with an applet, body, div, embed, object, or textarea element. See the description of these CSS attributes in Chapter 11 for details about which component each property governs.

Example
document.getElementById("comments").style.scrollbarArrowColor = "rgb(100, 75, 0");
Value

Case-insensitive CSS color specification (see discussion at beginning of Chapter 11).

Default

None.

size NN 6 IE n/a DOM 2
Read/Write
For a page context defined by an @page rule, this property controls the page size or orientation. Although the property is available for Netscape 6, the value is an empty strings and the property has no influence over the page context.

Value

CSS length values (as a string) or case-insensitive string of any of the following constants: auto | landscape | portrait. For length values, a single value is applied to height and width; two space-delimited length values are applied to width and height, respectively.

Default

auto

speak, speakHeader, speakNumeral, speakPunctuation, speechRate, stress
See azimuth.

styleFloat NN n/a IE 4 DOM n/a
Read/Write
Specifies on which side of the containing box the element aligns so that other content wraps around the element. When the property is set to none, the element appears in its source code sequence, and at most one line of surrounding text content appears in the same horizontal band as the element. See the float style attribute in Chapter 11 for more details. IE 5 for Macintosh duplicates this property as cssFloat, the DOM 2 version, which is also supported (by itself) in Netscape 6.

Example
document.getElementById("myDIV").style.styleFloat = "right";
Value

One of the following constants (as a string): none | left | right.

Default

None.

tableLayout NN 6 IE 5 DOM 2
Read/Write
Acts as a switch at load time to direct the browser to start rendering the table based on column widths set by the first row, or wait until the table data is loaded so that the browser can calculate optimum column widths based on cell contents. Changes to this property have no effect on a rendered table.

Example

document.getElementById("myTable").style.tableLayout = "fixed";

Value

One of the following constants (as a string): auto | fixed.

Default

auto

textAlign NN 6 IE 4 DOM 2
Read/Write
Determines the horizontal alignment of text within an element's box.

Example

document.getElementById("myDIV").style.textAlign = "right";

Value

One of the four constants (as a string): center | justify | left | right.

Default

Depends on default language of the browser.

textAlignLast NN n/a IE 5.5(Win) DOM n/a
Read/Write
Determines the horizontal alignment of the last line of text within an element's box. This style attribute may be helpful to obtain the desired look if you use some of the other proprietary text alignment style attributes in IE 5.5 or later for Windows.

Example

document.getElementById("myDIV").style.textAlignLast = "justify";

Value

One of the following constants (as a string): auto | center | justify | left | right.

Default

auto

textAutospace NN n/a IE 5(Win) DOM n/a
Read/Write
Controls the spacing between ideographic (typically Asian languages) and nonideographic characters.

Example

document.getElementById("myDIV").style.textAutospace = "ideograph-numeric";

Value

One of the following constants (as a string): ideograph-alpha | ideograph-numeric | ideograph-parenthesis | ideograph-space | none.

Default

none

textDecoration NN 6 IE 4 DOM 2
Read/Write
Specifies additions to the text content of the element in the form of underlines, strikethroughs, overlines, and (in Navigator and CSS) blinking. Browsers use this style attribute internally to assign by default underlines to a elements and strikethroughs to strike elements, so the default value varies with element type. You may specify more than one decoration style by supplying values in a space-delimited list. While browsers accept the (CSS optional) blink value, they (thankfully) do not cause the text to blink. Text decoration has an unusual parent-child relationship. Values are not inherited, but the effect of a decoration carries over to nested items in most cases. Therefore, unless otherwise overridden, an underlined p element underlines a nested b element within. Internet Explorer also includes Boolean properties for each decoration type.

Example

document.getElementById("emphasis").style.textDecoration = "underline";

Value

In addition to none, any of the following four constants (as a string): blink | line-through | overline | underline. Multiple values may be included in the string as a space-delimited list.

Default

Element and internal style sheet dependent.

textDecorationBlink, textDecorationLineThrough, textDecorationNone, textDecorationOverline, textDecorationUnderline NN n/a IE 4 DOM n/a
Read/Write
Specifies whether the specified text decoration feature is enabled for the element. Each of these properties corresponds to a value that can be assigned to the text-decoration style attribute in CSS (see Chapter 11). Internet Explorer does not blink text, so the textDecorationBlink property is ignored. Setting textDecorationNone to true sets all other related properties to false. Setting these properties on the Macintosh version of IE 4 does not alter the content. Use the textDecoration property instead—good practice all around.

Example
document.getElementById("emphasis").style.textDecorationLineThrough = "true";
Value

Boolean value: true | false.

Default

false

textIndent NN 6 IE 4 DOM 2
Read/Write
Specifies the size of the indent at the first line of a block of inline text (such as a p element). Only the first line is affected by this setting. A negative value can be used to outdent the first line, but be sure the text does not run beyond the left edge of the browser window or frame.

Example

document.getElementById("firstGraph").style.textIndent = "0.5em";

Value

Positive or negative CSS length value (see Chapter 11) as a string.

Default

0px

textJustify NN n/a IE 5 DOM n/a
Read/Write
Specifies detailed character distribution techniques for any block-level element that has a text-align CSS attribute or a textAlign style property set to justify.

Example

document.getElementById("inset").style.textJustify = "distribute-center-last";

Value

One of the following constants (as a string): auto | distribute | distribute-all-lines | distribute-center-last | inter-cluster | inter-ideograph | inter-word | kashdia | newspaper. See the text-justify attribute in Chapter 11 for details on the meanings of these values.

Default

auto

textKashidaSpace NN n/a IE 5.5(Win) DOM n/a
Read/Write
For Arabic text in a block-level element with a text alignment style that is set to justify, controls the ratio of kashida expansion to white space expansion.

Example

document.getElementById("inset").style.textKashidaSpace = "15%";

Value

Percentage value as a string.

Default

0%

textOverflow NN n/a IE 6(Win) DOM n/a
Read/Write
Controls whether text content that overflows a fixed box should display an ellipsis (...) at the end of the line to indicate more text is available. The element should also have its overflow style attribute or property set to hidden.

Example

document.getElementById("textBox").style.textOverflow = "ellipsis";

Value

One of the allowable constant string value: clip | ellipsis.

Default

clip

textShadow NN 6 IE 5(Mac) DOM 2
Read/Write
Controls the specifications for shadow effects on the element's text. Although this property is a member of the style object in IE 5/Mac and Netscape 6, neither the style attribute nor scripted changes to it affect the element's text display.

Value

A string consisting of one or more shadow specifications. Each shadow specification consists of space-delimited values for a color, a length for the offset to the right of the text, a length for the offset below the text, and an optional blur radius value. Multiple shadow specifications are comma-delimited or a value of none to turn off the shadow.

Default

none

textTransform NN 6 IE 4 DOM 2
Read/Write
Controls the capitalization of the element's text. When a value other than none is assigned to this attribute, the cases of all letters in the source text are arranged by the style sheet, overriding the case of the source text characters.

Example

document.getElementById("heading").style.textTransform = "capitalize";

Value

A value of none allows the case of the source text to be rendered as is. Other available constant values (as strings) are: capitalize | lowercase | uppercase. A value of capitalize sets the first character of every word to uppercase. Values lowercase and uppercase render all characters of the element text in their respective cases.

Default

none

textUnderlinePosition NN n/a IE 5.5(Win) DOM n/a
Read/Write
Controls whether an underline (i.e., an element with a text-decoration style set to underline) is rendered above or below the text.

Example

document.getElementById("heading").style.textUnderlinePosition = "above";

Value

IE 5.5 recognizes two constant values: above | below. IE 6 adds the values auto and auto-pos (which appear to do the same thing). The default value also changed between versions, from below to auto. In IE 6, the auto value underlines vertical Japanese text "above" (to the right) of the characters.

Default

none (IE 5.5); auto (IE 6).

top NN 6 IE 4 DOM 2
Read/Write
For positionable elements, defines the position of the top edge of an element's box (content plus top padding, border, and/or margin) relative to the top edge of the next outermost block content container. When the element is relative-positioned, the offset is based on the top edge of the inline location of where the element would normally appear in the content.
For calculations on this value, use parseFloat( ) on the returned value; or, in IE, retrieve the pixelTop or posTop properties, which return genuine numeric values.

Example

document.getElementById("blockD2").style.top = "40px";

Value

String consisting of a numeric value and length unit measure, a percentage, or auto.

Default

auto

unicodeBidi NN 6 IE 5 DOM 2
Read/Write
Controls the embedding of bidirectional text (such as a mixture of French and Arabic) in concert with the direction style attribute.

Example

document.getElementById("blockD2").style.unicodeBidi = "bidi-override";

Value

String constant values: bidi-override | embed | normal.

Default

normal

verticalAlign NN 6 IE 4 DOM 2
Read/Write
Specifies the vertical alignment characteristic of the element. This property operates in two spheres, depending on the selection of values you use. See the in-depth discussion of the vertical-align style sheet property in Chapter 11 for details.

Example
document.getElementById("myDIV").style.verticalAlign = "text-top";
Value

String value of an absolute measure (with units), a percentage (relative to the next outer box element), or one of the many constant values: bottom | top | baseline | middle | sub | super | text-bottom | text-top.

Default

baseline

visibility NN 6 IE 4 DOM 2
Read/Write
Specifies the state of the positioned element's visibility. Surrounding content does not close up the space left by an element that has its visibility property set to hidden.

Example

document.getElementById("myDIV").style.visibility = "hidden";

Value

One of the constant values (as a string): collapse | hidden | inherit | visible.

Default

visible

voiceFamily, volume
See azimuth.

whiteSpace NN 6 IE 5(Mac)/5.5(Win) DOM 2
Read/Write
Controls intepretation of whitespace (such as leading spaces and line breaks) from the source code.

Example

document.getElementById("myDIV").style.whiteSpace = "pre";

Value

One of the constant values (as a string): normal | nowrap | pre. Value of normal allows browsers to word-wrap lines in block elements and ignore leading spaces. Value of nowrap causes source code not to word-wrap, but still ignores leading spaces. Value of pre preserves leading spaces, extra spaces, and carriage returns in the source code. Note that IE 6 for Windows does not respond to the pre value unless the DOCTYPE element values place the browser into standards compatibility mode.

Default

normal

widows
See orphans.

width
See height.

wordBreak NN n/a IE 5(Win) DOM n/a
Read/Write
Specifies the word-break style for ideographic languages or content that mixes Latin and ideographic languages.

Example

document.getElementById("myDIV").style.wordBreak = "keep-all";

Value

One of the constant values (as a string): break-all | keep-all | normal.

Default

normal

wordSpacing NN 6 IE 4 DOM 2
Read/Write
Governs the length of space between words. IE 5 for Macintosh may exhibit overlap problems with the word-spacing of elements nested inside the one being controlled.

Example

document.getElementById("myDIV").style.wordSpacing = "1.0em";

Value

CSS length value (as a string) or the constant normal.

Default

normal

wordWrap NN n/a IE 5.5(Win) DOM n/a
Read/Write
Specifies the word-wrapping style for block-level, specifically-sized inline, or positioned elements. If a single word (i.e., without any whitespace) extends beyond the width of the element containing box, the normal behavior is to extend the content beyond the normal box width, without breaking. But you can force the long word to break at whatever character position occurs at the edge of the box.

Example

document.getElementById("myDIV").style.wordWrap = "break-word";

Value

One of the constant values (as a string): break-word | normal.

Default

normal

writingMode NN n/a IE 5.5(Win) DOM n/a
Read/Write
Intended primarily for languages that display characters in vertical sentences, this controls the progression of content, left-to-right, or right-to-left.

Example

document.getElementById("myDIV").style.writingMode = "lr-tb";

Value

One of the constant values (as a string): lr-tb | tb-rl. Value of tb-rl can rotate text of some languages by 90 degrees.

Default

lr-tb

zIndex NN 6 IE 4 DOM 2
Read/Write
For a positioned element, this specifies the stacking order relative to other elements within the same parent container. See Chapter 4 for details on relationships of element layering amid multiple containers.

Example
document.getElementById("myDIV").style.zIndex = "3"
Value

Integer. Netscape 6 prefers that this value be in string form (that's how the property returns its value), while IE returns a number.

Default

0

zoom NN n/a IE 5.5(Win) DOM n/a
Read/Write
Governs the magnification of rendered content. Particularly useful for output that might be displayed on monitors with very high pixel density. See screen.logicalXDPI property.

Example

document.body.style.zoom = "200%";

Value

Percentage value (where 100% is normal), floating-point multiplier (where 1.0 is normal), or constant normal.

Default

normal

getPropertyCSSValue( ) NN n/a IE n/a DOM 2
getPropertyCSSValue("CSSAttributeName")
Returns an object that represents a CSS value. In the W3C DOM, the CSSValue object returned from this method has properties that reveal the text of the attribute/value pair and a numeric value corresponding to a long list of primitive value types (indicating types such as percentage, pixel lengths, and RGB color). Although this method is implemented in Netscape 6, it returns an empty object for now.

Returned Value

Reference to a CSSValue object.

Parameters

CSSAttributeName

The CSS attribute name from an inline style declaration (not the DOM version of the property name).

getPropertyPriority( ) NN 6 IE 5(Mac) DOM 2
getPropertyPriority("CSSAttributeName")
Returns the string value of any priority (such as !important) associated with the inline CSS attribute.

Returned Value

String.

Parameters

CSSAttributeName

The CSS attribute name from an inline style declaration (not the DOM version of the property name).

getPropertyValue( ) NN 6 IE 5(Mac) DOM 2
getPropertyValue("CSSAttributeName")
Returns the string value of the inline CSS attribute/value pair.

Returned Value

String.

Parameters

CSSAttributeName

The CSS attribute name from an inline style declaration (not the DOM version of the property name).

item( ) NN 6 IE 5(Mac) DOM 2
item(index)
Returns the attribute name of the inline CSS attribute/value pair corresponding to the integer index value in source code order.

Returned Value

String. IE for Macintosh returns name in all-uppercase characters, while Netscape 6 returns all-lowercase characters.

Parameters

index

Zero-based integer corresponding to the specified inline CSS attribute/value pair in source code order.

removeProperty( ) NN 6 IE n/a DOM 2
removeProperty("CSSAttributeName")
Deletes the inline CSS attribute/value pair and returns a string with the previous value.

Returned Value

String.

Parameters

CSSAttributeName

The CSS attribute name from an inline style declaration (not the DOM version of the property name).

setProperty( ) NN 6 IE 5(Mac) DOM 2
setProperty("CSSAttributeName", "value", "priority")
Sets an inline style attribute/value pair. If the attribute already exists, the new value is applied to the existing attribute; otherwise the attribute and value are added to the element.

Returned Value

None.

Parameters

CSSAttributeName

The CSS attribute name from an inline style declaration (not the DOM version of the property name).

value

String of the value in the format applicable to the attribute.

priority

String of the priority assignment (such as !important) or empty string.

styleSheet NN 6 IE 4 DOM 2

The styleSheet object represents a style sheet that may have been created as a style element or imported with a link element or @import statement inside a style element. This object is different from the style element object, which strictly reflects the style HTML element and its attributes. The document.styleSheets[] collection contains zero or more styleSheet objects. The shared disabled property is available in all supporting browsers, facilitating the enabling and disabling of entire style sheets with simple Boolean assignments.

Object Model Reference

[window.]document.styleSheets[i]

Object-Specific Properties

`cssRules[]`	`cssText`	`href`	`imports[]`	`media`
`ownerNode`	`ownerRule`	`owningElement`	`pages[]`	`parentStyleSheet`
`readOnly`	`rules[]`	`title`	`type`

Object-Specific Methods

addImport( )

addRule( )

deleteRule( )

insertRule( )

removeRule( )

Object-Specific Event Handler Properties

None.

cssRules[ ] NN 6 IE 5(Mac) DOM 2
Read-only
Returns a collection of cssRule objects nested within the current styleSheet object. The IE-only equivalent is the rules property. See the cssRules object earlier in this chapter for a description of this collection object's property and methods; see the cssRule object earlier in this chapter for a description of the individual members of this collection.

Example

var allCSSRules = document.styleSheets[0].cssRules;

Value

Reference to a CSSRules collection object.

Default

Array of zero length.

cssText NN n/a IE 5 DOM n/a
Read/Write
Contains the entire text (as a string) of all rules defined in the style sheet. This is useful primarily if you wish to replace the entire set of rules with a new set. To act on the text of an individual rule in IE, access the cssText property of a single rule object (obtained by the styleSheet object's rules[i].cssText property); or, in Netscape 6, you can use the cssRules[i].cssText property.

Example

var allCSSText = document.styleSheets[0].cssText;

Value

String.

Default

Empty string.

href NN 6 IE 4 DOM 2
Read/Write
This is the URL specified by a link element's href attribute (when the link is used to import a style sheet). This value is read/write in IE for Windows, but read-only in Netscape 6 and IE/Mac.

Example

document.styleSheets[1].href = "css/altStyles.css";

Value

String of complete or relative URL.

Default

None.

imports[ ] NN n/a IE 4 DOM n/a
Read-only
Returns a collection (array) of styleSheet objects imported into an explicit styleSheet object via the @import rule. See the imports collection object earlier in this chapter for further discussion. For Netscape 6, you must loop through all cssRule objects of a styleSheet object in search of those with type property values equal to 3 (the same as the cssRule object's IMPORT_RULE constant).

Example

var allImportRules = document.styleSheets[0].imports;

Value

Reference to an imports collection object.

Default

Array of zero length.

media NN 6 IE 4 DOM 2
Read/Write
Specifies the intended output device for the content governed by the style sheet (reflecting the media attribute of the link and style elements). The media property looks forward to the day when browsers are able to tailor content to specific kinds of devices such as pocket computers, text-to-speech digitizers, or fuzzy television sets. This property is not available in IE 4/Macintosh.

Example

if (document.styleSheets[2].media == "print") { // process for print output }

Value

Any one of the following constant values as a string: all | print | screen.

Default

all

ownerNode NN 6 IE n/a DOM 2
Read-only
Returns a reference to the document tree node that contains the styleSheet object. This node is either a style or link element, depending on the way the style sheet is defined in the document. The IE (Windows and Mac) equivalent property is owningElement. IE for the Macintosh provides an extra owningNode property, which is very likely a mistaken implementation of the W3C DOM ownerNode property.

Example

var mama = document.styleSheets[2].ownerNode;

Value

Object reference.

Default

None.

ownerRule NN 6 IE n/a DOM 2
Read-only
For a styleSheet object brought into the document via an @import rule, returns a reference to that @import rule object (a W3C DOM CSSImportRule object). The cssRule object earlier in this chapter provides the properties and methods that apply to a CSSImportRule object. For other style sheet types, the property returns null.

Example

var hostRule = document.styleSheets[2].ownerRule;

Value

Object reference or null.

Default

null

owningElement NN n/a IE 4 DOM n/a
Read-only
Returns a reference to the style or link element object that defines the current styleSheet object. Each document maintains a collection of style sheets created with both the style and link elements. The comparable Netscape 6 property is ownerNode.

Example

var firstStyleID = document.styleSheets[0].owningElement.id;

Value

Element object reference.

Default

None.

pages[ ] NN n/a IE 5.5(Win) DOM n/a
Read-only
Returns a collection (array) of page objects (@page rules) nested within a styleSheet object. For Netscape 6, you must loop through all cssRule objects of a styleSheet object in search of those with type property values equal to 6 (the same as the cssRule object's PAGE_RULE constant). See the page object.

Example

var allPageRules = document.styleSheets[0].pages;

Value

Reference to a pages collection object.

Default

Array of zero length.

parentStyleSheet NN 6 IE 4 DOM 2
Read-only
For a styleSheet object generated by virtue of inclusion with an @page rule, the parentStyleSheet property returns a reference to the styleSheet (created as a link or style element) object that imported the current style sheet. For a nonimported style sheet, the property returns null.

Example

var myMaker = document.styleSheets[0].parentStyleSheet;

Value

Reference to a styleSheet object.

Default

null

readOnly NN n/a IE 4 DOM n/a
Read-only
Specifies whether the style sheet can be modified under script control. Style sheets imported through a link element or an @import rule cannot be modified, so they return a value of true.

Value

Boolean value: true | false.

Default

false

rules[ ] NN n/a IE 4 DOM n/a
Read-only
Returns a collection of rule objects nested within the current styleSheet object. The W3C DOM equivalent (implemented in Netscape 6 and IE 5/Mac) is the cssRules property. See the cssRules object earlier in this chapter for a description of this collection object's property and methods; see the cssRule object earlier in this chapter for a description of the individual members of this collection.

Example

var allrules = document.styleSheets[0].rules;

Value

Reference to a rules collection object.

Default

Array of zero length.

title NN 6 IE 4 DOM 2
Read/Write
Exposes the title attribute of the style or link element that owns the current styleSheet object. Since the attribute does not affect user interface elements (the elements are unrendered, and thus don't show tool tips), it is available to convey other string information to the styleSheet object under script control.

Example

if (document.styleSheets[2].title == "corpStyleWindows") { // process for the designated style }

Value

String value.

Default

Empty string.

type NN 6 IE 4 DOM 2
Read-only
Returns the style sheet MIME type specified by the type attribute of the style or link element.

Example

if (document.styleSheets[0].type == "text/css") { ... }

Value

String (text/css for typical CSS style sheets).

Default

None.

addImport( ) NN n/a IE 4 DOM n/a
addImport(url, [index])
Adds an external style sheet specification to a styleSheet object.

Returned Value

Integer of the index position within the styleSheets[] collection where the style sheet was added (in case you omit the second parameter and let the browser find the end position).

Parameters

url

A complete or relative URL to the style sheet (.css) file.

index

An optional integer indicating where in the collection the new element should be placed.

addRule( ) NN n/a IE 4 DOM n/a
addRule("selector", "style"[, index])
Adds a new rule for a style sheet. This method offers a scripted way of adding a rule to an existing styleSheet object:
document.styleSheets[1].addRule("p b","color:red");
You may duplicate a selector that already exists in the styleSheet and, therefore, override an existing rule for the same element selector. The only prohibition is that you may not override a rule to convert a plain style rule into one that creates a positionable element (or vice versa). The new rule is governed by the same cascading rules as all style sheet rules (that includes the rule's source code position among other rules with the same selector). Therefore, a new rule in a styleSheet object does not supersede a style set in an element's style property.

Returned Value

Early versions of IE returned no value. More recently, IE for Windows returns -1, while IE for Macintosh returns null. In the future, the returned value may become the integer of the index location of the new rule.

Parameters

selector

The style rule selector as a string.

style

One or more style attribute:value pairs. Multiple pairs are semicolon delimited, just as they are in the regular style sheet definition.

index

An optional integer indicating where in the collection the new element should be placed.

deleteRule( ) NN 6 IE 5(Mac) DOM 2
deleteRule(index)
Removes a rule from the styleSheet object. The integer index parameter value points to the zero-based item in the cssRules array to delete. Note that IE 5 for Macintosh implements both the Microsoft removeRule( ) and W3C DOM deleteRule( ) method for the same operation.

Returned Value

None.

Parameters

index

A zero-based integer indicating which rule in the cssRules collection is to be deleted.

insertRule( ) NN 6 IE 5(Mac) DOM 2
insertRule("ruleText", index)
Adds a new rule for a style sheet. This method offers a scripted way of adding a rule to an existing W3C DOM styleSheet object:
document.styleSheets[1].insertRule("p b {color:red}", 0);
You may duplicate a selector that already exists in the styleSheet and, therefore, override an existing rule for the same element selector. The only prohibition is that you may not override a rule to convert a plain style rule into one that creates a positionable element (or vice versa). The new rule is governed by the same cascading rules as all style sheet rules (that includes the rule's source code position among other rules with the same selector). Therefore, a new rule in a styleSheet object does not supersede a style set in an element's style property. Note that IE 5 for the Macintosh implements both the W3C DOM insertRule( ) and Microsoft addRule( ) methods to accomplish the same result.

Returned Value

Integer of the index location of the new rule.

Parameters

ruleText

The entire style rule selector as a string in exactly the same format as assigned in a style element: selector {attribute:value; attribute:value;...}.

index

Zero-based integer indicating where in the cssRules collection the new rule should be placed.

removeRule( ) NN n/a IE 4 DOM n/a
removeRule(index)
Removes a rule from the styleSheet object. The integer index parameter value points to the zero-based item in the rules array to delete.

Returned Value

None.

Parameters

index

A zero-based integer indicating which rule in the rules collection is to be deleted.

styleSheets, StyleSheetList NN 6 IE 4 DOM 2

A collection of styleSheet objects that are members of a document object. The W3C DOM abstract representation of this collection is called a StyleSheetList object. Members of this collection are accessed via their integer index number, but you may iterate through the collection and examine properties of each style sheet object (such as the selectorText property) to distinguish one rule from another.

Object Model Reference

document.styleSheets

Object-Specific Properties

length

Object-Specific Methods

item( )

Object-Specific Event Handler Properties

None.

length NN 6 IE 4 DOM 2
Read-only
Returns the number of elements in the collection.

Example

var howMany = document.styleSheets.length;

Value

Integer.

item( ) NN 6 IE 4 DOM 2
item(index)
Returns a styleSheet object corresponding to the object matching the index value in source code order.

Returned Value

Reference to a styleSheet object. If there are no matches to the parameters, the returned value is null.

Parameters

index

A zero-based integer corresponding to the specified item in source code order (nested within the current document object).

table NN 6 IE 4 DOM 1

The table object reflects the table element. Other objects related to the table object are: caption, col, colgroup, tbody, td, tfoot, thead, and tr.

HTML Equivalent

<table>

Object Model Reference

[window.]document.getElementById("elementID")

Object-Specific Properties

`align`	`background`	`bgColor`	`border`
`borderColor`	`borderColorDark`	`borderColorLight`	`caption`
`cellPadding`	`cells`[]	`cellSpacing`	`cols`
`dataPageSize`	`frame`	`height`	`rows[]`
`rules`	`summary`	`tbodies[]`	`tFoot`
`tHead`	`width`

Object-Specific Methods

`createCaption( )`	`createTFoot( )`	`createTHead( )`	`deleteCaption( )`
`deleteRow( )`	`deleteTFoot( )`	`deleteTHead( )`	`insertRow( )`
`lastPage( )`	`moveRow( )`	`nextPage( )`	`previousPage( )`
`refresh( )`

Object-Specific Event Handler Properties

None.

align NN 6 IE 4 DOM 1
Read/Write
Defines the horizontal alignment of the element within its surrounding container.

Example

document.getElementById("myTable").align = "center";

Value

Any of the three horizontal alignment constants: center | left | right.

Default

left

background NN n/a IE 4 DOM n/a
Read/Write
Provides the URL of the background image for the table. If you set a backgroundColor to the element as well, the color appears if the image fails to load; otherwise, the image overlays the color.

Example

document.getElementById("myTable").background = "images/watermark.jpg";

Value

Complete or relative URL to the background image file.

Default

None.

bgColor NN 6 IE 4 DOM 1
Read/Write
Specifies the background color of the element. This color setting is not reflected in the style sheet backgroundColor property. Even if the bgcolor attribute or bgColor property is set with a plain-language color name, the returned value is always a hexadecimal triplet.

Example

document.getElementById("myTable").bgColor = "yellow";

Value

A hexadecimal triplet or plain-language color name. See Appendix A for acceptable plain-language color names.

Default

Varies with browser and operating system.

border NN 6 IE 4 DOM 1
Read/Write
Specifies the thickness of the border around the table (in pixels). This is the default 3-D-look border and should not be confused with borders created with style sheets.

Example

document.getElementById("myTable").border = 4;

Value

An integer value. A setting of zero removes the border entirely.

Default

0

borderColor NN n/a IE 4 DOM n/a
Read/Write
Specifies the color of the table's border. Internet Explorer applies the color to all four lines that make up the interior border of a cell. Therefore, colors of adjacent cells do not collide.

Example

document.getElementById("myTable").borderColor = "salmon";

Value

A hexadecimal triplet or plain-language color name. A setting of empty is interpreted as "#000000" (black). See Appendix A for acceptable plain-language color names.

Default

Varies with operating system.

borderColorDark, borderColorLight NN n/a IE 4 DOM n/a
Read/Write
The 3-D effect of table borders in Internet Explorer is created by careful positioning of light and dark lines around the page's background or default color. You can independently control the colors used for the dark and light lines by assigning values to the borderColorDark (left and top edges of the cell) and borderColorLight (right and bottom edges) properties.
Typically, you should assign complementary colors to the pair of properties. There is also no rule that says you must assign a dark color to borderColorDark. The attributes merely control a well-defined set of lines so you can predict which lines of the border change with each attribute.

Example

document.getElementById("myTable").borderColorDark = "blue"; document.getElementById("myTable").borderColorLight = "cornflowerblue";

Value

A hexadecimal triplet or plain-language color name. A setting of empty is interpreted as "#000000" (black). See Appendix A for acceptable plain-language color names.

Default

Varies with operating system.

caption NN 6 IE 4(Win)/5(Mac) DOM 1
Read-only
Returns a reference to a caption element nested inside the table. From this reference you can access properties and methods of the caption object. In Netscape 6, you can create a new caption element, and assign that new element's reference to the caption property of a table, making the property read/write in that browser (although you really should be using the createCaption( ) method). For all browsers, however, you can modify properties of the caption object returned by the caption property.

Example

var capText = document.getElementById("myTable").caption.innerHTML;

Value

Object reference.

Default

None.

cellPadding NN 6 IE 4 DOM 1
Read/Write
Specifies the amount of empty space between the (visible or invisible) border of a table cell and the content of the cell. Note that this property applies to space inside a cell. Minor adjustments to this property are not as noticeable when the table does not also display borders (in which case the cellSpacing property can assist in adjusting the space between cells).

Example

document.getElementById("myTable").cellPadding = "15";

Value

A string value for a length in pixels or percentage.

Default

0

cells NN n/a IE 5(Win) DOM n/a
Read-only
Returns a collection of all td elements inside the table. Entries in the array are in source code order of td elements. This property is more widely available for a tr element (one row at a time).

Example

var totCells = document.getElementById("myTable").cells.length;

Value

Reference to a cells collection object.

Default

Array of zero length.

cellSpacing NN 6 IE 4 DOM 1
Read/Write
Specifies the amount of empty space between the outer edges of each table cell. If the table has a border, the effect of setting cellSpacing is to define the thickness of borders rendered between cells. Even without a visible border, the readability of a table often benefits from cell spacing, or a combination of cell spacing and cell padding.

Example

document.getElementById("myTable").cellSpacing = "5";

Value

A string value for a length in pixels or percentage.

Default

0 (with no table border); 2 (with table border).

cols NN n/a IE 4 DOM 1
Read/Write
Specifies the number of columns of the table. The corresponding IE-specific cols attribute assists the browser in preparation for rendering the table. Without this attribute, the browser relies on its interpretation of all downloaded tr and td elements to determine how the table is to be divided. You cannot change the column makeup of a table from this property, despite its read/write status. See also the col object earlier in this chapter

Example

document.getElementById("myTable").cols = 5;

Value

Integer.

Default

None.

dataPageSize NN n/a IE 4 DOM n/a
Read/Write
Used with IE data binding, this property advises the browser how many instances of a table row must be rendered to accommodate the number of data source records set by this attribute. See lastPage( ), nextPage( ), and previousPage( ) methods for navigating through groups of records.

Example

document.getElementById("inventoryTable").dataPageSize = 10;

Value

Integer.

Default

None.

frame NN 6 IE 4 DOM 1
Read/Write
Indicates which (if any) sides of a table's outer border (set with the border attribute or border property) are rendered. This property does not affect the interior borders between cells.

Example

document.getElementById("orderForm").frame = "hsides";

Value

Any one case-insensitive frame constant (as a string):

above

Renders border along top edge of table only

below

Renders border along bottom edge of table only

border

Renders all four sides of the border (same as box)

box

Renders all four sides of the border (same as border)

hsides

Renders borders on top and bottom edges of table only (a nice look)

lhs

Renders border on left edge of table only

rhs

Renders border on right edge of table only

void

Hides all borders (default in HTML 4)

vsides

Renders borders on left and right edges of table only

Default

void (when border=0); border (when border is any other value)

height, width NN 6 (width only) IE 4 DOM 1 (width only)
Read/Write
Specify the height and width in pixels of the element. Changes to these values are immediately reflected in reflowed content on the page. Only the width property is available in Netscape 6 (and the W3C DOM), as the table's height is considered to be the sum of the highest cell in each row.

Example

document.getElementById("myTable").height = 250;

Value

Integer.

Default

None.

rows NN 6 IE 4 DOM 1
Read-only
Returns a collection of tr elements inside the entire table. You can also get a group of rows for each table section (tbody, tfoot, and thead element objects).

Example

var allTableRows = document.getElementById("myTable").rows;

Value

Reference to a rows collection object.

Default

Array of zero length.

rules NN 6 IE 4 DOM 1
Read/Write
Indicates where (if at all) interior borders between cells are rendered by the browser. In addition to setting the table to draw borders to turn the cells into a matrix, you can set borders to be drawn only to separate borders, columns, or any sanctioned cell grouping (thead, tbody, tfoot, colgroup, or col). The border attribute must be present—either as a Boolean or set to a specific border size—for any cell borders to be drawn. Do not confuse this property with the rules[] collection of styleSheet objects. Scripted changes to this property do not always yield the desired results, especially in early versions of Netscape 6.

Example

document.getElementById("myTable").rules = "groups";

Value

Any one case-insensitive rules constant (as a string):

all

Renders borders around each cell

cols

Renders borders between columns only

groups

Renders borders between cell groups as defined by thead, tfoot, tbody, colgroup, or col elements

none

Hides all interior borders

rows

Renders borders between rows only

Default

none (when border=0); all (when border is any other value).

summary NN 6 IE 6 DOM 1
Read-only
Reflects the HTML 4 summary attribute, which provides no particular functionality in mainstream browsers. But you can assign a value to it in the source code to convey data to a script that reads the property.

Example

var data = document.getElementById("myTable").summary;

Value

String.

Default

Empty string.

tBodies[ ] NN 6 IE 4(Win)/5(Mac) DOM 1
Read-only
Returns a collection of tBody objects in the current table. Every table element has at least one (explicit or implied) tBody object nested inside.

Example

var bodSections = document.getElementById("myTable").tBodies;

Value

Reference to a collection of tBody objects.

Default

Array of length one.

tFoot NN 6 IE 4(Win)/5(Mac) DOM 1
Read-only
Returns a reference to the tfoot element object if one has been defined for the table. If no tfoot element exists, the value is null. You can access tfoot element object properties and methods through this reference if you like. This property is available only on the Win32 version of Internet Explorer 4.

Example

var tableFootTxt = document.getElementById("myTable").tFoot.firstChild.nodeValue;

Value

tfoot element object reference.

Default

null

tHead NN 6 IE 4(Win)/5(Mac) DOM 1
Read-only
Returns a reference to the thead element object if one has been defined for the table. If no thead element exists, the value is null. You can access thead element object properties and methods through this reference if you like. This property is available only on the Win32 version of Internet Explorer 4.

Example

var tableHeadTxt = document.getElementById("myTable").tHead.firstChild.nodevalue;

Value

thead element object reference.

Default

null

width
See height.

createCaption( ), deleteCaption( ) NN 6 IE 4 DOM 1
Add or remove a caption element nested within the current table element. If no caption exists, the creation method produces an empty element, which your scripts must then populate with caption text (through common element content modification techniques). If a caption exists, the method is essentially ignored, and returns a reference to the existing caption element.

Returned Value

Reference to new caption element (for createCaption( )); nothing for deleteCaption( ).

Parameters

None.

createTFoot( ), createTHead( ), deleteTFoot( ), deleteTHead( ) NN 6 IE 4 DOM 1
Add or remove a thead or tfoot element nested within the current table element. If no head or foot table section exists, the creation method produces an empty element, which your scripts must then populate with rows (through thead.insertRow( ) and tfoot.insertRow( ) methods). If the desired table section exists, the method is essentially ignored, and returns a reference to the existing thead or tfoot element.

Returned Value

Reference to newly created element (for createTFoot( ) and createTHead( )); Nothing for deleteTHead( ) and deleteTFoot( ).

Parameters

None.

deleteRow( ) NN 6 IE 4 DOM 1
deleteRow(index)
Removes a tr element nested within the current table element. The integer parameter points to the zero-based item in the rows collection. To repopulate a table with new or sorted content, empty the table (or just a table section) with iterative calls to the deleteRow( ) method:
while (tableReference.rows.length > 0) { tableReference.deleteRow(0); }

Returned Value

None.

Parameters

index

Zero-based integer corresponding to the said numbered tr element in source code order (nested within the current element).

insertRow( ) NN 6 IE 4(Win) DOM 1
insertRow(index)
Inserts a tr element nested within the current table element. The integer parameter points to the zero-based index in the rows collection where the new row should go, but in IE you can also use the shortcut value of -1 to append the row to the end of the collection. Adding the row inserts an empty element, to which you add cells via the insertCell( ) method. Unfortunately, scripting the addition of table rows and cells in IE for the Macintosh (including Version 5.1) is very broken, yielding elephantine row and cell dimensions. For nonnested tables, you might be able to get away with regular document tree node creation and insertion instead of the table (and related) object convenience methods.

Returned Value

Reference to the newly inserted row.

Parameters

index

Zero-based integer corresponding to a row of the rows collection before which the new row is to be inserted.

lastPage( ), nextPage( ), previousPage( ) NN n/a IE 4/5 DOM n/a
Advises the data binding facilities to load the last, next, or previous group of records from the data source to fill the number of records established with the dataPageSize property. The lastPage( ) method is available in IE 5 or later.

Returned Value

None.

Parameters

None.

moveRow( ) NN n/a IE 5(Win) DOM n/a
moveRow(indexToMove, destinationIndex)
Moves a row in the table from its original location to a different row position. The first parameter is a zero-based index of the row (within the rows collection) you wish to move. The second parameter is the index of the row before which you want to move the row. As a method of the table object, moveRow( )'s index parameters include the first row, which may contain th elements you don't want to move. Invoke the method on the tbody object if you want counting to be just within a table section.

Returned Value

Reference to the moved row.

Parameters

indexToMove

A zero-based integer pointing to the row to move.

destinationIndex

A zero-based integer pointing to the row above which the row is to be moved.

refresh( ) NN n/a IE 4 DOM n/a
Advises the data binding facilities to reload the current page of data from the data source. If your table is retrieving frequently-changing data from a database, you can create a setTimeout( ) loop to invoke document.getElementById("myTable").refresh( ) as often as users would want updated information from the database.

Returned Value

None.

Parameters

None.

tags NN |4| IE n/a DOM n/a

The tags object is used by JavaScript syntax for style sheets in Navigator 4 only. As a property of the document object, this tags object is used in building references to particular HTML elements to get or set their style-related properties. The direct properties of the tags object are all HTML element types. For example:

[document.]tags.p
[document.]tags.h1

There is no need to repeat a list of all HTML elements as properties for this object. These references are usable inside style elements with a type set to text/javascript. That's where you assign values to style sheet properties with JavaScript syntax, as in the following examples:

tags.p.color = "green";
tags.h1.fontSize = "14pt";

The properties in the following list are not properties of the tags object per se, but rather of the style sheet associated with an element, class, or ID singled out by a JavaScript syntax assignment statement. The properties are listed here for convenience (and historical completeness). Properties dedicated to element positioning are listed separately from regular style properties. For information about these property values, consult the CSS reference chapter, where you can find details of all style sheet properties listed by CSS syntax.

Style Object-Specific Properties

`backgroundColor`	`backgroundImage`	`borderBottomWidth`	`borderColor`
`borderLeftWidth`	`borderRightWidth`	`borderStyle`	`borderTopWidth`
`borderWidths( )`	`color`	`display`	`fontFamily`
`fontSize`	`fontStyle`	`fontWeight`	`listStyleType`
`marginBottom`	`marginLeft`	`marginRight`	`margins( )`
`marginTop`	`paddingBottom`	`paddingLeft`	`paddingRight`
`paddings`	`paddingTop`	`textAlign`	`textDecoration`
`textTransform`	`verticalAlign`	`whiteSpace`

Position Object-Specific Properties

`background`	`bgColor`	`clip`	`left`
`top`	`visibility`	`zIndex`

tBodies NN 6 IE 4 DOM 1

This is a collection of all tbody elements contained within a single table element. Collection members are sorted in source code order.

Object Model Reference

document.getElementById("tableID").tBodies

Object-Specific Properties

length

Object-Specific Methods

item( )

namedItem( )

tags( )

urns( )

Object-Specific Event Handler Properties

None.

length NN 6 IE 4 DOM 1
Read-only
Returns the number of elements in the collection.

Example

var howMany = document.getElementById("myTable").tBodies.length;

Value

Integer.

item( ) NN 6 IE 4 DOM 1
item(index[, subindex]) item(index)
Returns a single tBody object or collection of tBody objects corresponding to the element matching the index value (or, optionally in IE, the index and subindex values).

Returned Value

One tBody object or collection (array) of tBody objects. If there are no matches to the parameters, the returned value is null.

Parameters

index

When the parameter is a zero-based integer, the returned value is a single element corresponding to the specified item in source code order (nested within the current element); when the parameter is a string (IE only), the returned value is a collection of elements with id properties that match that string.

subindex

In IE only, if you specify a string value for the first parameter, you can use the second parameter to specify a zero-based index that retrieves the specified element from the collection with id properties that match the first parameter's string value.

namedItem( ) NN 6 IE 6 DOM 1
namedItem("ID")
Returns a single tBody object or collection of tBody objects corresponding to the element matching the parameter string value.

Returned Value

One tBody object or collection (array) of tBody objects. If there are no matches to the parameters, the returned value is null.

Parameters

ID

The string that contains the same value as the desired element's id attribute.

tags( ) NN n/a IE 4 DOM n/a
tags("tagName")
Returns a collection of objects (among all objects nested within the current collection) whose tags match the tagName parameter.

urns( ) NN n/a IE 5(Win) DOM n/a
urns(URN)
See the all.urns( ) method.

tbody, tfoot, thead NN 6 IE 4 DOM 1

The tbody, tfoot, and thead objects reflect the tbody, tfoot, and thead elements, respectively. For scripting purposes, you can treat each of these as a container of row groups inside a table. They all share the same properties and methods, so you need to keep their HTML functionality straight as you script these elements. A table can have only one tfoot and one thead element, but multiple tbody elements. Also, by default, Internet Explorer 4 or later and Netscape 6 create a tbody object for every table even if you don't include one in your table's source code. This default tbody element encompasses all rows of the table (except those you have wrapped inside thead or tfoot elements, if any). Although these objects are implemented in IE 4 for the Macintosh, they are incomplete. Moreover, the row insertion operations noted in the table element are just as strange for these objects under IE 4 for the Mac.

HTML Equivalent

<tbody>
<tfoot>
<thead>

Object Model Reference

[window.]document.getElementById("elementID")
[window.]document.getElementById("tableID").tBodies[i]
[window.]document.getElementById("tableID").tfoot
[window.]document.getElementById("tableID").thead

Object-Specific Properties

align

bgColor

ch

chOff

rows

vAlign

Object-Specific Methods

deleteRow( )

insertRow( )

moveRow( )

Object-Specific Event Handler Properties

None.

align NN 6 IE 4 DOM 1
Read/Write
Defines the horizontal alignment of content within all cells contained by the tbody element.

Example

document.getElementById("myTbody").align = "center";

Value

One of the three horizontal alignment string constants: center | left | right.

Default

left

bgColor NN 6 IE 4 DOM n/a
Read/Write
Specifies the background color of the cells contained by the tbody, tfoot, or thead element. This color setting is not reflected in the style sheet backgroundColor property. Even if the bgcolor attribute or bgColor property is set with a plain-language color name, the returned value is always a hexadecimal triplet.

Example

document.getElementById("myTable").tHead.bgColor = "yellow";

Value

A hexadecimal triplet or plain-language color name. See Appendix A for acceptable plain-language color names.

Default

Varies with browser and operating system.

ch NN 6 IE 5(Mac)/6(Win) DOM 1
Read/Write
Defines the text character used as an alignment point for text within a column or column group (reflecting the char attribute). This property is normally of value only for the align attribute set to "char". In practice, neither IE nor Navigator responds to these properties.

Example

document.getElementById("myTBody").ch = ".";

Value

Single character string.

Default

None.

chOff NN 6 IE 5(Mac)/6(Win) DOM 1
Read/Write
Defines the offset point at which the character specified by the char attribute is to appear within a cell. In practice, neither IE nor Navigator responds to these properties.

Example

document.getElementById("myTBody").chOff = "80%";

Value

String value of the number of pixels or percentage (within the cell).

Default

None.

rows NN 6 IE 4 DOM 1
Read-only
Returns a collection of tr elements inside the table section. You can also get a group of rows for an entire table in IE for Windows.

Example

var allTableRows = document.getElementById("myTFoot").rows;

Value

Reference to a rows collection object.

Default

Array of zero length.

vAlign NN 6 IE 4 DOM 1
Read/Write
Specifies the manner of vertical alignment of text within the cells contained by the tbody, tfoot, or thead element.

Example

document.getElementById("myTbody").vAlign = "baseline";

Value

Case-insensitive constant (as a string): baseline | bottom | middle | top.

Default

middle

deleteRow( ) NN 6 IE 4 DOM 1
deleteRow(index)
Removes a tr element nested within the current tbody, tfoot, or thead element. The integer parameter points to the zero-based item in the section's rows collection. To repopulate a table section with new or sorted content, empty the section with iterative calls to the deleteRow( ) method:
while (tBodyReference.rows.length > 0) { tBodyReference.deleteRow(0); }

Returned Value

None.

Parameters

index

Zero-based integer corresponding to the said numbered tr element in source code order (nested within the current element).

insertRow( ) NN 6 IE 4(Win) DOM 1
insertRow(index)
Inserts a tr element nested within the current tbody, tfoot, or thead element. The integer parameter points to the zero-based index in the rows collection where the new row should go, but in IE you can also use the shortcut value of -1 to append the row to the end of the collection. Adding the row inserts an empty element, to which you add cells via the insertCell( ) method. Unfortunately, scripting the addition of table rows and cells in IE for the Macintosh (including Version 5.1) is very broken, yielding elephantine row and cell dimensions. For nonnested tables, you might be able to get away with regular document tree node creation and insertion instead of the table section object convenience methods.

Returned Value

Reference to the newly inserted row.

Parameters

index

Zero-based integer corresponding to a row of the rows collection before which the new row is to be inserted.

moveRow( ) NN n/a IE 5(Win) DOM n/a
moveRow(indexToMove, destinationIndex)
Moves a row in the tbody, tfoot, or thead element from its original location to a different row position within the same section. The first parameter is a zero-based index of the row (within the rows collection) you wish to move. The second parameter is the index of the row before which you want to move the row.

Returned Value

Reference to the moved row.

Parameters

indexToMove

A zero-based integer pointing to the row to move.

destinationIndex

A zero-based integer pointing to the row above which the row is to be moved.

td, th NN 6 IE 4 DOM 1

The td and th objects reflect the td and th elements. From an HTML structure viewpoint, the two elements have different purposes within a table; but from a scripting perspective, the elements share the same properties and methods. A cell is a cell.

While a table cell element may inherit a number of visual properties from containers (e.g., a td element appearing to pick up the bgColor of a tbody or tr element), those inherited property values are not automatically assigned to the td object. Therefore, just because a cell may have a yellow background color doesn't mean its bgColor property is set at all. Due to incomplete implementation, IE 4 for the Macintosh does not offer complete scripted access to these element objects.

HTML Equivalent

<td>
<th>

Object Model Reference

[window.]document.getElementById("elementID")
[window.]document.getElementById("tableRowID").cells[i]

Object-Specific Properties

`abbr`	`align`	`axis`	`background`
`bgColor`	`borderColor`	`borderColorDark`	`borderColorLight`
`cellIndex`	`ch`	`chOff`	`colSpan`
`headers`	`height`	`noWrap`	`rowSpan`
`scope`	`vAlign`	`width`

Object-Specific Methods

None.

Object-Specific Event Handler Properties

None.

abbr NN 6 IE 5(Mac)/6(Win) DOM 1
Read/Write
Reflects the abbr attribute (cell description for speech), for which mainstream browsers have no functionality at this time.

Value

String.

Default

Empty string.

align NN 6 IE 4 DOM 1
Read/Write
Defines the horizontal alignment of content within the cell.

Example

document.getElementById("myTD").align = "center";

Value

Any of the three horizontal alignment constants: center | left | right.

Default

left

axis NN 6 IE 5(Mac)/6(Win) DOM 1
Read/Write
Reflects the axis attribute (cell category description for speech), for which mainstream browsers have no functionality at this time.

Value

String.

Default

Empty string.

background NN n/a IE 4 DOM n/a
Read/Write
Specifies the URL of the background image for the cell. If you set a bgColor to the element as well, the color appears if the image fails to load; otherwise, the image overlays the color.

Example

document.getElementById("myTD").background = "images/watermark.jpg";

Value

Complete or relative URL to the background image file.

Default

None.

bgColor NN 6 IE 4 DOM 1
Read/Write
Provides the background color of the table cell. This color setting is not reflected in the style sheet backgroundColor property. Even if the bgcolor attribute or bgColor property is set with a plain-language color name, the returned value is always a hexadecimal triplet.

Example

document.getElementById("myTD").bgColor = "yellow";

Value

A hexadecimal triplet or plain-language color name. See Appendix A for acceptable plain-language color names.

Default

Varies with browser and operating system.

borderColor NN n/a IE 4 DOM n/a
Read/Write
Provides the color of the element's border. Internet Explorer applies the color to all four lines that make up the interior border of a cell. Therefore, colors of adjacent cells do not collide.

Example

document.getElementById("myTD").borderColor = "salmon";

Value

A hexadecimal triplet or plain-language color name. A setting of empty is interpreted as "#000000" (black). See Appendix A for acceptable plain-language color names.

Default

Varies with operating system.

borderColorDark, borderColorLight NN n/a IE 4 DOM n/a
Read/Write
The 3-D effect of table borders in Internet Explorer is created by careful positioning of light and dark lines around the page's background or default color. You can independently control the colors used for the dark and light lines by assigning values to the borderColorDark (left and top edges of the cell) and borderColorLight (right and bottom edges) properties.
Typically, you should assign complementary colors to the pair of properties. There is also no rule that says you must assign a dark color to borderColorDark. The attributes merely control a well-defined set of lines so you can predict which lines of the border change with each attribute.

Example

document.getElementById("myTD").borderColorDark = "blue"; document.getElementById("myTD").borderColorLight = "cornflowerblue";

Value

A hexadecimal triplet or plain-language color name. A setting of empty is interpreted as "#000000" (black). See Appendix A for acceptable plain-language color names.

Default

Varies with operating system.

cellIndex NN 6 IE 4 DOM 1
Read-only
Returns a zero-based integer representing the position of the current cell among all other td elements in the same row. The count is based on the source code order of the td elements within a tr element. This property is not available in the Macintosh version of Internet Explorer 4.

Example

var whichCell = document.getElementById("myTD").cellIndex;

Value

Integer.

Default

None.

ch NN 6 IE 5(Mac)/6(Win) DOM 1
Read/Write
Defines the text character used as an alignment point for text within a cell. This property is normally of value only for the align attribute set to "char". In practice, neither IE nor Navigator responds to these properties.

Example

document.getElementById("myTD").ch = ".";

Value

Single character string.

Default

None.

chOff NN 6 IE 5(Mac)/6(Win) DOM 1
Read/Write
Defines the offset point at which the character specified by the char attribute is to appear within a cell. In practice, neither IE nor Navigator responds to these properties.

Example

document.getElementById("myTD").chOff = "80%";

Value

String value of the number of pixels or percentage (within the cell).

Default

None.

colSpan NN 6 IE 4 DOM 1
Read/Write
Specifies the number of columns across which the current table cell should extend itself. For each additional column included in the colSpan count, one less td element is required for the table row. If you set the align property to center or right, the alignment is calculated on the full width of the td element across the specified number of columns. Unless the current cell also specifies a rowspan attribute, the next table row returns to the original column count.

Example

document.getElementById("myTD").colSpan = 2;

Value

Integer, usually 2 or larger.

Default

1

headers NN 6 IE 5(Mac)/6(Win) DOM 1
Read/Write
Points to the ID of a table cell element designated as a column header for the current cell. In practice, no mainstream browsers provide functionality for this property.

Value

String ID value.

Default

None.

height, width NN 6 IE 4 DOM 1
Read/Write
Specify the height and width of the element. Changes to these values are immediately reflected in reflowed content on the page. These properties are read-only in the Macintosh version of Internet Explorer 4.

Example

document.getElementById("myTD").height = "250";

Value

Pixel integer count (as a string) or a percentage.

Default

None.

noWrap NN 6 IE 4 DOM 1
Read/Write
Indicates whether the browser should render the cell as wide as is necessary to display a line of nonbreaking text on one line. Abuse of this attribute can force the user into a great deal of inconvenient horizontal scrolling of the page to view all of the content.

Example

document.getElementById("myTD").noWrap = "true";

Value

Boolean value: true | false.

Default

false

rowSpan NN 6 IE 4 DOM 1
Read/Write
Specifies the number of rows through which the current table cell should extend itself downward. For each additional row included in the rowSpan count, one less td element is required for the next table row. If you set the vAlign property to middle, the alignment is calculated on the full height of the td element across the specified number of rows.

Example

document.getElementById("myTD").rowSpan = 12;

Value

Integer, usually 2 or larger.

Default

1

scope NN 6 IE 5(Mac)/6(Win) DOM 1
Read/Write
Reflects the scope attribute of table cell elements. In practice, no mainstream browsers provide functionality for this property.

Value

One of the recognized string constants: cols | colgroup | rows | rowgroup.

Default

None.

vAlign NN 6 IE 4 DOM 1
Read/Write
Specifies the manner of vertical alignment of text within the element's content box.

Example

document.getElementById("myTD").vAlign = "baseline";

Value

Case-insensitive constant (as a string): baseline | bottom | middle | top.

Default

middle

width
See height.

Text, TextNode NN 6 IE 5 DOM 1

A Text object is what this book calls in many places a "text node." Microsoft refers to this object as a TextNode object. This object represents the child object containing the characters that go between start and end tags of an element. The Text object exists in the abstract W3C DOM model by virtue of an inheritance chain between it and the fundamental Node object (Node to CharacterData to Text). The Node object ancestry automatically equips the Text object with a long list of properties and methods described among the shared items at the start of this chapter (the properties include: attributes, childNodes, firstChild, lastChild, localName, namespaceURI, nextSibling, nodeName, nodeType, nodeValue, ownerDocument, parentNode, prefix, previousSibling; the methods are: appendChild( ), cloneNode( ), hasAttributes( ), hasChildNodes( ), insertBefore( ), isSupported( ), normalize( ), removeChild( ), replaceChild( )). Along this inheritance chain, the Text object gains some additional properties and methods (described below) that let us manipulate the node's content within the constructs dictated by the formal W3C DOM model. Because the DOM is scripting language-independent, you find properties and methods that may be more easily or more powerfully manipulated through JavaScript string handling (see Chapter 12). Feel free to use those techniques in a client-side JavaScript environment of the browser.

Scripts refer to the Text node (or IE TextNode object) only through references that locate the node in the document tree (such as the first child of a particular element node) or as returned by the document.createTextNode( ) method.

Object Model Reference

elementReference.childReference
textNodeReference.siblingReference

Object-Specific Properties

data

length

Object-Specific Methods

`appendData( )`	`deleteData( )`	`insertData( )`	`replaceData( )`
`splitText( )`	`substringData( )`

Object-Specific Event Handler Properties

None.

data NN 6 IE 5 DOM 1
Read/Write
Contains the string of characters in the text node. The value is the same as the nodeValue property value, and there is no reason to favor one property over the other, except perhaps for plain-language syntactic preferences for reading the code.

Example

document.getElementById("myP").firstSibling.data = "Some new text.";

Value

String.

Default

Empty string.

length NN 6 IE 5 DOM 1
Read-only
Provides a count of characters in the text node.

Example

var howMany = document.getElementById("myP").firstSibling.length;

Value

Integer.

Default

0

appendData( ) NN 6 IE 5(Mac)/6(Win) DOM 1
appendData("newText")
Adds characters (passed as a string parameter) to the end of the current text node. The content consists of raw characters, so if you intend to add a sentence to a text node, your scripts are responsible for sentence spacing.

Returned Value

None.

Parameters

newText

String value of text to be appended. A reference that evaluates to a string (such as the data property of another text node in the document) copies the referenced value to the append location.

deleteData( ) NN 6 IE 5(Mac)/6(Win) DOM 1
deleteData(startOffset, count)
Removes characters from the current text node starting with the character in (zero-based) position signified by startOffset, and for a length of count characters in the normal text direction of the current language. If the length specified for deletion goes beyond the length of the data, all characters to the end of the text node are deleted without throwing an exception. Note that Netscape 6 includes source code white space in its counts for both parameters.

Returned Value

None.

Parameters

startOffset

Positive integer specifying the zero-based starting character point for the deletion.

count

Positive integer specifying the number of characters to be deleted.

insertData( ) NN 6 IE 5(Mac)/6(Win) DOM 1
insertData(startOffset, "newText")
Inserts text into a zero-based character position in the text node.

Returned Value

None.

Parameters

startOffset

Positive integer specifying the zero-based character before which the new text is to be inserted.

newText

String value of text to be inserted. A reference that evaluates to a string (such as the data property of another text node in the document) copies the referenced value to the append location.

replaceData( ) NN 6 IE 5(Mac)/6(Win) DOM 1
replaceData(startOffset, count, "newText")
Replaces text in the current text node with new text. The original content to be removed is signified by the zero-based start position and the number of characters. The string passed as a third parameter goes into the space vacated by the removed text. A bug in IE 5 for Macintosh crops the new text to the length of the removed text.

Returned Value

None.

Parameters

startOffset

Positive integer specifying the zero-based starting character point for the deletion.

count

Positive integer specifying the number of characters to be deleted.

newText

String value of text to be inserted where the remaining text collapses. A reference that evaluates to a string (such as the data property of another text node in the document) copies the referenced value to the append location.

splitText( ) NN 6 IE 5(Mac)/6(Win) DOM 1
splitText(offset)
Divides the current text node into two sibling text nodes; otherwise, doesn't disturb the text.

Returned Value

Reference to the second text node.

Parameters

offset

Positive integer specifying the zero-based character point before which the split occurs.

substringData( ) NN 6 IE 5(Mac)/6(Win) DOM 1
substringData(startOffset, count)
Returns a copy of the designated segment of the text node content. The section to be copied is signified by the zero-based start position and the number of characters

Returned Value

String.

Parameters

startOffset

Positive integer specifying the zero-based starting character point for the copy action.

count

Positive integer specifying the number of characters to be copied.

textarea NN 2 IE 3 DOM 1

The textarea object reflects the textarea element and is used as a form control. This object is the primary way of getting a user to enter multiple lines of text for submission to the server. Note that the innerHTML property is not available on the Macintosh version of Internet Explorer 4. Only a limited number of properties and methods shown below are available in early browsers that do not support addressing all HTML elements (prior to IE 4 and Netscape 6). IE 5 and later support the shared doScroll( ) method for this object.

HTML Equivalent

<textarea>

Object Model Reference

[window.]document.formName.elementName
[window.]document.forms[i].elements[j]
[window.]document.getElementById("elementID")

Object-Specific Properties

`cols`	`dataFld`	`dataSrc`	`defaultValue`	`form`
`name`	`readOnly`	`rows`	`status`	`type`
`value`	`wrap`

Object-Specific Methods

createTextRange( )

handleEvent( )

select( )

Object-Specific Event Handler Properties

Handler	NN	IE	DOM
`onblur`	2	3	n/a
`onchange`	2	3	n/a
`onfocus`	2	3	n/a
`onkeydown`	4	4	n/a
`onkeypress`	4	4	n/a
`onkeyup`	4	4	n/a
`onscroll`	n/a	4	n/a
`onselect`	2	3	n/a

cols NN 6 IE 4 DOM 1
Read/Write
Specifies the width of the editable space of the textarea element. The value represents the number of monofont characters that are to be displayed within the width. When the font size can be influenced by style sheets, the actual width changes accordingly.

Example

document.forms[0].comments.cols = 60;

Value

Integer.

Default

Varies with browser and operating system.

dataFld NN n/a IE 4 DOM n/a
Read/Write
Used with IE data binding to associate a remote data source column name to a textarea object's value property. A datasrc attribute must also be set for the element. Setting both the dataFld and dataSrc properties to empty strings breaks the binding between element and data source. Works only with text file data sources in IE 5/Mac.

Example

document.myForm.myTextArea.dataFld = "description";

Value

Case-sensitive identifier of the data source column.

Default

None.

dataSrc NN n/a IE 4 DOM n/a
Read/Write
Used with IE data binding to specify the ID of the page's object element that loads the data source object for remote data access. Content from the data source is specified via the datafld attribute. Setting both the dataFld and dataSrc properties to empty strings breaks the binding between element and data source. Works only with text file data sources in IE 5/Mac.

Example

document.myForm.myTextArea.dataSrc = "DBSRC3";

Value

Case-sensitive identifier of the data source.

Default

None.

defaultValue NN 2 IE 3 DOM 1
Read-only
Specifies the default text for the textarea element, as established by the text between the start and end tags in the page's source code.

Example

var txtAObj = document.forms[0].myTextArea; if (txtAObj.value != txtAObj.defaultValue ) { ... }

Value

Any string value.

Default

None.

form NN 2 IE 3 DOM 1a
Read-only
Returns a reference to the form element that contains the current element. When processing an event from this element, the event handler function automatically has access to the select element (as the event object's target or srcElement property). By reading the form property, the script can easily access other controls within the same form.

Example

var theForm = evt.srcElement.form;

Value

form element object reference.

Default

None.

name NN 2 IE 3 DOM 1
Read/Write
This is the identifier associated with the form control. The value of this property is submitted as one-half of the name/value pair when the form is submitted to the server. Names are hidden from user view, since control labels are assigned via other means, depending on the control type. Form control names may also be used by script references to the objects. Despite the modern standards' preference for the id attribute, many browsers still require that a control be assigned a name attribute to allow the control's value to be submitted.

Example

document.orderForm.myTextArea.name = "customerComment";

Value

Case-sensitive identifier that follows the rules of identifier naming: it may contain no whitespace, cannot begin with a numeral, and should avoid punctuation except for the underscore character.

Default

None.

readOnly NN 6 IE 4 DOM 1
Read/Write
Indicates whether the form element can be edited on the page by the user. A form control that has its readOnly property set to true may still be modified by scripts, even though the user may not alter the content.

Example

document.forms[0].myTextArea.readOnly = "true";

Value

Boolean value: true | false.

Default

false

rows NN 6 IE 4 DOM 1
Read/Write
Specifies the height of the textarea element based on the number of lines of text that are to be displayed without scrolling. The value represents the number of monofont character lines that are to be displayed within the height before the scrollbar becomes active. When the font size can be influenced by style sheets, the actual height changes accordingly.

Example

document.forms[0].comments.rows = 6;

Value

Integer.

Default

2 (IE/Windows); 1 (IE/Macintosh); -1 (Netscape 6, meaning that the attribute or property hasn't been set).

status NN n/a IE 4 DOM n/a
Read/Write
This is implemented in IE, but has no function for the textarea object.

Value

Boolean value: true | false; or null.

Default

null

type NN 3 IE 4 DOM 1
Read-only
Returns the type of form control element. The value is returned in all lowercase letters. It may be necessary to cycle through all form elements in search of specific types to do some processing on (e.g., emptying all form controls of type "textarea" while leaving other controls untouched).

Example

if (document.forms[0].elements[3].type == "textarea") { ... }

Value

Any of the following constants (as a string): button | checkbox | file | hidden | image | password | radio | reset | select-multiple | select-one | submit | text | textarea.

Default

textarea

value NN 2 IE 3 DOM 1
Read/Write
Specifies the current value associated with the form control that is submitted with the name/value pair for the element. All values are strings.

Example

var comment = document.forms[0].myTextArea.value;

Value

String.

Default

None.

wrap NN n/a IE 4 DOM n/a
Read/Write
Indicates whether the browser should wrap text in a textarea element and whether wrapped text should be submitted to the server with soft returns converted to hard carriage returns. A value of hard engages word-wrapping and converts soft returns to CR-LF characters in the value submitted to the server. A value of soft turns on word-wrapping, but does not include the CR-LF characters in the text submitted with the form. A value of off turns word-wrapping off.

Example

document.forms[0].comments.wrap = "soft";

Value

One of the constant values (as a string): hard | off | soft.

Default

soft

createTextRange( ) NN n/a IE 4(Win) DOM n/a
Creates a TextRange object from the content of the textarea object. See the TextRange object for details.

Returned Value

TextRange object.

handleEvent( ) NN |4| IE n/a DOM n/a
handleEvent(event)
Instructs the object to accept and process the event whose specifications are passed as the parameter to the method. The object must have an event handler for the event type to process the event. Navigator 4 only.

Returned Value

None.

Parameters

event

A Navigator 4 event object.

select( ) NN 2 IE 3 DOM 1
Selects all the text displayed in the form element. To position the insertion pointer in a specific location inside a textarea element in IE, see the TextRange object.

Returned Value

None.

Parameters

None.

TextRange NN n/a IE 4(Win) DOM n/a

The TextRange object-- similar in concept to the Netscape 6 and W3C DOM Range object—represents the text of zero or more characters in a document. When a text range consists of zero characters, it represents an insertion point between two characters (or before the first or after the last character).

A TextRange object is created via the createTextRange( ) method associated with the body, button, text, or textarea objects. You can also turn a user selection into a range via the selection object's createRange( ) (note the slight difference in the method name). Once you have created a text range, use its methods to adjust its start and end points to encompass a desired segment of the text (such as text that matches a search string). Once the range has been narrowed to the target text, assign values to its htmlText and text properties to change, remove, or insert text. A library of direct commands that perform specific textual modifications can also be invoked to act on the text range. See Chapter 5 for details and examples of using the TextRange object.

Shared properties and methods from the list at the start of this chapter are: offsetLeft, offsetTop, getBoundingClientRect( ), getClientRects( ), and scrollIntoView( ). Note that the TextRange object and all associated facilities are available only in the Win32 version of Internet Explorer.

Object Model Reference

objectRef.createTextRange( )
selectionObjectRef.createRange( )

Object-Specific Properties

`boundingHeight`	`boundingLeft`	`boundingTop`	`boundingWidth`
`htmlText`	`text`

Object-Specific Methods

`collapse( )`	`compareEndPoints( )`	`duplicate( )`
`execCommand( )`	`expand( )`	`findText( )`
`getBookmark( )`	`inRange( )`	`isEqual( )`
`move( )`	`moveEnd( )`	`moveStart( )`
`moveToBookmark( )`	`moveToElementText( )`	`moveToPoint( )`
`parentElement( )`	`pasteHTML( )`	`queryCommandEnabled( )`
`queryCommandIndeterm( )`	`queryCommandState( )`	`queryCommandSupported( )`
`queryCommandText( )`	`queryCommandValue( )`	`select( )`
`setEndPoint( )`

boundingHeight, boundingWidth NN n/a IE 4(Win) DOM n/a
Read-only
Return the pixel measure of the imaginary space occupied by the TextRange object. Although you do not see a TextRange object in the document (unless a script selects it), the area of a TextRange object is identical to the area that a selection highlight would occupy. These values cinch up to measure only as wide or tall as the widest and tallest part of the range. You would arrive at these same values by performing arithmetic on values returned from the getBoundingClientRect( ) method.

Example

var rangeWidth = document.forms[0].myTextArea.createTextRange( ).boundingWidth;

Value

Integer.

Default

None.

boundingLeft, boundingTop NN n/a IE 4(Win) DOM n/a
Read-only
Return the pixel distance between the top or left of the browser window or frame and the top or left edges of the imaginary space occupied by the TextRange object. Although you do not see a TextRange object in the document (unless a script selects it), the area of a TextRange object is identical to the area that a selection highlight would occupy. Values for these properties are measured from the fixed window or frame edges and not the top and left of the document, which may scroll out of view. Therefore, as a document scrolls, these values change.

Example

var rangeOffH = document.forms[0].myTextArea.createTextRange( ).boundingLeft;

Value

Integer.

Default

None.

htmlText NN n/a IE 4(Win) DOM n/a
Read-only
Specifies all HTML of the document for a given element when that element is used as the basis for a TextRange object. For example, if you create a TextRange for the body element (document.body.createTextRange( )), the htmlText property contains all HTML content between (but not including) the body element tags.

Example

var rangeHTML = document.body.createTextRange( ).htmlText;

Value

String.

Default

None.

text NN n/a IE 4(Win) DOM n/a
Read/Write
Indicates the text contained by the text range. In the case of a TextRange object of a body element, this consists of only the text that is rendered, but none of the HTML tags behind the scenes.

Example

var rangeText = document.body.createTextRange( ).text;

Value

String.

Default

None.

collapse( ) NN n/a IE 4(Win) DOM n/a
collapse([start])
Reduces the TextRange object to a length of zero (creating an insertion point) at the beginning or end of the text range before it collapsed.

Returned Value

None.

Parameters

start

Optional Boolean value that controls whether the insertion point goes to the beginning (true) of the original range or the end (false). The default value is true.

compareEndPoints( ) NN n/a IE 4(Win) DOM n/a
compareEndPoints("type", comparisonRange)
Compares the relative position of the boundary (start and end) points of two ranges (the current range and one that had been previously saved to a variable). The first parameter defines which boundary points in each range you wish to compare. If the result of the comparison is that the first point is earlier in the range than the other point, the returned value is -1. If the result shows both points to be in the same location, the returned value is 0. If the result shows the first point to be later in the range than the other point, the returned value is 1. For example, if you have saved the first range to a variable r1 and created a new range as r2, you can see the physical relationship between the end of r2 and the start of r1:
r1.compareEndPoints("EndToStart", r2)
If r1 ends where r2 starts (the insertion point between two characters), the returned value is 0.

Returned Value

-1, 0, or 1.

Parameters

type

One of the following constants (as a string): StartToEnd | StartToStart | EndToStart | EndToEnd.

comparisonRange

A TextRange object created earlier and saved to a variable.

duplicate( ) NN n/a IE 4(Win) DOM n/a
Creates a new TextRange object with the same values as the current range. The new object is an independent object (the old and new do not equal each other), but their values are initially identical (until you start modifying one range or the other).

Returned Value

TextRange object.

Parameters

None.

execCommand( ) NN n/a IE 4(Win) DOM n/a
execCommand("commandName"[, UIFlag[, value]])
Executes the named command on the current TextRange object. Many commands work best when the TextRange object is an insertion point. See Appendix D for a list of commands.

Returned Value

Boolean value: true if command is successful; false if unsuccessful.

Parameters

commandName

A case-insensitive string value of the command name. See Appendix D.

UIFlag

Optional Boolean value: true to display any user interface triggered by the command (if any); false to prevent such display.

value

A parameter value for the command.

expand( ) NN n/a IE 4(Win) DOM n/a
expand("unit")
Expands the current text range (including a collapsed range) to encompass the textual unit passed as a parameter. For example, if someone selects some characters from a document, you can create the range and expand it to encompass the entire sentence in which the selection takes place:
var rng = document.selection.createRange( ); rng.expand("sentence");
If the starting range extends across multiple units, the expand( ) method expands the range outward to the next nearest unit.

Returned Value

Boolean value: true if method is successful; false if unsuccessful.

Parameters

unit

A case-insensitive string value of the desired unit: character | word | sentence | textedit. The textedit value expands the range to the entire original range.

findText( ) NN n/a IE 4(Win) DOM n/a
findText("string"[, searchScope][, flags])
Searches the current TextRange object for a match of a string passed as the required first parameter. By default, matching is done on a case-insensitive basis. If there is a match, the TextRange object repositions its start and end points to surround the found text. To continue searching in the document, you must reposition the start point of the text range to the end of the found string (with collapse( )).
Optional parameters let you limit the scope of the search within the range to a desired number of characters after the range's start point, or dictate additional matching requirements, such as partial or whole words.

Returned Value

Boolean value: true if a match is found; false if unsuccessful.

Parameters

string

A case-insensitive string to be searched.

searchScope

Integer for the number of characters to search relative to the range's start point. A positive number searches forward; a negative number searches backward, to text earlier in the document than the start point of the text range.

flags

Integer for search detail codes: 0 (match partial words); 1 (match backwards); 2 (match whole words only); 4 (match case).

getBookmark( ), moveToBookmark( ) NN n/a IE 4(Win) DOM n/a
getBookmark( ) moveToBookmark(bookmarkString)
These two methods work together as a way to temporarily save a text range specification and restore it when needed. The getBookmark( ) method returns an opaque string (containing binary data that is of no value to human users). Once that value is stored in a variable, the range can be modified as needed for the script. Some time later, the bookmarked text range can be restored with the moveToBookmark( ) method:
var rangeMark = myRange.getBookmark( ); ... myRange.moveToBookmark(rangeMark);

Returned Value

Boolean value: true if the operation is successful; false if unsuccessful.

Parameters

bookmarkString

An opaque string returned by the getBookmark( ) method.

inRange( ) NN n/a IE 4(Win) DOM n/a
inRange(comparisonRange)
Determines whether the comparison range is within or equal to the physical range of the current text range.

Returned Value

Boolean value: true if the comparison range is in or equal to the current range; false if not.

Parameters

comparisonRange

TextRange object created earlier and saved to a variable.

isEqual( ) NN n/a IE 4(Win) DOM n/a
isEqual(comparisonRange)
Determines whether the comparison range is identical to the current text range.

Returned Value

Boolean value: true if the comparison range is equal to the current range; false if not.

Parameters

comparisonRange

A TextRange object created earlier and saved to a variable.

move( ) NN n/a IE 4(Win) DOM n/a
move("unit"[, count])
Collapses the current text range to an insertion point at the end of the current range and moves it forward or backward from the current position by one or more units.

Returned Value

Integer of the number of units moved.

Parameters

unit

A case-insensitive string value of the desired unit: character | word | sentence | textedit. The textedit value moves the insertion pointer to the start or end of the entire original range.

count

An optional integer of the number of units to move the insertion pointer. Positive values move the pointer forward; negative values move the pointer backward. Default value is 1.

moveEnd( ), moveStart( ) NN n/a IE 4(Win) DOM n/a
moveEnd("unit"[, count]) moveStart("unit"[, count])
Moves only the end or start point (respectively) of the current text range by one or more units. An optional parameter lets you specify both the number of units and direction. To shift the start point of a text range toward the beginning of the original range, be sure to specify a negative value. When moving the end point forward by word units, be aware that a word ends with a whitespace character (including a period). Therefore, if a findText( ) method sets the range to a found string that does not end in a space, the first moveEnd("word") method moves the ending point to the spot past the space after the found string rather than to the following word.

Returned Value

Integer of the number of units moved.

Parameters

unit

A case-insensitive string value of the desired unit: character | word | sentence | textedit. The textedit value moves the insertion pointer to the start or end of the entire original range.

count

An optional integer of the number of units to move the insertion pointer. Positive values move the pointer forward; negative values move the pointer backward. Default value is 1.

moveToBookmark
See getBookmark( ).

moveToElementText( ) NN n/a IE 4(Win) DOM n/a
moveToElementText(elementObject)
Moves the current TextRange object's start and end points to encase the specified HTML element object. The resulting text range includes the HTML for the element, as well.

Returned Value

None.

Parameters

elementObject

A scripted reference to the object. This can be in the form of a direct reference (document.getElementById("elementID") or a variable containing the same kind of value.

moveToPoint( ) NN n/a IE 4(Win) DOM n/a
moveToPoint(x, y)
Collapses the text range to an insertion pointer and sets its location to the spot indicated by the horizontal and vertical coordinates in the browser window or frame. This is as if the user had clicked on a spot in the window to define an insertion point. Use methods such as expand( ) to enlarge the text range to include a character, word, sentence, or entire text range.

Returned Value

None.

Parameters

x

Horizontal coordinate of the insertion point in pixels relative to the left edge of the window or frame.

y

Vertical coordinate of the insertion point in pixels relative to the top edge of the window or frame.

parentElement( ) NN n/a IE 4(Win) DOM n/a
Returns an object reference to the next outermost element that fully contains the TextRange object.

Returned Value

Element object reference.

Parameters

None.

pasteHTML( ) NN n/a IE 4(Win) DOM n/a
pasteHTML("HTMLText")
Replaces the current text range with the HTML content supplied as a parameter string. Typically, this method is used on a zero-length text range object acting as an insertion pointer. All tags are rendered as if they were part of the original source code.

Returned Value

None.

Parameters

HTMLText

Document source code to be inserted into the document.

queryCommandEnabled( ) NN n/a IE 4(Win) DOM n/a
queryCommandEnabled("commandName")
Indicates whether the command can be invoked in light of the current state of the document or selection.

Returned Value

Boolean value: true if enabled; false if not.

Parameters

commandName

A case-insensitive string value of the command name. See Appendix D.

queryCommandIndeterm( ) NN n/a IE 4(Win) DOM n/a
queryCommandIndeterm("commandName")
Indicates whether the command is in an indeterminate state.

Returned Value

Boolean value: true | false.

Parameters

commandName

A case-insensitive string value of the command name. See Appendix D.

queryCommandState( ) NN n/a IE 4(Win) DOM n/a
queryCommandState("commandName")
Determines the current state of the named command.

Returned Value

true if the command has been completed; false if the command has not completed; null if the state cannot be accurately determined.

Parameters

commandName

A case-insensitive string value of the command name. See Appendix D.

queryCommandSupported( ) NN n/a IE 4(Win) DOM n/a
queryCommandSupported("commandName")
Determines whether the named command is supported by the document object.

Returned Value

Boolean value: true | false.

Parameters

commandName

A case-insensitive string value of the command name. See Appendix D.

queryCommandText( ) NN n/a IE 4(Win) DOM n/a
queryCommandText("commandName")
Returns text associated with the command.

Returned Value

String.

Parameters

commandName

A case-insensitive string value of the command name. See Appendix D.

queryCommandValue( ) NN n/a IE 4(Win) DOM n/a
queryCommandValue("commandName")
Returns the value associated with the command, such as the name font of the selection.

Returned Value

Depends on the command.

Parameters

commandName

A case-insensitive string value of the command name. See Appendix D.

select( ) NN n/a IE 4(Win) DOM n/a
Selects all the text that is included in the current TextRange object. This method brings some visual confirmation to users that a script knows about a particular block of text. For example, if you were scripting a search with the findText( ) method, you would then use the scrollIntoView( ) and select( ) methods on that range to show the user where the matching text is.

Returned Value

None.

Parameters

None.

setEndPoint( ) NN n/a IE 4(Win) DOM n/a
setEndPoint("type", comparisonRange)
Sets the end point of the current TextRange object to the end point of another range that had previously been preserved as a variable reference.

Returned Value

None.

Parameters

type

One of the following constants (as a string): StartToEnd | StartToStart | EndToStart | EndToEnd.

comparisonRange

A TextRange object created earlier and saved to a variable.

TextRectangle NN n/a IE 5(Win) DOM n/a

A TextRectangle object contains the coordinates of the four edges of an invisible box that surrounds a string of body text. Two methods of all element objects and the TextRange object produce information about two different kinds of text rectangles. The getClientRects( ) method returns a collection of line-by-line text rectangles; the getBoundingClientRect( ) method returns a single TextRectangle object that has coordinates that encompass all line-by-line rectangles.

Invoking either of these methods gets the rectangles' values instantaneously. Resizing the window or altering the content of the target object may change the actual rectangles, but the TextRangle objects obtained earlier do not keep pace with the changes (since the content of each line's rectangle is likely to change). Therefore, obtain TextRectangle values immediately before you need to process them in other script statements.

Object Model Reference

elementOrTextRangeReference.getBoundingClientRect( )
elementOrTextRangeReference.getClientRects( )[i]

Object-Specific Properties

bottom

left

top

right

Object-Specific Methods

None.

Object-Specific Event Handler Properties

None.

bottom, left, right, top NN n/a IE 5(Win) DOM n/a
Read-only
Return integer pixel values for the browser window coordinates of the rectangle edges. Note that these values are not relative to the page. Therefore, values change as the text holder scrolls.

Example

var rightMostEdge = document.getElementById("myP").getBoundingClientRect( ).right;

Value

Integer pixel measures

Default

None.

title NN 6 IE 4 DOM 1

The title object reflects the title element. If you encounter problems referencing the element object by its id attribute (especially in IE 4/Windows or Netscape 6), use the tag access methods for the respective browsers: document.all.tags("title")[0] for IE, and document.getElementsByTagName("title")[0] for IE 5 or later and Netscape 6.

HTML Equivalent

<title>

Object Model Reference

[window.]document.getElementById("elementID")

Object-Specific Properties

text

Object-Specific Methods

None.

Object-Specific Event Handler Properties

None.

text NN 6 IE 4 DOM 1
Read/Write
Specifies the text content of the element. For the title element, this is the text between the start and end tags that also appears in the browser window's title bar (usually along with some identification of the browser brand). Changes you make to this property do not appear in the source code you view from the browser. Nor does the change appear in the title bar of IE for Windows.

Example

document.getElementsByTagName("title")[0].text = "Welcome, Dave!";

Value

String.

Default

None.

tr	`NN 6 IE 4 DOM 1`

The tr object reflects the tr element. Due to incomplete implementation, IE 4 for the Macintosh does not offer complete scripted access to these element objects.

HTML Equivalent

<tr>

Object Model Reference

[window.]document.getElementById("elementID")
[window.]document.getElementById("tableID").rows[i]

Object-Specific Properties

`align`	`bgColor`	`borderColor`	`borderColorDark`
`borderColorLight`	`cells[]`	`ch`	`chOff`
`height`	`rowIndex`	`sectionRowIndex`	`vAlign`

Object-Specific Methods

deleteCell( )

insertCell( )

Object-Specific Event Handler Properties

None.

align NN 6 IE 4 DOM 1
Read/Write
Defines the horizontal alignment of content within all cells of the row.

Example

document.getElementById("myTR").align = "center";

Value

Any of the three horizontal alignment constants: center | left | right.

Default

left

bgColor NN 6 IE 4 DOM 1
Read/Write
Specifies the background color of the table cells in the current row. This color setting is not reflected in the style sheet backgroundColor property. Even if the bgcolor attribute or bgColor property is set with a plain-language color name, the returned value is always a hexadecimal triplet.

Example

document.getElementById("myTR").bgColor = "yellow";

Value

A hexadecimal triplet or plain-language color name. See Appendix A for acceptable plain-language color names.

Default

Varies with browser and operating system.

borderColor NN n/a IE 4 DOM n/a
Read/Write
Specifies the color of the element's border. Internet Explorer applies the color to all four lines that make up the interior border of a cell. Therefore, colors of adjacent cells do not collide.

Example

document.getElementById("myTR").borderColor = "salmon";

Value

A hexadecimal triplet or plain-language color name. A setting of empty is interpreted as "#000000" (black). See Appendix A for acceptable plain-language color names.

Default

Varies with operating system.

borderColorDark, borderColorLight NN n/a IE 4 DOM n/a
Read/Write
The 3-D effect of table borders in Internet Explorer is created by careful positioning of light and dark lines around the page's background or default color. You can independently control the colors used for the dark and light lines by assigning values to the borderColorDark (left and top edges of the cell) and borderColorLight (right and bottom edges) properties.
Typically, you should assign complementary colors to the pair of properties. There is also no rule that says you must assign a dark color to borderColorDark. The attributes merely control a well-defined set of lines so you can predict which lines of the border change with each attribute.

Example

document.getElementById("myTR").borderColorDark = "blue"; document.getElementById("myTR").borderColorLight = "cornflowerblue";

Value

A hexadecimal triplet or plain-language color name. A setting of empty is interpreted as "#000000" (black). See Appendix A for acceptable plain-language color names.

Default

Varies with operating system.

cells[ ] NN 6 IE 4 DOM 1
Read-only
Returns a collection of td or th elements nested inside the table row. Items in the collection are in source code order.

Example

var allRowCells = document.getElementById("myTR").cells;

Value

Reference to a cells collection object.

Default

Array of zero length.

ch NN 6 IE 5(Mac)/6(Win) DOM 1
Read/Write
Defines the text character used as an alignment point for text cells of the row. This property is normally of value only for the align attribute set to "char". In practice, neither IE nor Navigator responds to these properties.

Example

document.getElementById("myTR").ch = ".";

Value

Single character string.

Default

None.

chOff NN 6 IE 5(Mac)/6(Win) DOM 1
Read/Write
Defines the offset point at which the character specified by the char attribute is to appear within a cell. In practice, neither IE nor Navigator responds to these properties.

Example

document.getElementById("myTR").chOff = "80%";

Value

String value of the number of pixels or percentage (within the cell).

Default

None.

height NN n/a IE 5 DOM n/a
Read/Write
Specifies the pixel or percentage height of the row. To change the height of a row dynamically, adjust the element's style.height value rather than the height property.

Value

String value of the number of pixels or percentage (within the row).

Default

None.

rowIndex NN 6 IE 4 DOM 1
Read-only
Returns a zero-based integer representing the position of the current row among all other tr elements in the entire table. The count is based on the source code order of the tr elements.

Example

var whichRow = document.getElementById("myTR").rowIndex;

Value

Integer.

Default

None.

sectionRowIndex NN 6 IE 4 DOM 1
Read-only
Returns a zero-based integer representing the position of the current row among all other tr elements in the row grouping. A row grouping can be one of the following elements: thead, tbody, tfoot. The count is based on the source code order of the tr elements.

Example

var whichRow = document.getElementById("myTR").sectionRowIndex;

Value

Integer.

Default

None.

vAlign NN 6 IE 4 DOM 1
Read/Write
Indicates the manner of vertical alignment of text within the cells of the current row.

Example

document.getElementById("myTR").vAlign = "baseline";

Value

Case-insensitive constant (as a string): baseline | bottom | middle | top.

Default

middle

deleteCell( ) NN 6 IE 4 DOM 1
deleteCell(index)
Removes a td or th element nested within the current tr element. The integer parameter points to the zero-based item in the row's cells collection.

Returned Value

None.

Parameters

index

Zero-based integer corresponding to the numbered td element in source code order (nested within the current element).

insertCell( ) NN 6 IE 4(Win) DOM 1
insertCell(index)
Inserts a td element nested within the current tr element. The integer parameter points to the zero-based index in the cells collection where the new cell should go, but in IE you can also use the shortcut value of -1 to append the cell to the end of the collection. Adding the cell inserts an empty element, to which you add content via the various document tree modification techniques. Unfortunately, scripting the addition of table rows and cells in IE for the Macintosh (including Version 5.1) is very broken, yielding elephantine row and cell dimensions. For nonnested tables, you might be able to get away with regular document tree node creation and insertion instead of the table section object convenience methods.

Returned Value

Reference to the newly inserted cell.

Parameters

index

Zero-based integer corresponding to a row of the cells collection before which the new cell is to be inserted.

TreeWalker NN 7 IE n/a DOM 2

The TreeWalker object is a live, hierarchical list of nodes that meet criteria defined by the document.createTreeWalker( ) method. The list assumes the same parent-descendant hierarchy for its items as the nodes to which its items point. The createTreeWalker( ) method describes the node where the list begins and which nodes (or classes of nodes) are exempt from the list by way of filtering.

The TreeWalker object maintains a kind of pointer inside the list (so that your scripts don't have to). Methods of this object let scripts access the next or previous node (or sibling, child, or parent node) in the list, while moving the pointer in the direction indicated by the method you chose. If scripts modify the document tree after the TreeWalker is created, changes to the document tree are automatically reflected in the sequence of nodes in the TreeWalker.

While fully usable in an HTML document, the TreeWalker can be even more valuable in an XML data document. For example, the W3C DOM does not provide a quick way to access all elements that have a particular attribute name (something that the XPATH standard can do easily on the server). But you can define a TreeWalker to point only to nodes that have the desired attribute, and quickly access those nodes sequentially (i.e., without having to script more laborious looping through all nodes in search of the desired elements). As an example, the following filter function allows only those nodes that contain the author attribute to be a member of a TreeWalker object:

function authorAttrFilter(node) {
    if (node.hasAttribute("author")) {
        return NodeFilter.FILTER_ACCEPT;		
    }
    return NodeFilter.FILTER_SKIP;
}

A reference to this function becomes one of the parameters to a createTreeWalker( ) method that also limits the list to element nodes:

var authorsOnly = document.createTreeWalker(document, 
NodeFilter.SHOW_ELEMENT, authorAttrFilter, false);

You can then invoke TreeWalker object methods to obtain a reference to one of the nodes in the list. When you invoke the method, the TreeWalker object applies the filter to candidates relative to the current poistion of the internal pointer in the direction indicated by the method. The next document tree node to meet the method and filter criteria is returned. Once you have that node reference, you can access any DOM node property or method to work with the node, independent of the items in the TreeWalker list.

Object Model Reference

TreeWalkerReference

Object-Specific Properties

currentNode

expandEntityReference

filter

root

whatToShow

Object-Specific Methods

`firstChild( )`	`lastChild( )`	`nextNode( )`	`nextSibling( )`
`parentNode( )`	`previousNode( )`	`previousSibling( )`

Object-Specific Event Handler Properties

None.

currentNode NN 7 IE n/a DOM 2
Read/Write
Returns a reference to the node where the TreeWalker's pointer is positioned. But more importantly, you can also assign a document tree node reference to this property to manually set a new position for the pointer. If the assigned node would normally be filtered out of the list, the next method invocation is performed from the position as if the assigned node were not filtered out of the list.

Example

myTreeWalker.currentNode = document.getElementById("main");

Value

Reference to a document tree node.

Default

First node of the document.

expandEntityReference, filter, root, whatToShow NN 7 IE n/a DOM 2
Read-only
These four properties reflect the parameter values passed to the document.createTreeWalker( ) method when the object was created.

firstChild( ), lastChild( ), nextSibling( ), parentNode( ), previousSibling( ) NN 7 IE n/a DOM 2
These methods return references to nodes within the hierarchy of items in the TreeWalker object. The parent-descendant relationships between nodes are identical to those of the nodes within the document tree. As you invoke any one of these methods, the TreeWalker's internal pointer moves to a position adjacent to the node's spot within the TreeWalker list. If there is no node meeting the desired reference, the method returns null. This means that you need to verify the existence of the node before reading any property of the node:
if (myTreeWalker.nextSibling( )) { var theTag = myTreeWalker.currentNode.tagName; }
If you reference a property of a null reference directly (myTreeWalker.nextSibling( ).tagName, for example), a reference error results.

Returned Value

Reference to a document tree node.

Parameters

None.

nextNode( ), previousNode( ) NN 7 IE n/a DOM 2
Move the internal NodeIterator pointer one position forward (nextNode( )) or backward (previousNode( )), while returning a reference to the node through which the pointer passed en route. These two methods operate as if the hierarchy were flattened (in the manner of a NodeIterator object).

Returned Value

Reference to a node in the document tree.

Parameters

None.

ul	`NN 6 IE 4 DOM 1`

The ul object reflects the ul element.

HTML Equivalent

<ul>

Object Model Reference

[window.]document.getElementById("elementID")

Object-Specific Properties

compact

type

Object-Specific Methods

None.

Object-Specific Event Handler Properties

None.

compact NN 6 IE 4 DOM 1
Read/Write
When set to true, the compact property should instruct the browser to render items in the list in a more compact format. This property has no effect in mainstream browsers.

Example

document.getElementById("myUL").compact = true;

Value

Boolean value: true | false.

Default

false

type NN 6 IE 4 DOM 1
Read/Write
Specifies the manner in which the leading item markers in the list are displayed.

Example

document.getElementById("myUL").type = "square";

Value

Any one of the constant values (as a string): circle | disc | square. Additional choices available through style sheets

Default

disc

userProfile NN n/a IE 4(Win) DOM n/a

The userProfile object reflects numerous pieces of information stored in the browser's user profile for the current user. This object has four methods that:

Let you queue requests for individual fields of the profile (items such as name, mailing address, phone numbers, and so on)
Display the request dialog that lets users see what you're asking for and disallow specific items or the whole thing
Grab the information
Clear the request queue

Once the information is retrieved (with the user's permission), it can be slipped into form elements (visible or hidden) for submission to the server. Compatibility listings here indicate support in IE for Windows only. While IE for Macintosh accepts the method calls without error, there is no functionality attached to those methods. Further details on the user profile are available from Microsoft at http://msdn.microsoft.com/workshop/management/profile/profile_assistant.asp.

Example

navigator.userProfile.addReadRequest("vcard.displayname");
navigator.userProfile.doReadRequest("3", "MegaCorp Customer Service");
var custName = navigator.userProfile.getAttribute("vcard.displayname");
navigator.userProfile.clearRequest( );
if (custName) {
    ...
}

Object Model Reference

navigator.userProfile

Object-Specific Properties

None.

Object-Specific Methods

addReadRequest( )

clearRequest( )

doReadRequest( )

getAttribute( )

Object-Specific Event Handler Properties

None.

addReadRequest( ) NN n/a IE 4(Win) DOM n/a
addReadRequest("attributeName")
Adds a request to inspect a particular user profile attribute to a queue that must be executed separately (via the doReadRequest( ) and getAttribute( ) methods). Items added to the queue are displayed to the user to select which item(s) can be submitted to a server. For multiple attributes, use multiple invocations of the addReadRequest( ) method.

Returned Value

Boolean value: true (if successful) | false (if unsuccessful).

Parameters

attributeName

One of the following case-insensitive attribute names as a string:

vCard.Business.City

vCard.Business.Country

vCard.Business.Fax

vCard.Business.Phone

vCard.Business.State

vCard.Business.StreetAddress

vCard.Business.URL

vCard.Business.Zipcode

vCard.Cellular

vCard.Company

vCard.Department

vCard.DisplayName

vCard.Email

vCard.FirstName

vCard.Gender

vCard.Home.City

vCard.Home.Country

vCard.Home.Fax

vCard.Home.Phone

vCard.Home.State

vCard.Home.StreetAddress

vCard.Home.Zipcode

vCard.Homepage

vCard.JobTitle

vCard.LastName

vCard.MiddleName

vCard.Notes

vCard.Office

vCard.Pager

clearRequest( ) NN n/a IE 4(Win) DOM n/a
Empties the queue of attribute names to be retrieved. Use this after your script has successfully retrieved the required information. This prepares the queue for the next list.

Returned Value

None.

Parameters

None.

doReadRequest( ) NN n/a IE 4(Win) DOM n/a
doReadRequest(usageCode[, "friendlyName"[, "domain"[, "path"[, "expiration"]]]])
Based on the items in the queue, this method inspects the browser to see whether the user has given permission to inspect these attributes in the past. If not (for some or all), the method displays a dialog box (the Profile Assistant window) that lets users turn off the items that should not be exposed to the server. Parameters provide information for the dialog and for maintenance of the permission (similar to the ways that cookies are managed). Only one doReadRequest( ) method is required, regardless of the number of attributes in the queue.

Returned Value

In Windows, the method returns no value, regardless of how the user responds to the Profile Assistant dialog box. On the Macintosh (which does not support this object fully), the method does not display the Profile Assistant dialog box and returns false.

Parameters

usageCode

One of the following code integers that display human-readable messages defined by the Internet Privacy Working Group, as shown in the following table.

Code

Meaning

0
Used for system administration.

1
Used for research and/or product development.

2
Used for completion and support of current transaction.

3
Used to customize the content and design of a site.

4
Used to improve the content of the site, including advertisements.

5
Used for notifying visitors about updates to the site.

6
Used for contacting visitors for marketing of services or products.

7
Used for linking other collected information.

8
Used by site for other purposes.

9
Disclosed to others for customization or improvement of the content and design of the site.

10
Disclosed to others who may contact you for marketing of services and/or products.

11
Disclosed to others who may contact you for marketing of services and/or products, but you have the opportunity to ask a site not to do this.

12
Disclosed to others for any other purpose.

friendlyName

An optional string containing an identifiable name (and URL) that the user recognizes as the source of the request. This may be a corporate identity.

domain

An optional string containing the domain of the server making the request. If an expiration date is set, this information is stored with the requested attributes to prevent future requests from this domain from interrupting the user with the Profile Assistant dialog box.

path

An optional string containing the path of the server document making the request. If an expiration date is set, this information is stored with the requested attributes to prevent future requests from this domain from interrupting the user with the Profile Assistant dialog box.

expiration

An optional string containing the date on which the user's permissions settings expire. Not recognized in Internet Explorer 4.

getAttribute( ) NN n/a IE 4 DOM n/a
getAttribute("attributeName")
Returns the value of the attribute, provided the user has given permission to do so. If that permission was denied, the method returns null. Use one getAttribute( ) method for each attribute value being retrieved.

Returned Value

String value or null

Parameters

attributeName

One of the vCard attribute names listed in the addReadRequest( ) method description.

window NN 2 IE 3 DOM n/a

The window object represents the browser window or frame in which document content is displayed. The window object plays a vital role in scripting when scripts must communicate with document objects located in other frames or subwindows. Managing multiple windows can be tricky business because of the transient nature of cross-window references. Strict interpretation of HTML and XHTML standards frowns upon multiple windows, and many confused users may agree.

Although the W3C DOM Level 2 does not provide in-depth specifications for the window object (a window, after all, is outside the scope of document markup), it nevertheless indicates possible future hooks through what it calls "view" objects. Thus, the Netscape 6 document.defaultView property returns the document's window; the Netscape 6 window object also takes on the method of the ViewCSS object to gain the DOM's getComputedStyle( ) method.

The window object has been scriptable since the beginning and bears a considerable legacy of properties and methods. Many of these features are browser-specific, so observe compatibility ratings carefully before adopting a particular object feature.

Object Model Reference

window
self
top
parent

Object Properties

`appCore`	`clientInformation`	`clipboardData`	`closed`
`Components`	`content`	`controllers`	`crypto`
`defaultStatus`	`dialogArguments`	`dialogHeight`	`dialogLeft`
`dialogTop`	`dialogWidth`	`directories`	`document`
`event`	`external`	`frameElement`	`frames[]`
`history`	`innerHeight`	`innerWidth`	`length`
`location`	`locationbar`	`menubar`	`name`
`navigator`	`offscreenBuffering`	`opener`	`outerHeight`
`outerWidth`	`pageXOffset`	`pageYOffset`	`parent`
`personalbar`	`pkcs11`	`prompter`	`returnValue`
`screen`	`screenLeft`	`screenTop`	`screenX`
`screenY`	`scrollX`	`scrollY`	`scrollbars`
`self`	`sidebar`	`status`	`statusbar`
`toolbar`	`top`	`window`

Object Methods

`addEventListener( )`	`alert( )`	`attachEvent( )`
`back( )`	`blur( )`	`captureEvents( )`
`clearInterval( )`	`clearTimeout( )`	`close( )`
`confirm( )`	`createPopup( )`	`detachEvent( )`
`disableExternalCapture( )`	`dispatchEvent( )`	`enableExternalCapture( )`
`execScript( )`	`find( )`	`focus( )`
`forward( )`	`GetAttention( )`	`getComputedStyle( )`
`getSelection( )`	`home( )`	`moveBy( )`
`moveTo( )`	`navigate( )`	`open( )`
`print( )`	`prompt( )`	`releaseEvents( )`
`removeEventListener( )`	`resizeBy( )`	`resizeTo( )`
`routeEvent( )`	`scroll( )`	`scrollBy( )`
`scrollByLines( )`	`scrollByPages( )`	`scrollTo( )`
`setCursor( )`	`setInterval( )`	`setTimeout( )`
`showHelp( )`	`showModalDialog( )`	`showModelessDialog( )`
`sizeToContent( )`	`stop( )`

Object-Specific Event Handler Properties

Handler	NN	IE/Windows	IE/Mac	DOM
`onafterprint`	n/a	5	n/a	n/a
`onbeforeprint`	n/a	5	n/a	n/a
`onbeforeunload`	n/a	4	4	n/a
`onblur`	3	4	4	n/a
`ondragdrop`	4	n/a	n/a	n/a
`onerror`	3	4	4	n/a
`onfocus`	3	4	4	n/a
`onhelp`	n/a	4	4	n/a
`onload`	2	3	3.01	n/a
`onmove`	4	5.5	n/a	n/a
`onresize`	4	4	4	n/a
`onscroll`	n/a	4	4	n/a
`onunload`	2	4	4	n/a

appCore, Components, content, controllers, prompter, sidebar NN 6 IE n/a DOM n/a
Read-only
These properties are associated with the proprietary Mozilla xpconnect ("cross-platform" connect) services. These services allow scripts that have the correct security clearance to work with XPCOM (decidedly not MS COM) objects to extend the functionality of the application that uses the Mozilla engine (such as the Netscape 6 browser). Access to these services requires enabling security privileges (typically via signed scripts), as follows:
netscape.security.PrivilegeManager.enablePrivilege("UniversalXPConnect"); // your xpconnect access code here netscape.security.PrivilegeManager.revertPrivilege("UniversalXPConnect");
For more details on this mechanism, visit http://www.mozilla.org/scriptable/.

clientInformation NN n/a IE 4 DOM n/a
Read-only
Returns the navigator object. The navigator object is named after a specific browser brand; the clientInformation property is a nondenominational way of accessing important environment variables that have historically been available through properties and methods of the navigator object (discussed separately earlier in this chapter as its own object). In Internet Explorer, you can substitute window.clientInformation for any reference that begins with navigator.

Example

if (parseInt(window.clientInformation.appVersion) >= 4) { // process code for IE 4 or later }

Value

The navigator object.

Default

The navigator object.

clipboardData NN n/a IE 5(Win) DOM n/a
Read-only
Returns the clipboardData object, discussed separately earlier in this chapter as its own object. The object (accessible as a property of a window or frame object) is a temporary container that scripts in IE 5 and later for Windows can use to transfer text data, particularly during script-controlled operations that simulate cutting, copying, and pasting, or that control dragging.

Example

var rng = document.selection.createRange( ); clipboardData.setData("Text",rng.text);

Value

The clipboardData object.

Default

The clipboardData object.

closed NN 3 IE 4 DOM n/a
Read-only
This is the Boolean value that says whether the referenced window is closed. A value of true means the window is no longer available for referencing its objects or script components. This is used most often to check whether a user has closed a subwindow generated by the window.open( ) method.

Example

if (!newWindow.closed) { newWindow.document.close( ); }

Value

Boolean value: true | false.

Default

None.

Components, content, controllers
See appCore.

crypto, pkcs11 NN 6 IE n/a DOM n/a
Read-only
Return references to objects associated with Mozilla public-key cryptography internals. For more details on this subject, visit http://www.mozilla.org/projects/security/.

defaultStatus NN 2 IE 3 DOM n/a
Read/Write
Specifies the default message displayed in the browser window's status bar when no browser loading activity is occurring. To temporarily change the message (during mouse rollovers, for example), set the window's status property. Most scriptable browsers and versions have difficulty managing the setting of the defaultStatus property. Expect odd behavior.

Example

window.defaultStatus = "Make it a great day!";

Value

Any string value.

Default

None.

dialogArguments NN n/a IE 4 DOM n/a
Read-only
This is the string or other data type passed as extra arguments to a modal dialog window created with the window.showModalDialog( ) or (in IE 5 and later for Windows only) window.showModelessDialog( ) methods. This property is best accessed by a script in the document displayed in the dialog window in order to retrieve whatever data is passed to the new window as arguments. It is up to your script to parse the data if you include more than one argument nugget separated by whatever argument delimiter you choose.

Example

// in dialog window var allArgs = window.dialogArguments; var firstArg = allArgs.substring(0, allArgs.indexOf(";"));

Value

String, number, array, or object.

Default

None.

dialogHeight, dialogWidth NN n/a IE 4(Win) DOM n/a
Read/Write
Specify the height and width values of a modal dialog window created with the showModalDialog( ) and showModelessDialog( ) methods. Although Internet Explorer does not balk at modifying these properties (in a script running in the modal dialog window), the changed values are generally not reflected in a resized dialog window. Initial values are set as parameters to the dialog-opening methods.

Example

var outerWidth = window.dialogWidth;

Value

String, including the unit value (e.g., 520px).

Default

None.

dialogLeft, dialogTop NN n/a IE 4 DOM n/a
Read/Write
Indicate the offset distance of the left and top edges of a modal dialog window (created with the showModalDialog( ) and showModelessDialog( ) methods) relative to the top-left corner of the video screen. Although Internet Explorer does not balk at modifying these properties (in a script running in the modal dialog window), the changed values are generally not reflected in a repositioned dialog window. Initial values are set as parameters to the dialog methods.

Example

var outerLeft = window.dialogLeft;

Value

String, including the unit value (e.g., 80px).

Default

None.

directories, locationbar, menubar, personalbar, scrollbars, statusbar, toolbar NN 4 IE n/a DOM n/a
Read-only
Return references to the Navigator browser window feature (the directories property is new for Netscape 6). See the discussion of the directories (et al.) objects earlier in this chapter for how to control the visibility of these window features with signed scripts.

Example

netscape.security.PrivilegeManager.enablePrivilege("UniversalBrowserWrite") window.statusbar.visible = "false"; netscape.security.PrivilegeManager.revertrivilege("UniversalBrowserWrite")

Value

Respective object references.

Default

None.

document NN 2 IE 3 DOM 2
Read-only
Returns a reference to the document object contained by the window. In browsers that offer W3C DOM document tree support, this property points more specifically to the root HTMLDocument node for the document tree loaded in the window. The W3C DOM even describes this property as a member of one of its View objects (analogous to a browser window). This is the property that lets scripts references to document methods and content begin with the word document.

Example

var oneElem = document.getElementById("myP");

Value

Reference to the root document object.

Default

Reference to the root document object.

event NN n/a IE 4 DOM n/a
Read-only
Internet Explorer's event model generates an event object for each user or system event. This event object is a property of the window object. For details about the IE event object, see Chapter 6 and the listing of the event object in this chapter.

Example
if (event.altKey) {
    // handle case of Alt key down
}
Value

event object reference.

Default

None.

external NN n/a IE 4(Win) DOM n/a
Read-only
Returns a reference to the external object, which provides access to lower-level functionality of the browser engine (security permissions willing). See the discussion of the external object earlier in this chapter.

Example

external.AddFavorite("http://www.dannyg.com", "Danny Home Page");

Value

external object reference.

Default

external object reference.

frameElement NN n/a IE 5.5(Win) DOM n/a
Read-only
If the current window is a member of a frameset or is an iframe, the frameElement property returns a reference to the frame or iframe element object (distinct from the frame-as-window object). Security restrictions, however, can impede script access to this property.

Example

var frameID = window.frameElement.id;

Value

frame or iframe object reference; or null.

Default

null.

frames[ ] NN 2 IE 3 DOM n/a
Read-only
Returns a collection (array) of window objects that are implemented as frames or iframes in the current window. For a frameset's parent or top window, the array contains references to first-generation frame windows. Index values can be zero-based integers (in source code order) or the identifier assigned to the name attribute of the frame element.

Example

parent.frames[1].myFunc( );

Value

Array of frame (window) object references.

Default

Array of length zero.

history NN 2 IE 3 DOM n/a
Read-only
Contains the history object for the current window or frame. For details, see the discussion of the history object.

Example

if (self.history.length > 4) { ... }

Value

history object reference.

Default

Current history object.

innerHeight, innerWidth NN 4 IE n/a DOM n/a
Read/Write
Specify the pixel measure of the height and width of the content region of a browser window or frame. This area is where the document content appears, exclusive of all window "chrome." For comparable values in IE, see the body element object.

Example

window.innerWidth = 600; window.innerHeight = 400;

Value

Integer.

Default

None.

length NN 6 IE 4 DOM n/a
Read-only
Specifies the number of frames (if any) nested within the current window. This value is the same as that returned by window.frames.length. When no frames are defined for the window, the value is zero.

Example

if (window.length > 0) { ... }

Value

Integer.

Default

0

location NN 2 IE 3 DOM n/a
Read/Write
Returns a location object containing URL details of the document currently loaded in the window or frame. To navigate to another page, you assign a URL to the location.href property (or see the navigate( ) method for an IE-only alternative). See the location object.

Example

top.location.href = "index.html";

Value

A full or relative URL as a string.

Default

Current location object.

locationbar
See directories.

menubar
See directories.

name NN 2 IE 3 DOM n/a
Read/Write
This is the identifier associated with a frame or subwindow for use as the value assigned to target attributes or as script references to the frame/subwindow. For a frame, the value is usually assigned via the name attribute of the frame tag, but it can be modified by a script if necessary. The name of a subwindow is assigned as a parameter to the window.open( ) method. The primary browser window does not have a name by default, but you can assign one via script if you need a subwindow to target a link or form back to the main window.

Example

if (parent.frames[1].name == "main") { ... }

Value

Case-sensitive identifier that follows the rules of identifier naming: it may contain no whitespace, cannot begin with a numeral, and should avoid punctuation except for the underscore character.

Default

None.

navigator NN 6 IE 4 DOM n/a
Read-only
Returns a reference to the navigator object. Since the window reference is optional, syntax without the window reference works on all scriptable versions of Internet Explorer and Navigator. See the navigator object.

Example

var theBrowser = navigator.appName;

Value

navigator object reference.

Default

navigator object.

offscreenBuffering NN n/a IE 4 DOM n/a
Read/Write
Indicates whether the browser should use offscreen buffering to improve path animation performance. Although the property is implemented in IE 5 for Macintosh, it is unclear that it offers any functionality. Recent versions of IE for Windows connect this property to the DirectX ActiveX control. When the document loads, the property is set to auto. After that, a script may turn buffering on and off by assigning a Boolean value to this property.

Example

window.offscreenBuffering = "true";

Value

Boolean value: true | false.

Default

auto

opener NN 3 IE 3 DOM n/a
Read/Write
This is an object reference to the window (or frame) that used a window.open( ) method to generate the current window. This property allows subwindows to assemble references to objects, variables, and functions in the originating window. To access document objects in the creating window, a reference can begin with opener and work its way through the regular document object hierarchy from there, as shown in the left side of the following example statement. The relationship between the opening window and the opened window is not strictly parent-child. The term "parent" has other connotations in scripted window and frame references. IE's dialog windows (the showModalDialog( ) and showModelessDialog( ) windows) do not support this property. Values between the main and dialog windows must be passed at creation time and via the dialog window's returnValue property upon closing.

Example

opener.document.forms[0].importedData.value = document.forms[0].entry.value;

Value

window object reference.

Default

None.

outerHeight, outerWidth NN 4 IE n/a DOM n/a
Read/Write
Specify the pixel measure of the height and width of the browser window or frame, including (for the top window) all tool bars, scoll bars, and other visible window "chrome." IE offers no equivalent properties.

Example

window.outerWidth = 80; window.outerHeight = 600;

Value

Integer.

Default

None.

pageXOffset, pageYOffset NN 4 IE n/a DOM n/a
Read-only
Specify the pixel measure of the amount of the page's content that has been scrolled upward and/or to the left. For example, if a document has been scrolled so that the topmost 100 pixels of the document (the "page") are not visible because the window is scrolled, the pageYOffset value for the window is 100. When a document is not scrolled, both values are zero.

Example

var vertScroll = self.pageYOffset;

Value

Integer.

Default

0

parent NN 2 IE 3 DOM n/a
Read-only
Returns a reference to the parent window object whose document defined the frameset in which the current frame is specified. Use parent in building a reference from one child frame to variables or methods in the parent document or to variables, methods, and objects in another child frame. For example, if a script in one child frame must reference the content of a text input form element in the other child frame (named "content"), the reference would be:
parent.content.document.forms[0].entryField.value
For more deeply nested frames, you can access the parent of a parent with syntax such as: parent.parent.frameName.

Example

parent.frames[1].document.forms[0].companyName.value = "MegaCorp";

Value

window object reference.

Default

Current window object reference.

personalbar
See directories.

pkcs11
See crypto.

prompter
See appCore.

returnValue NN n/a IE 4(Win)/5(Mac) DOM n/a
Read/Write
A value to be returned to the main window when an IE dialog window (generated by showModalDialog( ) method only) closes. The value assigned to this property in a script running in the dialog window becomes the value returned by the showModalDialog( ) method in the main window. For example, the document in the modal dialog window may have a statement that sets the returnValue property with information from the dialog:
window.returnValue = window.document.forms[0].userName.value;
The dialog is created in the main document with a statement like the following:
var userName = showModalDialog("userNamePrompt.html");
Whatever value is assigned to returnValue in the dialog is then assigned to the userName variable when the dialog box closes and script execution continues.

Value

Any scriptable data type.

Default

None.

screen NN 6 IE 4 DOM n/a
Read-only
Returns a reference to the screen object. Since the window reference is optional, syntax without the window reference works on all scriptable versions of Internet Explorer and Navigator.

Example

var howHigh = screen.availHeight;

Value

screen object reference.

Default

screen object.

screenLeft, screenTop NN n/a IE 5(Win) DOM n/a
Read-only
Return pixel coordinates of the top-left corner of the browser content area relative to the top-left corner of the screen. A maximized browser window returns a screenLeft value of 0, but the screenTop value varies with the complement of toolbars the user chooses to display. Use window.moveTo( ) to change the window position.

Example

var fromTheTop = window.screenTop;

Value

Integer.

Default

User-dependent

screenX, screenY NN 6 IE n/a DOM n/a
Read/Write
Return pixel coordinates of the top-left corner of the entire browser window (including "chrome") relative to the top-left corner of the screen. A browser window maximized under Windows returns screenX and screenY values of -4 because the chrome extends slightly beyond the screen display. You can adjust the window location through these properties or the window.moveTo( ) method.

Example

var fromTheTop = window.screenY;

Value

Integer.

Default

User-dependent.

scrollX, scrollY NN 6 IE n/a DOM n/a
Read-only
Return the pixel distance the window is scrolled along the horizontal (scrollX) and vertical (scrollY) axes. To determine these values in IE, you must take into account compatibility mode settings in IE 6 (see the DOCTYPE element in Chapter 8). In backward compatibility mode and in IE for Macintosh, use the document.body.scrollLeft and document.body.scrollTop properties. In IE 6 standards compatibility mode (where document.compatMode == "CSS1Compat"), use document.body.parentNode.scrollLeft and document.body.parentNode.scrollTop to get the scroll values of the html element.

Example
var scrolledDown = window.scrollY;
Value

Integer.

Default

0

scrollbars
See directories.

self NN 2 IE 3 DOM n/a
Read-only
This is a reference to the current window or frame. This property is synonymous with window, but is sometimes used to improve clarity in a complex script that refers to many windows or frames. Never use the reference window.self to refer to the current window or frame because some browser versions get confused with the reference.

Example

self.focus( );

Value

window object reference.

Default

Current window.

sidebar
See appCore.

status NN 2 IE 3 DOM n/a
Read/Write
Specifies the text of the status bar of the browser window. Setting the status bar to some message is recommended only for temporary messages, such as for mouse rollovers atop images, areas, or links. Double or single quotes in the message must be escaped (\'). Many users don't notice incidental text in the status bar, so avoid putting mission-critical information there. Temporary messages conflict with browser-driven use of the status bar for loading progress and other purposes. To set the default status bar message (when all is at rest), see the defaultStatus property.

Example

<...onmouseover="window.status='Table of Contents';return true" onmouseout = "window.status = '';return true">

Value

String.

Default

Empty string.

statusbar
See directories.

toolbar
See directories.

top NN 2 IE 3 DOM n/a
Read-only
This is an object reference to the browser window. Script statements from inside nested frames can refer to the browser window properties and methods or to variables or functions stored in the document loaded in the topmost position. Do not begin a reference with window.top, just top. To replace a frameset with a new document that occupies the entire browser window, assign a URL to the top.location.href property.

Example

top.location.href = "tableOfContents.html";

Value

window object reference.

Default

Browser window.

window NN 2 IE 3 DOM n/a
Read-only
This is an object reference to the browser window.

Example

if (window == top) { // load a frameset location.href = "mainFrameset.html"; }

Value

window object reference.

Default

Browser window.

addEventListener( ) NN 6 IE n/a DOM n/a
addEventListener("eventType", listenerFunction, useCapture)
Although the window object as we know it is not officially part of the W3C DOM, Netscape 6 implements this W3C DOM event model method for the window object. See the addEventListener( ) method discussion among the shared methods described earlier in this chapter.

alert( ) NN 2 IE 3 DOM n/a
alert("message")
Displays an alert dialog box with a message of your choice. Script execution halts while the dialog box appears. A single button lets the user close the dialog. The title bar of the window (and the "JavaScript Alert" legend in earlier browser versions) cannot be altered by script.

Returned Value

None.

Parameters

message

Any string.

attachEvent( ) NN n/a IE 5(Win) DOM n/a
attachEvent("eventName", functionReference)
This IE event model method, shared among all element objects, is also a member of the window object. See the attachEvent( ) method discussion among the shared methods described earlier in this chapter.

back( ) NN 4 IE n/a DOM n/a
Navigates one step backward through the history list of the window or frame. You may prefer the cross-browser history.back( ) method.

Returned Value

None.

Parameters

None.

blur( ) NN 3 IE 4 DOM n/a
Removes focus from the window and fires an onBlur event (in IE). No other element necessarily receives focus as a result, but if another IE window is open at the time, the current window moves to the rear of the stack.

Returned Value

None.

Parameters

None.

captureEvents( ) NN 4 IE n/a DOM n/a
captureEvents(eventTypeList)
Instructs the browser to grab events of a specific type before they reach their intended target objects. The object invoking this method must then have event handlers defined for the given event types to process the event. Although this method is part of the Navigator 4 event model, it continues to be supported in Netscape 6, creating the equivalent of a W3C DOM capture-mode event listener for the document object. Continue to use this method if you must support Navigator 4, but migrate new code to the W3C DOM event listener syntax as described in Chapter 6.

Returned Value

None.

Parameters

eventTypeList

A comma-separated list of case-sensitive event types as derived from the available Event object constants, such as Event.CLICK or Event.MOUSEMOVE.

clearInterval( ) NN 4 IE 4 DOM n/a
clearInterval(intervalID)
Turns off the interval looping action referenced by the intervalID parameter. See setInterval( ) for how to initiate such a loop.

Returned Value

None.

Parameters

intervalID

An integer created as the return value of a setInterval( ) method.

clearTimeout( ) NN 2 IE 3 DOM n/a
clearTimeout(timeoutID)
Turns off the timeout delay counter referenced by the timeoutID parameter. See setTimeout( ) for how to initiate such a delay.

Returned Value

None.

Parameters

timeoutID

An integer created as the return value of a setTimeout( ) method.

close( ) NN 2 IE 3 DOM n/a
Closes the current window. A script in a subwindow cannot close the main window without receiving the user's explicit permission from a security dialog box. A window can close itself (i.e., from a script running in the same window) or a window it generated via the window.open( ) method.

Returned Value

None.

Parameters

None.

confirm( ) NN 2 IE 3 DOM n/a
confirm("message")
Displays a dialog box with a message and two clickable buttons. Script execution halts while the dialog box appears. One button indicates a Cancel operation; the other button indicates the user's approval (OK or Yes). The text of the buttons is not scriptable. The message should ask a question to which either button would be a logical reply. A click of the Cancel button returns a value of false; a click of the OK button returns a value of true.
Because this method returns a Boolean value, you can use this method inside a condition expression:
if (confirm("Reset the entire form?")) { document.forms[0].reset( ); }

Returned Value

Boolean value: true | false.

Parameters

message

Any string, usually in the form of a question.

createPopup( ) NN n/a IE 5.5(Win) DOM n/a
Opens a blank popup rectangular space that can be populated with HTML content, yet the space can extend across frame boundaries and even window borders. Scripts must assign content (not an external URL) to the popup object returned by the method. See the popup object for more details and an example of usage.

Returned Value

popup object reference.

Parameters

None.

detachEvent( ) NN n/a IE 5(Win) DOM n/a
detachEvent("eventName", functionReference)
This IE event model method, shared among all element objects, is also a member of the window object. See the detachEvent( ) method discussion among the shared methods described earlier in this chapter.

disableExternalCapture( ), enableExternalCapture( ) NN |4| IE n/a DOM n/a
With signed scripts and the user's permission, a script can capture events in other windows or frames that come from domains other than the one that served the document with event-capturing scripts. Navigator 4 only.

Returned Value

None.

Parameters

None.

dispatchEvent( ) NN 6 IE n/a DOM 2
dispatchEvent(eventObjectReference)
Although the window object is not officially part of the W3C DOM, Netscape 6 implements this W3C DOM event model method for the window object. See the dispatchEvent( ) method discussion among the shared methods described earlier in this chapter.

execScript( ) NN n/a IE 4 DOM n/a
execScript(expressionList [, language])
Evaluates one or more script expressions in any scripting language embedded in the browser. Expressions must be contained within a single string; multiple expressions are delimited with semicolons:
window.execScript("var x = 3; alert(x * 3)")
The default script language is JavaScript. If you need to see results of the script execution, provide for the display of resulting data in the script expressions, as shown in the example. The execScript( ) method itself returns no value.

Returned Value

None.

Parameters

expressionList

String value of one or more semicolon-delimited script expressions.

language

String value for a scripting language: JavaScript | JScript | VBS | VBScript.

find( ) NN 4 IE n/a DOM n/a
find("searchString"[, matchCase[, searchUpward]])
Searches the document body text for a string and selects the first matching string. Optionally, you can specify whether the search should be case-sensitive or should search upward in the document. With the found text selected in Navigator 4, you can then use the document.getSelection( ) method to grab a copy of the found text. You don't, however, have nearly the dynamic content abilities afforded by Internet Explorer 4's TextRange object (for Win32). This method is disconnected in Netscape 6 (it always returns false), but is reconnected in Netscape 7.

Returned Value

Boolean value: true if a match was found; false if not or Netscape 6 only.

Parameters

searchString

String for which to search the document.

matchCase

Boolean value: true to allow only exact, case-sensitive matches; false (default) to use case-insensitive search.

searchUpward

Boolean value: true to search from the current selection position upward through the document; false (default) to search forward from the current selection position.

focus( ) NN 3 IE 4 DOM n/a
Brings the window to the front of all regular browser windows and fires the onFocus event (in IE). If another window had focus at the time, that other window receives an onBlur event.

Returned Value

None.

Parameters

None.

forward( ) NN 4 IE n/a DOM n/a
Navigates one step forward through the history list of the window or frame. If the forward history has no entries, no action takes place.

Returned Value

None.

Parameters

None.

GetAttention( ) NN |6| IE n/a DOM n/a
Mistakenly exposed to scripters, this method calls upon the operating system's way of alerting a user that the application needs attention. In Windows, the Taskbar box for the browser window flashes; in the Mac OS, a beep sounds, and a bullet appears next to the application in the Application menu. If the browser window is already at the front, no user signal appears. Removed for Netscape 7.

Returned Value

None.

Parameters

None.

getComputedStyle( ) NN 6 IE n/a DOM 2
getComputedStyle(elementNodeReference, "pseudoElementName")
Returns a style object (specifically, a CSSStyleDeclaration object in the W3C DOM terminology) showing the net cascade of style settings that affect the element passed as the first parameter. To retrieve a particular style attribute value (including a value inherited from the default browser style sheet), use the getPropertyValue( ) method of the style object returned from this method:
var compStyle = getComputedStyle(document.getElementById("myP"), ""); var pBGColor = compStyle.getPropertyValue("background-color");
See the style object for additional details.

Returned Value

style (CSSStyleDeclaration) object reference.

Parameters

elementNodeReference

Reference to an element node in the document tree that becomes the selection.

pseudoElementName

String name of a pseudo-element (e.g., :first-line) or an empty string.

getSelection( ) NN 6 IE n/a DOM n/a
Returns a selection object, which can then be turned into a W3C DOM Range object. This method takes the place of the old document.getSelection( ) method, which is deprecated in Netscape 6. The corresponding IE operation is the document.selection property. See the selection object for details on working with a selection.

Returned Value

selection object reference.

Parameters

None.

home( ) NN 4 IE n/a DOM n/a
Navigates to the URL designated as the home page for the browser. This is the same as the user clicking on the Home button.

Returned Value

None.

Parameters

None.

moveBy( ) NN 4 IE 4 DOM n/a
moveBy(deltaX, deltaY)
This is a convenience method that shifts the location of the window by specified pixel amounts along both axes. To shift along only one axis, set the other value to zero. Positive values for deltaX shift the window to the right; negative values to the left. Positive values for deltaY shift the window downward; negative values upward.

Returned Value

None.

Parameters

deltaX

Positive or negative pixel count of the change in horizontal direction of the window.

deltaY

Positive or negative pixel count of the change in vertical direction of the window.

moveTo( ) NN 4 IE 4 DOM n/a
moveTo(x, y)
This is a convenience method that shifts the location of the current window to a specific coordinate point. The moveTo( ) method uses the screen coordinate system.

Returned Value

None.

Parameters

x

Positive or negative pixel count relative to the top of the screen.

y

Positive or negative pixel count relative to the left edge of the screen.

navigate( ) NN n/a IE 3 DOM n/a
navigate(URL)
Loads a new document into the window or frame. This is the IE-specific way of assigning a value to the window.location.href property.

Returned Value

None.

Parameters

URL

A complete or relative URL as a string.

open( ) NN 2 IE 3 DOM n/a
open("URL", "windowName"[, "windowFeatures"]) open("URL", "windowName"[, "windowFeatures"][, replaceFlag])
Opens a new window (without closing the original one). You can specify a URL to load into the new window or set that parameter to an empty string to allow scripts to document.write( ) into that new window. The windowName parameter lets you assign a name that can be used by target attributes of link and form elements. This name is not to be used in script references as frame names are. Instead, a script reference to a subwindow must be to the window object returned by the window.open( ) method. Therefore, if your scripts must communicate with a window opened in this manner, it is best to save the returned value as a global variable so that future statements can use it.
A potential problem with subwindows is that they can be buried under the main window if the user clicks on the main window (or a script gives it focus). Any script that opens a subwindow should also include a focus( ) method for the subwindow (in Navigator 3 and later, and in IE 4 and later) to make sure it comes to the front in case it is already open. Subsequent invocations of the window.open( ) method in which the windowName parameter is the same as an earlier call automatically address the previously opened window, even if it is underneath the main window (and thus without bringing the window to the front).
The optional third parameter gives you control over various physical attributes of the subwindow. The windowFeatures parameter is a single string consisting of a comma-delimited list (without spaces between items) of attribute/value pairs:
newWindow = window.open("someDoc.html","subWind", "status,menubar,height=400,width=300"); newWindow.focus( );
By default, all window attributes are turned on and the subwindow opens to the same size that the browser would use to open a new window from the File menu. But if your script specifies even one attribute, all settings are turned off. Therefore, use the windowFeatures parameter to specify those features that you want turned on.
If you encounter problems referencing a subwindow immediately after it is created, the problem is most likely a timing issue (affecting IE for Windows more than others). Script statements seem to want to reference the window before it exists completely. To work around the problem, place the code that works with the subwindow in a separate function, and invoke that function via the setTimeout( ) method, usually with no more than 50 milliseconds needed.
Managing multiple windows through scripts can be difficult. Security restrictions across domains frequently foil the best intentions. Users aren't always fond of windows appearing and hiding on their own. If your audience uses newer browsers, consider simulating windows with positioned elements.

Returned Value

Window object reference.

Parameters

URL

A complete or relative URL as a string. If an empty string, no document loads into the window.

windowName

An identifier for the window to be used by target attributes. This is different from the title attribute of the document that loads into the window.

windowFeatures

A string of comma-delimited features to be turned on in the new window. Do not put spaces after the comma delimiters. The list of possible features is long, but a number of them are specific to Navigator 4 or later and require signed scripts because they are potentially a privacy and security concern to unsuspecting users. The features are listed as follows. To turn on a window feature, simply include its case-insensitive name in the comma-separated list. Only attributes specifying dimensions require values be assigned.

Attribute

NN

IE

Description

alwaysLowered

4

n/a

Always behind all other browser windows. Signed script required.

alwaysRaised

4

n/a

Always in front of all other browser windows. Signed script required.

channelMode

n/a

4

Show in theater mode with channel band.

copyhistory

2

3

Copy history listing from opening window to new window.

dependent

4

n/a

Subwindow closes if the window that opened it closes.

directories

2

3

Display directory buttons.

fullscreen

n/a

4

Display no titlebar or menus

height

2

3

Window height in pixels.

hotkeys

4

n/a

Disables menu keyboard shortcuts (except Quit and Security Info).

innerHeight

4

n/a

Content region height. Signed script required for very small measures.

innerWidth

4

n/a

Content region width. Signed script required for very small measures.

left

6

4

Offset of window's left edge from left edge of screen.

location

2

3

Display Location (or Address) text field.

menubar

2

3

Display menubar (a menubar is always visible on Mac).

outerHeight

4

n/a

Total window height. Signed script required for very small measures.

outerWidth

4

n/a

Total window width. Signed script required for very small measures.

resizable

2

3

Allow window resizing (always allowed on Mac).

screenX

4

n/a

Offset of window's left edge from left edge of screen. Signed script required to move window offscreen.

screenY

4

n/a

Offset of window's top edge from top edge of screen. Signed script required to move window offscreen.

scrollbars

2

3

Display scrollbars if document is too large for window.

status

2

3

Display status bar.

titlebar

4

n/a

Displays titlebar. Set this value to no to hide the titlebar. Signed script required.

toolbar

2

3

Display toolbar (with Back, Forward, and other buttons).

top

6

4

Offset of window's top edge from top edge of screen.

width

2

3

Window width in pixels.

z-lock

4

n/a

New window is fixed below browser windows. Signed script required.

replaceFlag

Boolean value (for IE only) that controls the effect of the new window's URL on the global history of the browser. Set to true to replace the current page with the new window's URL (so that the current page won't be accessed through the Back button); set to false to add the new window's URL to the history, as normal.

print( ) NN 4 IE 5 DOM n/a
Starts the printing process for the window or frame. A user must still confirm the print dialog box to send the document to the printer. This method is the same as clicking the browser's Print button or selecting Print from the File menu.

Returned Value

None.

Parameters

None.

prompt( ) NN 2 IE 3 DOM n/a
prompt("message", "defaultReply")
Displays a dialog box with a message, a one-line text entry field, and two clickable buttons. Script execution halts while the dialog box appears. The message should urge the user to enter a specific kind of answer. One button indicates a Cancel operation; the other button indicates the user's approval of the text entered into the field (OK or Yes). The text of the buttons is not scriptable. A click of the Cancel button returns a value of null; a click of the OK button returns a string of whatever is in the text entry field at the time (including the possibility of an empty string). It is up to your scripts to test for the type of response (if any) supplied by the user.

Returned Value

When clicking the OK button, a string of the text entry field; when clicking Cancel, null.

Parameters

message

Any string.

defaultReply

Any string that suggests an answer. Always supply a value, even if an empty string.

releaseEvents( ) NN 4 IE n/a DOM n/a
releaseEvents(eventTypeList)
The opposite of window.captureEvents( ), this method turns off event capture at the window level for one or more specific events named in the parameter list. Although this method is part of the Navigator 4 event model, it continues to be supported in Netscape 6, creating the equivalent of a W3C DOM capture-mode event listener for the document object. Continue to use this method if you must support Navigator 4, but migrate new code to the W3C DOM event listener syntax as described in Chapter 6.

Returned Value

None.

Parameters

eventTypeList

A comma-separated list of case-sensitive event types as derived from the available Event object constants, such as Event.CLICK or Event.MOUSEMOVE.

removeEventListener( ) NN 6 IE n/a DOM n/a
removeEventListener("eventType", listenerFunction, useCapture)
Although the window object as we know it is not officially part of the W3C DOM, Netscape 6 implements this W3C DOM event model method for the window object. See the removeEventListener( ) method discussion among the shared methods described earlier in this chapter.

resizeBy( ) NN 4 IE 4 DOM n/a
resizeBy(deltaX, deltaY)
This is a convenience method that shifts the width and height of the window by specified pixel amounts. To adjust along only one axis, set the other value to zero. Positive values for deltaX make the window wider; negative values make the window narrower. Positive values for deltaY make the window taller; negative values make the window shorter. The top and left edges remain fixed; only the right and bottom edges are moved.

Returned Value

None.

Parameters

deltaX

Positive or negative pixel count of the change in horizontal dimension of the window.

deltaY

Positive or negative pixel count of the change in vertical dimension of the window.

resizeTo( ) NN 4 IE 4 DOM n/a
resizeTo(x, y)
This is a convenience method that adjusts the height and width of the window to specific pixel sizes. The top and left edges of the window remain fixed, while the bottom and right edges move in response to this method.

Returned Value

None.

Parameters

x

Width in pixels of the window.

y

Height in pixels of the window.

routeEvent( ) NN |4| IE n/a DOM n/a
routeEvent(event)
Used inside an event handler function, this method directs Navigator 4 (only) to let the event pass to its intended target object.

Returned Value

None.

Parameters

event

A Navigator 4 event object.

scroll( ) NN 3 IE 4 DOM n/a
scroll(x, y)
Sets the scrolled position of the document inside the current window or frame. To return the document to its unscrolled position, set both parameters to zero.

Returned Value

None.

Parameters

x

Horizontal measure of scrolling within the window.

y

Vertical measure of scrolling within the window.

scrollBy( ) NN 4 IE 4 DOM n/a
scrollBy(deltaX, deltaY)
Scrolls the document in the window by specified pixel amounts along both axes. To adjust along only one axis, set the other value to zero. Positive values for deltaX scroll the document to the left (so the user sees content to the right in the document); negative values scroll the document to the right. Positive values for deltaY scroll the document upward (so the user sees content lower in the document); negative values scroll the document downward. Scrolling does not continue past the zero coordinate points (except in Navigator 4 for the Macintosh).

Returned Value

None.

Parameters

deltaX

Positive or negative pixel count of the change in horizontal scroll position.

deltaY

Positive or negative pixel count of the change in vertical scroll position.

scrollByLines( ), scrollByPages( ) NN 6 IE n/a DOM n/a
scrollByLines(intervalCount) scrollByPages(intervalCount)
Scroll the document in the window downward (positive value) or upward (negative value) by the increment of lines or pages. The methods perform the same actions as the user clicking on the arrow and "page" regions of the vertical scrollbar, respectively.

Returned Value

None.

Parameters

intervalCount

Positive or negative count of the change in vertical scroll position. Units are governed by the method choice (lines or pages).

scrollTo( ) NN 4 IE 4 DOM n/a
scrollTo(x, y)
Scrolls the document in the window to a specific scrolled pixel position.

Returned Value

None.

Parameters

x

Horizontal position in pixels of the window.

y

Vertical position in pixels of the window.

setCursor( ) NN |6| IE n/a DOM n/a
setCursor("cursorType")
Changes the cursor to a desired type. This method is an alternate to the style sheet cursor attribute. Starting with Netscape 6.2, a cursor changed with this method maintains its shape until explicitly changed to another shape or the default auto style. Precise cursor shape is determined by the operating system repertoire. Removed from Netscape 7.

Returned Value

None.

Parameters

cursorShape

String name of a cursor style such as:

alias

auto

cell

context-menu

copy

count-down

count-up

count-up-down

crosshair

default

e-resize

grab

grabbing

help

move

n-resize

ne-resize

nw-resize

pointer

s-resize

se-resize

spinning

sw-resize

text

w-resize

wait

setInterval( ) NN 4 IE 4 DOM n/a
setInterval("scriptExpression", msecs[, language]) setInterval(functionReference, msecs[, arg1, ..., argN])
Starts a timer that continually invokes the expression every msecs. Other scripts can run in the time between calls to expression. This method is useful for starting animation sequences that must reposition an element along a path at a fixed rate of speed. A repetitive call to an animation function would look like the following:
intervalID = setInterval("advanceAnimation( )", 500);
The parameter situation can be confusing. The simplest, most cross-browser approach is to invoke a script function (as a string), with the interval time (in milliseconds) as the second parameter. Any script expression will execute, but the expression is evaluated at the time the setInterval( ) method is invoked. Therefore, if you concatenate variables into this expression, their values must be ready when the setInterval( ) method runs, even though the variables won't be used until some milliseconds later.
IE permits a third parameter to specify a different scripting language in which the expression is to run. Unless it is a VBScript expression, you can omit this parameter. Navigator, however, lets you substitute a function reference (not a string) as the first parameter, and pass a comma-delimited list of parameters that go to the function call. These parameters go after the msecs time, and they can be any data types.
This method returns an ID that should be saved as a global variable and be available as the parameter for the clearInterval( ) method to stop the looping timer. Unless you explicitly clear the interval process, it will continue to execute until the page unloads.

Returned Value

Integer acting as an identifier for this repetitive process.

Parameters

scriptExpression

Any script expression as a string, but most commonly a function. The function name with parentheses is placed inside the parameter's quoted string.

functionReference

Nonstring function reference (function name without the parentheses).

msecs

The time in milliseconds between invocations of the expression or functionReference.

args

An optional comma-delimited list of parameters to be passed to a function used as the functionReference parameter. Navigator only.

language

An optional scripting language specification of the expression parameter (default is JavaScript). IE for Windows only.

setTimeout( ) NN 2 IE 3 DOM n/a
setTimeout("scriptExpression", msecs[, language]) setTimeout(functionReference, msecs[, arg1, ..., argN])
Starts a one-time timer that invokes the scriptExpression or functionReference after a delay of msecs. Other scripts can run while the browser waits to invoke the expression. A statement that sets the timer would look like the following:
timeoutID = setTimeout("finishWindow( )", 50);
The parameter situation can be confusing. The simplest, most cross-browser approach is to invoke a script function (as a string), with the interval time (in milliseconds) as the second parameter. Any script expression will execute, but the expression is evaluated at the time the setTimeout( ) method is invoked. Therefore, if you concatenate variables into this expression, their values must be ready when the setTimeout( ) method runs, even though the variables won't be used until some milliseconds later.
IE permits a third parameter to specify a different scripting language in which the expression is to run. Unless it is a VBScript expression, you can omit this parameter. Navigator, however, lets you substitute a function reference (not a string) as the first parameter, and pass a comma-delimited list of parameters that go to the function call. These parameters go after the msecs time, and they can be any data types.
This method returns an ID that should be saved as a global variable and be available as the parameter for the clearTimeout( ) method to stop the timer before it expires and invokes the delayed action.
The setTimeout( ) method can be made to behave like the setInterval( ) method in some constructions. If you place a setTimeout( ) method as the last statement of a function and direct the method to invoke the very same function, you can create looping execution with a timed delay between executions. This is how earlier browsers (before the setInterval( ) method was available) scripted repetitive tasks, such as displaying updated digital clock displays in form fields or the status bar.

Returned Value

Integer acting as an identifier.

Parameters

scriptExpression

Any script expression as a string, but most commonly a function. The function name with parentheses is placed inside the parameter's quoted string.

functionReference

Nonstring function reference (function name without the parentheses).

msecs

The time in milliseconds that the browser waits before invoking the expression.

args

An optional comma-delimited list of parameters to be passed to a function used as the functionReference parameter. Navigator only.

language

An optional scripting language specification of the expression parameter (default is JavaScript). IE for Windows only.

showHelp( ) NN n/a IE 4(Win) DOM n/a
showHelp("URL")
Displays a WinHelp window with the .hlp document specified with the URL parameter.

Returned Value

None.

Parameters

URL

A complete or relative URL to a WinHelp formatted file as a string.

showModalDialog( ) NN n/a IE 4 DOM n/a
showModalDialog("URL"[, arguments[, "features"]])
Displays a special window that remains atop all browser windows until the user explicitly closes the dialog window. This kind of window is different from the browser windows generated with the window.open( ) method. A modal dialog has no scriptable relationship with its opening window once the dialog window is opened. All values necessary for displaying content must be in the HTML document that loads into the window or be passed as parameters. The modal dialog may then have a script set its returnValue property, which becomes the value returned to the original script statement that opened the modal dialog box as the returned value of the showModalDialog( ) method.
You can pass arguments to the modal dialog by creating a data structure that best suits the data. For a single value, a string will do. For multiple values, you can create a string with a unique delimiter between values, or create an array and specify the array as the second parameter for the showModalDialog( ) method. A script in the document loaded into the modal dialog can then examine the window.dialogArguments property and parse the arguments as needed for its scripting purposes. See the dialogArguments property for an example.
The third optional parameter lets you set physical characteristics of the dialog window. These characteristics are specified in a CSS-style syntax. Dimensions for dialogWidth, dialogHeight, dialogLeft, and dialogTop should be specified in pixels. An example of a call to a modal dialog is as follows:
var answer = window.showModalDialog("subDoc.html",argsVariable, "dialogWidth:300px; dialogHeight:200px; center:yes");
None of the third parameter characteristics are recognized by the Macintosh version of Internet Explorer 4, which creates a full-size modal dialog.
Modal dialogs can present problems for scripts if the window loads a frameset. A script in one of the frames will likely not be able to reference the parent or top window to gain access to either the window's close( ) method or content in another frame.

Returned Value

The value (if any) assigned to the window.returnValue property in the document loaded into the modal dialog window.

Parameters

URL

A complete or relative URL as a string.

arguments

Data as a number, string, or array to be passed to the scripts in the document loaded into the modal dialog.

features

A string of semicolon-delimited style attributes and values to set the physical characteristics of the modal dialog. Available attributes are as shown in the following table.

Feature

Value

Description

center

yes | no | 1 | 0 | on | off

Center the dialog

dialogHeight

Length/units

Outer height of dialog

dialogLeft

Integer

Left pixel offset (overrides center)

dialogTop

Integer

Top pixel offset (overrides center)

dialogWidth

Length/units

Outer width of dialog

edge

raised | sunken

Transition style between border and content area

help

yes | no | 1 | 0 | on | off

Display help icon in titlebar

resizable

yes | no | 1 | 0 | on | off

Dialog is resizable

status

yes | no | 1 | 0 | on | off

Display status bar

showModelessDialog( ) NN n/a IE 5(Win) DOM n/a
showModelessDialog("URL"[, arguments[, "features"]])
Displays a special window that remains atop all browser windows, yet allows the user to interact with other open windows and their content. Other than browser versions that support it, this method has the same parameters and characteristics as the showModalDialog( ) method. See that method for details.

sizeToContent( ) NN 6 IE n/a DOM n/a
Lets the browser determine the optimum window size to display the window's content. Suitable for subwindows that display a limited amount of information.

Returned Value

None.

Parameters

None.

stop( ) NN 4 IE n/a DOM n/a
Halts the download of external data of any kind. This method is the same as clicking the browser's Stop button.

Returned Value

None.

Parameters

None.

xml NN n/a IE 5(Win) DOM n/a

The xml object reflects the Microsoft proprietary xml element, creating a so-called XML data island inside an HTML document.

HTML Equivalent

<xml>

Object Model Reference

[window.]document.getElementById("elementID")

Object-Specific Properties

src

XMLDocument

Object-Specific Methods

None.

Object-Specific Event Handler Properties

None.

src NN n/a IE 5(Win) DOM n/a
Read/Write
Contains the URL of the external XML document loaded into the data island. To load a new document after the fact, assign a new URL to this property.

Example

document.getElementById("xmlData").src = "xml/latestResults.xml";

Value

Relative or complete URL string.

Default

None.

XMLDocument NN n/a IE 5(Win) DOM n/a
Read-only
This is a reference to the Microsoft XML document object. This object resembles the W3C DOM core document object in many ways, but Microsoft provides a different syntax to read and write data from the object. See http://msdn.microsoft.com/xml/reference/xmldom/start.asp for details.

Example
var xmlDoc = document.getElementById("XMLData").XMLDocument;
Value

Reference to an MS XML document object.

Default

None.

`alternate`	`appendix`	`bookmark`	`chapter`	`contents`
`copyright`	`glossary`	`help`	`index`	`next`
`prev`	`section`	`start`	`stylesheet`	`subsection`

Constant	Equivalent integer
`cssRuleReference.UNKNOWN_RULE`	`0`
`cssRuleReference.STYLE_RULE`	`1`
`cssRuleReference.CHARSET_RULE`	`2`
`cssRuleReference.IMPORT_RULE`	`3`
`cssRuleReference.MEDIA_RULE`	`4`
`cssRuleReference.FONT_FACE_RULE`	`5`
`cssRuleReference.PAGE_RULE`	`6`

`NodeFilter.SHOW_ALL`	`NodeFilter.SHOW_ATTRIBUTE`
`NodeFilter.SHOW_CDATA_SECTION`	`NodeFilter.SHOW_COMMENT`
`NodeFilter.SHOW_DOCUMENT`	`NodeFilter.SHOW_DOCUMENT_FRAGMENT`
`NodeFilter.SHOW_DOCUMENT_TYPE`	`NodeFilter.SHOW_ELEMENT`
`NodeFilter.SHOW_ENTITY`	`NodeFilter.SHOW_ENTITY_REFERENCE`
`NodeFilter.SHOW_NOTATION`	`NodeFilter.SHOW_PROCESSING_INSTRUCTION`
`NodeFilter.SHOW_TEXT`

`NodeFilter.FILTER_ACCEPT`	`NodeFilter.FILTER_REJECT`
`NodeFilter.FILTER_SKIP`

Code	Constant	Most likely cause
`1`	`INDEX_SIZE_ERR`	An integer offset parameter is out of the range of the target object
`2`	`DOMSTRING_SIZE_ERR`	Property string value is too large for the hosting language
`3`	`HIERARCHY_REQUEST_ERR`	Appending a child to a node not capable of children
`4`	`WRONG_DOCUMENT_ERR`	Inserting a node created from a different document (without passing through the import process)
`5`	`INVALID_CHARACTER_ERR`	Assigning an identifier with an illegal character
`6`	`NO_DATA_ALLOWED_ERR`	Assigning data to a node that doesn't allow data
`7`	`NO_MODIFICATION_ALLOWED_ERR`	Assigning a value to a read-only property
`8`	`NOT_FOUND_ERR`	Method parameter reference to a nonexistent node in the object's scope
`9`	`NOT_SUPPORTED_ERR`	Invoking an XML-only method in an HTML document
`10`	`INUSE_ATTRIBUTE_ERR`	Method parameter to an `Attr` node that already belongs to another element (without cloning the `Attr` first)
`11`	`INVALID_STATE_ERR`	Referencing a node that is not readable or writable
`12`	`SYNTAX_ERR`	A slippery keyboard
`13`	`INVALID_MODIFICATION_ERR`	Modifying the type of a node
`14`	`NAMESPACE_ERR`	Namespace mismatch or malformed name
`15`	`INVALID_ACCESS_ERR`	You can't go there

	Event	UIEvent	MouseEvent	KeyEvent[22]	TextEvent[23]	MutationEvent
Event methods
`initEvent( )`	•	•	•	•	•	•
`getPreventDefault( )22`	•	•	•	•		•
`preventDefault( )`	•	•	•	•	•	•
`stopPropagation( )`	•	•	•	•	•	•
UIEvent methods
`initUIEvent( )`		•
MouseEvent methods
`initMouseEvent( )`			•
KeyEvent methods
`initKeyEvent( )`				•
TextEvent methods
`checkModifier( )23`					•
`initModifier( )23`					•
`initTextEvent( )23`					•
MutationEvent methods
`initMutationEvent( )`						•

Value	Constant	Description
`1`	`evtObj.MODIFICATION`	Changed value of existing `Attr` node
`2`	`evtObj.ADDITION`	The `Attr` node was added to the document tree
`3`	`evtObj.REMOVAL`	The `Attr` node was removed from the document tree

Button(s)	IE	NN 6	W3C DOM
No button	`0`	`null`	`null`
Left (primary)	`1`	`0`	`0`
Middle	`4`	`1`	`1`
Right	`2`	`2`	`2`
Left + Right	`3`	n/a	n/a
Left + Middle	`5`	n/a	n/a
Right + Middle	`6`	n/a	n/a
Left + Middle + Right	`7`	n/a	n/a

Value	Constant
`1`	`eventObjectReference.CAPTURING_PHASE`
`2`	`eventObjectReference.AT_TARGET`
`3`	`eventObjectReference.BUBBLING_PHASE`

Mutation event type	eventObj.relatedNode reference
`DOMNodeInserted`	Parent node of inserted node
`DOMNodeRemoved`	Original parent node of removed node
`DOMAttrModified`	`Attr` node

Type	Example
`A`	A, B, C, ...
`a`	a, b, c, ...
`I`	I, II, III, ...
`i`	i, ii, iii, ...
`1`	1, 2, 3, ...

Property	Value	Description
`commonAncestorContainer`	`[object` `HTMLParagraphElement]`	The `p` element embraces both the start and end points.
`startContainer`	`[object Text]`	Start point is within a text node.
`startOffset`	`19`	Start point is at the 20th (zero-based index of 19) character from the start of its container, the text node.
`endContainer`	`[object` `HTMLParagraphElement]`	End point is designated as the end of the `span` element, which makes the next outer `p` element the end point's container.
`endOffset`	`2`	End point is at the 3rd (zero-based index of 2) node in the context of its `endContainer` `p` element (first node is a text node; second node is the `span` element; end point is at the start of the third node of the `p` element).

Comparison type	Description
`rng``.START_TO_START`	Comparing the start position of the current range against the start position of the source range
`rng``.START_TO_END`	Comparing the start position of the current range against the end position of the source range
`rng``.END_TO_END`	Comparing the end position of the current range against the end position of the source range
`rng``.END_TO_START`	Comparing the end poisition of the current range against the start position of the source range

Constant	Value	Description
`rng``.NODE_BEFORE`	`0`	Entire node comes before the range.
`rng``.NODE_AFTER`	`1`	Entire node comes after the range.
`rng``.NODE_BEFORE_AND_AFTER`	`2`	Node starts before the current range and ends after it.
`rng``.NODE_INSIDE`	`3`	Node is contained in its entirety within the scope of the range.

Value	Description
`-1`	Point comes before the start of the range.
`0`	Point is located within the range.
`1`	Point comes after the end of the range.

Property	Value	Description
`startContainer`	`[object HTMLParagraphElement]`	Start point is right before the `span` element.
`startOffset`	`1`	Start point is at the 2nd (zero-based index of 1) node inside the `p` element.
`endContainer`	`[object` `HTMLParagraphElement]`	End point is immediately after the `span` element.
`endOffset`	`2`	End point is at the 3rd (zero-based index of 2) node in the context of its `endContainer` `p` element.

Property	Value	Description
`startContainer`	`[object HTMLSpanElement]`	Start point is just inside the `span` element.
`startOffset`	`0`	Start point is at the 1st (zero-based index of 0) node inside the `span` element.
`endContainer`	`[object` `HTMLSpanElement]`	End point is immediately after the `span` element's content.
`endOffset`	`1`	End point is at a position where the 2nd (zero-based index of 1) node, if present, would be in the context of its `endContainer` `span` element.

Property	Value	Description
`startContainer`	`[object Text]`	Start point is at the beginning of the text node.
`startOffset`	`0`	Start point is at the 1st (zero-based index of 0) position of the text node.
`endContainer`	`[object Text]`	End point is collapsed.
`endOffset`	`0`	End point is collapsed.

Code	Constant	Most Likely Cause
`1`	`BAD_BOUNDARYPOINTS_ERR`	The `surroundContents( )` method was applied to a range with a nonapplicable end point
`2`	`INVALID_NODE_TYPE_ERR`	The method tried to work in a nonapplicable type of node

Constant value pair	Percentage equivalents	Constant value pair	Percentage equivalents
`top left`	`0% 0%`	`center center`	`50% 50%`
`left top`	`0% 0%`	`right`	`100% 50%`
`top`	`50% 0%`	`right center`	`100% 50%`
`top center`	`50% 0%`	`center right`	`100% 50%`
`center top`	`50% 0%`	`bottom left`	`0% 100%`
`right top`	`100% 0%`	`left bottom`	`0% 100%`
`top right`	`100% 0%`	`bottom`	`50% 100%`
`left`	`0% 50%`	`bottom center`	`50% 100%`
`left center`	`0% 50%`	`center bottom`	`50% 100%`
`center left`	`0% 50%`	`bottom right`	`100% 100%`
`center`	`50% 50%`	`right bottom`	`100% 100%`

9.6. Alphabetical Object Reference

HTML Equivalent

Object Model Reference

Object-Specific Properties

Object-Specific Methods

Object-Specific Event Handler Properties

Example

Value

Default

Example

Value

Default

Example

Value

Default

Example

Value

Default

Example

Value

Default

Example

Value

Default

Example

Value

Default

Example

Value

Default

Example

Value

Default

Example

Value

Default

Example

Value

Default

Example

Value

Default

Example

Value

Default

Example

Value

Default

Example

Value

Default

Example

Value

Default

Example

Value

Default

Example

Value

Default

Value

Default

Value

Default

Example

Value

Default

Example

Value

Default

Example

Value

Default

Value

Default

Example

Value

Default

Example

Value

Cursor name	IE/Windows	IE/Mac	NN
`alias`	n/a	n/a	6
`all-scroll`	6	n/a	n/a
`auto`	4	4	6
`cell`	n/a	n/a	6
`col-resize`	6	n/a	n/a
`context-menu`	n/a	n/a	6
`copy`	n/a	n/a	6
`count-down`	n/a	n/a	6
`count-up`	n/a	n/a	6
`count-up-down`	n/a	n/a	6
`crosshair`	4	4	6
`default`	4	4	6
`e-resize`	4	4	6
`grab`	n/a	n/a	6
`grabbing`	n/a	n/a	6
`hand`	4	4	n/a
`help`	4	4	6
`move`	4	4	6
`n-resize`	4	4	6
`ne-resize`	4	4	6
`no-drop`	6	n/a	n/a
`not-allowed`	6	n/a	n/a
`nw-resize`	4	4	6
`pointer`	4	4	6
`progress`	6	n/a	n/a
`row-resize`	6	n/a	n/a
`s-resize`	4	4	6
`se-resize`	4	4	6
`spinning`	n/a	n/a	6
`sw-resize`	4	4	6
`text`	4	4	6
`url(``uri``)`	6	n/a	n/a
`vertical-text`	6	n/a	n/a
`w-resize`	4	4	6
`wait`	4	4	6

Display type	IE/Windows	IE/Mac	NN
`block`	5	4	6
`inline`	5	4	6
`inline-block`	5.5	n/a	n/a
`none`	4	4	6
`run-in`	n/a	5	6
`table-footer-group`	5.5	5	6
`table-header-group`	5	5	6

Type	Example
`decimal`	1, 2, 3, ...
`decimal-leading-zero`	01, 02, 03, ...
`lower-alpha`	a, b, c, ...
`lower-greek`	α, β, γ, ...
`lower-roman`	i, ii, iii, ...
`upper-alpha`	A, B, C, ...
`upper-roman`	I, II, III, ...

`vCard.Business.City`	`vCard.Business.Country`
`vCard.Business.Fax`	`vCard.Business.Phone`
`vCard.Business.State`	`vCard.Business.StreetAddress`
`vCard.Business.URL`	`vCard.Business.Zipcode`
`vCard.Cellular`	`vCard.Company`
`vCard.Department`	`vCard.DisplayName`
`vCard.Email`	`vCard.FirstName`
`vCard.Gender`	`vCard.Home.City`
`vCard.Home.Country`	`vCard.Home.Fax`
`vCard.Home.Phone`	`vCard.Home.State`
`vCard.Home.StreetAddress`	`vCard.Home.Zipcode`
`vCard.Homepage`	`vCard.JobTitle`
`vCard.LastName`	`vCard.MiddleName`
`vCard.Notes`	`vCard.Office`
`vCard.Pager`

Code	Meaning
`0`	Used for system administration.
`1`	Used for research and/or product development.
`2`	Used for completion and support of current transaction.
`3`	Used to customize the content and design of a site.
`4`	Used to improve the content of the site, including advertisements.
`5`	Used for notifying visitors about updates to the site.
`6`	Used for contacting visitors for marketing of services or products.
`7`	Used for linking other collected information.
`8`	Used by site for other purposes.
`9`	Disclosed to others for customization or improvement of the content and design of the site.
`10`	Disclosed to others who may contact you for marketing of services and/or products.
`11`	Disclosed to others who may contact you for marketing of services and/or products, but you have the opportunity to ask a site not to do this.
`12`	Disclosed to others for any other purpose.

Attribute	NN	IE	Description
`alwaysLowered`	4	n/a	Always behind all other browser windows. Signed script required.
`alwaysRaised`	4	n/a	Always in front of all other browser windows. Signed script required.
`channelMode`	n/a	4	Show in theater mode with channel band.
`copyhistory`	2	3	Copy history listing from opening window to new window.
`dependent`	4	n/a	Subwindow closes if the window that opened it closes.
`directories`	2	3	Display directory buttons.
`fullscreen`	n/a	4	Display no titlebar or menus
`height`	2	3	Window height in pixels.
`hotkeys`	4	n/a	Disables menu keyboard shortcuts (except Quit and Security Info).
`innerHeight`	4	n/a	Content region height. Signed script required for very small measures.
`innerWidth`	4	n/a	Content region width. Signed script required for very small measures.
`left`	6	4	Offset of window's left edge from left edge of screen.
`location`	2	3	Display Location (or Address) text field.
`menubar`	2	3	Display menubar (a menubar is always visible on Mac).
`outerHeight`	4	n/a	Total window height. Signed script required for very small measures.
`outerWidth`	4	n/a	Total window width. Signed script required for very small measures.
`resizable`	2	3	Allow window resizing (always allowed on Mac).
`screenX`	4	n/a	Offset of window's left edge from left edge of screen. Signed script required to move window offscreen.
`screenY`	4	n/a	Offset of window's top edge from top edge of screen. Signed script required to move window offscreen.
`scrollbars`	2	3	Display scrollbars if document is too large for window.
`status`	2	3	Display status bar.
`titlebar`	4	n/a	Displays titlebar. Set this value to `no` to hide the titlebar. Signed script required.
`toolbar`	2	3	Display toolbar (with Back, Forward, and other buttons).
`top`	6	4	Offset of window's top edge from top edge of screen.
`width`	2	3	Window width in pixels.
`z-lock`	4	n/a	New window is fixed below browser windows. Signed script required.

Feature	Value	Description
`center`	`yes` \| `no` \| `1` \| `0` \| `on` \| `off`	Center the dialog
`dialogHeight`	Length/units	Outer height of dialog
`dialogLeft`	Integer	Left pixel offset (overrides center)
`dialogTop`	Integer	Top pixel offset (overrides center)
`dialogWidth`	Length/units	Outer width of dialog
`edge`	`raised` \| `sunken`	Transition style between border and content area
`help`	`yes` \| `no` \| `1` \| `0` \| `on` \| `off`	Display help icon in titlebar
`resizable`	`yes` \| `no` \| `1` \| `0` \| `on` \| `off`	Dialog is resizable
`status`	`yes` \| `no` \| `1` \| `0` \| `on` \| `off`	Display status bar


9.5. Shared Object Properties, Methods, and Events		10. Event Reference