TeeChart Pro and XML. A tutorial.

Introduction

TeeChart version 5 added support for XML output of chart series data.
Version 6 introduces support for 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 version 6 includes a new 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:='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;

Output:

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.

This property refers to an late-bound created instance that implements Microsoft's IXMLDomDocument interface.
TeeChart does not use an early-bound instance to avoid dependency and version incompatibility problems that can arise depending on your Windows version, Internet Explorer version, etc.

If you want to read an excellent article about using the XML parser in Delphi, please follow this link to The Delphi Magazine website.

Another useful property of TeeXMLSource component is "XML" of type TStringList.
You can use this property to set XML data instead of using the FileName property. In this way, no XML external file is necessary.

The Tee6New demo (full sources included in TeeChart Pro 6 evaluation and registered versions), contains examples very similar to the ones here exposed.

The demo used in this tutorial is also available for download.
Note: TeeChart Pro version 6 (evaluation or registered) is required to compile this demo.

Steema Software
Support Department.