Value formatters in DOCX and XLSX templates¶

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 both DOCX and XLSX templates.

List of formatters

format
substring
join
offset
hide
hide-block-if
hide-block-if-not
hide-block-if-empty
bool
empty
merge-nulls
span-nulls
horizontal-resize
page
sheet
picture
url

format ¶

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:

Examples¶

Template

Data

Result

Date: {{date}:format(dd.MM.yyyy hh\:mm)}
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
Saturday, April 21, 2012 11:25:43 PM
Number: $8.00
Number: 800.00%
Number: 8.00

substring ¶

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.

Examples¶

Template	Data	Result
{{stringVal}:substring(6)} {{stringVal}:substring(0,5)}	{ "stringVal": "Derek Clark" }	Clark Derek

join ¶

join(separator) - joins array values with a separator.

Examples¶

Template	Data	Result
{{arr}:join(, )} {{arr}:join(; )} {{arr}:join(-)}	{ "arr": [ 1, 2, 3] }	1, 2, 3 1; 2; 3 1-2-3

offset ¶

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.

Examples¶

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 ¶

hide - replaces current tag value with an empty string. It can be used to hide the content of a specific tag.

Examples¶

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.

Examples¶

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 ¶

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.

Examples¶

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 ¶

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.

Examples¶

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 ¶

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.

Examples¶

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 ¶

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".

Examples¶

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 ¶

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.

Examples¶

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):

span-nulls ¶

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.

Examples¶

Template

Data

Result

Download template document

{
    "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"
        }
    ]
}

Download result document

horizontal-resize ¶

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.

Examples¶

Template	Data	Result
	{ "collection": [ { "name": "Derek Clark" }, { "name": "Jessica Adams" }, { "name": "Xue Li" } ] }	New columns are added instead of new rows:

page ¶

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.

Examples¶

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 ¶

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.

Examples¶

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 ¶

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)}.

Important

This formatter can not be used in PPTX templates.

Examples¶

Template	Data	Result
{{value}:picture}, {{value}:picture(100,100)}	{ "value": "https://picturesite.com/pics/picture.png" } { "value": "iVBORw0KGgoAAAANSUhEUgAAAIAAAAA9CAYAAABlamFgAA" }	the image

Note

Plumsail Documents support anonymous authentication only. To use a link to a picture stored in SharePoint, please, create a guest link and replace guestacces.aspx string with download.aspx one. Your link should look something like this: https://yourDomain.sharepoint.com/_layouts/15/download.aspx?docid=DocID&authkey=AuthKey

url ¶

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