Microsoft DOM Objects Reference

createAttribute(), createCDATASection(), createComment(),createElement(), createEntityReference(),createProcessingInstruction(), createTextNode()

Syntax

objXMLDOMAttribute = objDOMDocument.createAttribute(name)

Remark

Adding Nodes to the DOMDocument is done in two phases:

¬ You first need to create a Node of the type you want (Element, Comment, etc.)

¬ Then you append the created Node to the DOMDocument

Creating an element

objXMLDOMElement = objDOMDocument.createElement(tagName)

These methods are only applicable to the DOM-Document interface.

When creating an element, we need to pass the createElement() method the tag name of the element to be created. This tag name is case-sensitive. Once we've established a new element, then we need to give it its values. See the example below.

In the code for the appendChild() method, we see how an element is created and added to a parentNode. Therefore, we have already created a DOMDocument and its documentElement property (root element). Now we want to add children to the documentElement:

Dim objPerson As IXMLDOMNode

Dim objChild As IXMLDOMNode

Set objPerson = objDOMDocument.createElement("PERSON")

objDOMDocument.documentElement.appendChild objPerson

Set objChild = objDOMDocument.createElement("NAME")

objChild.Text = "Monty Python"

objPerson.appendChild objChild

¬ The tag name (element name) is passed as a string to say which element to create. We get a reference to objPerson, because we will add childNodes (Name, Address etc.) to this parentNode.

¬ Add objPerson Node to the documentElement Node.

¬ Create another element-note that we are using the DOMDocument object here.

¬ Add this childNode to the Person element.

Before appending the element to its parentNode, don't forget to give it its properties, like the text, etc.

Here again we see the append method being used to actually add this element to the parentNode. If this is not done, then the new element's parent will be NULL and not part of the DOMDocument.

This create-Element() method does not add the new child- Node to the document tree. To actually add it to the document, you need to call the append-Child() method.

You now need to use a method such as insertBefore(), replaceChild(), or appendChild() to add the new child to the DOMDocument. Then you need to use the save() method on the DOMDocument to actually write the change to the XML file. This applies to the methods that follow as well.

Namespaces

If you have specified a namespace in your document (namespaceURI = ....), the element will be added in the context of this namespace. If no prefix is used before a tagName, then element is added to the default namespace. If you say:

Set objChild = objDOMDocument.createElement("resume:NAME")

the colon will be ignored.

Creating an attribute

The VB code line:

objXMLDOMAttribute = objDOMDocument.createAttribute(name)

creates an attribute with a specific name, where name is the name of the attribute. You then need to give the attribute its details. See the example below.

Attributes can only be added to created or current elements. Therefore, you need to first get access to an element object to which you are about to add an attribute.

There are several methods used to add an attribute to an element (which you will see as you go through the methods). If you use the createAttribute() method, this is how to go about it:

Dim objNode As IXMLDOMNode

Dim objAttrib As IXMLDOMAttribute

Set objNode = m_objDOMPeople.createElement("PERSON")

Set objAttrib = m_objDOMPeople.createAttribute("PERSONID")

objAttrib.Text = "p7"

objNode.Attributes.setNamedItem objAttrib

m_objDOMPeople.documentElement.appendChild objNode

¬ Create the element Node if it's a new element.

¬ Create the attribute type, passing it a string of its name.

¬ Give the attribute properties.

¬ To the created Node (element), add the attribute object.

¬ Append the created Node to the documentElement.

¬ See the setAttribute() method in this chapter.

Creating a CDATA section

The following VB code creates a CDATA section in an element Node in the DOMDocument:

objXMLDOMCDATASection = objElement.createCDATASection(data)

This method can be really handy if you need to find an easy way to put those crazy brackets (<![CDATA[#]]>) around a CDATA section, without having to put the brackets around yourself when you are busy modifying a DOMDocument.

In the following example, we need to have the following in our address Node:

#123 Narrabundah Avenue

We accomplish this by wrapping the hash (#) in a CDATA section:

Dim objCDATA As IXMLDOMCDATASection

Set objCDATA = objDOMDocument.createCDATASection("#")

Set objChild = objDOMDocument.createElement("ADDRESS")

objChild.Text = objCDATA.XML & "123 Narrabundah Avenue"

Set objNode = objDOMDocument.documentElement.appendChild(objChild)

If you query the text property for this Node (objNode), it returns:

<![CDATA [#]]>123 Narrabundah Avenue

Creating a comment

The following VB code creates a comment in the DOMDocument:

objXMLDOMComment = objDOMDocument.createComment(data)

If you need to add a comment to your XML, then you need to use the following method. It automatically adds the correct characters (<!-- -->) around the comment; you only need to add the data.

In the following example, we add a comment to the DOMDocument:

Dim objDOMDocument As DOMDocument

Dim objComment As IXMLDOMComment

Set objDOMDocument = New DOMDocument

Set objComment = objDOMDocument.createComment("This is a comment.")

objDOMDocument.appendChild objComment

objDOMDocument.save http://localhost/xmlcode/people2.xml

¬ Create your DOMDocument.

¬ Create a Comment object, passing just your comment, no XML tags. Note that this object can also be an XMLDOMNode object.

¬ Add this new comment object to the DOMDocument.

If you run this example and look at the xml property for the objComment object, you will see that the comment tags (<!-- -->) have been automatically added, but the text property does not have these tags.

Creating an entity reference

The following VB code creates a CDATA section in an element Node in the DOMDocument:

objXMLDOMEntityReference = objElement.createEntityReference(name)

This creates an entity reference with a specified case-sensitive name. This method is important when you want to create a Node that needs to have the entity reference in the XML. The entity is defined in the DTD. In our DTD example (people2.dtd), we have specified the following entity:

<!ENTITY UK "United Kingdom">

In the following example, we need to create an address element for a person. However, our example is a bit more complicated, because the entity UK needs to come at the end of the address. Therefore, we need to create an element for the address, plus we need to create an entity reference Node for the address element. This is how we need to combine the two:

Dim objDOMDocument As DOMDocument

Dim objPerson As IXMLDOMNode

Dim objChild As IXMLDOMNode

Dim objEntityRef As IXMLDOMEntityReference

Set objDOMDocument = New DOMDocument

objDOMDocument.async = False

objDOMDocument.resolveExternals = True

objDOMDocument.validateOnParse = True

objDOMDocument.Load "http://localhost/xmlcode/people2.xml"

Set objPerson = objDOMDocument.createElement("PERSON")

objDOMDocument.documentElement.appendChild objPerson

Set objChild = objDOMDocument.createElement("ADDRESS")

Set objEntityRef = objDOMDocument.createEntityReference("UK")

objChild.Text = "34 Erica Street, Isle of Dogs,"

objChild.appendChild objEntityRef

objPerson.appendChild objChild

¬ Load a DOMDocument from file.

¬ Create a person element and add it to the documentElement NodeList.

¬ Create the child Node for the Address element.

¬ Create an entity reference Node, which we know is the "UK" entity from our DTD.

¬ To our address element (objChild), add the address text, excluding the entity reference.

¬ Append the entity reference object to the address element as a child Node. This creates the correct syntax for an element that has normal text, plus an entity reference in it.

When running this example, after the line

objChild.appendChild objEntityRef

the objChild xml and text properties are as follows:

objChild.xml: <ADDRESS>34 Erica Street, Isle of Dogs, &UK;</ADDRESS>

objChild.text: 34 Erica Street, Isle of Dogs, United Kingdom

This manuscript is an abridged version of a chapter from the Manning Publications book XML Programming with VB and ASP. This chapter looks at the Microsoft DOM objects. NOTE: Most images have been removed to increase speed and many of the code comments have also been removed for presentation. Please purchase the book to enjoy the full experience of all the chapters with images and code comments!