---

---

1. Document Object Model (Core) Level 2

Editors

Arnaud Le Hors, W3C

1.1. Overview of the DOM Level 2 Core Interfaces

This section defines a set of extensions to the interfaces defined in the Core section of the DOM Level 1 Recommendation to provide functionalities which are found to be essential but were not addressed in DOM Level 1.

These functionalitites include:

• Creating a Document object
• Copying a node from one document to another
• A way to get the element an attribute is attached to

1.2. The Core Interfaces

Interface DocumentType2

Two new attributes are added to the DocumentType interface to provide a way for retrieving the public and system identifiers

IDL Definition

interface DocumentType2 : DocumentType {
  readonly attribute DOMString        publicID;
  readonly attribute DOMString        systemID;
};

Attributes

publicID

The public identifier of the document type.

systemID

The system identifier of the document type.

Interface DOMImplementation2

The DOMImplementation interface is extended with methods for creating an XML document instance.

IDL Definition

interface DOMImplementation2 : DOMImplementation {
  DocumentType       createDocumentType(in DOMString name, 
                                        in DOMString publicID, 
                                        in DOMString systemID)
                                        raises(DOMException);
  Document           createDocument(in DOMString name, 
                                    in DocumentType doctype)
                                        raises(DOMException);
};

Methods

createDocumentType

Creates an empty DocumentType node.

Parameters

name		The document type name.
publicID		The document type public identifier.
systemID		The document type system identifier.

Return Value

A new DocumentType node with Node.ownerDocument set to null.

Exceptions

DOMException

NOT_SUPPORTED_ERR: Raised if the requested document type is not supported.

createDocument

Creates an XML Document object of the specified type with its document element.

(ED: Depending on how namespaces are supported this method may need one more parameter to hold the namespace name.)

Parameters

name		The name of document element to be created.
doctype		The type of document to be created or null. When doctype is not null, its Node.ownerDocument attribute is set to the document being created.

Return Value

A new Document object.

Exceptions

DOMException

WRONG_DOCUMENT_ERR: Raised if doctype has already been used with a different document.

NOT_SUPPORTED_ERR: Raised if the requested document type is not supported.

Interface Document2

The Document interface is extended with a method for importing nodes from another document.

IDL Definition

interface Document2 : Document {
  Node               importNode(in Node importedNode, 
                                in boolean deep);
};

Methods

importNode

Imports a node from another document to this document. The returned node has no parent (parentNode is null.).

For all nodes, importing a node creates a node object owned by the importing document, with attribute values identical to the source node's nodeName and nodeType, plus the attributes related to namespaces (prefix and namespaces URI). As in the Node.cloneNode() operation, the source node is not altered.

Additional information is copied as appropriate to the nodeType, attempting to mirror the behavior expected if a fragment of XML or HTML source was copied from one document to another, recognizing that the two documents may have different DTDs in the XML case. The following list describes the specifics for every type of node.

ELEMENT_NODE

Specified attributes nodes of the source element are imported, and the generated Attr nodes are attached to the generated Element. Default attributes are not copied, though if the document being imported into defines default attributes for this element name, those are assigned. If importNode's "deep" option was set True, the descendents of the the source element will be recursively imported and the resulting nodes reassembled to form the corresponding subtree.

ATTRIBUTE_NODE

The specified flag is set false on the generated Attr. The descendents of the the source Attr are recursively imported and the resulting nodes reassembled to form the corresponding subtree.Note that the deep parameter does not apply to Attr nodes, they always carry their children with them when imported.

TEXT_NODE, CDATA_SECTION_NODE, COMMENT_NODE

These three types of nodes inheriting from CharacterData copy their data and length attributes from those of the source node.

ENTITY_REFERENCE_NODE

Only the EntityReference itself is copied, even if a deep import was requested, since the source and destination documents might have defined the entity differently. If the document being imported into provides a definition for this entity name, its value is assigned.

ENTITY_NODE

Entity nodes cannot be imported.

PROCESSING_INSTRUCTION_NODE

The imported node copies its target and data values from those of the source node.

DOCUMENT_NODE

Document nodes cannot be imported.

DOCUMENT_TYPE_NODE

DocumentType nodes cannot be imported.

DOCUMENT_FRAGMENT_NODE

If the deep option was set true, the descendents of the the source element will be recursively imported and the resulting nodes reassembled to form the corresponding subtree. Otherwise, this simply generates an empty DocumentFragment.

NOTATION_NODE

Notation nodes cannot be imported.

Parameters

importedNode		The node to import.
deep		If true, recursively import the subtree under the specified node; if false, import only the node itself, as explained above. This does not apply to Attr and EntityReference nodes.

Return Value

The imported node that belongs to this Document.

This method raises no exceptions.

Interface Node2

The Node interface is extended with an additional method to test if it supports a specific feature.

IDL Definition

interface Node2 : Node {
  boolean            supports(in DOMString feature, 
                              in DOMString version);
};

Methods

supports

Tests whether the DOM implementation implements a specific feature and that feature is supported by this node.

Parameters

feature		The package name of the feature to test. This is the same name as what can be passed to the method hasFeature on DOMImplementation.
version		This is the version number of the package name to test. In Level 2, version 1, this is the string "2.0". If the version is not specified, supporting any version of the feature will cause the method to return true.

Return Value

Returns true if this node defines a subtree within which the specified feature is supported, false otherwise.

This method raises no exceptions.

Interface Attr2

The Attr interface provides an additional method for accessing the Element node the attribute is attached to.

IDL Definition

interface Attr2 : Attr {
  readonly attribute Element          ownerElement;
};

Attributes

ownerElement

The Element node this attribute is attached to or null if this attribute is not in use.

1.3. The HTML Interfaces

Interface HTMLDOMImplementation

The HTMLDOMImplementation interface extends the DOMImplementation interface with a method for creating an HTML document instance.

IDL Definition

interface HTMLDOMImplementation : DOMImplementation {
  HTMLDocument       createHTMLDocument(in DOMString title);
};

Methods

createHTMLDocument

Creates an HTMLDocument object with the minimal tree made of the following elements: HTML, HEAD, TITLE, and BODY.

Parameters

title

The title of the document to be set as the content of the TITLE element, through a child Text node.

Return Value

A new HTMLDocument object.

This method raises no exceptions.

1.4. Open Issues

1. Should import of an ENTITY_NODE be supported?
2. Should import of an DOCUMENT_NODE be supported?
3. Should import of an DOCUMENT_TYPE_NODE be supported?
4. Should import of an NOTATION_NODE be supported?
5. Should we add a flag to importNode to request for removal of the source node? This would potentially allow implementations to optimize the operation by doing an actual move underneath when possible.

---

---