How to create custom chart bindings

About this article

This article explains how to create a custom chart binding.

A custom chart binding is a binding that can be used to automate the creation of dynamic charts with external data when generating PowerPoint presentations or Word documents. To enhance data compliance, built-in data quality and efficiency.

Automated charts reduce the risk of manual errors in data entry and calculations, ensuring that the information is reliable and consistent.

Charts can be connected to reliable data sources, ensuring that the information is current and relevant, when the presentation or document is created.

• Technical limitations
• Technical clarifications
• Example Word (Data Connector)
• Example PowerPoint (Document Generation API)

Prerequisites

Technical limitations

Technical clarifications

Example Word (Data Connector)

In this example a text element with a data connector is created which allows a user to select a value (Customer ID) from an external data source in the dropdown. The selected value is used for the chart in the document.

For this example the external data source 'Orders' is used, which contains an array named 'Order_Details':

Below some records of the external data source are shown:

1. In Word open a new document then in Template Designer click + Create template.
   
   

   Charts are supported in documents and text elements.

    
2. On the Form tab click + Add question, then in the Type field select Data connector.
   
   
3. In the Question field type 'Customer'.
   
   
4. In External data source select Orders, then in Label column select CustomerID (this is the second column shown in the screenshot above). The result looks like this:
   
   
   
   
5. Click Add to form.
   
   
6. On the Insert tab click Chart, then select the chart you want to use. In this example the Column chart is selected. Click Ok to insert the chart:
   
   
   
   
7. The chart is inserted with some default dummy values. As you don't need these values, close the Excel sheet:
   
   
   
   

   In the Excel sheet above cell A1 is empty and cells B1, C1 and D1 contain the dummy values 'Series 1', 'Series 2' and 'Series 3'. The values of these cells will be replaced by the values of the Column header. If one or more Column headers are left empty then the values of the cells become 'Column1', 'Column2' etc..

    
   
8. On the Template tab click Custom chart binding:
   
   
   
   
9. Now all fields need to be linked to fields in the external data source above, using Form bindings.
   
   - Chart title: The title of the chart. This can be plain text like "My Title" or a binding. In this example a binding is used. Type {{Form.Customer.CustomerID}}.
   - Chart data: The data used for the chart, this must be an array! Type {{Form.Customer.Order_Details}}.
   
   Column A
   - Column header: Type the name of the label you want to show, for example Product ID.
   - Data type: Select the type of data (Number, Text or Date) from the external data source, in this case Number, because the product ID is a number.
   - Values: The value(s) you want to show. In this case {{CurrentItem.ProductID}}. This field is part of the array (item 17.2 in the schema shown above).
   
   Column B
   - Column header: The name of the label, for example Quantity.
   - Data type: Select the type of data. In this case Number, because the quantity is a number.
   - Values: The value(s) you want to show. In this case {{CurrentItem.Quantity}}. This field is part of the array (item 17.4 in the schema shown above).
   
   
10. Click + Add column to another column (Column C) and add these values:
    
    Column C
    - Column header: The name of the label, for example Unit Price.
    - Data type: Select the type of data. In this case Number, because the unit price is a number.
    - Values: The value(s) you want to show. In this case {{CurrentItem.UnitPrice}}. This field is part of the array (item 17.3 in the schema shown above).
    
    The result looks like this:
    
    
    
    

    Note that bindings are case sensitive. If the Chart title field of a Column chart is left empty then, when a document is generated, the dummy value from Word will be shown as title. So the title of the chart becomes Chart Title (see image in step 7) instead of the Customer ID. This also applies to Line and Bar charts. For Pie charts the behavior is different, in that case the value of the Column header of Column B will be shown as title (this is Office behavior). If the Column header field is left empty then the output value becomes 'Column1', 'Column2' etc..

     
11. Select the chart (if it's not already selected), then click Add to template.
    
    

    Only the layout option In Line with Text (this option is selected by default) is supported for a chart.

     
12. The result looks like this:
    
    
    
    

    The chart style and colors can be changed using native Word functions on the Chart Design tab. Each chart on a slide will have a unique name on the Template tab. In the example above the name of the chart is 1866325255.

     
13. Save the template and upload it to the Admin Center as a text element.
    
    
14. When creating a document a user can insert the text element multiple times and each time select a different customer from the external data source. The dynamic chart will show the values for each individual customer. The result looks like this:
    
    
    

Example PowerPoint (Document Generation API)

In this example the values for the chart in the presentation will use a JSON file as source.
You can directly link a HostSystem binding to a specific field in a JSON file when using the Document Generation API (see this article for more information).

For this example this JSON file is used:

1. In PowerPoint create a new presentation. Remove any default placeholder fields like 'Click to add title', so you start with a blank slide.
   
   

   Charts are supported in presentations, slides and slide elements.

    
2. On the Insert tab click Chart, then select the chart you want to use. In this example the Pie chart is selected. Click Ok to insert the chart:
   
   
   
   
3. The chart is inserted with some default dummy values. As you don't need these values, close the Excel sheet:
   
   
   
   

   In the Excel sheet above cell A1 is empty and cell B1 contains the dummy value 'Sales'. The values of these cells will be replaced by the values of the Column header in step 6. If one or more Column headers are left empty then the values of the cells become 'Column1', 'Column2' etc..

    
4. In Template Designer click + Create template.
   
   
5. On the Template tab click Custom chart binding:
   
   
   
   
6. Now all fields need to be linked to fields in the JSON file above, using HostSystem bindings.
   
   - Chart title: The title of the chart. This can be plain text like "My Title" or a binding. In this example a binding is used. Type {{HostSystem.Title}}.
   - Chart data: The data used for the chart, this must be an array! Type {{HostSystem.ChartData}}.
   
   Column A
   - Column header: Type the name of the label you want to show, for example Type(the type of fruit).
   - Data type: Select the type of data (Number, Text or Date) from the JSON file, in this case Text, because the type of fruit is a string.
   - Values: The value(s) you want to show. In this case {{CurrentItem.Fruit}}.
   
   Column B
   - Column header: The name of the label, for example Unit Price.
   - Data type: Select the type of data. In this case Number, because the unit price is a number.
   - Values: The value(s) you want to show. In this case {{CurrentItem.UnitPrice}}.
   
   The result looks like this:
   
   
   
   

   Note that bindings are case sensitive. If the Chart title field of a Pie chart is left empty then, when a presentation is generated, the value of the Column header of Column B will be shown as title. So the title of the chart in this example becomes Unit Price instead of Products (this is Office behavior). For Column, Line and Bar charts the behavior is different, in that case the dummy value from PowerPoint will be shown as title. If the Column header field is left empty then the output value becomes 'Column1', 'Column2' etc..

    
7. Click Add to template. If the button is greyed out then you need to select the chart.
   
   
8. The result looks like this:
   
   
   
   

   The chart style and colors can be changed using native PowerPoint functions on the Chart Design tab. In the example above numbers have been added to the pie. Each chart on a slide will have a unique name on the Template tab. In the example above the name of the chart is slide/256/shape/11.

    
9. Save the template and upload it to the Admin Center.
   
   
10. When a user creates a presentation with the JSON above then the result looks like this:
    
    

Related articles