Shape bindings

Bindings placed into the alt text of a shape

Shape bindings are placed in the alternative text of a shape or grouped shapes.

Most shape bindings will follow a similar format as the section or slide bindings, for instance:

<<Chart:AltText$ChartData>>

The AltText parameter is usually optional and allows you to keep the option of describing the shape with alternative text.

Here are the bindings that are inserted into the alternative text of a shape.

Alt text bindingDescription
ChartInsert a basic chart.
DynamicTableRepeat table rows and set visibility and width of columns.
ExtendedChartInsert a Box and whisker, Funnel, Sunburst, Treemap, or Waterfall chart.
FillColorSet the color of a shape.
HyperlinkAdd a link to a shape.
ImageInsert an image into a shape.
MultiInsert multiple bindings into a shape.
ShapeReferenceMake internal references or links to another slide in the presentation.
ShapeVisibleDynamically show or hide a shape based on the transformed data output.
TableSet values and cell colors in a table of fixed size.
TableFormatFormat tables with static length.

Chart

<<Chart:AltText$ChartData>>

📘

The structure of the data passed to the chart bindings has to be very specific. Check out the required data structure here.

Insert chart data to a chart. The chart data has to fit a specified chart data format, and the content control must surround a chart or the anchor of a chart. Most basic chart types are supported, except Box and whisker, Funnel, Sunburst, Treemap, and Waterfall charts. For them, use ExtendedChart.

If you want your chart to have data labels, you'll have to use data values instead of cell values to show the labels for the data inserted by Documotor.

Category labels in the template need to be of the same type as the output labels, that is, they need to be strings if they are going to be strings in the output document. The reason for this is that PowerPoint automatically expects the same type of labels as is present in the template, so the generated document is broken if this is not followed. In practice, add some text to category labels if you want standard textual category labels.

Parameters

string AltText [optional]

The alternative text for the chart.

JSON path ChartDataPath

A path to the object containing the chart data. There is a specific chart data format that the object must have.

DynamicTable

<<DynamicTable:[AltText]$tableData>>

Define table properties; set the visibility, number and whether to adjust width of columns. Also set the number of rows. Note that this binding has more options than DynamicTable in Word.

Parameters

string AltText

The alternative text for the table.

JSON path tableData

A path to a JSON object with a defined model for storing the configuration of the table. The data needs to be transformed into an object with the following properties, where indentations indicate that the indented properties belong to an object above them (all property names are case-sensitive):

  • object Options [optional]
    Properties in the Options object define general properties for the table or its formatting. Only one is currently supported:
    • boolean KeepTotalWidth [optional]
      Set to true to keep the width of the table the same as before processing. false or null will not preserve the width.
    • boolean KeepBottomBorderOnPopulatedRows [optional]
      Set to true if you want to preserve the same bottom border formatting when populating the last row (native dynamic table behavior).
  • array Headers [optional]
    Set the number of columns in the resulting table. Each object defined in this parameter must contain a Visible key that controls the visibility of that column. If null, processing will not set the amount of columns in the table. The number of elements in the array can be smaller or bigger than the number of columns. In the first case, the other columns are going to be hidden, and otherwise, a repeat of the last column will be appended as many times as needed to match the length of the array.
    • boolean Visible
      Set visibility of an existing or populated column. If the value is truthy, show the column. Otherwise, hide the column.
  • array[object] Rows [optional]
    Set the number of rows in the resulting table. First object in the list defines the header values. In order not to change header values, the object needs to be defined, but left empty. If the length of the list is larger than the existing number or rows, the processing will populate the last row to match the length the list. If the list is shorter, the processing will decrease the amount of rows. Each object can define unlimited amount of properties for the row. If there are no dynamic elements in rows, the table will be hidden.
    • boolean __mergeCells [optional]
      If defined and set to true, the processing will merge all cells from the row. False value doesn't merge cells, instead keeping the pre-existing layout.
    • string alignment [optional]
      Paragraph alignment parameter. The following inputs are valid: "Left", "Right", "Center", "Justified", "JustifiedLow", "Distributed", "ThaiDistributed". Usually defined together with __mergeCells to control the final text alignment of the paragraph after merging.
    • array[object] Cells [optional]
      Set the formatting of cells in that particular row. The nth element of Cell sets the value of the nth cell in the row.
      • string BackgroundColor [optional]
        Set the background color of a cell by defining a specific rgb code in the format "R,G,B". Any other format defined will not take effect.

Example

{
  "tableData": {
    "Options": {
      "KeepTotalWidth": true,
      "KeepBottomBorderOnPopulatedRows": true
    },
    "Headers" : 
    [
      {
        "Visible" : true 
      },
      {
        "Visible" : false
      },
      {
        "Visible" : true
      }
    ],
    "Rows":
      [
        {
          "H1" : "Header value 1",
          "H2" : "Header value 2",
          "Cells": 
          [
            {
              "BackgroundColor": "160,220,255"
            },
            {
              "BackgroundColor": "208,208,208"
            },
            {
              "BackgroundColor": "160,220,255"
            }
          ] 
        },
        {
          "L1" : "Second row value",
          "L2" : "Second row value 2",
          "__mergeCells": true,
          "__alignment" : "Right",
          "Cells": 
            [
              {
                "BackgroundColor": "160,220,255"
              },
              {},
              {
                "BackgroundColor": "160,220,255"
              }
            ] 
          } 
      ]
  }
}

ExtendedChart

<<ExtendedChart:AltText$ChartData>>

Insert chart data to a chart. Use this binding instead of Chart when using one of the following chart types:

  • Box and whisker
  • Funnel
  • Sunburst
  • Treemap
  • Waterfall

The content control must surround a chart or the anchor of a chart.

📘

The structure of the data passed to the chart bindings has to be very specific. Check out the required data structure here.

Parameters

string AltText [optional]

The alternative text for the shape.

JSON path ChartDataPath

The content control must surround a chart or the anchor of a chart. The chart data has to fit a specified chart data format.

FillColor

<<FillColor:AltText$RgbColor>>

Set the color of a shape.

Parameters

string AltText [optional]

The alternative text for the shape.

JSON path RgbColor

A path to a key whose value is a string with RGB format, e.g., "255,0,0".

Hyperlink

<<Hyperlink:AltText$Link>>

Add a link to a shape.

Parameters

string AltText [optional]

The alternative text for the shape.

JSON path Link

A path to a key whose value is a string that's also a valid URL, e.g., http://www.example.com.

Image

<<Image:AltText$ImagePath$FitType>>

Insert an image into a shape. All formats supported in PowerPoint are also supported in Documotor. Note that Microsoft 365 support for .webp is lacking.

📘

The shape needs to be an image, or a shape whose fill is defined as a picture, in order for image insertion to work.

Parameters

string AltText [optional]

The alternative text for the inserted image.

JSON path ImagePath

A path to a string that contains an image. It can be either a URL leading to a file or a Base64 encoded image. A URL is recommended to ensure better performance.

FitType

Must be equal to one of the following:

FitTypeDescription
FillCrops image to fill out the entire content control in the template.
FitThe entire image is shown inside of the content control. Any empty space is set to transparent.
RawFillSimilar to Fill, but uses PowerPoint's native cropping feature. This improves performance, but can result in a larger presentation since the image is not resized.
RawFitSimilar to Fit, but uses PowerPoint's native cropping feature. This improves performance, but can result in a larger presentation since the image is not resized.
StretchThe entire image is shown inside of the content control, and the image is stretched to fill it out if needed.

Multi

{  
  "Bindings":  
  {  
    "Hyperlink": [ "LinkPath" ],  
    "Image": [ "ImagePath", "Fit" ],  
    "AltText": "Green wall with staircase"  
  }
}

If a shape needs to be hold multiple bindings, the syntax changes to JSON format, and should follow the structure of the example above. The encompassing object contains only the Bindings key, whose value is an object with multiple properties. In those properties, each key represents a binding type and the value is an array whose first element is the binding key, and other elements, if any, are the other parameters to the binding.

ShapeReference

<<ShapeReference:AltText$ShapeReferencePath>>

Link to another slide in the presentation.

Parameters

string AltText [optional]

The alternative text for the shape.

JSON path ShapeReferencePath

A path to a key whose value is a string or a number. The value is considered the ID of the slide that the reference should link to. The ID needs to be defined on the slide that we want to refer to as well, which is done by adding the following to the notes of the slide that the ShapeReference should point to:

#-- Documotor-References --#
ShapeReferencePath
#-- Documotor-References-End --#

Here, ShapeReferencePath needs to be the same one used in the ShapeReference binding. It also needs to be different from any other paths used as ShapeReferencePath elsewhere. These notes will be removed on generated documents.

ShapeVisible

<<ShapeVisible:AltText$BindingKey>>

Dynamically show or hide a shape based on the value of BindingKey.

Parameters

string AltText [optional]

The alternative text for the shape, if the shape is visible.

JSON path BindingKey

A path to a value to evaluate. If the value is truthy, the shape is visible, otherwise, the shape is hidden.

Table

<<Table:[AltText]$tableData>>

Set values and cell colors in a table of fixed size.

Parameters

string AltText

The alternative text for the table.

JSON path tableData

A path to an object with two properties, array[array[string|null]] cellBackgroundColor and array[array[string|null]] cellValues. The cellBackgroundColor property defines the background color of the cells in the table, and cellValues sets the values of the cells. The nth element of each of these arrays sets the color/values of the cells in the nth row. The nth element is an array with length equal to table width, so the kth element of that array sets the color/value in the cell that's in the kth column and nth row. Here's an example of a table with three columns and two rows, where the fill color from the template is kept in the first column, while the second one is red, and the third one blue:

"tableData": {
  "cellBackgroundColor": 
  [
    [
      null,
      "Red",
      "Blue"
    ],
    [
      null,
      "Red",
      "Blue"
    ]
  ],
  "cellValues": [
    [
      "no fill",
      "Red fill",
      "Blue fill"
    ],
    [
      "no fill",
      "Red fill",
      "Blue fill"
    ]
  ]
}

If there are extra rows or columns in the table in the document, they are not colored and their content is not changed. If there are less rows or columns in the table in the document than in the data, the transformation is applied to the existing cells, but no rows or columns are added.

TableFormat

Set visibility of table columns and provide data for the table, similar to DynamicTable in Word, but with following differences:

  • The entire table receives the same scope as the TableFormat binding, so it's not a true repeater, just used in similar cases.
  • If there are less headers in Headers than there are columns in the table, the columns for which visibility is not set will be visible by default.
  • If there are more headers in Headers than there are columns in the table, the visibility will be set only for the columns that are present in the table; the number of columns will not be changed.
  • The number of rows is not changed dynamically.

Parameters

{ "BindingType": "TableFormat", "BindingKey": "tableData" }

string BindingType

Always "TableFormat" to invoke the TableFormat binding.

JSON path tableData

A path to an object with a defined model representing the configuration of the table. Uses the same structure as in the DynamicTable binding in Word.