Charts¶

New in Atfinity 17.

ADX can draw pie, bar, stacked bar and line charts directly into a document. The chart tags are a pure presentation layer: they contain no queries and no aggregation. The numbers come from Jinja, and every data point is written as its own child element, so a Jinja loop produces the chart.

<pieChart width="100%" aspectRatio="2:1">
  {% for group in cases|groupby('status') %}
  <slice label="{{ group.grouper }}" value="{{ group.list|length }}"/>
  {% endfor %}
</pieChart>

All four charts can be used within <body>, <box>, <column>, a <td> of a <table>, <keepTogether> and inside a <template>.

Which chart to use¶

Chart	Use it for	Notes
Pie Chart	Shares of a single total	Set `innerRadius` to get a donut
Bar Chart	Comparing values across categories	Several `<series>` are drawn side by side
Stacked Bar Chart	Composition within each category	`stackMode="percentage"` makes every column full height
Line Chart	Values that are connected, usually over time	Do not use it for unrelated categories

Data¶

A chart with one set of values takes a leaf element per data point, <slice> for pie charts and <bar> for the others. A chart with several sets wraps each set in a <series> of <point> elements:

<barChart width="16cm" height="7cm">
  <series label="Retail">
    <point label="Q1" value="42"/>
    <point label="Q2" value="51"/>
  </series>
  <series label="Corporate">
    <point label="Q1" value="15"/>
    <point label="Q2" value="12"/>
  </series>
</barChart>

A series may skip categories. The categories of the chart are the union of all <point> labels in the order in which they first appear, and a missing value counts as 0. Repeating the same label inside one series adds the values together.

An empty value is 0, which matters because Jinja renders a missing value as an empty string. A value that is not a number stops the rendering with an error.

Sizing¶

Every chart needs a width and either a height or an aspectRatio.

width \ An absolute length such as 16cm, or a percentage of the available width such as 100%. Percentages are useful inside a <column> or a table cell.

height \ An absolute length such as 7cm. Percentages are not supported.

aspectRatio \ Derives the height from the resolved width, e.g. aspectRatio="16:9". Use this together with width="100%" when the surrounding width is not known.

A chart never splits across pages. If it does not fit on the rest of the page it moves to the next one at its full size. A chart that is taller than a whole page is scaled down to fit.

Common attributes¶

These attributes exist on all four chart tags.

left, bottom (optional) \ Position of the chart when it is used inside a <template>, e.g. left="2cm" bottom="20cm". Both are required there and ignored in the <body>.

spaceBefore, spaceAfter (optional) \ Vertical space before and after the chart.

legend (optional) \ Where to put the legend: none, right, left, top or bottom. Pie charts default to right, bar and stacked bar charts to bottom, line charts to top.

legendWidth (optional) \ Width reserved for a left or right legend. Defaults to 35% of the chart width.

legendColumns (optional) \ Fixes the number of legend columns, 1 to 4. By default the legend picks the layout that fits.

legendFontSize (optional) \ Font size of the legend in pt. Defaults to fontSize. If the legend does not fit, the font shrinks and the plot gets smaller so that no entry is ever dropped.

valueType (optional) \ How values are written in labels and the legend: amount (42), amountPercentage (42 (35%)) or percentage (35%). Defaults to amount.

valueSuffix (optional) \ Appended to every value, e.g. valueSuffix=" CHF".

decimals (optional) \ Number of decimals in labels, 0 to 4. Defaults to 0.

maxLabelChars (optional) \ Labels longer than this are shortened with an ellipsis, 4 to 60. Defaults to 24.

minLabelPercentage (optional) \ Data points smaller than this share of the total get no label, 0 to 50. Defaults to 3.

order (optional) \ value sorts by value, label alphabetically, none keeps the order of the document. Pie charts default to value, all others to none so that a time series stays in order.

orderDirection (optional) \ desc or asc. Defaults to desc.

otherLabel (optional) \ Label of the bucket that collects everything beyond the maximum number of slices, categories or series. Defaults to Other. A data point that already carries this label absorbs the bucket instead of appearing twice.

palette, colors (optional) \ palette="insights" uses the same twelve colours as the insights charts and is the default. colors overrides it with a space separated list, e.g. colors="hex(0x186C95) hex(0x7ECBF1)". A single data point can always set its own color.

font, fontSize, color (optional) \ Font and colour of the labels. fontSize is 4 to 24 and defaults to 8.

backgroundColor, borderWidth, borderColor (optional) \ Background and border of the whole chart area.