You can use formatters to add complex logic to values rendered in your templates. For example, you can change value format, hide content, join arrays, etc.
This article covers formatters for DOCX, XLSX and PPTX templates.
List of formatters
It formats a tag value. You can use it with or without parameters:
format
- if encountered on date value it will format it as short date string.
format(val)
- formats current value using specified format string. For example, you can use N2
for a numbers with two decimals.
Note
If you want to use colon character :
with the formatter then it must be escaped with a backslash
{{date}:format(hh\:mm)}
It uses standard format strings. You can find more information in Microsoft documentation:
Template |
Data |
Result |
---|---|---|
Date: {{date}:format(dd.MM.yyyy)}
Date: {{date}:format(MM/dd)}
Date: {{date}:format(U)}
Number: {{num}:format(C)}
Number: {{num}:format(P)}
Number: {{num}:format(N2)}
|
{
"date": "2012-04-21T18:25:43-05:00",
"num": 8
}
|
Date: 22 Apr 2012
Date: 04/22
Date: Saturday, April 21, 2012 11:25:43 PM
Number: $8.00
Number: 800.00%
Number: 8.00
|
Returns substring. You can use the formatter with one or two parameters:
substring(index)
- returns substring of provided values after index
chars
substring(index,length)
- returns substring of provided values after index
with length
.
Template |
Data |
Result |
---|---|---|
{{stringVal}:substring(6)}
{{stringVal}:substring(0,5)}
|
{
"stringVal": "Derek Clark"
}
|
Clark
Derek
|
join(separator)
- joins array values with a separator
.
Template |
Data |
Result |
---|---|---|
{{arr}:join(, )}
{{arr}:join(; )}
{{arr}:join(-)}
|
{
"arr": [ 1, 2, 3]
}
|
1, 2, 3
1; 2; 3
1-2-3
|
offset(d)
- date and time value will be offset by d
days.
offset(d.hh\:mm\:ss)
- advanced approach for offsetting d
days, hh
hours, mm
minutes, ss
seconds.
Note
If you want to use colon character :
with the formatter then it must be escaped with a backslash
Just replace d
, hh
, mm
and ss
by the required number of days, hours, minutes and seconds in this string pattern d.hh\:mm\:ss
.
Template |
Data |
Result |
---|---|---|
Without offset:
{{date}}
Plus 10 days
{{date}:offset(10)}
Minus 10 days:
{{date}:offset(-10)}
Plus 10 days, 1 hour,
5 minutes, 10 seconds:
{{date}:offset(10.1\:5\:10)}
Minus 10 days, 1 hour,
5 minutes, 10 seconds:
{{date}:offset(-10.1\:5\:10)}
|
{
"date": "2012-04-21T18:25:43-05:00"
}
|
Without offset:
4/22/2012 3:25:43 AM
Plus 10 days
5/2/2012 3:25:43 AM
Minus 10 days:
4/12/2012 3:25:43 AM
Plus 10 days, 1 hour,
5 minutes, 10 seconds:
5/2/2012 4:30:53 AM
Minus 10 days, 1 hour,
5 minutes, 10 seconds:
4/12/2012 2:20:33 AM
|
hide
- replaces current tag value with an empty string. It can be used to hide the content of a specific tag.
Template |
Data |
Result |
---|---|---|
{{val1}}
{{val2}:hide}
|
{
"val1":"Derek Clark",
"val2":"Jessica Adams"
}
|
Derek Clark
|
hide-block-if(val)
- it can be used to conditionally hide blocks of a document. If a value in the tag is equal to a value of the parameter, it will be applied. This formatter works in repeatable sections such as list items or table rows.
The formatter can be used in both DOCX and XLSX templates. However, it behaves differently for them. Read the articles below for more information:
Template |
Data |
---|---|
{{value}:hide-block-if(1)}
{{value}:hide-block-if(Jessica)}
{{value}:hide-block-if([1, 2])}
{{value}:hide-block-if(Jessica, John)}
|
{
"value": 1
}
{
"value": "Jessica"
}
{
"value": [1, 2]
}
{
"value": [Jessica, John]
}
|
hide-block-if-not(val)
- it can be used to conditionally hide all block of list or table except specified. If a value in the tag is equal to a value of the parameter, it will be applied. This formatter works in repeatable sections such as list items or table rows.
The formatter can be used in both DOCX and XLSX templates. However, it behaves differently for them. Read the articles below for more information:
Template |
Data |
---|---|
{{value}:hide-block-if-not(1)}
{{value}:hide-block-if-not(Jessica)}
{{value}:hide-block-if-not([1, 2])}
{{value}:hide-block-if-not(Jessica, John)}
|
{
"value": 1
}
{
"value": "Jessica"
}
{
"value": [1, 2]
}
{
"value": [Jessica, John]
}
|
hide-block-if-empty
- it can be used to conditionally hide blocks of a document. If a value in the tag is null, empty or empty array, it will be applied. This formatter works in repeatable sections such as list items or table rows.
This is a special case of hide-block-if(val) where a value is null, empty or empty array. Read the articles below for more information about hiding blocks in DOCX templates and cells in XLSX templates:
Template |
Data |
---|---|
{{value}:hide-block-if-empty}
|
{
"value": null
}
{
"value": ""
}
{
"value": []
}
|
bool(yes,no,maybe)
- boolean value will be converted to yes
, no
or maybe
. You can specify your own value for each state. The last parameter is optional. You can use it if your bool value can be null.
Template |
Data |
Result |
---|---|---|
{{boolVal1}:bool(yes,no,maybe)}
{{boolVal2}:bool(yes,no,maybe)}
{{boolVal3}:bool(yes,no,maybe)}
|
{
"boolVal1": true,
"boolVal2": false,
"boolVal3": null,
}
|
yes
no
maybe
|
empty(val)
- if a value in a tag is null, empty or empty array it will replace the value with val
. You can use this formatter to display default value. For example, “N/A”.
Template |
Data |
Result |
---|---|---|
{{val1}:empty(N/A)}
{{val2}:empty(N/A)}
{{val3}:empty(N/A)}
|
{
"val1": "Jessica Adams",
"val2": "",
"val3": [],
}
|
Jessica Adams
N/A
N/A
|
merge-nulls
- use this formatter to merge table cells horizontally if there is null value.
Note
This formatter can be used in both DOCX and XLSX templates. However, Excel doesn’t support merging cells in table ranges. Thus, if you want to use this formatter, apply it to regular Excel cells instead. See the example below.
Template |
Data |
Result |
---|---|---|
DOCX template: ![]() XLSX template (download): ![]() |
{
"collection": [
{
"name": "Derek Clark",
"sold": null
},
{
"name": "Jessica Adams",
"sold": 14000
},
{
"name": "Xue Li",
"sold": null
},
{
"name": "Martin Huston",
"sold": 9400
},
{
"name": "Anton Frolov",
"sold": null
}
]
}
|
Cells with null values were merged. DOCX result: ![]() XLSX result (download result): ![]() |
span-nulls
- use this formatter to merge table cells vertically if there is null value.
Important
This formatter can be used in DOCX templates only.
Template |
Data |
Result |
---|---|---|
![]() |
{
"collection": [
{
"name": "Derek Clark",
"sold": null,
"period": "Jan 2018"
},
{
"name": "Jessica Adams",
"sold": 14000,
"period": "Feb 2018"
},
{
"name": "Xue Li",
"sold": null,
"period": "Mar 2018"
},
{
"name": "Martin Huston",
"sold": 9400,
"period": "May 2018"
},
{
"name": "Anton Frolov",
"sold": null,
"period": "Jun 2018"
}
]
}
|
![]() |
horizontal-resize
- it can be used to repeat collections horizontally instead of vertically in Excel. See the example below.
Important
This formatter can be used in XLSX templates only.
Template |
Data |
Result |
---|---|---|
![]() |
{
"collection": [
{
"name": "Derek Clark"
},
{
"name": "Jessica Adams"
},
{
"name": "Xue Li"
}
]
}
|
New columns are added instead of new rows: ![]() |
page
- it can be used for changing the logic of repeating collections. When a tag is placed inside the table and you want to repeat entire page instead of a table row, use page
to override default repeating logic.
Important
This formatter can be used in DOCX templates only.
Template |
Data |
Result |
---|---|---|
![]() |
{
"collection": [
{
"name": "Derek Clark",
"sold": 10000
},
{
"name": "Jessica Adams",
"sold": 14000
},
{
"name": "Xue Li",
"sold": 9400
}
]
}
|
New pages are added instead of new table rows: ![]() |
sheet
- it can be used for changing the logic of repeating collections. When a tag is placed inside the table and you want to create a separate sheet for each collection item instead of a table row, use sheet
to override default repeating logic.
Important
This formatter can be used in XLSX templates only.
Template |
Data |
Result |
---|---|---|
![]() |
{
"collection": [
{
"name": "Derek Clark",
"sold": 10000
},
{
"name": "Jessica Adams",
"sold": 14000
},
{
"name": "Xue Li",
"sold": 9400
}
]
}
|
New sheets are added instead of new table rows: ![]() |
picture
- it resolves URL or base64 string and converts it to an image.
picture
formatter can be used with resizing options, for example, {{value}:picture(100,100)}
.
Also you can specify only the width parameter and height will be calculated automatically to keep the image proportions. For example, {{value}:picture(50)}
.
The formatter can be used in both DOCX and PPTX templates. Read the articles below for more information:
Note
Resizing of an image is not supported for PPTX templates yet.
Template |
Data |
Result |
---|---|---|
{{value}:picture}, {{value}:picture(100,100)}, {{value}:picture(50)}
|
{
"value": "https://picturesite.com/pics/picture.png"
}
{
"value": "iVBORw0KGgoAAAANSUhEUgAAAIAAAAA9CAYAAABlamFgAA"
}
|
the image
|
url
- it corrects an url to full qualified with HTTP scheme or checks correctness when a scheme is existing. When result URL is not correct - removes it from the document
Template |
Data |
Result |
---|---|---|
{{value}:url}
|
{
"value": "picturesite.com/pics/picture.png"
}
{
"value": "ya.ru"
}
{
"value": ".net"
}
|
http://picturesite.com/pics/picture.png
http://ya.ru
|
keep-token
keeps tokens as they are. It can be useful in case you have other system tags in double curly brackets (for instance, Adobe Sign text tags). Or you have some text enclosed with double curly brackets as a part of a document.
Template |
Result |
---|---|
{{value}:keep-token}
{{Sig_es_:signer1:signature}:keep-token}
|
{{value}}
{{Sig_es_:signer1:signature}}
|