For Word templates all bindings are placed in the tag field of rich text content controls, with the exception of images which uses the image content control. The tag field can be changed by selecting a content control and pressing the Properties button in the Developer ribbon. A binding is a JSON object with a property “BindingType” and some additional properties which we refer to as parameters.

DocuMotor generates a document by reading the binding from the tag value of the content controls in the template.. A common format of a binding looks like this:

{
  "BindingType":"<Type Of Binding>",
  "BindingKey":"<Json Property To Bind To>"
}

Since word only accepts single line input in the the content control tag, you have to use a compact json format such as:

{ "BindingType":"<Type Of Binding>", "BindingKey":"<Json Property To Bind To>" }

Binding keys

Bindings are resolved from the binding scope based on the path defined. Initially the scope of the document is the whole dataset.

For example, a document created with the following dataset:

{
   "title": "Product Quote",
   "contact": {
     "name": "John Doe"
   },
   "products": [
     {
       "name": "Grey Tile",
       "price": "40 $"
     },
     {
       "name": "White Tile",
       "price": "39 $"
     }
   ]
 }

Can have field bindings made for:

title -> "Product Quote"
contact.name -> "John Doe"
products[0].name -> "Grey Tile"
products[0].price -> "40 $"
products[1].name -> "WhiteTile"
products[1].price -> "39 $"

Some bindings instead evaluate the binding value to determine a true/false value. Because any data can be evaluated we refer to these as a truthy or falsy. For a full list of falsies, see Truthy values. Anything that is not a falsy is truthy. An example is the Visibility binding where the following bindings could be made:

title -> true
contact.name -> true
products -> true
services -> false
products[0].name -> true
products[0].qty -> false

Paths are relative to the current scope. The scope starts at the root of the data and can change in case of some nested bindings, for example a field binding inside a table binding. If a binding doesn’t mention change of scope, it means the scope is unchanged even in case of nested bindings. For example if there is a field inside a visibility, then the field will have the same scope as the visibility.

A path can consist of a property name or/and index as shown in the example above. Besides this, the path can also be @. @ is the current scope and is useful in cases where you have an array of values like the following example:

{
  "products": [ "Grey Tile", "White Tile"]
}

If we then take the example of a field inside a table, the table would bind to products, while the field can then bind to @.

Binding types

Chart

Alter the data of chart based on the ChartData received. The content control must surround a chart or the anchor of a chart.

Parameters

{ "BindingType": "Chart", "BindingKey": "ChartDataPath" }

ChartDataPath, ChartData
The chart data to insert into the chart.

Here is the structure of the ChartData object:

Property	Type	Description
title	string	The title of the chart. Is ignored if null.
categories	string[]	The values of the x-axis. Is Optional.
series	SeriesData[]	The data for each series. Series in the chart will be added or removed as needed. Formatting of new series are based on the last series in the chart.

ChartData

Property	Type	Description
name	string	Legend name of the series. Is optional.
values	number[]	The values of the y-axis in this series.
labels	string[]	The data label of the value with the same index. Use null to remove the data label. Is optional.

SeriesData

Categories, values, and labels must be of the same length, or null in order to produce a valid chart.

Extended Chart

Types

Box and whisker
Funnel
Sunburst
Treemap
Waterfall

Alter the data of an extended chart based on the ChartData received. The content control must surround a chart or the anchor of a chart.

Parameters

{ "BindingType": "ExtendedChart", "BindingKey": "ChartDataPath" }

ChartDataPath, ChartData
The chart data to insert into the chart.

Here is the structure of the ChartData object:

Property	Type	Description
title	string	The title of the chart. Is ignored if null.
primaryValueAxisTitle	string	The primary value (vertical) axis title. Is ignored if null.
primaryCategoryAxisTitle	string	The primary category (horizontal) axis title. Is ignored if null.
categories	string[]	The values of the x-axis. Is optional.
extendedCategories	CategoryData[]	The data for each category. Categories in the chart will be added or removed as needed.
series	SeriesData[]	The data for each series. Series in the chart will be added or removed as needed. Formatting of new series are based on the last series in the chart.
subtotals	number[]	The indexes of the series that is to be considered a subtotal. This is only relevant for Waterfall charts. Is optional.

ChartData

Property	Type	Description
name	string	The name of the category. Is optional.
categories	string[]	the values of each category or the x-axis depending on the type.

CategoryData

Property	Type	Description
name	string	Legend name of the series. Is optional.
values	number[]	The values of the y-axis in this series.

SeriesData

Categories and series-values must be of the same length, or null in order to produce a valid chart.

Field

Replaces the content of the content control with the text or number in the data. The content is removed if the path doesn’t exist or is null.

Parameters

{ "BindingType": "Field", "BindingKey": "TextToInsert" }

TextToInsert, string or number
The string or number to insert inside of the content control.

Hyperlink

Adds a link to the text inside of the content control, similar to right clicking on selected text and selecting link.

Parameters

{ "BindingType": "Hyperlink", "BindingHyperlink": "UrlPath", "BindingAltText": "AtlTextPath" }

UrlPath, string
A string that is an url.
AltTextPath, string
A string which is used for the tooltip of the link. Is optional.

Images

It is possible to insert images from the data. In contrast to other bindings, the picture content control (referred to as picture cc from here on) is used instead of the rich text content control. Like with other bindings, the binding JSON is added to the created content controls tag.

An image binding has three possible BindingTypes:

FillImage
The image will be cropped so that it can fill out the entire picture cc in the template.
FitImage
The entire image will be shown inside of the picture cc. Any empty space that there might be, will be filled out with transparent color.
StretchImage
The entire image will be shown inside of the picture cc. If there is any empty space, the image will be stretched to fill out the picture cc.

If you beforehand know the ratio of the images dimensions, e.g. width and height is the same size, it is recommended to set the picture cc to the same ratio. In this case all three BindingTypes will result have the same result. All three types have the same parameters.

Parameters

{ "BindingType": "FillImage", "BindingKey": "ImagePath", "BindingHyperlink": "HyperlinkPath" }

ImagePath, string
A string that is either a base64 string or a public url. If it is an url the image will be downloaded and embedded in the generated document.
HyperlinkPath, string
A string which is an url. The parameter is optional. If the parameter is included, the url will be added to the image as a link.

List

Intended to be used for dynamically creating lists. The content control should have a list in its content. The binding will iterate through each element of the bound array and duplicate the content of the content control, except for the first element. The scope of the content is changed to the current element being iterated through.

Parameters

{ "BindingType": "List", "BindingKey": "ArrayPath" }

ArrayPath, array
The array to create the list from.

Locked

The locked binding is used for making the content of content control uneditable if the value is a truthy. Nested locks will lock/unlock themselves and their child content controls. Thus the controlling lock is the closest parent.

Parameters

{ "BindingType": "Locked", "BindingKey": "IsLockedPath" }

IsLockedPath, any
If the data of the path is a truthy, the content inside of the content control will be locked, otherwise the content is not locked.

Repeat

Similar to the list binding, but will simply duplicates its content without any special consideration for what that content is. Scope is also changed like in list.

Parameters

{ "BindingType": "Repeat", "BindingKey": "ArrayPath", "Separator": "SeparatorText" }

ArrayPath, array
The array to create the duplicated content from.
SeparatorText, string
An optional parameter. If SeparatorText is not an empty string, it will be appended to the end of each repeated element, except for the last one.

RichHtmlText

Inserts text formatted using html into the document. The html doesn’t need to be a full document, but paragraphs does need to be tagged. The string This is a text with <b>bold</b> text. Is not a valid format, but <p>This is a text with <b>bold</b> text.</p> is valid.

Parameters

{ "BindingType": "RichHtmlText", "BindingKey": "RichTextPath" }

RichTextPath, string
The html string to insert. See below for valid html elements.

Supported HTML tags

<b>
<br/>
<font face=”” size=”” color=””>
- Face
  Optional attribute, name of the font family
- Size
  Optional attribute, size of the font, integer from 1 to 7, 3 being the normal size
- Color
  Optional attribute, the color of the text. Can be a name, ex: ‘Red’, hex value, or RGB format, ex ‘rgb(255,0,0)’.
<h1>
<h2>
<h3>
<h4>
<h5>
<h6>
<i>
<li>
<ol start=””>
- Start
  Optional attribute, the value of the first list item in the list
<p>
<sub>
<sup>
<u>

User Style

It is possible to overwrite how tags change the style of a paragraph and introduce new inline tags. Inline tags are tags used within a paragraph, such as <b>. All style properties that can be set is listed below in the Style Properties section. The following user style makes the bold tag also add underscore.

{ “b”: 
  { “underscore”: true }
}

The type <Integer, String> is a dictionary with Integer as key and String as value. It is used when mapping the level of a list to a specific style or string/symbol. The level of a list starts at 0, with no indent. The following user style sets the style of numbered list to use Arabic numbers at no indent, Roman numbers at one indent and alphabetic letters at two indents.

{ “ol”: 
  { “bulletStyle”: 
    { 
      “0”: “1.”, 
      “1”: ”i.”,
      “2”: “a.” 
    } 
  }
}

Style Properties

The following properties can be used to override HTML styling.

Alignment
- L
  Left
- Ctr
  Center
- R
  Right
BackgroundColor, string
The color behind the text, same format as TextColor
BaseLine, number
Moves text down if negative, and up if positive. Default for Subscript and Superscript is -25000 and 30000 respectively.
Bold, boolean
Makes text bold if true
BulletChar, <integer, string>
A mapping of numbered list level, and what string to use as the bullet
BulletStyle, <integer, string>
A mapping of numbered list level and what style to use for bullets. The following types of bullets are supported:
- l.
- l)
- i.
- i)
- I.
- I)
- a.
- a)
- A.
- A)
DefaultFontSize, decimal number
The size of the text at a factor of 1. Usually only set int he body, and then factor is used in the remaining tags, but it is not a requirement.
Font, text
Name of the font to use. Write it as displayed in Powerpoint.
FontSizeFactor, decimal number
The size of teh text in a tag is by default some % of the default font size. A factor of 1 means that size is unchanged.
Indent, number
Adds a margin to the left side of the first line of a paragraph.
IsNumbered, boolean
Marks paragraph as a numbered list item.
Italic, boolean
Makes text italic if true
LineSpace, decimal number
Multiplier of line space in a paragraph. So 2 is 200% and 1.5 is 150%
MarginLeft, number
Adds a margin to the left side of the entire paragraph.
NumberStart, number
The number of the first list item in a numbered list.
ShowBullet, boolean
Markrs paragraph as a bullet list item.
SpaceAfter, decimal number
Points of empty space to add after a paragraph.
SpaceBefore, decimal number
Points of empty space to add before a paragraph.
TextColor, text
The color of the text. Can either use a name ‘red’, Hex value ‘#ff0000’, or rgb format ‘rgb(255,0,0)’.
Underscore, boolean
Adds a single line of underscore to the text if true.

Table

Functions like a repeat binding around a table row, but can also be wrapped around an entire table. If the content control wraps around a whole table, then the first row with bindings until the last row with bindings will be duplicated. Like with repeat, the scope is changed for each duplicate.

Parameters

{ "BindingType": "Table", "BindingKey": "ArrayPath" }

ArrayPath, array
The array to create the table rows from.

Dynamic Table

Dynamic table can be defined with following binding:

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

Description

This binding allows to control a table in terms of the amount of columns and rows as well as its formatting.

Parameters

AltText – string to replace the binding in the alt text of the table
tableData – object with a defined model representing the configuration of the table

Model

Options (case sensitive, optional). Properties in the Options object define general properties for the table or its formatting. Currently we support only 2. These are:
- KeepTotalWidth (case sensitive, optional) – boolean parameter. Set to true if you want to keep the same width of the table as before processing. False or NULL means that width will not be preserved.
Headers (case sensitive, optional) – list parameter. If defined – it controls the amount of columns in the resulted table. It can either be hardcoded amount of objects or dynamic coming from another object (Jmes transformation). Each object defined in this parameter must contain a “Visible” parameter that controls the visibility of that column. If NULL, processing will not control the amount of columns in the table.
- Visible – (case sensitive, required) – boolean parameter. Parameter that controls visibility of the existing or populated column. If set to true, it shows the column. If false – hides the column.
- KeepWidth – (case sensitive, optional) – boolean parameter. Define if a column must preserve its width after processing. This parameter makes sense in cases of resizing table columns.
Rows (case sensitive, optional) – list parameter. If defined – it controls the amount of rows in the resulted table. It can either be hardcoded amount of objects or dynamic coming from another object (Jmes transformation). First object in the list defines the header values – if you wish to not change header values – define the object but leave empty. If the list size is larger than existing amount or rows – the processing will populate the last row to match the size from the list. If less – the processing will decrease the amount of rows. Each object can define unlimited amount of properties for the row.

Example of a JSON object that can define a dynamic table:

{
   "tableData":{
        "Options": {
            "KeepTotalWidth": true
        },
        "Headers" : 
        [
         {
             "Visible" : true 
         },
         {
             "Visible" : ValueFromMyData
         },
         {
             "Visible" : Value2FromMyData,
             "KeepWidth" : true
         }
        ]
        "Rows":
        [
          {
             "H1" : "Header value 1",
             "H2" : "Header value 2"
          },
          {
             "L1" : "Second row value",
             "L2" : "Second row value 2"
          } 
        ]
    }
}

Cell Repeater

Cell repeater can be defined with following binding:

{"BindingType":"RepeatTableCells","BindingKey":"sampleKey"}

Description

Cell repeater binding allows us to control table cells length and its values.

Depending on the model defined, the processing will either expand the amount of cells or shrink them.

The binding must enclose the entire table, not just a row or a cell, but the entire table. The first cell in the table will be the template for the remaining cells, and the amount of cells in the first row, defines the amount of cells in rows added.

Parameters

sampleKey – object with a defined model representing the configuration of the cell repeater

Model

options (case sensitive, required) – defines the general options for cell repeater processing.
- direction (case sensitive, required) – string parameter. Defines the direction of the cells to be expanded. Currently only “lrtb” is supported.
cells (case sensitive, required) – list parameter. Data for cells.

{
  "options":{
    "direction": "lrtb" 
  },
  "cells":[{"testkey":"testvalue"}] 
}

TextElement

Inserts a document into the template. The document can be a template and will be generated with the current scope as its starting scope. The entire paragraph of the content control will be replaced, so it is recommended that the binding is a line by itself in the template.

Parameters

{ "BindingType": "TextElement", "BindingKey": "FilePath" }

FilePath, string
A string which is either a base64 string or a public url that can be used to download the text element.

Visibility

Used to hide the content of the content control based on the data received.

Parameters

{ "BindingType": "Visibility", "BindingKey": "IsVisiblePath" }

IsVisibilePath, any
If the data of the path is a truthy, the content inside of the content control will be shown, otherwise the content is removed.