Programming XML Documents

An application reads and changes a loaded XML document through its elements. TXTextControl exposes them as collections of XMLElement objects, one collection for each kind of element, and each collection can also insert and delete elements within the rules of the document's DTD.

The Visual Basic examples below work with the address list of Editing XML Files, loaded into a TXTextControl named TXTextControl1.

Get the Elements of One Kind

The XMLElements property returns an XMLElements collection with all elements of the same tag name. In the example document there is one collection for all Address elements and another one for all Name elements. The following line of code gets the collection of the Name elements:

Set NameElements = TXTextControl1.XMLElements("Name")

Read the Text of an Element

A collection has the standard Item method, which returns a single element. The Text property of the XMLElement object returns its text. The following line of code displays the content of the second Name element:

MsgBox TXTextControl1.XMLElements("Name").Item(2).Text

Item is the default method of the XMLElements collection, so the following line of code is equivalent:

MsgBox TXTextControl1.XMLElements("Name")(2)

Read and Set the Text of Elements With Sub-Elements

The Text property of an element that contains sub-elements is the complete text of all sub-elements, separated by Chr(10) characters. For the second Address element of the example document, TXTextControl1.XMLElements("Address")(2), it displays:

Tom Baker
Miller Street
Los Angeles

To set a new text with the Text property, specify a string whose parts are separated by Chr(10) characters:

TXTextControl1.XMLElements("Address")(2) = _
   "Paul Baskerville" & Chr(10) & "Jackson Street" & Chr(10) & "London"

Iterate Through a Collection

With a For Each statement, a program iterates through an XML collection. The following example displays all names:

For Each element in TXTextControl1.XMLElements("Name")
   MsgBox element.Text
Next

For development environments that don't support For Each processing, the following code is equivalent. It uses the Count property of the collection:

Set elements = TXTextControl1.XMLElements("Name")
For i = 1 To elements.Count
   MsgBox elements(i).Text
Next i

How the DTD Controls Insertions and Deletions

An XMLElements collection also has an Add and a Remove method, which insert and delete elements. What they may insert or delete is decided by the structure of the document.

The structure of an XML document is described by a document type definition (DTD), which is either contained inline in the XML file or stored in a separate DTD file. The following DTD file, addresses.dtd, belongs to the example document:

<!ELEMENT Addresses (DocumentHeadline, AddressTable)>
<!ELEMENT DocumentHeadline (#PCDATA)>
<!ELEMENT AddressTable (Address+)>
<!ELEMENT Address (Name, Street, City)>
<!ELEMENT Name (#PCDATA)>
<!ELEMENT Street (#PCDATA)>
<!ELEMENT City (#PCDATA)>

The rules of this DTD are:

• Text is allowed only in elements declared with #PCDATA.
• The document has a single document headline and a single address table.
• The address table has one or more addresses.
• Each address has the three sub-elements Name, Street and City.

With these rules, elements can be inserted or removed only as complete addresses. Inserting or removing any of the other elements results in an invalid document, and an XMLInvalid event occurs when a program tries it.

Insert an Element

To insert an address, create a new XMLElement object, initialize it with text and call the Add method of the Address collection:

Dim NewAddress As Object
Set NewAddress = CreateObject("TIS.TX.XMLElement.34")
NewAddress.Text = "Paul Baskerville" & Chr(10) & "Jackson Street" & Chr(10) & "London"
TXTextControl1.XMLElements("Address").Add NewAddress, , 2

The code works as follows:

• CreateObject creates the new XMLElement object from its class name, TIS.TX.XMLElement.34.
• The Text property fills the name, street and city of the new address, separated by Chr(10) characters.
• Add inserts the new address after the second address in the document. With its before parameter, an element is inserted before a certain element instead.

Delete an Element

The following line of code removes the address inserted above:

TXTextControl1.XMLElements("Address").Remove(3)

Remove is also checked against the DTD. Because the DTD requires at least one address, trying to remove the last address results in an invalid document, and an XMLInvalid event occurs.

Key Members

Next Steps

• Editing XML Files: what users can do in the XML editor mode.
• Loading and Saving XML Files: validation, load errors and saving the CSS file.
• XML Basics: the rules of a DTD in the XML Basics sample program.