Using TXMLDocument, Working with XML Nodes

Using TXMLDocument

The starting point for working with an XML document is the Xml.XMLDoc.TXMLDocument component.

The following steps describe how to use TXMLDocument to work directly with an XML document:

1. Add a TXMLDocument component to your form or data module. TXMLDocument appears on the Internet category of the Tool Palette.
   
   
2. Set the DOMVendor property to specify the DOM implementation you want the component to use for parsing and editing an XML document.
   The Object Inspector lists all the currently registered DOM vendors.
   For information on DOM implementations, see Using the Document Object Model.
   
   
3. Depending on your implementation, you may want to set the ParseOptions property to configure how the underlying DOM implementation parses the XML document.
   
   
4. If you are working with an existing XML document, specify the document:
   • If the XML document is stored in a file, set the FileName property to the name of that file.
   • You can specify the XML document as a string instead by using the XML property.
     
     
5. Set the Active property to True.

Once you have an active TXMLDocument object, you can traverse the hierarchy of its nodes, reading or setting their values.

The root node of this hierarchy is available as the DocumentElement property.

For information on working with the nodes of the XML document, see Working with XML Nodes.

Working with XML Nodes

Once an XML document has been parsed by a DOM implementation, the data it represents is available as a hierarchy of nodes.

Each node corresponds to a tagged element in the document.

For example, given the following XML:

<?xml version="1.0" encoding="UTF-8" standalone="no" ?>

<!DOCTYPE StockHoldings SYSTEM "sth.dtd">

<StockHoldings>

   <Stock exchange="NASDAQ">
      <name>Borland</name>
      <price>15.375</price>
      <symbol>BORL</symbol>
      <shares>100</shares>
   </Stock>

   <Stock exchange="NYSE">
      <name>Pfizer</name>
      <price>42.75</price>
      <symbol>PFE</symbol>
      <shares type="preferred">25</shares>
   </Stock>

</StockHoldings>

TXMLDocument would generate a hierarchy of nodes as follows:

The root of the hierarchy would be the StockHoldings node. 

StockHoldings would have two child nodes, which correspond to the two Stock tags.

Each of these two child nodes would have four child nodes of its own (name, price, symbol, and shares).

Those four child nodes would act as leaf nodes.

The text they contain would appear as the value of each of the leaf nodes.

Note: 

This division into nodes differs slightly from the way a DOM implementation generates nodes for an XML document.

In particular, a DOM parser treats all tagged elements as internal nodes.

Additional nodes (of type text node) are created for the values of the name, price, symbol, and shares nodes.

These text nodes then appear as the children of the name, price, symbol, and shares nodes.

Each node is accessed through an Xml.XMLIntf.IXMLNode interface, starting with the root node, which is the value of the XML document component's DocumentElementproperty.

Working with a node's value

Given an IXMLNode interface, you can check whether it represents an internal node or a leaf node by checking the IsTextElement property.

• If it represents a leaf node, you can read or set its value using the Text property.
• If it represents an internal node, you can access its child nodes using the ChildNodes property.

BorlandStock := XMLDocument1.DocumentElement.ChildNodes[0];
Price := BorlandStock.ChildNodes['price'].Text;

Working with a node's attributes

If the node includes any attributes, you can work with them using the Attributes property.

You can read or change an attribute value by specifying an existing attribute name.

You can add new attributes by specifying a new attribute name when you set the Attributes property: 

BorlandStock := XMLDocument1.DocumentElement.ChildNodes[0];
BorlandStock.ChildNodes['shares'].Attributes['type'] := 'common';

Adding and deleting child nodes

You can add child nodes using the AddChild method. 

AddChild creates new nodes that correspond to tagged elements in the XML document.

Such nodes are called element nodes.

To create a new element node, specify the name that appears in the new tag and, optionally, the position where the new node should appear.

For example, the following code adds a new stock listing to the document above:

var
  NewStock: IXMLNode;
  ValueNode: IXMLNode;
begin
  NewStock := XMLDocument1.DocumentElement.AddChild('stock');
  NewStock.Attributes['exchange'] := 'NASDAQ';
  ValueNode := NewStock.AddChild('name');
  ValueNode.Text := 'Cisco Systems'
  ValueNode := NewStock.AddChild('price');
  ValueNode.Text := '62.375';
  ValueNode := NewStock.AddChild('symbol');
  ValueNode.Text := 'CSCO';
  ValueNode := NewStock.AddChild('shares');
  ValueNode.Text := '25';
end;

You can delete child nodes using the methods of the ChildNodes property. 

ChildNodes is an IXMLNodeList interface, which manages the children of a node.

You can use its Delete method to delete a single child node that is identified by position or by name.

For example, the following code deletes the last stock listed in the document above:

StockList := XMLDocument1.DocumentElement;
StockList.ChildNodes.Delete(StockList.ChildNodes.Count - 1);

Xml.XMLIntf.TNodeType

TNodeType = (
    ntReserved, 
    ntElement, 
    ntAttribute, 
    ntText, 
    ntCData,
    ntEntityRef, 
    ntEntity, 
    ntProcessingInstr, 
    ntComment, 
    ntDocument,
    ntDocType, 
    ntDocFragment, 
    ntNotation);

Value	Meaning
ntReserved	Not used
ntElement	The node represents an element. Element nodes represent simple tags that have child nodes. (Note that sometimes these child nodes do not appear when using IXMLNode. For example child nodes of type ntText are typically hidden by IXMLNode and appear only as the value of the Text property). The child nodes of an element node can have the following node types: ntElement, ntText, ntCData, ntEntityRef, ntProcessingInstr, and ntComment. Element nodes can also have attributes (ntAttribute). Element nodes can be the child of a node of type ntDocument, ntDocFragment, ntEntityRef, and ntElement. ntElement -> ntElement -> ntElement ... --> ntText
ntAttribute	The node represents an attribute of an element. It is not the child of another node, but its value can be accessed using the Attribute property of the element node's IXMLNode interface. An attribute node can have child nodes of type ntText and ntEntityRef.
ntText	The node represents the text content of a tag. A text node cannot have any child nodes, but can appear as the child node of a node of type ntAttribute, ntDocFragment, ntElement, or ntEntityRef.
ntCData	The node represents a CDATA section in the XML source. CDATA sections identify blocks of text that would otherwise be interpreted as markup. An ntCData node can't have any child nodes. They can appear as the child of an ntDocFragment, ntEntityRef, or ntElement node.
ntEntityRef	The node represents a reference to an entity in the XML document. This can be any type of entity, including character entity references. The children of an entity reference node can be of the following types: ntElement, ntProcessingInstr, ntComment, ntText, ntCData, and ntEntityRef. The entity reference node can appear as the child of an ntAttribute, ntDocFragment, ntElement, or ntEntityRef node.
ntEntity	The node represents an expanded entity. Entity nodes can have child nodes that represent the expanded entity (for example, ntText and ntEntityRef nodes). Entity nodes only appear as the child of an ntDocType node.
ntProcessingInstr	The node represents a processing instruction (PI) from the XML document. A PI node cannot have any child nodes, but can appear as the child node of a node of type ntDocument, ntDocFragment, ntElement, or ntEntityRef.
ntComment	The node represents a comment in the XML document. Comment nodes do not have child nodes. They appear as the child of an ntDocument, ntDocFragment, ntElement, or ntEntityRef node.
ntDocument	The node represents a document object, which is the root of the entire XML document. Document nodes have a single ntElement node as a child (the DocumentElement). In addition, they can have child nodes of type ntProcessingInstr, ntComment, and ntDocType. Because the document is the root of the XML document, it never appears as a child node.
ntDocType	The node represents the document type declaration, indicated by the <!DOCTYPE > tag. The document type node can child nodes of type ntNotation and ntEntity. It always appears as the child of the document node.
ntDocFragment	The node represents a document fragment. A document fragment node associates a node or subtree with a document without actually being contained in the document. Document fragment nodes can have child nodes of type ntElement, ntProcessingInstr, ntComment, ntText, ntCData, and ntEntityRef. It never appears as the child of another node.
ntNotation	A node represents a notation in the document type declaration. It always appears as the child of an ntDocType node and never has any child nodes.