DevExtreme Data Visualization - Custom Templates (v19.2)

DevExtreme Visualization widgets now support custom templates for Chart Annotations, Legend items, Tooltip content and the center region of Pie and Donut charts. The template system is the same that other DevExtreme widgets use, but custom templates for the Visualization widgets should use SVG markup instead of HTML. Note that Tooltip content is an exception and should be rendered using HTML.

Custom Annotations

Chart Annotations were introduced in v19.1. They can show an image or text anchored to elements or surface points of a chart. Now it is also possible to include additional information in annotations by using a custom template for complex content.

Here is an Angular example of a simple annotation with a custom layout.

<dxo-common-annotation-settings
  type="custom"
  template="annotationTemplate"
>
</dxo-common-annotation-settings>

<dxi-annotation
  argument="New York"
  series="Population"
  [data]="{ capital: 'Albany' }"
>
</dxi-annotation>

<svg *dxTemplate="let annotation of 'annotationTemplate'">
  <image
    attr.href="annotation.flagUrl"
    x="0"
    y="0"
    width="60"
    height="40"
  />
  <text x="70" y="25">{{annotation.argument}}</text>
  <text x="0" y="60">
    <tspan class="caption">Capital:</tspan>
    <tspan dx="5">{{annotation.data.capital}}</tspan>
    ...
  </text>
</svg>

Embedded Widgets

It is also possible to create complex custom templates that include additional widgets. This example uses annotations to implement a drill-down scenario with an embedded chart.

Please click here for a demo of annotation templates. There is also documentation for the annotation template feature.

Custom Content Inside a Donut Chart

We added the centerTemplate property for Pie and Donut charts, which allows you to show custom content in the center area of these charts - a frequently requested feature.

Here is an example that shows a total value using the centerTemplate.

<dx-pie-chart
  [dataSource]="data"
  type="doughnut"
  centerTemplate="holeTemplate"
>
  <dxi-series>...</dxi-series>

  <svg *dxTemplate="let pieChart of 'holeTemplate'">
    <text
      text-anchor="middle"
      style="font-size: 18px"
      x="100"
      y="100"
      fill="#494949"
    >
      <tspan x="100">Total:</tspan>
      <tspan x="100" dy="20px" style="font-weight: 600">
        {{ calculateTotal(pieChart) }}
      </tspan>
    </text>
  </svg>
</dx-pie-chart>

Documentation for the centerTemplate property is here and the online demo shows an implementation with slightly more complicated markup.

Tooltip Templates

The new option tooltip.contentTemplate allows you to use templates for tooltips. It was previously possible to embed custom HTML content in tooltips by generating a string in customizeTooltip, and of course this option remains available. However, templates offer a much cleaner approach and template code is easier to maintain.

Using customizeTooltip, you may have written code like this (or much longer in real applications):

customizeTooltip = args => {
  const { point, value } = args;
  const valueText = this.pipe.transform(value, '3.0-0');
  return {
    html: `
    <div class='state-tooltip'>
      <div>
        <span class='caption'>Capital</span>:
        ${point.capital}
      </div>
      <div>
        <span class='caption'>Population</span>:
        ${valueText}
      </div>
    </div>`
  };
};

Using the new contentTemplate, you can use this short template instead:

<div *dxTemplate="let info of 'content'">
  <div>
    <span class="caption">Capital</span>:
    {{info.point.data.capital}}
  </div>
  <div>
    <span class="caption">Population</span>: {{info.value |
    number:"3.0-0"}} people
  </div>
</div>

The template is easier to read and maintain, and it supports built-in framework features like the Angular “pipe” formats in the sample. In Vue or React, the template is simply a component.

We have modified our existing tooltip customization demo to take advantage of the new template mechanism. Documentation for the contentTemplate option is also available.

Custom Legend Item Markers

Custom markers for Legend items are a frequently requested feature. It is now possible to use templates for these markers. Please click here for the Custom Legend Markers demo or read the documentation of the markerTemplate option.

Please Let Us Know What You Think

We are looking forward to your feedback, especially if you need to be able to customize additional elements of charts and other visualization widgets with templates.