Converting XML Documents into Data Packets

Once you have created a transformation file that indicates how to transform an XML document into a data packet, you can create data packets for any XML document that conforms to the schema used in the transformation. These data packets can then be assigned to a client dataset and saved to a file so that they form the basis of a file-based database application.

The TXMLTransform component transforms an XML document into a data packet according to the mapping in a transformation file.

Note: You can also use TXMLTransform to convert a data packet that appears in XML format into an arbitrary XML document.

Specifying the source XML document

There are three ways to specify the source XML document:

If the source document is an .xml file on disk, you can use the SourceXmlFile property.
If the source document is an in-memory string of XML, you can use the SourceXml property.
If you have an IDOMDocument interface for the source document, you can use the SourceXmlDocument property.

TXMLTransform checks these properties in the order listed above. That is, it first checks for a file name in the SourceXmlFile property. Only if SourceXmlFile is an empty string does it check the SourceXml property. Only if SourceXml is an empty string does it then check the SourceXmlDocument property.

Specifying the transformation

There are two ways to specify the transformation that converts the XML document into a data packet:

Set the TransformationFile property to indicate a transformation file that was created using xmlmapper.exe.
Set the TransformationDocument property if you have an IDOMDocument interface for the transformation.

TXMLTransform checks these properties in the order listed above. That is, it first checks for a file name in the TransformationFile property. Only if TransformationFile is an empty string does it check the TransformationDocument property.

Obtaining the resulting data packet

To cause TXMLTransform to perform its transformation and generate a data packet, you need only read the Data property. For example, the following code uses an XML document and transformation file to generate a data packet, which is then assigned to a client dataset:

Copy Code

XMLTransform1.SourceXMLFile := 'CustomerDocument.xml';
XMLTransform1.TransformationFile := 'CustXMLToCustTable.xtr';
ClientDataSet1.XMLData := XMLTransform1.Data;

Copy Code

XMLTransform1->SourceXMLFile = "CustomerDocument.xml";
XMLTransform1->TransformationFile = "CustXMLToCustTable.xtr";
ClientDataSet1->XMLData = XMLTransform1->Data;

Converting user-defined nodes

When you define a transformation using xmlmapper.exe, you can specify that some of the nodes in the XML document are "user-defined." User-defined nodes are nodes for which you want to provide the transformation in code rather than relying on a straightforward node-value-to-field-value translation.

You can provide the code to translate user-defined nodes using the OnTranslate event. The OnTranslate event handler is called every time the TXMLTransform component encounters a user-defined node in the XML document. In the OnTranslate event handler, you can read the source document and specify the resulting value for the field in the data packet.

For example, the following OnTranslate event handler converts a node in the XML document with the following form

Copy Code

<FullName>
   <Title> </Title>
   <FirstName> </FirstName>
   <LastName> </LastName>
</FullName>

into a single field value:

Copy Code

procedure TForm1.XMLTransform1Translate(Sender: TObject; Id: String; SrcNode: IDOMNode;
  var Value: String; DestNode: IDOMNode);
var
  CurNode: IDOMNode;
begin
  if Id = 'FullName' then
  begin
    Value = '';
    if SrcNode.hasChildNodes then
    begin
      CurNode := SrcNode.firstChild;
      Value := Value + CurNode.nodeValue;
      while CurNode <> SrcNode.lastChild do
      begin
        CurNode := CurNode.nextSibling;
        Value := Value + ' ';
        Value := Value + CurNode.nodeValue;
      end;
    end;
  end;
end;

Copy Code

void __fastcall TForm1::XMLTransform1Translate(TObject *Sender, AnsiString Id,
_di_IDOMNode SrcNode, AnsiString &Value, _di_IDOMNode DestNode)
{
  if (Id == "FullName")
  {
    Value = "";
    if (SrcNode.hasChildNodes)
    {
      _di_IXMLDOMNode CurNode = SrcNode.firstChild;
      Value = SrcValue + AnsiString(CurNode.nodeValue);
      while (CurNode != SrcNode.lastChild)
      {
        CurNode = CurNode.nextSibling;
        Value = Value + AnsiString(" ");
        Value = Value + AnsiString(CurNode.nodeValue);
      }
    }
  }
}