Document class

A Document object represents the root node of a well-formed XML document (refer to the XML 1.0 specification). The root node is the "invisible" node that contains the document element and any top-level comments.

Document inherits from the Node class, so all functions defined for Node can be used with Document. Document is the only class in the XML module with a constructor; all other classes are instantiated from within a document.

Constructing, loading and saving

Document( )

Constructs a new empty XML document (in memory).

Document( path : String, discardBlankNodes: Boolean )

Constructs a new XML document (in memory) and parses the contents of the file at the specified absolute path into the document's node tree. If the specified file is not well-formed XML, this function logs an error message and it constructs a partial or empty document.

If discardBlankNodes is true, text nodes that contain only white space (such as line breaks) are discarded while parsing the input stream. If discardBlankNodes is false, null or missing, white-space text nodes are left in place.

save( path : String )

Serializes the XML document into a file at the specified absolute path.

Performing transformations

Refer to the XSLT 1.0 specification and to widely available literature about XSLT for more information.

createTransform( stylesheet : Document ) : Document

Returns a newly created document that contains the transformation of this document according to the rules of the specified stylesheet. The stylesheet argument must be a valid XML document which is assumed to be an XSLT 1.0 stylesheet.

transform( in-path : String, stylesheet-path : String, out-path : String )

This is a static function.

Transforms the XML file at "in-path" using the XSLT 1.0 stylesheet at "stylesheet-path" and saves the result in a file at "out-path".

Child nodes

A Document can directly contain any number of Comment nodes (including the XML declaration, which if present is always the first node of the document) and a single Element node (which is called the document element). A Document can not contain any Text nodes and it can not contain two or more Element nodes. The functions described in this section log an error if these restrictions are violated.

hasChildNodes( ) : Boolean: Returns true if this element has any child nodes and false if not.
getChildNodes( ) : NodeList: Returns the list of child nodes of this element, in document order, or an empty list if the element has no child nodes.
getFirstChild( ) : Node: Returns the first child node of this element, or null if there is none.
getLastChild( ) : Node: Returns the last child node of this element, or null if there is none.
appendChild( new-child : Node ): Appends a new child node to the list of children for this element.
insertBefore( new-child : Node, ref-child : Node ): Inserts a new child node before the specified reference node, which must be in the list of children of this element.
removeChild( oldChild : Node ) : Node: Removes the specified node from the list of children of this element and returns the removed node.
replaceChild( newChild : Node, oldChild : Node ) : Node: Replaces the specified child of this element with another node and returns the removed node.

Directly accessing the document element

getDocumentElement( ) : Element

Returns the document element, i.e. the single element directly under the root node (which is represented by the Document object).

setDocumentElement( doc-element : Element )

Sets the document element, i.e. the single element directly under the root node (which is represented by the Document object). Specifically, if before this function is called the document node contained:

No children at all, this function adds an XML declaration comment and the specified document element.
One or more children but none of them is an element, this function appends the specified document element at the end.
A document element, this function replaces the document element by the specified document element.

Creating new objects

createEmptyMap( ) : Map: Returns a new empty prefix map object.
createDefaultMap( ) : Map: Returns a new prefix map object that already contains all mappings that occur in the document.
createElement( qualified-name : String, prefix-map : Map ) : Element: Returns a newly created element node with the specified name, owned by this document. If the element name is qualified its namespace prefix must occur in the map provided in the second argument. If the name is not qualified the second argument may be null.
createText( value : String ) : Text: Returns a newly created text node with the specified text content, owned by this document.
createComment( value : String ) : Comment: Returns a newly created comment node with the specified content (i.e. all the characters that appear between the ''), owned by this document.
cloneNode( node : Node, deep : Boolean ) : Node: Returns a clone of the specified node that is owned by this document. If deep is true, all descendant nodes are cloned as well.