DOM2 Reference
   [Back] [Go to standard]  [Glossary]  [Help]   
| Reference Search | Sitemap | XML Glossary |       ZVON | IDOOX

Document

Type of the interface: fundamental
Own properties:
attributes -  doctype, documentElement, implementation
methods -  createAttribute, createAttributeNS, createCDATASection, createComment, createDocumentFragment, createElement, createElementNS, createEntityReference, createProcessingInstruction, createTextNode, getElementById, getElementsByTagName, getElementsByTagNameNS, importNode
Inherited properties:
attributes -  attributes, childNodes, firstChild, lastChild, localName, namespaceURI, nextSibling, nodeName, nodeType, nodeValue, ownerDocument, parentNode, prefix, previousSibling
methods -  appendChild, cloneNode, hasAttributes, hasChildNodes, insertBefore, isSupported, normalize, removeChild, replaceChild

Description:
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.

Note:
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. The Node objects created have a ownerDocument attribute which associates them with the Document within whose context they were created.

 attribute:    Document.doctype      example  
readonly: yes
type: DocumentType
description: Stores the Document Type Declaration associated with document (or null if the DTD was not specified).
note: docType cannot be altered in any way, including through the use of methods inherited from the Node interface, such as insertNode or removeNode.

 attribute:    Document.documentElement      example  
readonly: yes
type: Element
description: Stores the root element of the document.
note: (For HTML documents, this is the element with the tagName "HTML".)

 attribute:    Document.implementation      example  
readonly: yes
type: DOMImplementation
description: The DOMImplementation object that handles this document.
note: A DOM application may use objects from multiple implementations.

 attribute:    Document.attributes      (inherited from Node)   example  
readonly: yes
type: NamedNodeMap
description: A NamedNodeMap containing the attributes of this node (if it is an Element) or null otherwise.

 attribute:    Document.childNodes      (inherited from Node)   example  
readonly: yes
type: NodeList
description: A NodeList that contains all children of this node. If there are no children, this is a NodeList containing no nodes.

 attribute:    Document.firstChild      (inherited from Node)   example  
readonly: yes
type: Node
description: The first child of this node. If there is no such node, this returns null.

 attribute:    Document.lastChild      (inherited from Node)   example  
readonly: yes
type: Node
description: The last child of this node. If there is no such node, this returns null.

 attribute:    Document.localName      (inherited from Node)   example  
readonly: yes
type: DOMString
description: Returns the local part of the qualified name of this node.
note: For nodes of any type other than ELEMENT_NODE and ATTRIBUTE_NODE and nodes created with a DOM Level 1 method, such as createElement() from the Document interface, this is always null.

 attribute:    Document.namespaceURI      (inherited from Node)   example  
readonly: yes
type: DOMString
description: The namespace URI of this node, or null if it is unspecified.
note:
  • For nodes of any type other than ELEMENT_NODE and ATTRIBUTE_NODE and nodes created with a DOM Level 1 method, such as createElement() from the Document interface, this is always null.
  • Per the Namespaces in XML Specification an attribute does not inherit its namespace from the element it is attached to. If an attribute is not explicitly given a namespace, it simply has no namespace.

 attribute:    Document.nextSibling      (inherited from Node)   example  
readonly: yes
type: Node
description: The node immediately following this node. If there is no such node, this returns null.

 attribute:    Document.nodeName      (inherited from Node)   example  
readonly: yes
type: DOMString
description: The name of this node, depending on its type.

 attribute:    Document.nodeType      (inherited from Node)   example  
readonly: yes
type: unsigned short
description: A code representing the type of the underlying object.

 attribute:    Document.nodeValue      (inherited from Node)   example  
readonly: no
type: DOMString
description: The value of this node, depending on its type.
note: When it is defined to be null, setting it has no effect.
exceptions:
DOMException NO_MODIFICATION_ALLOWED_ERR  -  This exception raises on setting when the node is readonly.
DOMException DOMSTRING_SIZE_ERR  -  This exception raises on retrieval when it would return more characters than fit in a DOMString variable on the implementation platform.

 attribute:    Document.ownerDocument      (inherited from Node)   example  
readonly: yes
type: Document
description: The Document object associated with this node. This is also the Document object used to create new nodes. When this node is a Document or a DocumentType which is not used with any Document yet, this is null.

 attribute:    Document.parentNode      (inherited from Node)   example  
readonly: yes
type: Node
description: The parent of this node. All nodes, except Attr, Document, DocumentFragment, Entity and Notation may have a parent. However, if a node has just been created and not yet added to the tree, or if it has been removed from the tree, this is null.

 attribute:    Document.prefix      (inherited from Node)   example  
readonly: yes
type: DOMString
description: The namespace prefix of this node, or null if it is unspecified.
exceptions:
DOMException INVALID_CHARACTER_ERR  -  This exception is raised on setting if the specified prefix contains an illegal character.
DOMException NO_MODIFICATION_ALLOWED_ERR  -  This exception is raised on setting if this node is readonly.
DOMException NAMESPACE_ERR  -  This exception is raised on setting if the specified prefix is malformed, if the namespaceURI of this node is null, if the specified prefix is "xml" and the namespaceURI of this node is different from "http://www.w3.org/XML/1998/namespace", if this node is an attribute and the specified prefix is "xmlns" and the namespaceURI of this node is different from "http://www.w3.org/2000/xmlns/", or if this node is an attribute and the qualifiedName of this node is "xmlns".

 attribute:    Document.previousSibling      (inherited from Node)   example  
readonly: yes
type: Node
description: The node immediately preceding this node. If there is no such node, this returns null.


 method:    Document.createAttribute(name)      example  
description: Creates an Attr of the given name. Note that the Attr instance can then be set on an Element using the setAttribute() method.
parameters:
DOMString name  -  The name of the attribute.
returns:
Attr  -  A new Attr object with the nodeName attribute set to name, and localName, prefix, and namespaceURI set to null. The value of the attribute is the empty string.
exceptions:
DOMException INVALID_CHARACTER_ERR  -  Raised if the specified name contains an illegal character.

 method:    Document.createAttributeNS(namespaceURI, qualifiedName)      example  
description: Creates an attribute of the given qualified name and namespace URI.
parameters:
DOMString namespaceURI  -  The namespace URI of the attribute to create.
DOMString qualifiedName  -  The qualified name of the attribute to instantiate.
returns:
Attr  -  A new Attr object. (For complete list of attributes of created Attr object see standard.)
exceptions:
DOMException INVALID_CHARACTER_ERR  -  Raised if the specified name contains an illegal character.
DOMException NAMESPACE_ERR  -  Raised if the qualifiedName is malformed, if the qualifiedName has a prefix and the namespaceURI is null, if the qualifiedName has a prefix that is "xml" and the namespaceURI is different from "http://www.w3.org/XML/1998/namespace", or if the qualifiedName is "xmlns" and the namespaceURI is different from "http://www.w3.org/2000/xmlns/".

 method:    Document.createCDATASection(data)      example  
description: Creates a CDATASection node whose value is the specified string.
parameters:
DOMString data  - 
returns:
CDATASection  -  The new CDATASection object.
exceptions:
DOMException NOT_SUPPORTED_ERR  -  Raised if this document is an HTML document.

 method:    Document.createComment(data)      example  
description: Creates a Comment node given the specified string.
parameters:
DOMString data  -  The data for the node.
returns:
Comment  -  The new Comment object.
exceptions:  none

 method:    Document.createDocumentFragment()      example  
description: Creates an empty DocumentFragment object.
parameters:  none
returns:
DocumentFragment  -  A new DocumentFragment.
exceptions:  none

 method:    Document.createElement(tagName)      example  
description: Creates an element of the type specified. Note that the instance returned implements the Element interface, so attributes can be specified directly on the returned object.
parameters:
DOMString tagName  -  The name of the element type to instantiate. (Remember that for XML this is case-sensitive.)
returns:
Element  -  A new Element object with the nodeName attribute set to tagName, and localName, prefix, and namespaceURI set to null.
exceptions:
DOMException INVALID_CHARACTER_ERR  -  Raised if the specified name contains an illegal character.
note: If there are known attributes with default values, Attr nodes representing them are automatically created and attached to the element.

 method:    Document.createElementNS(namespaceURI, qualifiedName)      example  
description: Creates an element of the given qualified name and namespace URI.
parameters:
DOMString namespaceURI  - 
DOMString qualifiedName  - 
returns:
Element  -  A new Element object. (For complete list of attributes of created Element object see standard.)
exceptions:
DOMException INVALID_CHARACTER_ERR  -  Raised if the specified qualified name contains an illegal character.
DOMException NAMESPACE_ERR  -  Raised if the qualifiedName is malformed, if the qualifiedName has a prefix and the namespaceURI is null, or if the qualifiedName has a prefix that is "xml" and the namespaceURI is different from "http://www.w3.org/XML/1998/namespace".

 method:    Document.createEntityReference(name)      example  
description: Creates an EntityReference object.
parameters:
DOMString name  -  The name of the entity to reference.
returns:
EntityReference  -  The new EntityReference object.
exceptions:
DOMException INVALID_CHARACTER_ERR  -  Raised if the specified name contains an illegal character.
DOMException NOT_SUPPORTED_ERR  -  Raised if this document is an HTML document.
note: If the referenced entity is known, the child list of the EntityReference node is made the same as that of the corresponding Entity node.

 method:    Document.createProcessingInstruction(target, data)      example  
description: Creates a ProcessingInstruction node given the specified name and data strings.
parameters:
DOMString target  -  The target part of the processing instruction.
DOMString data  -  The data for the node.
returns:
ProcessingInstruction  -  The new ProcessingInstruction object.
exceptions:
DOMException INVALID_CHARACTER_ERR  -  Raised if the specified target contains an illegal character.
DOMException NOT_SUPPORTED_ERR  -  Raised if this document is an HTML document.

 method:    Document.createTextNode(data)      example  
description: Creates a Text node given the specified string.
parameters:
DOMString data  -  The data for the node.
returns:
Text  -  The new Text object.
exceptions:  none

 method:    Document.getElementById(elementId)      example  
description: Returns the Element whose ID is given by elementId. If no such element exists, returns null. Behavior is not defined if more than one element has this ID.
parameters:
DOMString elementId  -  The unique id value for an element.
returns:
Element  -  The matching element.
exceptions:  none
note: The DOM implementation must have information that says which attributes are of type ID. Attributes with the name "ID" are not of type ID unless so defined. Implementations that do not know whether attributes are of type ID or not are expected to return null.

 method:    Document.getElementsByTagName(tagName)      example  
description: Returns a NodeList containing all Elements of the given name in the same order as they appear in the source document.
parameters:
DOMString tagName  -  The name of the tag to match on. The special value "*" matches all tags.
returns:
NodeList  -  A new NodeList object containing all the matched Elements.
exceptions:  none

 method:    Document.getElementsByTagNameNS(namespaceURI, localName)      example  
description: Returns a NodeList containing all Elements of the given local name and namespace URI in the same order as they appear in the source document.
parameters:
DOMString namespaceURI  -  The namespace URI of the elements to match on. The special value "*" matches all namespaces.
DOMString localName  -  The local name of the elements to match on. The special value "*" matches all local names.
returns:
NodeList  -  A new NodeList object containing all the matched Elements.
exceptions:  none

 method:    Document.importNode(importedNode, deep)      example  
description: Imports a node from another document to this document. The returned node has no parent; (parentNode is null). The source node is not altered or removed from the original document; this method creates a new copy of the source node.
parameters:
Node importedNode  -  The node to import.
Boolean deep  -  If true, recursively import the subtree under the specified node; if false, import only the node itself. This has no effect on Attr, EntityReference, and Notation nodes.
returns:
Node  -  The imported node that belongs to this Document.
exceptions:
DOMException NOT_SUPPORTED_ERR  -  Raised if the type of node being imported is not supported.
note: (Exact behavior for diferent node-types see in standard.)

 method:    Document.appendChild(newChild)      (inherited from Node)   example  
description: Adds the node newChild to the end of the list of children of this node. If the newChild is already in the tree, it is first removed.
parameters:
Node 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.
returns:
Node  -  The node added.
exceptions:
DOMException HIERARCHY_REQUEST_ERR  -  Raised if this node is of a type that does not allow children of the type of the newChild node, or if the node to append is one of this node's ancestors or this node itself.
DOMException WRONG_DOCUMENT_ERR  -  Raised if newChild was created from a different document than the one that created this node.
DOMException NO_MODIFICATION_ALLOWED_ERR  -  Raised if this node is readonly or if the previous parent of the node being inserted is readonly.

 method:    Document.cloneNode(deep)      (inherited from Node)   example  
description: Returns a duplicate of this node, i.e., serves as a generic copy constructor for nodes. The duplicate node has no parent (parentNode is null).
parameters:
Boolean 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).
returns:
Node  -  The duplicate node.
exceptions:  none
note:
  • Cloning an Element copies all attributes and their values, including those generated by the XML processor to represent defaulted attributes, but this method does not copy any text it contains unless it is a deep clone, since the text is contained in a child Text node. Cloning an Attribute directly, as opposed to be cloned as part of an Element cloning operation, returns a specified attribute (specified is true). Cloning any other type of node simply returns a copy of this node.
  • Note that cloning an immutable subtree results in a mutable copy, but the children of an EntityReference clone are readonly. In addition, clones of unspecified Attr nodes are specified. And, cloning Document, DocumentType, Entity, and Notation nodes is implementation dependent.

 method:    Document.hasAttributes()      (inherited from Node)   example  
description: Returns whether this node (if it is an element) has any attributes.
parameters:  none
returns:
Boolean  -  true if this node has any attributes, false otherwise.
exceptions:  none

 method:    Document.hasChildNodes()      (inherited from Node)   example  
description: Returns whether this node has any children.
parameters:  none
returns:
Boolean  -  true if this node has any children, false otherwise.
exceptions:  none

 method:    Document.insertBefore(newChild, refChild)      (inherited from Node)   example  
description: Inserts the node newChild before the existing child node refChild. If refChild is null, insert newChild at the end of the list of children.
parameters:
Node newChild  -  The node to insert.
Node refChild  -  The reference node, i.e., the node before which the new node must be inserted.
returns:
Node  -  The node being inserted.
exceptions:
DOMException HIERARCHY_REQUEST_ERR  -  Raised if this node is of a type that does not allow children of the type of the newChild node, or if the node to insert is one of this node's ancestors or this node itself.
DOMException WRONG_DOCUMENT_ERR  -  Raised if newChild was created from a different document than the one that created this node.
DOMException NO_MODIFICATION_ALLOWED_ERR  -  Raised if this node is readonly or if the parent of the node being inserted is readonly.
DOMException NOT_FOUND_ERR  -  Raised if refChild is not a child of this node.
note: If newChild is a DocumentFragment object, all of its children are inserted, in the same order, before refChild. If the newChild is already in the tree, it is first removed.

 method:    Document.isSupported(feature, version)      (inherited from Node)   example  
description: Tests whether the DOM implementation implements a specific feature and that feature is supported by this node.
parameters:
DOMString feature  -  The name of the feature to test. This is the same name which can be passed to the method hasFeature on DOMImplementation.
DOMString version  -  This is the version number of the feature 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.
returns:
Boolean  -  Returns true if the specified feature is supported on this node, false otherwise.
exceptions:  none

 method:    Document.normalize()      (inherited from Node)   example  
description: Puts all Text nodes in the full depth of the sub-tree underneath this node, including attribute nodes, into a "normal" form where only structure (e.g., elements, comments, processing instructions, CDATA sections, and entity references) separates Text nodes, i.e., there are neither adjacent Text nodes nor empty Text nodes.
parameters:  none
returns:  nothing
exceptions:  none
note:
  • This can be used to ensure that the DOM view of a document is the same as if it were saved and re-loaded, and is useful when operations (such as XPointer lookups) that depend on a particular document tree structure are to be used.
  • In cases where the document contains CDATASections, the normalize operation alone may not be sufficient, since XPointers do not differentiate between Text nodes and CDATASection nodes.

 method:    Document.removeChild(oldChild)      (inherited from Node)   example  
description: Removes the child node indicated by oldChild from the list of children, and returns it.
parameters:
Node oldChild  -  The node being removed.
returns:
Node  -  The node removed.
exceptions:
DOMException NO_MODIFICATION_ALLOWED_ERR  -  Raised if this node is readonly.
DOMException NOT_FOUND_ERR  -  Raised if oldChild is not a child of this node.

 method:    Document.replaceChild(newChild, oldChild)      (inherited from Node)   example  
description: Replaces the child node oldChild with newChild in the list of children, and returns the oldChild node.
parameters:
Node newChild  -  The new node to put in the child list.
Node oldChild  -  The node being replaced in the list.
returns:
Node  -  The node replaced.
exceptions:
DOMException HIERARCHY_REQUEST_ERR  -  Raised if this node is of a type that does not allow children of the type of the newChild node, or if the node to put in is one of this node's ancestors or this node itself.
DOMException WRONG_DOCUMENT_ERR  -  Raised if newChild was created from a different document than the one that created this node.
DOMException NO_MODIFICATION_ALLOWED_ERR  -  Raised if this node or the parent of the new node is readonly.
DOMException NOT_FOUND_ERR  -  Raised if oldChild is not a child of this node.
note: If newChild is a DocumentFragment object, oldChild is replaced by all of the DocumentFragment children, which are inserted in the same order. If the newChild is already in the tree, it is first removed.