Designing XML Templates From Examples¶
Introduction¶
The charts.js documentation provides examples for the different charts.
The SAV Charts extension comes with templates for all chart types.
These templates are in the directory
Resources/Private/Templates/ChartExamples
of the extension.
To display a template, simply create a SAV Charts plugin content element in a page.

Then click on the plugin tab.

Fill the template field of the flexform and save.

Go to the frontend and you should see the following image.

Writing Templates¶
The templates provided with the extension were adpated from the examples given in the charts.js documentation. Let us illustrate the principle for the line chart.
The javascript code to display the line graph is the following:
var data = {
labels: ["January", "February", "March", "April", "May", "June", "July"],
datasets: [
{
label: "My First dataset",
fillColor: "rgba(220,220,220,0.2)",
strokeColor: "rgba(220,220,220,1)",
pointColor: "rgba(220,220,220,1)",
pointStrokeColor: "#fff",
pointHighlightFill: "#fff",
pointHighlightStroke: "rgba(220,220,220,1)",
data: [65, 59, 80, 81, 56, 55, 40]
},
{
label: "My Second dataset",
fillColor: "rgba(151,187,205,0.2)",
strokeColor: "rgba(151,187,205,1)",
pointColor: "rgba(151,187,205,1)",
pointStrokeColor: "#fff",
pointHighlightFill: "#fff",
pointHighlightStroke: "rgba(151,187,205,1)",
data: [28, 48, 40, 19, 86, 27, 90]
}
]
};
The template is built by transforming this javascript code into a
XML structure using the <data>
tag. By doing so, thanks to the
data tag id, references can be used.
References provide an easy means to split the data and therefore
to make it possible to have them overloaded in the flexform data section or with queries.
The following code is the translation in XML of the previous
javascript code where <data>
tags whose id are labels
, dataSet1
and dataSet2
can be easily overloaded as explained in the next section.
<?xml version="1.0" encoding="UTF-8"?>
<charts>
<lineChart id="1" data="data#lineChartData" options="data#lineChartOptions" >
<marker id="labelSet0">My First dataset</marker>
<marker id="labelSet1">My Second dataset</marker>
<data id="labels">
January, February, March, April, May, June, July
</data>
<data id="dataSet0">
65, 59, 80, 81, 56, 55, 40
</data>
<data id="dataSet1">
28, 48, 40, 19, 86, 27, 90
</data>
<data id="set0">
<item key="label" value="marker#labelSet0" />
<item key="backgroundColor">rgba(220,220,220,0.2)</item>
<item key="pointColor">rgba(220,220,220,1)</item>
<item key="pointBackgroundColor">#fff</item>
<item key="pointHoverBackgroundColor">rgba(220,220,220,1)</item>
<item key="data" value="data#dataSet0" />
</data>
<data id="set1">
<item key="label" value="marker#labelSet12" />
<item key="backgroundColor">rgba(151,187,205,0.2)</item>
<item key="pointColor">rgba(151,187,205,1)</item>
<item key="pointBackgroundColor">#fff</item>
<item key="pointHoverBackgroundColor">rgba(151,187,205,1)</item>
<item key="data" value="data#dataSet1" />
</data>
<data id="dataSets">
<item key="0" value="data#set0" />
<item key="1" value="data#set1" />
</data>
<data id="lineChartData">
<item key="labels" value="data#labels" />
<item key="datasets" value="data#dataSets" />
</data>
<data id="lineChartOptions">
</data>
</lineChart>
</charts>
Tip
<data>
were inserted inside the <lineChart>
tag just by personal choice.
They could have been provided before
the <lineChart>
tag. In that case, this tag would have no content
and would simply be written:
<lineChart id="1" data="data#lineChartData" options="data#lineChartOptions" />
Overloading Data¶
Open the plugin in the backend and fill the Data section of the flexform as follows and save:

Go in the frontend and you should see the following figure.

The principle in SAV Charts is to consider that for a given tag
with a given id the first definition is the first one to use. Therefore, in the
previous example, since <data> tag for id dataSet0
and dataSet1
are defined in the data section, which is
before the template section, they will not be replaced by the
same <data>
tags in the template. One may consider
that the <data>
tags in the data section overloads the same tags in the template.
It provides a quite simple way of working with generic templates and
adapting their behavior with your real data.
For example, using the same template LineChart.xml
, you may want
to display only one curve.
It can simply be done by defining the <data>
tag whose id is
dataSets
in the data section as shown below.
<data id="dataSet0">1,6,3,9</data>
<data id="labels">1,2,3,4</data>
<data id="dataSets">
<item key="0" value="data#set0" />
</data>
Enter the previous code in the flexform data section, save and go to the frontend.

Note
In very specific cases you may explicitly allow to overload a given tag
by setting the attribute overload to 1. See
Resources/Private/Templates/ChartExamples/LineChartAdvanced.xml
in which this
feature is used to build a flexible template.
Overloading Markers¶
Markers are tags which can be used to create strings. In the line chart
template two markers are used to define labels
which are displayed in the legend. The markers can be overloaded in the
Markers
section of the flexform. Assuming that you have
the previous code to display only one line chart, input the following code in
the Markers
sections, save and go to the frontend.
<marker id="labelSet0">Single curve</marker>

Options¶
Options are defined in the charts.js documentation. They can be set by
overloading the <data>
tag associated with the options
attribute of the chart. For example, in the LineChart.xml
template,
the chart is defined as follows:
<lineChart id="1" data="data#lineChartData" options="data#lineChartOptions" >
....
</lineChart>
The options
attribute is a reference to the <data>
tag whose id is lineChartOptions
.
Overloading this tag in the Data
section of the flexform will set options.
Let us assume that the data section is still configure for a single chart, with a modifed label.
Add the following code in the Data
section of the flexform. It will cancel the animation,
set a linear interpolation between points.
<data id="lineChartOptions" >
<item key="animation"></item>
<item key="elements">
<item key="line">
<item key="tension" value="0" />
</item>
</item>
</data>
Note
A linear interpolation is obtained by setting tension to 0 in
Chart.defaults.global.elements.line
(see charts.js documentation).
Since the global option are in the <data>
whose id is lineChartOptions
, nested items whose
keys are elements
and line
provide acces to Chart.defaults.global.elements.line
.

Tip
To generate a boolean value, set the attribute value
to true
or false
.