[Back] [Go to standard]  [Glossary]  [Help]   

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