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

DocumentFragment

Type of the interface: fundamental
Own properties:
attributes -  none
methods -  none
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:
For some cases (extracting a portion of a document's tree, creating a new fragment of a document, inserting nodes as children of another node) it is desirable to have an object which can hold fragments of document. Document object itself is a little bit heavyweight for this, something lightweight that behaves like Node is much better. And exactly this is DocumentFragment.

Note:
When a DocumentFragment is inserted into a Document (or indeed any other Node that may take children) the children of the DocumentFragment and not the DocumentFragment itself are inserted into the Node.

 attribute:    DocumentFragment.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:    DocumentFragment.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:    DocumentFragment.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:    DocumentFragment.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:    DocumentFragment.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:    DocumentFragment.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:    DocumentFragment.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:    DocumentFragment.nodeName      (inherited from Node)   example  
readonly: yes
type: DOMString
description: The name of this node, depending on its type.

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

 attribute:    DocumentFragment.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:    DocumentFragment.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:    DocumentFragment.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:    DocumentFragment.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:    DocumentFragment.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:    DocumentFragment.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:    DocumentFragment.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:    DocumentFragment.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:    DocumentFragment.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:    DocumentFragment.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:    DocumentFragment.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:    DocumentFragment.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:    DocumentFragment.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:    DocumentFragment.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.