DOMDocument Class Reference

The DOMDocument is the root of a DOM tree. More...

Inheritance diagram for DOMDocument:

Public Member Functions
DOMAttr	createAttribute (String name)
	Create a new atttribute within this document. More...
DOMCharacterData	createCDATASection (String data)
	Create a new CDATA section within this document. More...
DOMCharacterData	createComment (String data)
	Create a new comment node within this document. More...
DOMElement	createElement (String tagName)
	Create a new DOMElement within this document. More...
DOMCharacterData	createTextNode (String data)
	Create a new text node within this document. More...
	DOMDocument (String rootElementName)
	Create a new empty XML document structure. More...
DOMNodeList	getElementsByTagName (String tagName)
	List all DOMElements in the document with a certain tag name. More...
Public Member Functions inherited from DOMNode
DOMNode	appendChild (DOMNode newChild)
	Append a new node to the list of child nodes. More...
DOMNode	cloneNode (boolean deep)
	Create a duplicate of this node. More...
boolean	hasAttributes ()
	Test, whether a node has got any associated attributes. More...
boolean	hasChildNodes ()
	Test, whether a node has got any associated child nodes. More...
DOMNode	insertBefore (DOMNode newChild, DOMNode refChild)
	Insert a new node into the list of child nodes. More...
void	normalize ()
	Normalize the node ans its subtree. More...
DOMNode	removeChild (DOMNode oldChild)
	Remove a node from the list of child nodes. More...
DOMNode	replaceChild (DOMNode newChild, DOMNode oldChild)
	Replace a node in the list of child nodes. More...

Public Attributes
DOMElement	documentElement
	The node, which represents the outermost structure element of the document. More...
Public Attributes inherited from DOMNode
DOMNamedNodeMap	attributes
	A map of DOM attributes. If this node is not a DOMElement, the value is null. The property is readonly.
DOMNodeList	childNodes
	A list of all children of this node. The property is readonly.
DOMNode	firstChild
	The first child node, otherwise null. The property is readonly.
DOMNode	lastChild
	The last child node, otherwise null. The property is readonly.
DOMNode	nextSibling
	The next sibling node, otherwise null. The property is readonly.
String	nodeName
	The name of this node. The property is readonly.
Integer	nodeType
	The type or subclass of a this node, encoded as an integer. The property is readonly.
String	nodeValue
	The value of the node, which depends on the type. More...
DOMDocument	ownerDocument
	The document, which owns this node. The property is readonly.
DOMNode	parentNode
	The parent node or null. The property is readonly.
DOMNode	previousSibling
	The previous sibling node, otherwise null. The property is readonly.
Integer	ELEMENT_NODE
	Constant for the nodeType "Element". The actual subclass is DOMElement.
Integer	ATTRIBUTE_NODE
	Constant for the nodeType "Attr". The actual subclass is DOMAttr.
Integer	TEXT_NODE
	Constant for the nodeType "Text". The actual subclass is DOMCharacterData, differing from the standard.
Integer	CDATA_SECTION_NODE
	Constant for the nodeType "CDATASection". The actual subclass is DOMCharacterData, differing from the standard.
Integer	ENTITY_REFERENCE_NODE
	Constant for the nodeType "EntityReference". The actual implementation does not provide a subclass for this type.
Integer	ENTITY_NODE
	Constant for the nodeType "Entity". The actual implementation does not provide a subclass for this type.
Integer	PROCESSING_INSTRUCTION_NODE
	Constant for the nodeType "ProcessingInstruction". The actual implementation does not provide a subclass for this type.
Integer	COMMENT_NODE
	Constant for the nodeType "Comment". The actual subclass is DOMCharacterData, differing from the standard.
Integer	DOCUMENT_NODE
	Constant for the nodeType "Document". The actual subclass is DOMDocument.
Integer	DOCUMENT_TYPE_NODE
	Constant for the nodeType "DocumentType". The actual implementation does not provide a subclass for this type.
Integer	DOCUMENT_FRAGMENT_NODE
	Constant for the nodeType "DocumentFragment". The actual implementation does not provide a subclass for this type.
Integer	NOTATION_NODE
	Constant for the nodeType "Notation". The actual implementation does not provide a subclass for this type.

Detailed Description

The DOMDocument is the root of a DOM tree.

The constructor of this class always creates an empty document structure. Use the class DOMParser to obtain the structure of an existing XML. To create any new child nodes, a script must call the appropriate create method of the DOMDocument. It is not possible to create child nodes standalone.

After a DOMDocument has been deleted by the scripting engine's garbage collector, accessing any nodes and lists of that document may issue an error. You should avoid code like the following.

function buildSomeElement()
{
   var domDoc = new DOMDocument("root");
   var someElement = domDoc.createElement("Test");

   // This is an error: Some operations on the DOMElement may no
   // longer work, when the owning DOMDocument has already died.
   return someElement;
}

Remarks about W3C conformity
The class covers much of the Document interface of DOM level 1, but the following properties and functions have not been implemented until now.

• DocumentType doctype
• DOMImplementation implementation
• DocumentFragment createDocumentFragment()
• ProcessingInstruction createProcessingInstruction(String target, String data)
• EntityReference createEntityReference(in String name)

The native DOM library behind the scripting API already supports at least DOM level 2. This is worth knowing, because the behaviour of a few operations might have changed with level 2.

Since

DOCUMENTS 4.0c

Constructor & Destructor Documentation

DOMDocument()

DOMDocument::DOMDocument

(

String

rootElementName

)

Create a new empty XML document structure.

Parameters

rootElementName

A qualified name for the document element.

Exceptions

DOMException

Since

DOCUMENTS 4.0c

Member Function Documentation

createAttribute()

DOMAttr DOMDocument::createAttribute

(

String

name

)

Create a new atttribute within this document.

Parameters

name	The name of the attribute.

Returns

A new DOMAttr object, which may initially appear anywhere or nowhere in the DOM tree.

Exceptions

DOMException

See also

DOMElement.setAttributeNode() to place the node within the tree.

Since

DOCUMENTS 4.0c

createCDATASection()

DOMCharacterData DOMDocument::createCDATASection

(

String

data

)

Create a new CDATA section within this document.

Parameters

data	The data for the node

Returns

A new DOMCharacterData object, which may initially appear anywhere or nowhere in the DOM tree.

Exceptions

DOMException

See also

DOMNode.appendChild() and DOMNode.insertBefore() to place the node within the tree.

Remarks about W3C conformity
The W3C specifies the return type as "CDATASection". Considering code size (and work) the actual implementation omits a class CDATASection and presents the only additional member (splitText(), inherited from "Text") directly in the second level base class. Scripts can examine DOMNode.nodeType to distinguish different types of character data, if necessary.

Since

DOCUMENTS 4.0c

createComment()

DOMCharacterData DOMDocument::createComment

(

String

data

)

Create a new comment node within this document.

Parameters

data	The data for the node

Returns

A new DOMCharacterData object, which may initially appear anywhere or nowhere in the DOM tree.

See also

DOMNode.appendChild( and DOMNode.insertBefore() to place the node within the tree.

Remarks about W3C conformity
The W3C specifies the return type as "Comment". Considering code size (and work) the actual implementation omits a class DOMComment, which would not get any more members apart from the inherited ones. Scripts can examine DOMNode.nodeType to distinguish different types of character data, if necessary.

Since

DOCUMENTS 4.0c

createElement()

DOMElement DOMDocument::createElement

(

String

tagName

)

Create a new DOMElement within this document.

Parameters

tagName

The name of the element.

Returns

A new DOMElement, which may initially appear anywhere or nowhere in the DOM tree.

Exceptions

DOMException

See also

DOMNode.appendChild() and DOMNode.insertBefore() to place the element within the tree.

Since

DOCUMENTS 4.0c

createTextNode()

DOMCharacterData DOMDocument::createTextNode

(

String

data

)

Create a new text node within this document.

Parameters

data	The data for the node

Returns

A new DOMCharacterData object, which may initially appear anywhere or nowhere in the DOM tree.

See also

DOMNode.appendChild( and DOMNode.insertBefore() to place the node within the tree.

Remarks about W3C conformity
The W3C specifies the return type as "Text". Considering code size (and work) the actual implementation omits a class DOMText and presents the only additional member (splitText()) directly in the base class. Scripts can examine DOMNode.nodeType to distinguish different types of character data, if necessary.

Since

DOCUMENTS 4.0c

getElementsByTagName()

DOMNodeList DOMDocument::getElementsByTagName

(

String

tagName

)

List all DOMElements in the document with a certain tag name.

The order of the elements in the returned list corresponds to a preorder traversal of the DOM tree.

Parameters

tagName

The name to match on. The special value "*" matches all tags.

Returns

A dynamic list of the found elements.

See also

DOMNodeList.

Since

DOCUMENTS 4.0c

Member Data Documentation

documentElement

DOMElement DOMDocument::documentElement

The node, which represents the outermost structure element of the document.

This property is readonly.

Remarks

Unlike written in older versions of this document, the documentElement is not necessarily the first child of the DOMDocument. A DocumentType node, for example, may precede it in the list of direct children.

Since

DOCUMENTS 4.0d