Tutorial 15 - Working with XML

Tutorial 15 - XML Export & Import

Introduction

TeeChart version 5 and later supports XML output of chart series data.

Version 6 and later supports data input in XML format.

This tutorial shows a detailed explanation about exporting and importing chart data in XML format.

Exporting

Chart data can be easily exported to XML format either at design-time or run-time using the Chart export dialog:

Fig. 1. TeeChart export dialog, data tab.

From this dialog you can choose which series to export (or "all" to export all series), and whether you want to export point indexes (0,1,2... etc), point texts (labels) or colors.

The "Copy" button generates XML text and copies it to Windows or Linux clipboard. The "Save" button creates a new XML file.
The XML file can be opened, for example, with Internet Explorer.

Sample XML file containing a single series

When exporting multiple series, the XML format is a little bit different:

Sample XML file containing a single series

Exporting by code

TeeChart provides a class to export series data in XML format.
This class is located in TeeStore.pas unit, and its name is TSeriesDataXML.

Example of saving to file:

Uses TeeStore;

with TSeriesDataXML.Create(Chart1, Series1) do
try
  SaveToFile('c:\sample.xml');
finally
  Free;
end;

If you want to export all series in Chart1, pass "nil" instead of passing Series1 in the last parameter of Create constructor.

This class also provides a function to get the XML output into a string:

var S : String;
with TSeriesDataXML.Create(Chart1, Series1) do
try
  S:=AsString;
finally
  Free;
end;

Several properties control what kind of data to export, like for example if including point colors or not:

with TSeriesDataXML.Create(Chart1, Series1) do
try
  IncludeColors:=True;
  SaveToFile('c:\sample.xml');
finally
  Free;
end;

We have seen so far how to generate XML data containing TeeChart series points.
Let's now do the opposite, to import this XML into charts.

Importing XML data

TeeChart Pro includes a component to automatically load XML data.
This component resides at TeeXML.pas unit, and the class name is TTeeXMLSource.

Fig 2. TeeXMLSource component at Delphi's toolbar.

The minimum properties required to load XML charts are "Chart" and "FileName".
The Chart property indicates where (which Chart) to add the XML data. The FileName property can be also a web address (URL).
The Load method initiates loading the XML data into chart series.

Let's create a new application and drop a Chart1 component and a TeeXMLSource1 component.

uses Series;

procedure TForm1.FormCreate(Sender: TObject);
begin
  RegisterTeeStandardSeries; // make sure "Line" style is loaded.

  TeeXMLSource1.Chart:=Chart1;
  TeeXMLSource1.FileName:='http://www.steema.com/support/teechart/9/tutorials/xml/TeeChartSampleManySeries.xml';
  TeeXMLSource1.Load;
end;

Note: In the above example, the call to RegisterTeeStandardSeries can be omitted by adding a TeeChart toolbar or adding the TeeGally unit to the "uses" clause. It simply registers basic chart styles (line, bar, pie, etc) so the XML importing process can automatically create series based on the series style that is found in the xml file.

The resulting Chart is:

Fig 3. Chart loaded with sample xml file.

Loading a remote XML file from a web URL is also as simple:

procedure TForm1.FormCreate(Sender: TObject);
begin
  TeeXMLSource1.Chart:=Chart1;
  TeeXMLSource1.FileName:='http://www.steema.com/SampleData.xml';
  TeeXMLSource1.Load;
end;

Fig 3. Chart loaded with sample xml file from web url.

Loading just one series

The XML source component has a SeriesNode property that can be used to load just one series (in case the XML file contains more than one series).

 
TeeXMLSource1.SeriesNode:='Series2';

Loading to an existing series

If you want to load one series data contained in the XML file, into an existing series, set the Series property:

TeeXMLSource1.Series:=Series1; 
TeeXMLSource1.SeriesNode:='Series2';

The above code will load the XML data that corresponds to "Series2", into Series1.

Note:

If the series classes are different (for example, XML Series2 is a "Line" , and Series1 is a "Bar"), the final output will be Series1 filled with null points.

Why ?

The XML data for "Series2" defines point values as "Y" values, while Series1 (a Bar series), expects points to be defined as "Bar".

There are two solutions to this problem:

a) Set Series1 valuesource property to match the name of the XML points:

Series1.YValues.ValueSource := 'Y';

b) Set the ValueSource property of the XMLSource component to match the name of the Series1 valuesource:

TeeXMLSource1.ValueSource := 'Y';

Additional features

The TeeXMLSource component also includes a XMLDocument property that returns an OleVariant reference to the internal object that parses and loads XML data.

The demo used in this tutorial is also available for download.