Chapter 8 Working with XML Documents

Introduction to the Document Object Model

Dynamo provides a set of DynaScript objects for navigating and manipulating XML documents. These objects implement the Document Object Model (DOM) core Level 1 features. The DOM is a W3C recommendation (REC-DOM-Level-1-19981001).

What you can do with DOM

With the DOM interface, you can access and modify the content and structure of XML documents from DynaScript. Tasks that you can carry out using DOM including:

Parsing XML documents The toDOMDocument function parses a string that contains XML data. It builds an internal representation of the XML document so that it can be manipulated and acted on.
Converting XML to other formats For example, you can convert XML to HTML for sending to a browser.
Selectively displaying pieces of a document The DOM interface allows you to navigate through a document and locate specific pieces. If an XML document contains a SUMMARY element, you can select just that piece and send it to the application.
Change XML documents In addition to processing an existing document, the DOM interface allows you to develop applications that create and edit XML documents.

The DOM view of documents

The DOM interface presents XML documents to your application as a tree. Consider the following simple XML document, shown with indented lines for readability:

<?xml version='1.0' ?>
<Customer>
  <FName>Jessie</FName>
  <LName>Gagliardo</LName>
  <Address>
     <Street>2800 Park Avenue</Street>
     <City>Hull</City>
     <Region Type=Province>PQ</Region>
   </Address>
</Customer>

The tree representation of this document is shown in Figure 8-1.

Figure 8-1: Tree representation of XML document

The node interface to DOM

In a DOM representation of this document, each element is a node. You can navigate the document using the relationships among these nodes:

Each node has at most one parent The parent of City is Address. The parent of LName is Customer, and the parent of Customer is a special node named the document node. The document node does not have a parent node. No node can have more than one parent, and only certain classes of node (such as the document node) can have zero parents.

In the DOM representation, each node has a parentNode property that takes you to the parent of the current node.
Nodes have zero, one, or more child nodes For example, the children of Customer are FName, LName, and Address.

In the DOM representation, each node has a childNodes property that provides you with a list of all children of the current node. It also provides a firstChild and lastChild node to take you to those specific child nodes. These nodes are ordered, and each has a previousSibling property and a nextSibling property that enable you to loop through the current node.
Not all nodes are elements Some nodes represent text, such as the text nodes shaded gray in the above diagram. Other nodes represent attributes, entity references, comments, and so on.

For example, the Region element has a single attribute. This attribute is a node, with a name of Type and a value of Province. Attribute nodes have some differences from element and text nodes.

For more information on attribute nodes, see "Working with attributes".
Some nodes contain text and other nodes Character data, or text, in a node, is also considered to be a separate node. Thus, the child of the FName node is a node that has a nodeType of Text and a nodeValue of Gagliardo .

In the following example:
```
<Sentence>The cat was <Em>very</Em> black</Sentence>
```
the Sentence node contains three children. The first is a text node (with a value of "The cat was" ), the second is an Em element, and the third is another text node (with a value of "black").

Using nodes to work with XML documents

The DOMNode object is the primary object for the DOM model of documents. It has a set of properties that you can use to obtain information about the node:

Characteristics The nodeName , nodeType , and nodeValue properties give information about the node. For example, nodeType tells you whether the node represents an element, attribute, text, or some other node type.
Position You can use the parentNode , previousSibling , nextSibling , firstChild , and lastChild properties to take you to related nodes. You can use the hasChildNodes() method to determine if a node has children; if it does, the childNodes property returns a whole list of children nodes.
Modification You can use insertBefore , replaceChild , removeChild , appendChild , and cloneNode to add or remove related nodes.
Element attributes If the node represents an element, the attributes property returns a list of the XML attributes of the element.

The properties of nodes depend on what piece of an XML document they represent. The node types and their corresponding values are:

node type value	XML	Comments
1	Element	Many nodes are XML elements.
2	Attribute	Attributes of an XML element.
3	Text	Text can occur in elements, or in the values of attributes.
4	CDATASection	Typically used for including blocks of text that contain characters that would otherwise be regarded as markup (such as <, >).
5	EntityReference	A reference to an XML entity.
6	Entity	An XML entity.
7	ProcessingInstruction	An XML processing instruction.
8	Comment	An XML comment: all the characters between `<!--` and `-->` .
9	Document	The document with which the node is associated.
10	DocumentType	The document type definition (DTD) of the document.
11	DocumentFragment	A piece of a document, primarily used for editing purposes.
12	Notation	An XML notation.

The object interface to XML documents

While you can access all parts of a document as nodes, the DOM interface also provides explicit objects for elements (DOMElement ), attributes (DomAttr ), and other node types. These objects inherit properties from the DOMNode object and provide some additional functionality of their own. The properties and methods of each of these objects reflect the features of the XML object they represent.

The following sections describe both the DOMNode approach and the object interface. You can mix these approaches, although you will probably want to use one method per task, for consistency.

Performance tip
It is generally more efficient to use explicit objects instead of the generic node interface to XML documents.

Error checking XML-handling scripts

To assist in developing reliable scripts, Dynamo provides:

prettyPrint method The DOMNode object provides a prettyPrint() method that returns the XML tree starting at the current node. This method is an extension to the DOM recommendation, and takes no arguments. You can use it in a statement such as:
```
document.writeln( myNode.prettyPrint() );
```
returned object is null Many methods return an object. For example, the DOMNode.appendChild() returns the child node. On failure, the return value is null. You can compare the return value to null to check for the success of a method.
Check that the document parses correctly If the XML document is not well-formed, the call to toDOMDocument returns null. You can use site.GetErrorInfo() to provide information on where the document is incorrect:
```
domDoc = toDOMDocument( xmlString );
if( domDoc == null ) {
  document.writeln( site.GetErrorInfo() );
}
else {
...
}
```