2.1. Introduction

This section extends the Level 1 Core API to describe objects and
methods specific to HTML documents. 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 address issues of backwards compatibility with the
"DOM Level 0".

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

The term "DOM Level 0" refers to a mix (not formally specified) of HTML
document functionalities offered by Netscape Navigator version 3.0 and
Microsoft Internet Explorer version 3.0. In some cases, attributes or
methods have been included for reasons of backward compatibility with "DOM
Level 0".

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. For DOM Level 1, the transitional and
frameset DTDs for HTML 4.0 are assumed. Interoperability
between implementations is only guaranteed for elements and
attributes that are specified in these 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 1 does not include mechanisms to access and
modify style specified through CSS 1. Furthermore, it does not
define an event model for HTML documents. This functionality
is planned to be specified in a future Level of this specification.

2.2. HTML Application of Core DOM

2.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. 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. 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.0
Recommendation, some of them cannot. Similarly, not
all attributes listed below have counterparts in the
HTML 4.0 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.

2.3. Miscellaneous Object Definitions

An HTMLCollection is a list of nodes. An individual node
may be accessed by either ordinal index or the node's
name or id attributes. Note:
Collections in the HTML DOM are assumed to be live meaning
that they are automatically updated when the underlying document is
changed.

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.

2.4. Objects related to HTML documents

An HTMLDocument is the root of the HTML hierarchy and
holds the entire content. Beside 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:

A collection of all the anchor (A) elements in a document
with a value for the name attribute.Note. For reasons of backwards
compatibility, the returned set of anchors only contains those anchors created with the name
attribute, not those created with the id attribute.

The cookies associated with this document. If there are none, the
value is an empty string. Otherwise, the value is a string: a
semicolon-delimited list of "name, value" pairs for all the cookies
associated with the page. For example, name=value;expires=date.

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. The following methods
may be deprecated at some point in the future in favor of a more
general-purpose mechanism.

Open a document stream for writing. If a document exists in the
target, this method clears it.
This method has no parameters.
This method returns nothing.
This method raises no exceptions.

Returns the (possibly empty) collection of elements whose
name value is given by elementName.

Parameters

elementName

The name attribute value for an element.

Return Value

The matching elements.

This method raises no exceptions.

2.5. HTML Elements

2.5.1. Property Attributes

HTML attributes are exposed as properties on the element
object. The name of the exposed property always uses the
naming conventions, and is independent of the case of the
attribute in the source document. The data type of the
property is determined by the type of the attribute as
determined by the HTML 4.0 transitional and frameset DTDs.
The attributes have the
semantics (including case-sensitivity)
given in the HTML 4.0 specification.

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, as is required
both for XML and potentially for future versions of HTML. We
recommend the use of generic methods on the core Element
interface for setting, getting and removing attributes.

DTD Data Type

Object Model Data Type

CDATA

DOMString

Value list (e.g., (left | right | center))

DOMString

one-value Value list (e.g., (border))

boolean

Number

long int

The return value of an attribute that has a data type that is a
value list is always capitalized, 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" then it is
returned as "Left". For attributes with the CDATA
data type, the case of the return value is that given in
the source document.

2.5.2. Naming Exceptions

To avoid name-space conflicts, an attribute with the same
name as a keyword in one of our chosen binding languages is
prefixed. For HTML, the prefix used is "html".
For example, the for attribute of the
LABEL element
collides with loop construct naming conventions and is renamed
htmlFor.

2.5.3. Exposing Element Type Names (tagName)

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

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

Form control. Note. Depending upon the environment
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.0.

Describes whether a radio or check box is checked, when
type has the value "Radio" or "Checkbox". The value is
TRUE if explicitly set. Represents the current state of the checkbox
or radio button. See the checked attribute definition
in HTML 4.0.

Select the contents of the text area. For INPUT elements
whose type attribute has one of the following values:
"Text", "File", or "Password".
This method has no parameters.
This method returns nothing.
This method raises no exceptions.

Simulate a mouse-click. For INPUT elements whose
type attribute has one of the following
values: "Button", "Checkbox", "Radio", "Reset", or "Submit".
This method has no parameters.
This method returns nothing.
This method raises no exceptions.

Generic embedded object. 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.0.

The create* and delete* methods on the table allow authors to construct
and modify tables. HTML 4.0 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.0.