1.1. Introduction

This section extends the DOM Level 2 Core API [DOM Level 2
Core] to describe objects and methods specific to HTML documents [HTML
4.01], and XHTML documents [XHTML 1.0]. In general, the
functionality needed to manipulate hierarchical document
structures, elements, and attributes will be found in the core
section; functionality that depends on the specific elements
defined in HTML will be found in this section.

The goals of the HTML-specific DOM API are:

to specialize and add functionality that relates specifically
to HTML documents and elements.

to provide convenience
mechanisms, where appropriate, for common and frequent operations
on HTML documents.

The key differences between the core DOM and the HTML
application of DOM is that the HTML Document Object Model exposes a
number of convenience
methods and properties that are consistent with the existing models
and are more appropriate to script writers. In many cases, these
enhancements are not applicable to a general DOM because they rely
on the presence of a predefined DTD. The transitional or frameset
DTD for HTML 4.01, or the XHTML 1.0 DTDs are assumed.
Interoperability between implementations is only guaranteed for
elements and attributes that are specified in the HTML 4.01 and
XHTML 1.0 DTDs.

More specifically, this document includes the following
specializations for HTML:

An HTMLDocument
interface, derived from the core Document interface.
HTMLDocument
specifies the operations and queries that can be made on a HTML
document.

An HTMLElement
interface, derived from the core Element interface. HTMLElement specifies
the operations and queries that can be made on any HTML element.
Methods on HTMLElement include
those that allow for the retrieval and modification of attributes
that apply to all HTML elements.

Specializations for all HTML elements that have attributes that
extend beyond those specified in the HTMLElement
interface. For all such attributes, the derived interface for the
element contains explicit methods for setting and getting the
values.

The DOM Level 2 includes mechanisms to access and modify style
specified through CSS and defines an event model that can be used
with HTML documents.

The interfaces found within this section are not mandatory. A
DOM application may use the hasFeature(feature,
version) method of the DOMImplementation
interface with parameter values "HTML" and "2.0" (respectively) to
determine whether or not this module is supported by the
implementation. In addition to the feature string "HTML", the
feature string "XHTML" (version string "2.0") can be used to check
if the implementation supports XHTML (this is equivalent to
checking the features "XML" and "HTML"). In order to fully support
this module, an implementation must also support the "Core" feature
defined [DOM Level 2 Core]. Please refer
to additional information about conformance in the DOM Level 2 Core specification [DOM Level 2
Core].

A DOM application can use the hasFeature method of
the DOMImplementation interface to determine whether
they are supported or not. The feature string for all the
interfaces listed in this section is "HTML" and the version is
"2.0". In order to fully support this feature, an implementation
needs also to support the "Core" feature defined in the Document
Object Model Level 2 Core [DOM Level 2 Core] (see also Conformance).

The interfaces in this specification are designed for [HTML
4.01] documents, as well as for [XHTML 1.0] documents.

1.2. HTML Application of Core
DOM

1.2.1. Naming
Conventions

The HTML DOM follows a naming convention for properties,
methods, events, collections, and data types. All names are defined
as one or more English words concatenated together to form a single
string.

1.2.1.1. Properties and
Methods

The property or method name starts with the initial keyword in
lowercase, and each subsequent word starts with a capital letter.
For example, a property that returns document meta information such
as the date the file was created might be named "fileDateCreated".
In the ECMAScript binding, properties are exposed as properties of
a given object. In Java, properties are exposed with get and set
methods.

1.2.1.2. Non-HTML 4.0
interfaces and attributes

While most of the interfaces defined below can be mapped
directly to elements defined in the HTML 4.01 Recommendation, some
of them cannot. Similarly, not all attributes listed below have
counterparts in the HTML 4.01 specification (and some do, but have
been renamed to avoid conflicts with scripting languages).
Interfaces and attribute definitions that have links to the HTML
4.0 specification have corresponding element and attribute
definitions there; all others are added by this specification,
either for convenience or backwards compatibility with DOM Level 0
implementations.

1.3. XHTML and the HTML
DOM

The DOM HTML Level 1 API [DOM Level 1] were originally
intended to be used only for HTML 4.01 documents [HTML
4.01]. The APIs were defined well before XHTML 1.0 [XHTML
1.0] became a specification, or before it was worked on by the
HTML Working Group.

From the DOM point of view, The biggest difference between HTML
4.01 (and earlier) and XHTML 1.0 is that XHTML is case sensitive,
whereas HTML 4.01 is case insensitive. The HTML case insensitivity
is also reflected in the DOM HTML API. For instance, element and
attribute names are exposed as all uppercase (for consistency) when
used on an HTML document, regardless of the character case used in
the markup. Since XHTML is based on XML, in XHTML everything is
case sensitive, and element and attribute names must be lowercase
in the markup.

Developers need to take two things into account when writing
code that works on both HTML and XHTML documents. When comparing
element or attribute names to strings, the string compare needs to
be case insensitive, or the element or attribute name needs to be
converted into lowercase before comparing against a lowercase
string. Second, when calling methods that are case insensitive when
used on a HTML document (such as
getElementsByTagName() and namedItem()),
the string that is passed in should be lowercase.

Note: The interfaces provided in this document are only
for [HTML
4.01] and [XHTML 1.0] documents and are not
guaranteed to work with any future version of XHTML.

This method retrieves a Node using
a name. With [HTML 4.01] documents, it first
searches for a Node with a matching id
attribute. If it doesn't find one, it then searches for a
Node with a matching name attribute, but
only on those elements that are allowed a name attribute. With [XHTML
1.0] documents, this method only searches for
Nodes with a matching id attribute. This
method is case insensitive in HTML documents and case sensitive in
XHTML documents.

Parameters

name of type
DOMString

The name of the Node to be fetched.

Return Value

Node

The Node with a name or
id attribute whose value corresponds to the specified
string. Upon failure (e.g., no node with this name exists), returns
null.

This method retrieves a Node using
a name. It first searches for a Node with a matching
id attribute. If it doesn't find one, it then searches
for a Node with a matching name
attribute, but only on those elements that are allowed a name
attribute. This method is case insensitive in HTML documents and
case sensitive in XHTML documents.

Parameters

name of type
DOMString

The name of the Node to be fetched.

Return Value

Node

The Node with a name or
id attribute whose value corresponds to the specified
string. Upon failure (e.g., no node with this name exists), returns
null.

No Exceptions

1.5. Objects related to HTML
documents

An HTMLDocument is the root of the HTML hierarchy
and holds the entire content. Besides providing access to the
hierarchy, it also provides some convenience
methods for accessing certain sets of information from the
document.

The following properties have been deprecated in favor of the
corresponding ones for the BODY element:

alinkColor

background

bgColor

fgColor

linkColor

vlinkColor

Note: In DOM Level 2, the method
getElementById is inherited from the
Document interface where it was moved to.

A collection of all the anchor (A) elements in a
document with a value for the name attribute.

Note: For reasons of backward compatibility, the returned
set of anchors only contains those anchors created with the
name attribute, not those created with the
id attribute. Note that in [XHTML
1.0], the name attribute (see section
4.10) has no semantics and is only present for legacy user
agents: the id attribute is used instead. Users should
prefer the iterator mechanisms provided by [DOM Level 2 Traversal]
instead.

This mutable string attribute denotes persistent state
information that (1) is associated with the current frame or
document and (2) is composed of information described by the
cookies non-terminal of [IETF RFC 2965], Section
4.2.2.
If no persistent state information is available for the current
frame or document document, then this property's value is an empty
string.
When this attribute is read, all cookies are returned as a single
string, with each cookie's name-value pair concatenated into a list
of name-value pairs, each list item being separated by a ';'
(semicolon).
When this attribute is set, the value it is set to should be a
string that adheres to the cookie non-terminal of [IETF RFC
2965]; that is, it should be a single name-value pair followed
by zero or more cookie attribute values. If no domain attribute is
specified, then the domain attribute for the new value defaults to
the host portion of an absolute URI [IETF RFC 2396] of the current
frame or document. If no path attribute is specified, then the path
attribute for the new value defaults to the absolute path portion
of the URI [IETF RFC 2396] of the current
frame or document. If no max-age attribute is specified, then the
max-age attribute for the new value defaults to a user agent
defined value. If a cookie with the specified name is already
associated with the current frame or document, then the new value
as well as the new attributes replace the old value and attributes.
If a max-age attribute of 0 is specified for the new value, then
any existing cookies of the specified name are removed from the
cookie storage.

Note: See [IETF RFC 2965] for the
semantics of persistent state item attribute value pairs.

Note: The precise nature of a user agent session is not
defined by this specification.

Exceptions on setting

DOMException

SYNTAX_ERR: If the new value does not adhere to the cookie
syntax specified by [IETF RFC 2965].

A collection of all the IMG elements in a
document. The behavior is limited to IMG elements for
backwards compatibility.

Note: As suggested by [HTML 4.01], to include images,
authors may use the OBJECT element or the
IMG element. Therefore, it is recommended not to use
this attribute to find the images in the document but
getElementsByTagName with HTML 4.01 or
getElementsByTagNameNS with XHTML 1.0.

With [HTML 4.01] documents, this method
returns the (possibly empty) collection of elements whose
name value is given by elementName. In
[XHTML
1.0] documents, this methods only return the (possibly empty)
collection of form controls with matching name. This method is case
sensitive.

Open a document stream for writing. If a
document exists in the target, this method clears it.

Note: This method and the ones following allow a user to
add to or replace the structure model of a document using strings
of unparsed HTML. At the time of writing alternate methods for
providing similar functionality for both HTML and XML documents
were being considered (see [DOM Level 3 Load and Save]).

Write a string of text to a document stream
opened by open(). Note that the function will produce
a document which is not necessarily driven by a DTD and therefore
might be produce an invalid result in the context of the document.

Parameters

text of type
DOMString

The string to be parsed into some structure in the document
structure model.

Write a string of text followed by a newline
character to a document stream opened by open(). Note
that the function will produce a document which is not necessarily
driven by a DTD and therefore might be produce an invalid result in
the context of the document

Parameters

text of type
DOMString

The string to be parsed into some structure in the document
structure model.

No Return Value

No Exceptions

1.6. HTML Elements

1.6.1. Property
Attributes

HTML attributes are exposed as properties on the element object.
The DOM naming conventions always determine the name of the exposed
property, and are independent of the case of the attribute in the
source document. The data type of the property is in general
determined by the type of the attribute as determined by the HTML
4.01 (transitional and frameset) and XHTML 1.0 DTDs. The attributes
have the semantics (including case-sensitivity) given in the [HTML
4.01] and [XHTML 1.0] specifications.

The attributes are exposed as properties for compatibility with
DOM Level 0.
This usage is deprecated because it can not be generalized to all
possible attribute names for XML. We recommend the use of generic
methods on the core Element interface for setting,
getting and removing attributes.

In an HTML document the return value of an attribute that has a
data type that is a value list is normalized to lowercase
(independent of the case of the value in the source document).

For example, if the value of the align attribute on a P element
is "Left" (which is not a valid value in XHTML due to the case
sensitivity of XHTML) then the value is returned as "left". For
attributes with the CDATA data type, the case of the
return value is that given in the source document.

The return value of an attribute that is unspecified and does
not have a default value is the empty string if the return type is
a DOMString, false if the return type is a boolean and 0 if the
return type is a number.

1.6.2. Naming Exceptions

To avoid namespace conflicts, two attributes with the same name
as a keyword in one of our chosen binding languages
were prefixed. The for attribute of the
LABEL and SCRIPT elements collides with
loop construct naming conventions and is renamed
htmlFor. The class attribute of the HTML
elements collides with class definitions naming conventions and is
renamed className.

1.6.3. Exposing Element Type
Names (tagName, (nodeName))

If the document is an HTML 4.01 document the element type names
exposed through a property are in uppercase. For example, the body
element type name is exposed through the tagName
property as BODY. If the document is an XHTML 1.0
document the element name is exposed as it is written in the XHTML
file. This means that the element type names are exposed in
lowercase for XHTML documents since the XHTML 1.0 DTDs defines
element type names as lowercase, and XHTML, being derived from XML,
is case sensitive.

The FORM element encompasses behavior similar to a
collection and an element. It provides direct access to the
contained form controls as well as the attributes of the form
element. See the
FORM element definition in HTML 4.01.

Add a new element to the collection of
OPTION elements for this SELECT. This
method is the equivalent of the appendChild method of
the Node interface if the before
parameter is null. It is equivalent to the
insertBefore method on the parent of
before in all other cases. This method may have no
effect if the new element is not an OPTION or an
OPTGROUP.

Represents the value of the HTML selected attribute. The value
of this attribute does not change if the state of the corresponding
form control, in an interactive user agent, changes. See the
selected attribute definition in HTML 4.01.

Represents the current state of the corresponding form control,
in an interactive user agent. Changing this attribute changes the
state of the form control, but does not change the value of the
HTML selected attribute of the element.

Note: Depending upon the environment in which the page is
being viewed, the value property may be read-only for the file
upload input type. For the "password" input type, the actual value
returned may be masked to prevent unauthorized use. See the
INPUT element definition in [HTML 4.01].

When the type attribute of the element has the
value "radio" or "checkbox", this represents the current state of
the form control, in an interactive user agent. Changes to this
attribute change the state of the form control, but do not change
the value of the HTML checked attribute of the INPUT element.

Note: During the handling of a click event on an input
element with a type attribute that has the value "radio" or
"checkbox", some implementations may change the value of this
property before the event is being dispatched in the document. If
the default action of the event is canceled, the value of the
property may be changed back to its original value. This means that
the value of this property during the handling of click events is
implementation dependent.

When type has the value "radio" or "checkbox",
this represents the HTML checked attribute of the element. The
value of this attribute does not change if the state of the
corresponding form control, in an interactive user agent, changes.
See the
checked attribute definition in HTML 4.01.

When the type attribute of the element has the
value "text", "file" or "password", this represents the HTML value
attribute of the element. The value of this attribute does not
change if the contents of the corresponding form control, in an
interactive user agent, changes. See the
value attribute definition in HTML 4.01.

When the type attribute of the element has the
value "text", "file" or "password", this represents the current
contents of the corresponding form control, in an interactive user
agent. Changing this attribute changes the contents of the form
control, but does not change the value of the HTML value attribute
of the element. When the type attribute of the element
has the value "button", "hidden", "submit", "reset", "image",
"checkbox" or "radio", this represents the HTML value attribute of
the element. See the
value attribute definition in HTML 4.01.

Represents the current contents of the corresponding form
control, in an interactive user agent. Changing this attribute
changes the contents of the form control, but does not change the
contents of the element. If the entirety of the data can not fit
into a single DOMString, the implementation may
truncate the data.

Width of border around image. See the
border attribute definition in HTML 4.01. This attribute is
deprecated in HTML 4.01. Note that the type of this attribute was
DOMString in DOM Level 1 HTML [DOM
Level 1].

Horizontal space to the left and right of this image in pixels.
See the
hspace attribute definition in HTML 4.01. This attribute is
deprecated in HTML 4.01. Note that the type of this attribute was
DOMString in DOM Level 1 HTML [DOM
Level 1].

Vertical space above and below this image in pixels. See the
vspace attribute definition in HTML 4.01. This attribute is
deprecated in HTML 4.01. Note that the type of this attribute was
"DOMString" in DOM Level 1 HTML [DOM Level 1].

Note: In principle, all properties on the object element
are read-write but in some environments some properties may be
read-only once the underlying object is instantiated. See the
OBJECT element definition in [HTML 4.01].

The create* and delete* methods on the table allow authors to
construct and modify tables. [HTML 4.01] specifies that only
one of each of the CAPTION, THEAD, and
TFOOT elements may exist in a table. Therefore, if one
exists, and the createTHead() or createTFoot() method is called,
the method returns the existing THead or TFoot element. See the
TABLE element definition in HTML 4.01.

The index of the row to be deleted. This index starts from 0
and is relative to the logical order (not document order) of all
the rows contained inside the table. If the index is -1 the last
row in the table is deleted.

Exceptions

DOMException

INDEX_SIZE_ERR: Raised if the specified index is greater than or
equal to the number of rows or if the index is a negative number
other than -1.

Insert a new empty row in the table. The new
row is inserted immediately before and in the same section as the
current indexth row in the table. If
index is -1 or equal to the number of rows, the new
row is appended. In addition, when the table is empty the row is
inserted into a TBODY which is created and inserted
into the table.

Insert a row into this section. The new row is
inserted immediately before the current indexth row in
this section. If index is -1 or equal to the number of
rows in this section, the new row is appended.

Parameters

index of type
long

The row number where to insert a new row. This index starts
from 0 and is relative only to the rows contained inside this
section, not all the rows in the table.

This is in logical order and not in document order. The
rowIndex does take into account sections
(THEAD, TFOOT, or TBODY)
within the table, placing THEAD rows first in the
index, followed by TBODY rows, followed by
TFOOT rows.