home | O'Reilly's CD bookshelfs | FreeBSD | Linux | Cisco | Cisco Exam    

Dynamic HTML: The Definitive Reference, 2rd Ed.Dynamic HTML: The Definitive ReferenceSearch this book

9.6. Alphabetical Object Reference

aNN 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.

coordsNN 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.

dataFldNN 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.

dataFormatAsNN 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

dataSrcNN 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.

hashNN 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.

hostNN 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.

hostnameNN 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.

hrefNN 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.

hreflangNN 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.

MethodsNN 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.

mimeTypeNN 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.

nameNN 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.

namePropNN 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.

pathnameNN 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.

portNN 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.

protocolNN 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.

protocolLongNN 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

searchNN 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.

shapeNN 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

targetNN 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.

textNN 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.

urnNN 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.

AbstractView

See the window object.

acronym, cite, code, dfn, em, kbd, samp, strong, varNN 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.

addressNN n/a IE 4 DOM 1

The address object reflects the address element.

HTML Equivalent

<address>

Object Model Reference

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

Object-Specific Properties

None.

Object-Specific Methods

None.

Object-Specific Event Handler Properties

None.

allNN 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.

lengthNN 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.

anchorsNN 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.

lengthNN 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.

appletNN 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.

alignNN 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

altNN 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.

altHTMLNN 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.

archiveNN 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.

codeNN 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.

codeBaseNN 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.

dataFldNN 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.

dataSrcNN 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, widthNN 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, vspaceNN 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

nameNN 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.

objectNN 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.

srcNN 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.

appletsNN 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( )

lengthNN 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.

areaNN 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.

altNN 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.

coordsNN 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.

hashNN 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.

hostNN 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.

hostnameNN 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.

hrefNN 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.

noHrefNN 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

pathnameNN 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.

portNN 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.

protocolNN 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.

searchNN 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.

shapeNN 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).

targetNN 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.

areasNN 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( )

lengthNN 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, attributeNN 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.

expandoNN 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

nameNN 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.

ownerElementNN 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

specifiedNN 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

valueNN 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, NamedNodeMapNN 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.

lengthNN 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, uNN 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.

baseNN 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.

hrefNN 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.

targetNN 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

basefontNN 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.

faceNN 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.

sizeNN 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

bdoNN n/a IE n/a DOM 1

The bdo element is designed to assist in instances when, due to various conversions during text processing, the normal bidirectional algorithms must be explicitly overridden. The primary property of this object is dir, which is shared among all other element objects.

HTML Equivalent

<bdo>

Object-Specific Properties

None.

Object-Specific Methods

None.

Object-Specific Event Handler Properties

None.

bgsoundNN 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.

balanceNN 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

loopNN 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

srcNN 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.

volumeNN 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.

big

See b.

bodyNN 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

backgroundNN 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.

bgPropertiesNN 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.

bottomMarginNN 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

leftMarginNN 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).

noWrapNN 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

rightMarginNN 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).

scrollNN 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

topMarginNN 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).

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.

buttonNN 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.

dataFldNN 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.

dataFormatAsNN 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

dataSrcNN 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.

formNN 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.

nameNN 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.

statusNN 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

typeNN 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

valueNN 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.

cellsNN 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.

lengthNN 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.

centerNN 6 IE 4 DOM n/a

The center object reflects the center element. The W3C DOM does not support the deprecated HTML 4 center element. For backward compatibility, Netscape 6 treats the element as earlier browsers do, but the scriptable element is treated as a span object, whose default text-align style is set to center.

HTML Equivalent

<center>

Object Model Reference

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

Object-Specific Properties

None.

Object-Specific Methods

None.

Object-Specific Event Handler Properties

None.

checkbox

See input (type="checkbox").

CharacterData

See Text.

childrenNN 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.

lengthNN 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.

cite

See acronym.

clientInformation

See navigator.

clipboardDataNN 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, effectAllowedNN 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.

code

See acronym.

col, colgroupNN 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.

alignNN 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

chNN 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.

chOffNN 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.

spanNN 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

vAlignNN 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

widthNN 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, CommentNN 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.

dataNN 6 IE 6 DOM 1

Read/Write
Provides the text content of the comment. See Text.data.

lengthNN 6 IE 6 DOM 1

Read-only
Provides the character count of the comment data. See Text.length.

textNN 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.

CSSImportRule, CSSMediaRule, CSSPageRule

See CSSRule.

cssRule, CSSRule, ruleNN 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.

cssRulesNN 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.

cssTextNN 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.

encodingNN 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.

hrefNN 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.

mediaNN 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

parentRuleNN 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

parentStyleSheetNN 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.

readOnlyNN 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.

selectorTextNN 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.

styleNN 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.

styleSheetNN 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.

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.

CSSStyleDeclaration

See style.

CSSStyleSheet

See styleSheet.

currentStyleNN n/a IE 5(Win) DOM n/a

The currentStyle object (a property of all HTML element objects in IE 5 and later for Windows) provides read-only access to the effective (cascaded) style properties applied to the current element, including properties influenced by linked, imported, and explicit style sheet settings. This object is a property of all renderable HTML element objects and stands in contrast to an element's style object, which reports, and allows modification of, style sheet properties explicitly assigned to the inline style attribute.

Object Model Reference

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

Object-Specific Properties

See the style object.

Object-Specific Methods

See the style object.

Object-Specific Event Handler Properties

None.

custom, HTMLUnknownElementNN 6 IE 5 DOM 1

Provides scriptable access to author-defined elements. Such elements share properties, methods, and event handlers of generic HTML element objects, and usually have custom attributes associated with them.

HTML Equivalent

<user-defined-tag>

Object Model Reference

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

Object-Specific Properties

None.

Object-Specific Methods

None.

Object-Specific Event Handler Properties

None.

dataTransferNN 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.

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.

dfn

See acronym.

Dialog HelperNN 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.

blockFormatsNN 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.

fontsNN 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.

divNN 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.

alignNN 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

dataFldNN 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.

dataFormatAsNN 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

dataSrcNN 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.

noWrapNN 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

documentNN 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

activeElementNN 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.

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.

bodyNN 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.

compatModeNN 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

cookieNN 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.

defaultViewNN 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.

doctypeNN 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.

documentElementNN 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.

domainNN 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.

expandoNN 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

fileCreatedDateNN 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.

fileModifiedDateNN 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.

fileSizeNN 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.

fileUpdatedDateNN 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, widthNN 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.

implementationNN 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.

lastModifiedNN 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.

locationNN <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.

mediaNN 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.

mimeTypeNN 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"

namePropNN 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.

parentWindowNN 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.

protocolNN 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.

readyStateNN 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.

referrerNN 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("<p>Thanks for following the link to our web site.</p>");
}

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.

securityNN 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."

selectionNN 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.

titleNN 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.

URLNN 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.

URLUnencodedNN 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.

getAnonymousElementByAttribute( )

See height.

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.

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.

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.

DocumentNN 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.

DocumentEvent

See document.

DocumentFragmentNN 6 IE n/a DOM 1

The W3C DOM DocumentFragment object is essentially a context-free container of other DOM nodes. In other words, you can use all node properties and methods to assemble a sequence of element and text nodes outside of the document tree, but not influenced by the containment that the DocumentFragment provides. If you then append or insert the DocumentFragment node into the document tree, the DocumentFragment container disappears, and its node contents stand on their own within the context of their position in the document tree. The DocumentFragment isn't necessary to assemble content that is wrapped by an element node, because the element node can act as both the temporary container outside the document tree and the container after insertion into the document tree. But if one or both ends of a content segment end in a text node, the DocumentFragment node provides a transparent bucket to keep the string of nodes together until they are dropped into the document.

Create an empty DocumentFragment container via the document.createDocumentFragment( ) method. A DocumentFragment type of node inherits all properties and methods of the Node object (for inserting and appending other nodes you create), and adds nothing of its own other than its silent ability to hold other nodes. Do not confuse a DocumentFragment node with a string of tagged text that gets assigned to the innerHTML property of an element. The W3C DOM (as of Level 2) provides no such string-to-node-hierarchy conversion.

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.

Object Model Reference

documentFragmentNodeReference

Object-Specific Properties

None.

Object-Specific Methods

None.

Object-Specific Event Handler Properties

None.

DocumentRange

See document.

DocumentStyle

See document.

DocumentTraversalNN 7 IE n/a DOM 2

The DocumentTraversal object is defined in the Traversal module of the W3C DOM, where it defines the createNodeIterator( ) and createTreeWalker( ) methods. These methods (and the otherwise invisible DocumentTraversal interface) are blended into the document object so that scripts can access them (only the document.createTreeWalker( ) method is implemented in Netscape 7, but createNodeIterator( ) is sure to follow).

DocumentTypeNN 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.

entitiesNN 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

internalSubsetNN 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.

nameNN 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

notationsNN 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

publicIdNN 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.

systemIdNN 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.

DocumentView

See document.

DOMExceptionNN 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.

codeNN 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.

DOMImplementation

See implementation.

ElementNN 6 IE n/a DOM 1

The W3C DOM Element object is from the Core module and represents the kind of element object you find in true XML documents. This node type inherits properties and methods from the root Node object and adds capabilities that let it act as a container of other nodes. Elements in HTML documents are of the HTMLDocument type, which inherits form the Element object. All properties and methods of the Element object are shared among all HTML element objects, as described at the beginning of this chapter.

Object Model Reference

elementNodeReference

Object-Specific Properties

None.

Object-Specific Methods

None.

Object-Specific Event Handler Properties

None.

ElementCSSInlineStyleNN 6 IE n/a DOM 2

The W3C DOM ElementCSSInlineStyle object is from the StyleSheets module and represents style settings assigned to an element through an explicit style attribute. The HTMLElement object (and thus, all elements in HTML documents) gets its style property as a result of its connection with the ElementCSSInlineStyle object (the object's only property is style, which is what HTML elements pick up). Scripts don't ever touch this object, but dynamic styles in the W3C DOM couldn't exist without it in the abstract model.

Object Model Reference

None.

Object-Specific Properties

None.

Object-Specific Methods

None.

Object-Specific Event Handler Properties

None.

em

See acronym.

embedNN 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.

alignNN 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, widthNN 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

hiddenNN 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

nameNN 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.

paletteNN 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.

pluginspageNN 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.

srcNN 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.

typeNN 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.

unitsNN 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.

eventNN 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.

altKeyNN 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

altLeftNN 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

attrNameNN 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, boundElementsNN 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.

bubblesNN 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.

cancelableNN 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.

cancelBubbleNN 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

charCodeNN 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, clientYNN 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.

ctrlKeyNN 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

ctrlLeftNN 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

currentTargetNN 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.

dataNN |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.

dataFldNN 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.

dataTransferNN 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.

detailNN 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.

fromElementNN 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.

isCharNN 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

layerX, layerYNN 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

metaKeyNN 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

newValue, prevValueNN 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.

offsetX, offsetYNN 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.

originalTargetNN 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, pageYNN 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.

qualifierNN 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.

rangeOffsetNN 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

rangeParentNN 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.

reasonNN 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.

recordsetNN 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.

relatedTargetNN 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.

repeatNN 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

returnValueNN 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, screenYNN 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

shiftKeyNN 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

shiftLeftNN 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

srcElementNN 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.

srcFilterNN 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.

srcUrnNN 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

timeStampNN 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.

toElementNN 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.

typeNN 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.

viewNN 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.

wheelDeltaNN 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.

whichNN 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, yNN 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.

EventNN 6 IE n/a DOM 2

The W3C DOM Event object is an abstract object that contains the properties and methods shared by every instance of a W3C DOM event. This object type is also the generic event object created from the document.createEvent( ) method. See the discussion of the event object earlier in this chapter for property and method support for this object and how these items are inherited by more specific event types.

EventListenerNN 6 IE n/a DOM 2

The W3C DOM EventListener object is nothing more than a reference to a script function that is invoked by a node in response to an event. Its existence in the W3C DOM offers a convenient way for the specification to signify the data type of the second parameter to the nodeObject.addEventListener( ) and nodeObject.removeEventListener( ) methods, described earlier in this chapter.

EventTargetNN 6 IE n/a DOM 2

The W3C DOM EventTarget object is the events module connection with nodes that actually receive events. All node objects (especially text and element nodes in an HTML document tree) implement the EventTarget object, thus giving those nodes the three methods that belong to the EventTarget object: addEventListener( ), dispatchEvent( ), and removeEventListener( ). In other words, every node in a document is also an EventTarget object.

fileUpload

See input (type="file").

fontNN 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.

faceNN 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.

sizeNN 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

fonts

For details on this IE/Windows object, see the fonts property of the Dialog Helper object earlier in this chapter.

formNN 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

actionNN 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.

encodingNN 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.

enctypeNN 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.

lengthNN 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

methodNN 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

nameNN 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.

targetNN 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.

formsNN 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.

lengthNN 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.

frameNN 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.

allowTransparencyNN 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

contentDocumentNN 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.

contentWindowNN 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.

dataFldNN 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.

dataSrcNN 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.

frameBorderNN 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, widthNN 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.

longDescNN 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, marginWidthNN 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.

nameNN 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.

noResizeNN 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

scrollingNN 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

srcNN 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.

framesetNN 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

borderNN 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).

colsNN 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%

frameBorderNN 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

frameSpacingNN 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

rowsNN 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, h6NN 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.

alignNN 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

hidden

See input (type="hidden").

historyNN 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, previousNN 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.

lengthNN 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.

hrNN 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.

alignNN 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

noShadeNN 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

sizeNN 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

widthNN 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%

HTMLCollectionNN 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.

lengthNN 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.

HTMLDocumentNN 6 IE 5(Mac)/6(Win) DOM 1

The HTMLDocument object is an abstract representation in the W3C DOM of the document node for an HTML document tree. Scripts reference this object via the document object.

This object inherits properties and methods from a chain of node objects in the W3C DOM core module, namely the root Node object and the Document object. To this set of properties and methods, the HTMLDocument object adds properties and methods that apply specifically to HTML documents (in contrast to XML documents)—properties such as referrer and body, and methods such as write( ). Browser implementations add numerous additional proprietary properties and methods. See the full discussion of the scriptable implementations of the HTMLDocument object within the document object discussion earlier in this chapter.

HTMLDOMImplementationNN n/a IE n/a DOM 2

The W3C HTMLDOMImplementation object is an HTML-specific extension to the DOMImplementation object. Although not yet implemented in browsers, it may in the future provide an avenue to creating virtual HTML documents, much like the way you can create virtual XML documents in Netscape 6 and later. The one method that this object brings to the DOM is createHTMLDocument( ).

HTMLElementNN 6 IE 5(Mac)/6(Win) DOM 1

Every scriptable element object in modern browsers is, at its core, a descendant of the basic HTMLElement abstract object in the W3C DOM. The HTMLElement, itself, inherits properties and methods from the Node and Element chain in the core DOM module. To this inherited set of features, the HTMLElement adds properties that apply to HTML elements (in contrast to XML elements), including the className, dir, id, lang, and title properties. All individual HTML element objects, such as HTMLBodyElement and HTMLFormElement, inherit their characteristics from the HTMLElement object. That's one reason why the list of shared properties and methods at the beginning of this chapter is so long: it includes items inherited from the long chain of Node to Element to HTMLElement.

The terminology of the DOM abstract object names (e.g., HTMLBodyElement) is not essential knowledge to scripting element objects. That is to say, the abstract object names almost never appear in scripts because scripts reference instances of such HTML objects by way of their identifiers or through properties of other objects (such as eventObject.target). The only place you are likely to see these abstract names is during debugging, when you use alert( ) methods or other tools to inspect the object referenced by a variable. Netscape 6 reports such object references as instances of a specific HTML element class (e.g., HTMLParagraphElement or HTMLInputElement). This information, in itself, is often far more helpful than IE's reporting of the reference being just [object].

i

See b.

iframeNN 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.

alignNN 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

allowTransparencyNN 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

borderNN 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.

borderColorNN 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.

contentDocumentNN 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.

contentWindowNN 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.

dataFldNN 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.

dataSrcNN 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.

frameBorderNN 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.

frameSpacingNN 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, widthNN 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, vspaceNN 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

longDescNN 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, marginWidthNN 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.

nameNN 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.

noResizeNN 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.

scrollingNN 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

srcNN 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.

ilayer

See layer.

imagesNN 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( )

lengthNN 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.

imgNN 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

alignNN 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

altNN 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.

borderNN 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

completeNN 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

dataFldNN 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.

dataFormatAsNN 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.

dataSrcNN 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.

dynsrcNN 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.

fileCreatedDateNN 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.

fileModifiedDateNN 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.

fileSizeNN 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.

fileUpdatedDateNN 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, widthNN 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.

hrefNN 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, vspaceNN 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).

isMapNN 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

longDescNN 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.

loopNN 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

lowsrcNN 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.

mimeTypeNN 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.

nameNN 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.

namePropNN 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, naturalWidthNN 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.

protocolNN 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.

prototypeNN 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

srcNN 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.

startNN 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

useMapNN 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, yNN 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.

implementationNN 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.

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.

inputNN 6 IE 4 DOM 1

The input object reflects the input element. While Netscape Navigator exposes this HTML element completely only starting with Version 6, most of these form controls had some of their properties and methods available to earlier versions, going all the way back to Version 2.

In the W3C DOM specification, all input element objects share the same properties, even when the properties don't necessarily apply (the checked property of an input element of type text, for example). To reduce potential confusion, the discussions here for input types limit the properties to those that apply directly to a specific input type. See the following individual descriptions for each input object type: button, checkbox, fileUpload, hidden, image, password, radio, reset, submit, and text.

A few properties and methods that don't appear here in the lists of object-specific items are worth highlighting. While the IE DOM (especially in the Windows versions) ascribes properties such as accessKey, disabled, and tabIndex to virtually every HTML element, the W3C DOM is typically more parsimonious in handing out these properties to elements. But input elements are the right places for these properties, and you'll find full implementations in Netscape 6, as well as IE 4 or later. The same goes for the blur( ), click( ), and focus( ) methods, which are described among the shared items earlier in this chapter.

Event handlers for each input type are listed here, even though they are shared among all elements in more recent browsers. If your development must take backward compatibility into account, it's important to know precisely which input types recognize each of the long-supported events.

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

dataFldNN 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.

dataSrcNN 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.

formNN 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.

nameNN 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.

typeNN 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

valueNN 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

checkedNN 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

dataFldNN 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.

dataSrcNN 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.

defaultCheckedNN 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.

formNN 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.

indeterminateNN 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

nameNN 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.

statusNN 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.

typeNN 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

valueNN 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

acceptNN 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.

defaultValueNN 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.

formNN 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.

nameNN 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.

typeNN 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

valueNN 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.

dataFldNN 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.

dataSrcNN 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.

defaultValueNN 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.

formNN 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.

nameNN 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.

typeNN 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

valueNN 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

altNN 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.

completeNN 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.

dynsrcNN 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.

formNN 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, widthNN 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, vspaceNN 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.

loopNN 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.

lowsrcNN 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.

nameNN 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.

srcNN 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.

startNN 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.

typeNN 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

useMapNN 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

dataFldNN 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.

dataSrcNN 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.

defaultValueNN 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.

formNN 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.

maxLengthNN 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.

nameNN 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.

readOnlyNN 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, selectionStartNN 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.

textLengthNN 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.

typeNN 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

valueNN 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

checkedNN 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

dataFldNN 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.

dataSrcNN 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.

defaultCheckedNN 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.

formNN 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.

nameNN 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.

statusNN 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.

typeNN 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

valueNN 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

formNN 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.

nameNN 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.

typeNN 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

valueNN 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

formNN 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.

nameNN 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.

typeNN 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

valueNN 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

dataFldNN 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.

dataSrcNN 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.

defaultValueNN 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.

formNN 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.

maxLengthNN 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.

nameNN 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.

readOnlyNN 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

typeNN 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

valueNN 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.

kbd

See acronym.

labelNN 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.

dataFldNN 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.

dataFormatAsNN 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

dataSrcNN 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.

formNN 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.

htmlForNN 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.

layerNN |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, belowNN |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.

backgroundNN |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.

clipNN |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.

hiddenNN |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

leftNN |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

nameNN |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, pageYNN |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.

parentLayerNN |4| IE n/a DOM