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.

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.

It uses standard format strings. You can find more information in Microsoft documentation:

Examples

Template Data Result
Date: {{date}:format(d MMM 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
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.

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

collapse

collapse - it can be used to conditionally hide blocks of a Word document or to clear cells in an Excel document. If a value in the tag is null, true, empty or empty array, it will be applied.

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:

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:

merge nulls formatter template

XLSX template (download):

merge nulls formatter template
{
    "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:

merge nulls fortammer result

XLSX result (download):

merge nulls fortammer result

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

span nulls formatter template
{
    "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

span nulls fortammer result

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
horizontal-resize formatter template
{
    "collection": [
        {
            "name": "Derek Clark"
        },
        {
            "name": "Jessica Adams"
        },
        {
            "name": "Xue Li"
        }
    ]
}

New columns are added instead of new rows:

horizontal-resize formatter result

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
page formatter template
{
    "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:

page formatter result

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
sheet formatter template
{
    "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:

sheet formatter result