1. Document Object Model (Core) Level 1

Editors: Mike Champion, ArborText (from November 20, 1997); Steve Byrne, JavaSoft (until November 19, 1997); Gavin Nicol, Inso EPS

1.1. Introduction

This specification defines a minimal set of objects and interfaces for accessing and manipulating document objects. The functionality specified in this draft (the core functionality) should be sufficient to implement higher level operations, such as navigating and modifying a document.

Level 1 of the Document Object Model (DOM) provides a common API for software developers and web script authors to access and manipulate parsed HTML and XML content inside conforming products. Primary document structures and some document type declarations are made available. Level 1 also allows creation from scratch of entire web documents in memory; saving those documents persistently is left to the programmer. DOM Level 1 is intentionally limited in scope to methods to represent and manipulate document structure and content; a standard API for controlling how documents are rendered via stylesheets, validated against a DTD, accessed by given users, etc., will be specified in a subsequent revision level of the DOM.

1.2. Fundamental Interfaces

The interfaces within this section are considered fundamental, and must be fully implemented by all conformant implementations of the DOM, including all HTML DOM implementations.

Enumeration `ExceptionCode`

An integer indicating the type of error generated.

Enumerator Values

UNSUPPORTED_DOCUMENT_ERR
If the implementation does not support the type of document requested

NOT_CHILD_ERR
If specified node is not a child of this node

NO_CHILDREN_ALLOWED_ERR
If this node is of a type that does not allow children of the type of node specified.

INDEX_SIZE_ERR
If index is negative, or greater than or equal to the number of nodes in the list

WSTRING_SIZE_ERR
If the specfied range of text will not fit into a wstring

DATA_SIZE_ERR
If the specfied offset is greater than the number of characters in data

Exception DOMException

DOM operations only raise exceptions in "exceptional" circumstances, i.e., when an operation is impossible to perform (either for logical reasons, because data is lost, or because the implementation has become unstable). In general, DOM methods return specific error values in ordinary processing situation, such as out-of-bound errors when using NodeList.

IDL Definition

exception DOMException {
   ExceptionCode   code;
};

Interface DOMImplementation

The DOMImplementation interface provides a number of methods for performing operations that are independent of any particular instance of the document object model. Note: The DOM Level 1 does not specify a way of creating a document instance, and hence document creation is an operation specific to an implementation. Future Levels of the DOM specification will provide methods for creating documents directly.

IDL Definition

interface DOMImplementation {
  boolean                   hasFeature(in wstring feature, 
                                       in wstring version);
};

Methods

hasFeature

Test if the DOM implementation implements a specific feature.

Parameters

feature		The package name of the feature to test. In Level 1, the legal values are "HTML" and "XML" (case-insensitive).
version		This is the version number of the package name to test. If not specified, any supported version of the feature will cause the method to return `TRUE`.

Return Values: TRUE if the feature is implemented in the specified version, FALSE otherwise.

This method raises no exceptions.

Interface DocumentFragment

DocumentFragment is the "lightweight" or "minimal" document object, and it (as the superclass of Document) anchors the XML/HTML tree in a full-fledged document.

The children of a DocumentFragment node are zero or more nodes representing the tops of any sub-trees defining the structure of the document, including the actual root element of the XML or HTML document, as well as the XML prolog, comments, processing instructions, etc. For a document fragment, there could be a number of subtrees, since fragments do not need to be well-formed XML documents (although they do need to follow the rules imposed upon well-formed XML parsed entities, which can have multiple top nodes). Criteria for "well-formedness" are much looser in the HTML world, and the DOM will not attempt to impose any constraints here. For a complete HTML document, this will contain an Element instance whose tagName is "HTML"; for a complete XML document this will contain the outermost element, i.e. the element non-terminal in production [41] in Section 3 of the XML-lang specification.

DocumentFragments have two primary uses: First of all, a Document IS A DocumentFragment so that a Document really is a tree, and not a forest or grove, with all Nodes having a common ancestor, namely the Document Node itself. For example, a document which started with a comment followed by an HTML element would result in the Document node having two children each with the Document node as parent.

Second of all, it is very common to want to be able to extract a portion of a document's tree or to create a new fragment of a document. Imagine implementing a user command like cut or rearranging a document by moving fragments around. It is desirable to have an object which can hold such fragments and it is quite natural to use a Node for this purpose. While it is true that a Document itself could fulfill this role, a Document object can potentially be quite heavyweight when what is really needed is a very lightweight object. DocumentFragment is such an object and it contains a reference to a Document so that the Document interface is indirectly available for those times when it is needed.

Furthermore, various operations -- such as inserting Nodes as children of another Node -- may take DocumentFragment objects as arguments; this will result in all the child nodes of the DocumentFragment being moved to the child list of this node.

Note that a DocumentFragment must always contain a valid reference to a Document object. If the DocumentFragment *is* a Document, the reference is to itself. A DocumentFragment can contain the same Node types as a Document. However, there is no requirement that a DocumentFragment be a well-formed document. For example, a DocumentFragment might have only one child and that child node could be a TextNode. Such a structure model represents neither an HTML document nor a well-formed XML document. The nature of the DOM's structure model representation means that a DocumentFragment will follow the rules imposed upon a well-formed XML parsed entity. (ED: The exact relationship between Entity, DocumentFragment and Document is still subject to change.)

IDL Definition

interface DocumentFragment : Node {
  readonly attribute  Document             masterDoc;
};

Attributes

masterDoc: This provides access to the Document object associated with this DocumentFragment.

Interface Document

The Document interface represents the entire HTML or XML document. Conceptually, it is the root of the document tree, and provides the primary access to the document's data. A document ISA document fragment that happens to be a discrete unit in the repository, and has contextual information similar to a document transported over HTTP. Since Document inherits from DocumentFragment, its children are contents of the Document, e.g., the root Element, the XML prolog, any processing instructions and or comments, etc.

Since elements, text nodes, comments, processing instructions, etc. cannot exist outside the context of a Document, the Document interface also contains the factory methods needed to create these objects.

IDL Definition

interface Document : DocumentFragment {
  readonly attribute  DocumentType         doctype;
  readonly attribute  DOMImplementation    implementation;
  readonly attribute  Element              documentElement;
  Element                   createElement(in wstring tagName);
  DocumentFragment          createDocumentFragment();
  Text                      createTextNode(in wstring data);
  Comment                   createComment(in wstring data);
  CDATASection              createCDATASection(in wstring data);
  ProcessingInstruction     createProcessingInstruction(in wstring target, 
                                                        in wstring data);
  Attribute                 createAttribute(in wstring name);
  Entity                    createEntity();
  EntityReference           createEntityReference();
  NodeList                  getElementsByTagName(in wstring tagname);
};

Attributes

doctype: For XML, this provides access to the Document Type Definition (see DocumentType) associated with this XML document. For HTML documents and XML documents without a document type definition this returns null.

implementation: This provides access to the DOMImplementation object that handles this document. This is necessary because a DOM application may use objects from multiple implementations, and it may be necessary to get a specific document's DOMImplementation in order to query the features it supports.

documentElement: This is a convenience attribute to that allows direct access to the child node that is the root element of the document. For HTML documents, this is the element with the tagName "HTML".

Methods

createElement

Create an element of the type specified. Note that the instance returned will implement the Element interface, so attributes can be specified directly on the returned object.

Parameters

tagName

The name of the element type to instantiate.

Return Values: A new Element object.

This method raises no exceptions.

createDocumentFragment

Create an empty DocumentFragment object. The masterDoc for this newly created DocumentFragment is the Document on which this method is invoked.

Return Values: A new DocumentFragment.

This method has no parameters.
This method raises no exceptions.

createTextNode

Create a Text node given the specified string.

Parameters

data

The data for the node.

Return Values: The new Text object.

This method raises no exceptions.

createComment

Create a Comment node given the specified string.

Parameters

data

The data for the node.

Return Values: The new Comment object.

This method raises no exceptions.

createCDATASection

Create a CDATASection node whose value is the specified string.

Parameters

data

The data for the CDATASection contents.

Return Values: The new CDATASection object.

This method raises no exceptions.

createProcessingInstruction

Create a ProcessingInstruction node given the specified name and data strings.

Parameters

target		The target part of the processing instruction.
data		The data for the node.

Return Values: The new ProcessingInstruction object.

This method raises no exceptions.

createAttribute

Create an Attribute of the given name. Note that the Attribute instance can then be set on an Element using the setAttribute method.

Parameters

name

The name of the attribute.

Return Values: A new Attribute object.

This method raises no exceptions.

createEntity

Creates an Entity object.

Return Values: The new Entity object.

This method has no parameters.
This method raises no exceptions.

createEntityReference

Creates an EntityReference object.

Return Values: The new EntityReference object.

This method has no parameters.
This method raises no exceptions.

getElementsByTagName

Returns a collection of all descendant Elements with a given tag name.

Parameters

tagname

The name of the tag to match on. If the string "*" is given, this method will return all elements in the document

Return Values: A new NodeList object containing reference to all the Elements found.

This method raises no exceptions.

Interface Node

The Node object is the primary datatype for the entire Document Object Model. It represents a single node in the document tree. While all objects implementing the Node interface expose methods for dealing with children, not all objects implementing the Node interface may have children. For example, Text nodes may not have children, and adding children to such nodes will result in an error.

The attributes nodeName, nodeValue and attributes are included as a mechanism to get at node information without casting down to the specific derived interface. In cases where there is no obvious mapping of these attributes for a specific nodeType (e.g. nodeValue for an Element or attributes for a Comment), the value returned is null. Note that the specialized interfaces may contain additional and more convenient mechanism to get and set the relevant information.

IDL Definition

interface Node {
  // NodeType
  const unsigned short      DOCUMENT           = 1;
  const unsigned short      ELEMENT            = 2;
  const unsigned short      ATTRIBUTE          = 3;
  const unsigned short      PROCESSING_INSTRUCTION = 4;
  const unsigned short      COMMENT            = 5;
  const unsigned short      TEXT               = 6;
  const unsigned short      CDATA_SECTION      = 7;
  const unsigned short      DOCUMENT_FRAGMENT  = 8;
  const unsigned short      ENTITY             = 9;
  const unsigned short      ENTITY_REFERENCE   = 10;
  const unsigned short      DOCUMENT_TYPE      = 11;

  readonly attribute  wstring              nodeName;
           attribute  wstring              nodeValue;
  readonly attribute  unsigned short       nodeType;
  readonly attribute  Node                 parentNode;
  readonly attribute  NodeList             childNodes;
  readonly attribute  Node                 firstChild;
  readonly attribute  Node                 lastChild;
  readonly attribute  Node                 previousSibling;
  readonly attribute  Node                 nextSibling;
  readonly attribute  NamedNodeMap         attributes;
  Node                      insertBefore(in Node newChild, 
                                         in Node refChild)
                                         raises(DOMException);
  Node                      replaceChild(in Node newChild, 
                                         in Node oldChild)
                                         raises(DOMException);
  Node                      removeChild(in Node oldChild)
                                        raises(DOMException);
  Node                      appendChild(in Node newChild);
  boolean                   hasChildNodes();
  Node                      cloneNode(in boolean deep);
  boolean                   equals(in Node arg, 
                                   in boolean deep);
};

Definition group `NodeType`

An integer indicating which type of node this is.

Defined Constants

DOCUMENT
The node is a Document.

ELEMENT
The node is an Element.

ATTRIBUTE
The node is an Attribute.

PROCESSING_INSTRUCTION
The node is a ProcessingInstruction.

COMMENT
The node is a Comment.

TEXT
The node is a Text.

CDATA_SECTION
The node is a CDATASection.

DOCUMENT_FRAGMENT
The node is a DocumentFragment.

ENTITY
The node is an Entity.

ENTITY_REFERENCE
The node is an EntityReference.

DOCUMENT_TYPE
The node is a DocumentType.

(ED: Should maybe change the order of Nodes to make it more logical.)

The values of nodeName, nodeValue, and attributes vary according to the node type as follows:

nodeName nodeValue attributes

Document #document null null

Element tag null nodelist

Attribute name value null

ProcessingInstruction #processing-instruction text null

Comment #comment comment text null

Text #text the text null

CDATASection #cdata-section the text null

DocumentFragment #document-fragment null null

Entity #entity TBD null

EntityReference #entity-reference null null

DocumentType #document-type TBD TBD

Attributes

nodeName: The name of the node, or a special string for node types that do not have an explicit name associated with them.

nodeValue: The value of a node depends on its type; see the table above.

nodeType: A code representing the type of the underlying object's type. The actual type of the returned data is dependent on the language binding; the IDL specification uses an enum, and it is expected that most language bindings will represent this runtime-queryable node type using an integral data type. The names of the node type enumeration literals are straightforwardly derived from the names of the actual node subtypes, and are fully specified in the IDL definition of node in the OMG IDL Definitions for Level 1 Core

parentNode: The parent of the given Node instance. All nodes, except Documents and DocumentFragments, have a parent. If a node has just been created and not yet added to the tree, it has an implicit parent which is a DocumentFragment. (ED: Attributes probably do not have a DocumentFragment as a parent. The parent is the Element; maybe it should not be possible to create Attributes outside of the context of the Element that the Attribute belongs to. )

childNodes: A NodeList object that will enumerate all children of this node. If there are no children, this is a NodeList containing no nodes. The content of the returned NodeList is "live" in the sense that changes to the children of the node object that it was created from will be immediately reflected in the nodes returned by the NodeList accessors; it is not a static snapshot of the content of the Node. Similarly, changes made to the nodes returned by the NodeList access methods will be immediately reflected in the tree.

firstChild: The first child of a node. If there is no such node, this is set to null.

lastChild: The last child of a node. If there is no such node, this is set to null.

previousSibling: The node immediately preceding the current node in a breadth-first traversal of the tree. If there is no such node, it is set to null.

nextSibling: The node immediately following the current node in a breadth-first traversal of the tree. If there is no such node, null is returned.

attributes: Provides access to a NamedNodeMap containing the node's attributes (if it is an Element) or null otherwise.

Methods

insertBefore

Inserts a child node newChild before the existing child node refChild. If refChild is null, insert newChild at the end of the list of children. If refChild is not a child of the Node that insertBefore is being invoked on, a DOMException is raised.

If newChild is a DocumentFragment object, the entire contents of the document fragment are moved into the child list of this node. Note: After a successful call to this method, the newChild node will be removed from its previous position in the tree, and all NodeLists that reference the child list of this object, and previous and next sibling attributes of some children, must be updated.

Parameters

newChild		The node to insert
refChild		The reference node, i.e., the node before which the new node will be inserted.

Return Values: The node being inserted.

Exceptions

DOMException
: Thrown if refChild is not a child of this node or if this node is of a type that does not allow children of the type of the newChild node.

replaceChild

Replaces the child node oldChild with newChild in the set of children of the given node, and return the oldChild node. If oldChild was not already a child of the node that the replaceChild method is being invoked on, a DOMException is raised. Note: After a successful call to this method, the newChild node will be removed from its previous position in the tree and all NodeLists that reference the child list of this object, and previous and next sibling attributes of some children, must be updated.

Parameters

newChild		The new node to put in the child list.
oldChild		The node being replaced in the list.

Return Values: The node replaced.

Exceptions

DOMException
: Thrown if oldChild is not a child of the node.

removeChild

Removes the child node indicated by oldChild from the list of children and returns it. If oldChild was not a child of the given node, a DOMException is raised. Note: After a successful call to this method, all NodeLists that reference the child list of this object, and previous and next sibling attributes of some children, must be updated.

Parameters

oldChild

The node being removed

Return Values: The node removed.

Exceptions

DOMException
: Thrown if oldChild is not a child of the node.

appendChild

Adds a child node to the end of the list of children for this node. Note: After a successful call to this method, the newChild node will be removed from its previous position in the tree and all NodeLists that reference the child list of this object, and previous and next sibling attributes of some children, must be updated.

Parameters

newChild

The node to add.

If it is a DocumentFragment object, the entire contents of the document fragment are moved into the child list of this node

Return Values: The node added.

This method raises no exceptions.

hasChildNodes

This is a convenience method to allow easy determination of whether a Node has children or not.

Return Values: Set to true if the node has any children, false if the node has no children at all.

This method has no parameters.
This method raises no exceptions.

cloneNode

Returns a duplicate of a given node, i.e., serves as a generic "copy constructor" for Nodes. Note: Cloning a Text node will copy the Text Node and the text it contains; cloning an Element will not copy any text it contains unless it is a deep clone, since the text is contained in a Text node.

Parameters

deep

If TRUE, recursively clone the subtree under the specified node; if FALSE, clone only the node itself and its attributes (if it is an Element). Note: When Elements are cloned, all attribute nodes are cloned, including those generated by the XML processor to represent defaulted attributes

Return Values: The duplicate node.

This method raises no exceptions.

equals

Tests whether two nodes are equivalent. Note: This method tests for equality of nodes, not sameness (i.e. whether the two nodes are exactly the same object) which should be implemented using language-specific methods. All objects that are the same will also be equal, though the reverse may not be true.For example, in C++ the == operator could be bound to test for sameness. So if two objects were equivalent in terms of == they would also be equivalent in terms of this method, but even if the objects compared true using this method, they may compare differently in terms of the == operator.

Parameters

arg		The node to compare equality with.
deep		A flag indicating whether the entire subtree below the object should also be checked for equality. Is this is `true` and the return value is `true`, the two subtree should be considered equivalent.

Return Values: If the nodes, and possibly subtrees are equivalent, true otherwise false.

This method raises no exceptions.

Interface NodeList

The NodeList interface provides the abstraction of an ordered collection of nodes, without defining or constraining how this collection is implemented, allowing different DOM implementations to be tuned for their specific environments.

The items in the NodeList are accessible via an integral index, starting from 0.

IDL Definition

interface NodeList {
  Node                      item(in unsigned long index);
  readonly attribute  unsigned long        size;
};

Methods

item

Returns the indexth item in the collection. If index is greater than or equal to the number of nodes in the list, NULL is returned.

Parameters

index

Index into the collection

Return Values: The node at the index position in the NodeList, or null if that is not a valid index.

This method raises no exceptions.

Attributes

size: The number of nodes in the NodeList instance. The range of valid child node indices is 0 to size-1 inclusive.

Interface NamedNodeMap

Objects implementing the NamedNodeMap interface are used to represent collections of nodes that can be accessed by name. Objects contained in an object implementing NamedNodeMap may also be accessed by ordinal index. The ability to access members of a NamedNodeMap by ordinal index does not imply that the DOM specifies an order to these Nodes. These methods may simply be used for enumerating all of members of the NamedNodeMap.

IDL Definition

interface NamedNodeMap {
  Node                      getNamedItem(in wstring name);
  void                      setNamedItem(in Node arg);
  Node                      removeNamedItem(in wstring name);
  Node                      item(in unsigned long index);
  readonly attribute  unsigned long        size;
};

Methods

getNamedItem

Retrieves a node from a list by name

Parameters

name

Name of a node to retrieve.

Return Values: A Node (of any type) with the specified name, or null if the specified name did not identify any node in the list.

This method raises no exceptions.

setNamedItem

Add a node to a NamedNodeMap using the nodeName attribute of the node.Note: As the nodeName attribute is used to derive the named which the node must be stored under, multiple nodes of certain types (those that have a "special" string value) cannot be stored as the names will clash. This is seen as preferable to allowing nodes to be aliased.

Parameters

arg

A node to store in a named node list. The node will later be accessible using the value of the nodeName attribute of the node.

This method returns nothing.
This method raises no exceptions.

removeNamedItem

Remove a node identified by its name.

Parameters

name

The name of a node to remove

Return Values: The node removed from the list or null if no node with such a name exists.

This method raises no exceptions.

item

Returns the indexth item in the collection. If index is greater than or equal to the number of nodes in the list, null is returned.

Parameters

index

Index into the collection

Return Values: The node at the index position in the NamedNodeMap, or null if that is not a valid index.

This method raises no exceptions.

Attributes

size: The number of nodes in the NamedNodeMap instance. The range of valid child node indices is 0 to size-1 inclusive.

Interface Data

The Data interface extends Node with a set of attributes and methods for accessing character data in the DOM. The set of interfaces is defined here rather than on each object that uses these interfaces for clarity. No DOM objects correspond directly to Data, though Text and others do inherit the interfaces from it.

IDL Definition

interface Data : Node {
           attribute  wstring              data;
  readonly attribute  unsigned long        size;
  wstring                   substring(in unsigned long start, 
                                      in unsigned long count)
                                      raises(DOMException);
  void                      append(in wstring arg);
  void                      insert(in unsigned long offset, 
                                   in wstring arg)
                                   raises(DOMException);
  void                      delete(in unsigned long offset, 
                                   in unsigned long count)
                                   raises(DOMException);
  void                      replace(in unsigned long offset, 
                                    in unsigned long count, 
                                    in wstring arg)
                                    raises(DOMException);
};

Note: Since Data is a general name, and this interface is designed for Character Data (text), the name of this interface may change. Some method and attribute names may also change to avoid confusion.

Attributes

data: This provides access to the character data of a node that implements these interfaces. If the character data of node cannot fit into the length of a wstring a DOMException is raised. If this exception is detected, the user may call substring to retrieve the data in manageable chunks.

size: This provides access to the number of characters that are available through data and the substring method below. This may have the value zero, i.e., Data nodes may be empty.

Methods

substring

Extracts a range of the data from this object implementing these interfaces.

Parameters

start		Start offset of substring to extract
count		The number of characters to extract.

Return Values: This method returns the specified substring.

Exceptions

DOMException
: Thrown if the specified range of text will not fit into a wstring.

append

Append the string to the end of the character data in the object implementing these interfaces. Upon success, data will provide access to the concatenation of data and the wstring specified.

Parameters

arg

The wstring to append.

This method returns nothing.
This method raises no exceptions.

insert

Insert a string at the specified character offset.

Parameters

offset		The character offset at which to insert
arg		The `wstring` to insert

Exceptions

DOMException
: Thrown if the specified offset is greater than the number of characters in data.

This method returns nothing.

delete

Remove a range of characters from the node. Upon success, data and size will reflect the change.

Parameters

offset		The offset from which to remove characters.
count		The number of characters to delete. If the sum of `offset` and `count` exceeds `size` then all characters from `offset` to the end of the data are deleted.

Exceptions

DOMException
: Thrown if the specified offset is greater than the number of characters in data.

This method returns nothing.

replace

Replace the characters starting at the specified character offset with the specified string.

Parameters

offset		The offset from which to start replacing.
count		The number of characters to replace. If the sum of `offset` and `count` exceeds `size`, then all characters to the end of the data are replaced (i.e. the effect is the same as a `remove` method call with the same range, followed by an `append` method invocation).
arg		The `wstring` with which the range will be replaced.

Exceptions

DOMException
: Thrown if the specified offset is greater than the number of characters in data.

This method returns nothing.

Interface Attribute

The Attribute interface represents an attribute in an Element object. Typically the allowable values for the attribute are defined in a document type definition.

The attribute's effective value is determined as follows: if this attribute has been explicitly assigned any value, that value is the attribute's effective value; otherwise, if there is a declaration for this attribute, and that declaration includes a default value, then that default value is the attribute's effective value; otherwise, the attribute has no effective value. Note, in particular, that an effective value of the null string would be returned as a Text node instance whose data attribute will contain a zero length string. If the attribute has no effective value, then this method will return null. Note the value attribute on the Attribute instance can also be used to retrieve the string version of the attribute's value(s). (ED: We should probably have a table here showing how the combination of the attribute value and specified suffice to also determine if an attribute was defaulted.)

The Attribute inherits the Node interface, which has a parentNode attribute. This attribute is set to the Element associated with the attribute as an expedient way of getting from the attribute to the Element. Note: In XML, the value of an attribute is represented by the child nodes of an attribute node, since the value can be contain entity references. Thus, attributes which contain entity references will have a child list containing both text nodes and entity reference nodes. In addition, tokenised attribute types, such as NMTOKENS will result in a child list where each child represents a single token from the attribute value.

IDL Definition

interface Attribute : Node {
  wstring                   getName();
           attribute  boolean              specified;
  wstring                   getValue();
};

Methods

getName

Returns the name of this attribute. (ED: Given that we have nodeName on node, is this necessary? Also, even if we leave it in, it should probably be a readonly attribute.)

Return Values: (ED: TBD.)

This method has no parameters.
This method raises no exceptions.

Attributes

specified: If this attribute was explicitly given a value in the original document, this will be true; otherwise, it will be false.

Methods

getValue

Returns the value of the attribute as a string. Character and general entity references will have been replaced with their values in the returned string.

Return Values: The value of the attribute as a wstring. (ED: Given that we have nodeValue on node, is this necessary? Also, even if we leave it in, it should probably be an attribute.)

This method has no parameters.
This method raises no exceptions.

Interface Element

By far the vast majority (apart from text) of node types that authors will encounter when traversing a document will be Element nodes. These objects represent both the element itself, as well as any contained nodes. For example (in XML):

<elementExample id="demo">
  <subelement1/>
  <subelement2><subsubelement/></subelement2>
</elementExample>

When represented using DOM, the top node would be "elementExample", which contains two child Element nodes (and some space), one for "subelement1" and one for "subelement2". "subelement1" contains no child nodes of its own.

IDL Definition

interface Element : Node {
  wstring                   getTagName();
  NamedNodeMap              getAttributes();
  wstring                   getAttribute(in wstring name);
  void                      setAttribute(in string name, 
                                         in string value);
  void                      removeAttribute(in wstring name);
  Attribute                 getAttributeNode(in wstring name);
  void                      setAttributeNode(in Attribute newAttr);
  void                      removeAttributeNode(in Attribute oldAttr);
  NodeList                  getElementsByTagName(in wstring tagname);
  void                      normalize();
};

Methods

getTagName

This method returns the string that is the element's name. For example, in:

<elementExample id="demo"> 
        ... 
</elementExample>

This would have the value "elementExample". Note that this is case-preserving, as are all of the operations of the DOM. (ED: Need to add section about name case etc. and a reference to it here. )
(ED: Could we choose a better name for nodeName? Should tagName be an attribute (possibly read-only)?)

Return Values: The element's tag name

This method has no parameters.
This method raises no exceptions.

getAttributes

Returns the attributes for this element. In the elementExample example above, the attributes list would consist of the id attribute, as well as any attributes which were defined by the document type definition for this element which have default values. (ED: Is this necessary given that we have attributes() on node? Should this be an attribute here?)

Return Values: Attribute list

This method has no parameters.
This method raises no exceptions.

getAttribute

Retrieves an Attribute value by name.

Parameters

name

The name of the attribute to retrieve

Return Values: The Attribute value as a string, or the empty string if that attribute does not have a specified or defaulted value.

This method raises no exceptions.

setAttribute

Adds a new attribute/value pair. If an attribute with that name is already present in the element, its value is changed to be that of the value parameter. (ED: Perhaps this should return the Attribute so that when a value is being replaced, you can still access it?)

Parameters

name		Name of an attribute
value		Value to set in string form

This method returns nothing.
This method raises no exceptions.

removeAttribute

Removes the specified attribute. (ED: Perhaps this should return the Attribute so that when an attribute is being removed, you can still access it?)

Parameters

name

The name of attribute to remove

This method returns nothing.
This method raises no exceptions.

getAttributeNode

Retrieves an attribute node by name.

Parameters

name

The name of the attribute to retrieve

Return Values: The attribute node with the specified attribute name

This method raises no exceptions.

setAttributeNode

Adds a new attribute/value pair. If an attribute by that name is already present in the element, its value is changed to be that of the Attribute instance.(ED: Perhaps this should return the Attribute so that when an attribute is being removed, you can still access it?)

Parameters

newAttr

The attribute node to add to the attribute list

This method returns nothing.
This method raises no exceptions.

removeAttributeNode

Removes the specified attribute/value pair.(ED: Perhaps this should return the Attribute so that when an attribute is being removed, you can still access it?)

Parameters

oldAttr

The attribute node to remove from attribute list

This method returns nothing.
This method raises no exceptions.

getElementsByTagName

Returns a list of all elements in the sub-tree of this element with a given tag name.

Parameters

tagname

The name of the tag to match on, or the wildcard string "*" to return all elements.

Return Values: This method returns a list of element nodes that have the specified tag name.

This method raises no exceptions.

normalize: Puts all Text nodes in the sub-tree underneath this Element into a "normal" form where only markup (e.g., tags, comments, processing instructions, CDATA sections, and entity references separates Text nodes. This can be useful to ensure that the DOM view of a document is identical to how it would look if saved and re-loaded, and is useful if operations (such as XPointer lookups) that depend on a particular document tree structure must be allowed.

This method has no parameters.
This method returns nothing.
This method raises no exceptions.

Interface Text

The text interface represents the non-markup content of an Element. If there is no markup inside an element's content, the text will be contained in a single object implementing the Text interface that is the child of the element. Any markup will parse into child elements that are siblings of the text nodes on either side of it, and whose content will be represented as text node children of the markup element.

When a document is first made available to the DOM, there is only one Text node for each block of text. Users may create adjacent Text nodes that represent the contents of a given element without any intervening markup, but should be aware that there is no way to represent the separations between these nodes in XML or HTML, so they will not (in general) persist between DOM editing sessions. The normalize() method on Element will merge any such adjacent Text objects into a single node for each block of text; this is recommended before employing operations that depend on a particular document structure, such as navigation with XPointers.

IDL Definition

interface Text : Data {
  Text                      splitText(in unsigned long offset);
  Text                      joinText(in Text node1, 
                                     in Text node2);
};

Methods

splitText

Breaks a text node into two text nodes at the specified offset, keeping both in the tree as siblings.

Parameters

offset

The offset at which to split.

Return Values: This method returns the new text node containing all the content at and after the offset point. The original node contains all the content up to the offset point.

This method raises no exceptions.

joinText

Joins the contents of two Text nodes into a single text node, with only one returned node left in the tree.

Parameters

node1		The first Text node to join.
node2		The second Text node to join.

Return Values: This method returns a new text node containing the contents of node1 and node2. The input nodes are not modified.(ED: This is just a suggestion; the WG has not decided on the actual semantics of what joinText does to the original nodes.)

This method raises no exceptions.

Interface Comment

This represents the content of a comment, i.e. all the characters between the starting ''. Note that this is the definition of a comment in XML, and, in practice, HTML, although some HTML tools may implement the full SGML comment structure.

IDL Definition

interface Comment : Data {
};

Interface ProcessingInstruction

The ProcessingInstruction interface represents a "processing instruction", used in XML (and legal, though seldom supported, in HTML) as a way to keep processor-specific information in the text of the document. The content of the node is the entire content between the delimiters of the processing instruction.

IDL Definition

interface ProcessingInstruction : Node {
           attribute  wstring              target;
           attribute  wstring              data;
};

Attributes

target: XML defines a target as the first token following the markup that begins the processing instruction, and this attribute returns that name. For HTML, the returned value is null.

data: The content of the processing instruction, from the character immediately after the <? (after the target in XML) to the character immediately preceding the ?> (the > in HTML).(ED: How does this relate to the attribute on Node?)

1.3. Extended Interfaces

The interfaces defined here form part of the DOM Level 1 Core specification, but objects that expose these interfaces will never be encountered in a DOM implementation that deals only with HTML. As such, HTML-only DOM implementations do not need to have objects that implement these interfaces.

Interface CDATASection

CDATA sections are used in the document instance, and provide a region in which most of the XML delimiter recognition does not take place. The primary purpose is for including material such as XML fragments, without needing to escape all the delimiters.

The wstring attribute of the Text node holds the text that was contained by the CDATA section. Note that this may contain characters that need to be escaped outside of CDATA sections.

IDL Definition

interface CDATASection : Text {
};

Interface DocumentType

Each document has a (possibly null) attribute that contains a reference to a DocumentType object. The DocumentType class in the DOM Level 1 core provides an interface to the list of entities that are defined for the document, and little else because the effect of namespaces and the various XML scheme efforts on DTD representation are not yet clearly understood.

IDL Definition

interface DocumentType : Node {
           attribute  wstring              name;
  readonly attribute  NamedNodeMap         entities;
  readonly attribute  NamedNodeMap         notations;
};

Attributes

name: The name attribute is a wstring that holds the name of DTD; i.e. the name immediately following the DOCTYPE keyword.

entities

This is a NamedNodeMap containing the general entities, both external and internal, declared in the DTD. For example in:

<!DOCTYPE ex SYSTEM "ex.dtd" [
  <!ENTITY foo "foo">
  <!ENTITY bar "bar">
  <!ENTITY % baz "baz">
]>
<ex/>

the interface would provide access to foo and bar but not baz. All objects supporting the Node interface that are accessed though this attribute, will also support the Entity interface. For HTML, this will always be null.

notations: This is a NamedNodeMap containing the notations declared in the DTD. Each node in this map will also implement the Notation interface.

Interface Notation

This interface represents a notation declared in the DTD. A notation declares, by name, the format of an unparsed entity (see section 4.7 of the XML 1.0 specification). The nodeName attribute inherited from Node is set to the declared name of the notation.

IDL Definition

interface Notation : Node {
           attribute  wstring              publicId;
           attribute  wstring              systemId;
};

Attributes

publicId: The public identifier for the notation. If the public identifier was not specified, this is null.

systemId: The system identifier for the notation. If the system identifier was not specified, this is null.

Interface Entity

This interface represents an entity, either parsed or unparsed, in an XML document. Note that this models the entity itself not the entity declaration. Entity declaration modeling has been left for a later Level of the DOM specification.

The nodeName attribute that is inherited from Node contains the name of the entity.

The structure of the child list is exactly the same as the structure of the child list for an EntityReference with the same nodeName value. (ED: Should we have something about resolution of entities? What happens if an entity was declared but not resolved? Should we have a method to force resolution?)

IDL Definition

interface Entity : Node {
           attribute  wstring              publicId;
           attribute  wstring              systemId;
           attribute  wstring              notationName;
};

Attributes

publicId: The public identifier associated with the entity, if specified. If the public identifier was not specified, this is null.

systemId: The system identifier associated with the entity, if specified. If the system identifier was not specified, this is null.

notationName: For unparsed entities, the name of the notation for the entity. For parsed entities, this is null. (ED: Perhaps there should be a predefined value for parsed entities other than null?)

Interface EntityReference

EntityReference objects are inserted into the DOM by the XML processor whenever the processor sees a reference to an entity other than the pre-defined character entities in the XML specification. The replacement value, if it is available, will appear in the child list of the EntityReference.

XML does not mandate that a non-validating XML processor read and process entity declarations made in the external subset or declared in external parameter entities. This means that parsed entities declared in the external subset need not be expanded by some classes of applications, and that the replacement value of the entity may not be available. Note: There is a suggestion that the nodeName attribute inherited from Node be set to the declared name of the entity. This could then be used to access the entity via the NamedNodeMap in the object implementing the DocumentType interfaces for a given document. Another suggestion is to add an entityName attribute instead, to avoid clashes with the nodeName of the Entity itself.

IDL Definition

interface EntityReference : Node {
};

UNSUPPORTED_DOCUMENT_ERR	If the implementation does not support the type of document requested
NOT_CHILD_ERR	If specified node is not a child of this node
NO_CHILDREN_ALLOWED_ERR	If this node is of a type that does not allow children of the type of node specified.
INDEX_SIZE_ERR	If index is negative, or greater than or equal to the number of nodes in the list
WSTRING_SIZE_ERR	If the specfied range of text will not fit into a wstring
DATA_SIZE_ERR	If the specfied offset is greater than the number of characters in data

DOCUMENT	The node is a `Document`.
ELEMENT	The node is an `Element`.
ATTRIBUTE	The node is an `Attribute`.
PROCESSING_INSTRUCTION	The node is a `ProcessingInstruction`.
COMMENT	The node is a `Comment`.
TEXT	The node is a `Text`.
CDATA_SECTION	The node is a `CDATASection`.
DOCUMENT_FRAGMENT	The node is a `DocumentFragment`.
ENTITY	The node is an `Entity`.
ENTITY_REFERENCE	The node is an `EntityReference`.
DOCUMENT_TYPE	The node is a `DocumentType`.

	nodeName	nodeValue	attributes
Document	#document	null	null
Element	tag	null	nodelist
Attribute	name	value	null
ProcessingInstruction	#processing-instruction	text	null
Comment	#comment	comment text	null
Text	#text	the text	null
CDATASection	#cdata-section	the text	null
DocumentFragment	#document-fragment	null	null
Entity	#entity	TBD	null
EntityReference	#entity-reference	null	null
DocumentType	#document-type	TBD	TBD

1. Document Object Model (Core) Level 1

1.1. Introduction

1.2. Fundamental Interfaces

Enumeration ExceptionCode

Definition group NodeType

1.3. Extended Interfaces

Enumeration `ExceptionCode`

Definition group `NodeType`