Visual Basic and the XML DOM: An Annotated Example
July 12, 2000
One of the most frequently asked questions we get concerning XML and Visual Basic is about how to work with the Microsoft XML Parser (MSXML.DLL) that comes with Internet Explorer 5. It's fine knowing how to write XML, but one needs to know how to read and manipulate an XML file.
This article takes us through an annotated example of how to use the Microsoft XML Document Object Model (DOM) parser to load a TreeView control in Visual Basic. (Populating a TreeView is a good example, as XML documents themselves are tree-structured.) From there we then go on to explain how to manipulate an XML document by adding and deleting data items.
This article is based on a section of the book "XML Programming with VB and ASP" (Manning Publications) by Mark Wilson and Tracey Wilson. This is an extract from Chapter 4, Section 9.
The DOM consists of several interfaces. Every object in the DOM is called a "node," whether it's an element, attribute, CDATA section, comment, or processing instruction.
The DOMDocument object will contain our XML document. From there, we access our XML data via the DOMDocument's documentElement property, which is available from the IXMLDOMElement or IXMLDOMNode interface.
These interfaces have a childNodes property, which is how we iterate through each of the "child" elements, comments, etc., of the parent node. The IXMLDOMNodeList interface allows us to access a collection of nodes, such as the children of an element.
The following diagram shows the hierarchy of these interfaces. Note that only the most common interfaces are shown below:
Figure 1: MSXML DOMDocument Interfaces
Working back-to-front, here's what we're aiming for:
Figure 2: DOM Example screenshot
Clicking on the "Populate People" command button loads and displays the content of an XML "People" document. As you click on each person in the TreeView, the text box contents on the right-hand side will show details relating to the element you click, using the DOM object to get the details.
We've included a web-browser control to the form, so that you can see the changes happening to the XML file as you add and delete elements. To add a new person, click on the "Clear Items for new Person" button. Add your details to the text boxes. Then click on the "Save New Person" button. This creates the new "PERSON" element and adds it to the XML document.
To delete a person, click on a person in the TreeView. Then click on the "Delete Person" button, which will automatically delete the selected person, removing him/her from the TreeView, DOM Object, and the actual XML file.
To run this project, download the source code, then
- copy the contents of the downloaded zip into a directory,
- make sure that you have the "Microsoft XML 2.0" dll installed, and
- run the DOMExample.vbp.
One word of caution before we examine the code: because the DOMDocument and the TreeView use the term "node" for specifying their objects, we've tried to explicitly differentiate between the two in our comments.
Right, let's dig into the code!
The following XML document has been used for this example:
<?xml version="1.0"?> <!-- *********** Resumes for People *********** --> <!DOCTYPE PEOPLE SYSTEM "people2.dtd"> <PEOPLE> <PERSON PERSONID="p1"> <NAME>Mark Wilson</NAME> <ADDRESS>911 Somewhere Circle, Canberra, Australia</ADDRESS> <TEL>(++612) 12345</TEL> <FAX>(++612) 12345</FAX> <EMAIL>email@example.com</EMAIL> </PERSON> <PERSON PERSONID="p2"> <NAME>Tracey Wilson</NAME> <ADDRESS>121 Zootle Road, Cape Town, South Africa</ADDRESS> <TEL>(++2721) 531 9090</TEL> <FAX>(++2721) 531 9090</FAX> <EMAIL>Tracey_Wilson@somewhere.com</EMAIL> </PERSON> <PERSON PERSONID="p3"> <NAME>Jodie Foster</NAME> <ADDRESS>30 Animal Road, New York, USA</ADDRESS> <TEL>(++1) 3000 12345</TEL> <FAX>(++1) 3000 12345</FAX> <EMAIL>Jodie_Foster@somewhere.com</EMAIL> </PERSON> <PERSON PERSONID="p4"> <NAME>Lorrin Maughan</NAME> <ADDRESS>1143 Winners Lane, London, UK</ADDRESS> <TEL>(++94) 17 12345</TEL> <FAX>++94) 17 12345</FAX> <EMAIL>Lorrin Maughan@somewhere.com</EMAIL> </PERSON> <PERSON PERSONID="p5"> <NAME>Steve Rachel</NAME> <ADDRESS>90210 Beverly Hills, California, USA</ADDRESS> <TEL>(++1) 2000 12345</TEL> <FAX>(++1) 2000 12345</FAX> <EMAIL>Steve_Rachel@somewhere.com</EMAIL> </PERSON> </PEOPLE>
These global variables go into the General Declarations of the project:
General_Declarations Option Explicit ' The member variables used throughout the project Private m_objDOMPeople As DOMDocument Private m_blnItemClicked As Boolean ' constant used throughout the code for when we want to ' save the document Const XMLPATH As String = "people2.xml"
When the user clicks on the "Populate People" button, the following code populates the TreeView with the contents of the DOMDocument:
Private Sub cmdPopulate_Click() Dim objPeopleRoot As IXMLDOMElement Dim objPersonElement As IXMLDOMElement Dim tvwRoot As Node Set m_objDOMPeople = New DOMDocument
ResolveExternals prevents the m_objDOMPeople object from looking for external files--which in our case is the people2.dtd. Set this to true if you want the parser to find the external files.
m_objDOMPeople.resolveExternals = True
ValidateOnParse can stop the m_objDOMPeople from validating the XML file against the people.dtd file--set this to true if you want validation to occur.
m_objDOMPeople.validateOnParse = True
The XML file first needs to be loaded into the DOMDocument (m_objDOMPeople). We need to load the file synchronously to instruct that the XML file will be completed loaded into the DOM, when loading; therefore we set the async property to false.
m_objDOMPeople.async = False Call m_objDOMPeople.Load(XMLPATH)
Check that the load of the XML document was successful.
If m_objDOMPeople.parseError.reason <> "" Then
There has been an error with the loaded XML--show the reason.
MsgBox m_objDOMPeople.parseError.reason Exit Sub End If
Get to the root element of the XML document--bypassing the comments, PIs, etc.
Set objPeopleRoot = m_objDOMPeople.documentElement
Once we have obtained the root element (documentElement) of the DOMDocument, we can start working with the data from the XML file. The first thing we want to add to the TreeView is the name of the root element of the XML file, which is "PEOPLE". Then we need to start adding child nodes.
Set the TreeView control properties.
tvwPeople.LineStyle = tvwRootLines tvwPeople.Style = tvwTreelinesPlusMinusText tvwPeople.Indentation = 400
Check if the TreeView has already been populated: if so, remove the root, which removes everything.
If tvwPeople.Nodes.Count > 0 Then tvwPeople.Nodes.Remove 1 End If
Add a child to the root node of the TreeView.
Set tvwRoot = tvwPeople.Nodes.Add()
Now all we need to do is iterate through these childNodes of the DOMDocument's "PEOPLE" elements, which is going to return five "PERSON" elements. This is done by the "For Each" loop, which leads us to the code in populateTreeWithChildren method.
Iterate through each "PERSON" element in the DOM to fill the tree, which in itself iterates through each childNode of that element (objPersonElement) to drill down into its childNodes.
For Each objPersonElement In objPeopleRoot.childNodes populateTreeWithChildren objPersonElement Next webTarget.Navigate XMLPATH cmdDelete.Enabled = True cmdClear.Enabled = True End Sub
This code is called from the cmdPopulate click event. For each parent node created on the TreeView, drill down into the DOM Element that has been passed in and populate the TreeView with these DOMElement childNodes.
The parameter, objDOMNode, is the current child node from the docElement property of the DOMDocument.
Dim objNameNode As IXMLDOMNode Dim objAttributes As IXMLDOMNamedNodeMap Dim objAttributeNode As IXMLDOMNode Dim intIndex As Integer Dim tvwElement As Node Dim tvwChildElement As Node
We need to add a title to the current TreeView node, by adding the element's main child node ("NAME") as the heading for the TreeView of this section. We use the method selectSingleNode to return the first node that it finds with the nodeName of "NAME".
Set objNameNode = objDOMNode.selectSingleNode("NAME")
Add the "NAME" element's parent node nodeName and its value to the TreeView.
Set tvwElement = tvwPeople.Nodes.Add(1, tvwChild) tvwElement.Text = objNameNode.parentNode.nodeName & ": " _ & objNameNode.nodeTypedValue
Add the ID of the node to the TreeView node's tag property. The element node holds the ID attribute that we want to store in the tag, as an identity reference. We therefore need to get hold of this node to get its value.
Set objAttributes = objDOMNode.Attributes
We know that we've named our ID reference as "PERSONID", therefore we ask the NameNodeListMap to get this node by using the getNamedItem method. But firstly, we need to check if there are attributes:
If objAttributes.length > 0 Then Set objAttributeNode = objAttributes.getNamedItem("PERSONID")
Store this value in the tag of the TreeView.
tvwElement.Tag = objAttributeNode.nodeValue End If tvwElement.EnsureVisible intIndex = tvwElement.Index
We then need to populate the current TreeView node from the current DOM element node (objDOMNode) by once again iterating through the childNodes of the objDOMNode.
For Each objPersonElement In objDOMNode.childNodes Set tvwChildElement = tvwPeople.Nodes.Add(intIndex, tvwChild) tvwChildElement.Text = objPersonElement.nodeTypedValue Next End Sub
This completes our population of the TreeView from the DOMDocument.
When the user clicks on the TreeView, we need to fetch data from the DOMDocument to populate the text boxes on the right-hand side of the screen.
Private Sub tvwPeople_Click() Dim objSelNode As Node
A little bit of VB checking for unwanted event firing--if this code has just come from the expand and collapse event, then ignore it.
If m_blnItemClicked = True Then m_blnItemClicked = False Exit Sub End If Set objSelNode = tvwPeople.SelectedItem
Call the procedure that handles populating the text boxes.
populatePeopleDetails objSelNode End Sub Private Sub populatePeopleDetails(objSelNode As Node)
This procedure populates the form's text boxes with details from the passed Node object (objSelNode). The parameter objSelNode is the current TreeView node, which the user has clicked on.
Dim objPersonElement As IXMLDOMElement Dim objChildElement As IXMLDOMElement If objSelNode Is Nothing Then Exit Sub
Ignore this TreeView selection if it has not been the "PERSON" node that has been clicked on:
If Trim(objSelNode.Tag) <> "" Then
We need to find the node in the DOMDocument that corresponds to the TreeView item the user has clicked:
Set objPersonElement = m_objDOMPeople.nodeFromID(objSelNode.Tag) lblElement.Caption = objPersonElement.nodeName & ": ID = " & _ objPersonElement.Attributes(0).nodeValue
With this found node (objPersonElement), once again we are going to iterate through its childNodes to populate the text boxes, by using a "Select Case" to filter which element we are dealing with.
For Each objChildElement In objPersonElement.childNodes
Check that the type of node you are dealing with is an element node, as it could also be other types of nodes, for example PIs. Then populate the text box with the text from the DOM node.
If objChildElement.nodeType = NODE_ELEMENT Then Select Case UCase(objChildElement.nodeName) Case "NAME" txtName.Text = objChildElement.nodeTypedValue Case "ADDRESS" txtAddress.Text = objChildElement.nodeTypedValue Case "TEL" txtTel.Text = objChildElement.nodeTypedValue Case "FAX" txtFax.Text = objChildElement.nodeTypedValue Case "EMAIL" txtEmail.Text = objChildElement.nodeTypedValue End Select End If Next objChildElement End If
Clear the object memory resources.
Set objChildElement = Nothing Set objPersonElement = Nothing End Sub
Here the user will fill the text boxes on the right-hand side with the details for the new person: these then need to be saved to the DOMDocument.
This is done in two parts: firstly, clearing all the text boxes, then saving the content. We know this is not "cool" coding but it's just for ease of coding to show the basics of working with the DOMDocument.
Private Sub cmdClear_Click()
This clears the contents of the text boxes.
lblElement.Caption = "" txtName.Text = "" txtAddress.Text = "" txtTel.Text = "" txtFax.Text = "" txtEmail.Text = "" cmdAdd.Enabled = True End Sub
After filling in the text boxes, the user clicks on the "Save New Person", which fires cmdAdd to save the new "Person" to the DOMDocument.
Private Sub cmdAdd_Click() saveNewPerson cmdAdd.Enabled = False End Sub Private Sub saveNewPerson()
This method creates a new element from the user input, and adds it and its children to the DOM object.
Dim objPerson As IXMLDOMElement Dim objNewChild As IXMLDOMElement
Firstly we need to create a new "PERSON" child node (objPerson) for the documentElement node ("PEOPLE").
Set objPerson = m_objDOMPeople.createElement("PERSON")
Before continuing, we also need to give this "PERSON" node a "PERSONID" attribute--here we use our getNewID method to return this ID string. We need to do this as the attribute has been set up as "required" in the DTD. We use the setAttribute method to set this attribute value and add the attribute to the element node.
objPerson.setAttribute "PERSONID", getNewID m_objDOMPeople.documentElement.appendChild objPerson
To this new "PERSON" child we must add its childNodes ("NAME", "ADDRESS", etc). We have chosen to use the createElement method to add the childNodes. However, you can choose to use the createNode method; which you use is just a matter of preference.
Set objNewChild = m_objDOMPeople.createElement("NAME"). objNewChild.Text = txtName.Text
Each childNode needs to be appended to the current "PERSON" node.
objPerson.appendChild objNewChild Set objNewChild = m_objDOMPeople.createElement("ADDRESS") objNewChild.Text = txtAddress.Text objPerson.appendChild objNewChild Set objNewChild = m_objDOMPeople.createElement("TEL") objNewChild.Text = txtTel.Text objPerson.appendChild objNewChild Set objNewChild = m_objDOMPeople.createElement("FAX") objNewChild.Text = txtFax.Text objPerson.appendChild objNewChild Set objNewChild = m_objDOMPeople.createElement("EMAIL") objNewChild.Text = txtEmail.Text objPerson.appendChild objNewChild
We reuse the populateTreeWithChildren method to keep the TreeView in sync with the changes to the DOMDocument.
The new element may be added to the DOMDocument, but it is not added to the source XML until you save the document.
m_objDOMPeople.save XMLPATH webTarget.Refresh Set objPerson = Nothing Set objNewChild = Nothing End Sub
Clicking the "Delete" button allows the user to delete a node from the DOMDocument.
Private Sub cmdDelete_Click() deleteSelectedPerson tvwPeople.SelectedItem End Sub Private Sub deleteSelectedPerson(objSelNode As Node)
The following code deletes the selected TreeView view node, as well as the corresponding item from the DOMDocument. The parameter objSelNode is the TreeView node that has been clicked on.
Dim objPersonElement As IXMLDOMNode
If no tree node has been selected, then exit the procedure.
If objSelNode Is Nothing Then Exit Sub
Once again, we need to find the ID stored in the selected TreeView node, or its parent node tag property, to be able to delete it.
If Trim(objSelNode.Tag) = "" Then If Trim(objSelNode.Parent.Tag) <> "" Then Set objSelNode = objSelNode.Parent End If End If
Once we have found this ID, use the nodeFromID method of the DOMDocument to return the DOMDocument node that needs to be deleted. Find the DOMDocument node, using the tag value found in the selected node of TreeView tag property.
If Trim(objSelNode.Tag) <> "" Then Set objPersonElement = m_objDOMPeople.nodeFromID(objSelNode.Tag)
If the DOMDocument node exists, use the removeChild method that can be accessed via the DOMDocument's documentElement property.
We need to save the DOMDocument, to reflect the removal of the childNode. The TreeView also needs to be kept in sync with this deletion.
m_objDOMPeople.save XMLPATH tvwPeople.Nodes.Remove objSelNode.Index webTarget.Refresh End If End Sub
In this example, techniques for working with the DOMDocument covered included the following:
- The fundamentals of loading an XML document into your program
- What to watch out for when you're using a DTD or Schema to validate your document
- Populating a TreeView control with the same hierarchy found in the DOMDocument
- When clicking on the TreeView control, how to find an item in the DOMDocument, based on a value stored in the tag of the selected TreeView item
- How to add a new item to an XML file, using the createElement and appendChild methods
- How to delete an item from the XML file, using the removeChild method
- How to save the document using the save method after making changes in the DOMDocument
Here are a few suggestions for expanding the application, and hints on doing a bit of experimentation to broaden your knowledge of working with the DOM:
- Update the document when the user has changed an item.
- In the populateTreeWithChildren procedure, we have specifically shown you how to use the IXMLDOMNamedNodeMap interface for iterating through attributes. You can change this procedure to use the getAttributeNode or getAttribute methods.
- In the section, "Adding a New Person to the DOMDocument," instead of using setAttribute for adding an attribute to the element, have a look at using the createAttribute method on the DOMDocument object and then using the setNamedItem method to add it to its element's attribute property.
For more information on using XML and Visual Basic visit VBXML.com, run by the authors of this article.
Copyright 1999 Manning Publications Company. Reprinted with permission.