The W3C DOM

The W3C DOM specifies a way of treating a document as a tree of nodes. In this model, every discrete data item is a node, and child elements or enclosed text become subnodes. Treating a document as a tree of nodes is one good way of handling XML documents (although there are others, as we'll see when we start working with Java) because it makes it relatively easy to explicitly state which elements contain which other elements; the contained elements become subnodes of the container nodes. Everything in a document becomes a node in this model—elements, element attributes, text, and so on. Here are the possible node types in the W3C DOM:

• Element

• Attribute

• Text

• CDATA section

• Entity reference

• Entity

• Processing instruction

• Comment

• Document

• Document type

• Document fragment

• Notation

For example, take a look at this document:

<?xml version="1.0" encoding="UTF-8"?>
<DOCUMENT>
    <GREETING>
        Hello From XML
    </GREETING>
    <MESSAGE>
        Welcome to the wild and woolly world of XML.
    </MESSAGE>
</DOCUMENT>

This document has a processing instruction node and a root element node corresponding to the <DOCUMENT> element. The <DOCUMENT> node has two sub-nodes, the <GREETING> and <MESSAGE> nodes. These nodes are child nodes of the <DOCUMENT> node and sibling nodes of each other. Both the <GREETING> and <MESSAGE> elements have one subnode—a text node that holds character data. We'll get used to handling documents like this one as a tree of nodes in this chapter. Figure 7.1 shows what this document looks like.

Every discrete data item is itself treated as a node. Using the methods defined in the W3C DOM, you can navigate along the various branches of a document's tree using methods such as nextChild to move to the nextChild node, or lastSibling to move to the last sibling node of the current node. Working with a document this way takes a little practice, and that's what this chapter is all about.

There are a number of different levels of DOM:

• Level 0. There is no official DOM "level 0," but that's the way W3C refers to the DOM as implemented in relatively early versions of the popular browsers—in particular, Netscape Navigator 3.0 and Microsoft Internet Explorer 3.0.

• Level 1. This level of the DOM is the current W3C recommendation, and it concentrates on the HTML and XML document models. You can find the documentation for this level at http://www.w3.org/TR/REC-DOM-Level-1/.

• Level 2. Currently at the Candidate Recommendation stage, this level of the DOM is more advanced and includes a style sheet object model. It also adds functionality for manipulating the style information attached to a document. In addition, it enables you to traverse a document, has a built-in event model, and supports XML namespaces. You can find the documentation for this level at http://www.w3.org/TR/DOM-Level-2/.

• Level 3. This level is still in the planning stage and will address document loading and saving, as well as content models (such as DTDs and schemas) with document validation support. In addition, it will also address document views and formatting, key events, and event groups. There is no documentation on this level yet.

Practically speaking, the only nearly complete implementation of the XML DOM today is that in Internet Explorer version 5 or later. You can find the documentation for the Microsoft DOM at http://msdn.microsoft.com/library/psdk/xmlsdk/xmld20ab.htm as of this writing. However, the Microsoft sites are continually (and annoyingly) being reorganized, so it's quite possible that by the time you read this, that page will be long gone. In that case, your best bet is to go to http://msdn.microsoft.com and search for "xml dom." (The general rule is not to trust an URL at a Microsoft site for more than about two months.)

Because Internet Explorer provides substantial support for the W3C DOM level 1, I'm going to use it in this chapter. Let's hope that the translation to other W3C-compliant browsers, as those browsers begin to support the W3C DOM, won't be terribly difficult.

The XML DOM Objects

Here are the official W3C DOM level 1 objects:

Microsoft uses different names for these objects and adds its own. In particular, Microsoft defines a set of "base objects" that form the foundation of its XML DOM. The top-level object is the DOMDocument object, and it's the only one that you create directly—you reach the other objects through that object. Here's the list of base objects in Internet Explorer. Note the objects designed to treat a document as a tree of nodes—XMLDOMNode, XMLDOMNodeList, and so on:

Besides these base objects, the Microsoft XML DOM also provides these XML DOM objects that you use when working with documents in code, including the various types of nodes, which you see supported with objects of types such as XMLDOMAttribute, XMLDOMCharacterData, and XMLDOMElement:

We'll put many of these objects to work in this chapter, seeing how to parse and access XML documents using the Microsoft XML DOM and handling events as documents are loaded. We'll also see how to alter an XML document at run time.

This previous list of objects is pretty substantial, and each object can contain its own properties, methods, and events. Although most of these properties, methods, and events are specified in the W3C XML DOM, many are added by Microsoft as well (and so are nonstandard). If we're going to work with the XML DOM in practice, it's essential to have a good understanding of these objects, both practically for the purposes of this chapter and also for reference. I'll go through the major objects in some detail to make handling the XML DOM clear, starting with the main object, the DOMDocument object.

The DOMDocument Object

The DOMDocument object is the main object that you work with, and it represents the top node in every document tree. When working with the DOM, this is the only object that you create directly.

As we'll see in this chapter, there are two ways to create document objects in Internet Explorer: using the Microsoft.XMLDOM class and using XML data islands. Creating a document object with the Microsoft.XMLDOM class looks like this, where you explicitly load a document into the object with the load method:

function readXMLDocument()
{
    var xmldoc
    xmldoc = new ActiveXObject("Microsoft.XMLDOM")
    xmldoc.load("meetings.xml")
    .
    .
    .

We'll also see that you can use the <XML> HTML element to create a data island in Internet Explorer, and then use the XMLDocument property of that element to gain access to the corresponding document object:

<XML ID="meetingsXML" SRC="meetings.xml"></XML>

<SCRIPT LANGUAGE="JavaScript">
    function readXMLDocument()
    {
         xmldoc = document.all("meetingsXML").XMLDocument
         .
         .
         .

var xmldoc = new ActiveXObject("Microsoft.FreeThreadedXMLDOM")

Here are the properties of this object:

^[*] Microsoft extension to the W3C DOM.

Here are the methods of the document object:

Here are the events of the document object:

The XMLDOMNode Object

The Microsoft XMLDOMNode object extends the core XML DOM node interface by adding support for data types, namespaces, DTDs, and schemas as implemented in Internet Explorer. We'll use this object a good deal as we traverse document trees. Here are the properties of this object:

Here are the methods of this object:

This object has no events.

The XMLDOMNodeList Object

You use the XMLDOMNodeList to handle lists of nodes. Node lists are useful because a node itself can have many child nodes. Using a node list, you can handle all the children of a node at once.

For example, here I'm loading a document and getting a list of all <PERSON> elements as a node list, using the document object's getElementsByTagName method:

function readXMLDocument()
{
    var xmldoc, nodeList
    xmldoc = new ActiveXObject("Microsoft.XMLDOM")
    xmldoc.load("meetings.xml")
    nodeList = xmlDoc.getElementsByTagName("PERSON")
    .
    .
    .

The XMLDOMNodeList object has a single property, length, which describes the number of items in the collection and is read-only.

Here are the methods of the XMLDOMNodeList object:

This object has no events.

The XMLDOMNamedNodeMap Object

The Microsoft XML DOM also supports an XMLDOMNamedNodeMap object, which provides support for namespaces. Here are the properties of this object:

Here are the methods of this object:

This object has no events.

The XMLDOMParseError Object

The Microsoft XMLDOMParseError object holds information about the most recent parse error, including the error number, line number, character position, and a text description. Although it's not obvious to anyone who loads an XML document into Internet Explorer, the browser does actually validate the document using either a DTD or schema if one is supplied. It's not obvious that this happens because, by default, Internet Explorer does not display any validation error messages. However, if you use the XMLDOMParseError object, you can get a full validation report, and I'll do so later in this chapter.

Here are the properties of this object:

Note that this object does not have any methods or events, and it does not correspond to any official W3C object in the W3C DOM.

The XMLDOMAttribute Object

In both the W3C and Microsoft DOM, attribute objects are node objects (that is, they are based on the node object), but they are not actually child nodes of an element and are not considered part of the document tree. Instead, attributes are considered properties of their associated elements. (This means that properties such as parentNode, previousSibling, or nextSibling are meaningless for attributes.) We'll see how to work with attributes in this chapter.

Here are the properties of the XMLDOMAttribute object:

Here are the methods of the XMLDOMAttribute object:

This object does not support any events.

The XMLDOMElement Object

XMLDOMElement objects represent elements and are probably the most common node objects that you'll deal with. Because attributes are not considered child nodes of an element object, you use special methods to get the attributes of an element—for example, you can use the getAttribute method, which returns an XMLDOMNamedNodeMap object that contains all the element's attributes.

Here are the properties of the XMLDOMElement object:

Here are the methods of the XMLDOMElement object:

This object has no events.

The XMLDOMText Object

The XMLDOMText object holds the text content of an element or attribute. If there is no markup inside an element, but there is text, that element will contain only one node—a text node that holds the text. (In mixed-content models, text nodes can have sibling element nodes.)

When a document is first made available to the XML DOM, all text is normalized, which means that there is only one text node for each block of text. You can actually create text nodes that are adjacent to each other, although they will not be saved as distinct the next time that the document is opened. (It's worth noting that the normalize method on the XMLDOMElement object merges adjacent text nodes into a single node.)

Here are the properties of the XMLDOMText object:

Here are the methods of the XMLDOMText object:

This object doesn't support any events.

That gives us an overview of the most commonly used objects in the Microsoft XML DOM. Now I'm going to put them to work in the rest of the chapter. I'll start at the beginning—loading an XML document.