Documentation › Word DOCX templates (Modern) › Value functions in DOCX templates

Value functions in DOCX templates

You can use functions to add complex logic to values rendered in your templates. Functions are tools for formatting, math operations, and manipulating lists and strings.

In this article, you’ll find a list of all the functions you can use in DOCX templates, along with some examples to help you understand how each one works.

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.

  • format(val, locale) - formats current value using specified format string and Locale. For example, you can use format(C, fr-FR) to apply a specific currency to the tag.

It uses standard format strings and supports different Locales. For example, you can place tags with different locales in a docx template

  • {{num1|format(C, en-US)}}

  • {{num2|format(C, fr-FR)}}

Please find more information about using Locale in the Microsoft documentation:

Note

Special characters and spaces are supported, but you’ll need to enclose the tag in square brakes inside the curly braces:

{{[date value]|format(dd.MM.yyyy)}}

Examples

Template

Data

Result

 
Date: {{date|format(dd.MM.yyyy)}}
Date: {{[date value]|format(dd.MM.yyyy)}}
Date: {{date|format(MM/dd)}}
Date: {{date|format(U)}}
Time: {{date|format(hh:mm)}}
Number: {{num|format(C)}}
Number: {{[num+1]|format(C)}}
Number: {{num|format(C, fr-FR)}}
Number: {{num|format(P)}}
Number: {{num|format(N2)}}

{
    "date": "2012-04-21T18:25:43-05:00",
    "date value": "2021-05-25T10:44:00-02:00",
    "num": 8,
    "num+1": 5
}

Date: 21.04.2012
Date: 25.05.2021
Date: 04/22
Date: Saturday, April 21, 2012 11:25:43 PM
Time: 11:25
Number: $8.00
Number: $5.00
Number: 8.00 €
Number: 800.00%
Number: 8.00

filter

This function returns an array of objects that meet a condition and assign them to a calculated property.

Syntax:

{{filteredObjects = objects|filter(@value.objectProperty != false)}}

Available operators:

  • == equal to,

  • != not equal to,

  • > more than,

  • < less than,

  • >= more than or equal to,

  • <= less than or equal to,

  • || logical “or”,

  • && logical “and”,

  • () group.

Example

Template

Data

Result

{{filteredColors = colors|filter(@value.name != “green”)}}

Filtered colors:

  • {{filteredColors.name}}

 
{
  "colors": [
    {
      "name": "red"
    },
    {
      "name": "green"
    },
    {
      "name": "blue"
    }
  ]
}

Filtered colors:

  • red

  • blue

sort

This function reorders the items in a list and saves the sorted values in a new calculated property.

Syntax:

{{sorted = items|sort(property, DESC)}}

Sorting parameters

  • ASC (Ascending): Sorts from A to Z or smallest to largest. This is the default and can be skipped.

  • DESC (Descending): Sorts from Z to A or largest to smallest.

Example

Template

Data

Result

 
Items: {{sorted = items|sort()}}
- {{sorted}}

{
  "items": [987, 6534, 54]
}

Items:
- 54
- 987
- 6534

Employees: {{sorted = employees|sort(lastName, DESC)}}
- {{sorted.lastName}}, {{sorted.name}}

{
  "employees": [
    {
      "name": "James",
      "lastName": "Williams"
    },
    {
      "name": "Jessica",
      "lastName": "Brown"
    },
    {
      "name": "Robert",
      "lastName": "Jones"
    },
    {
      "name": "Emily",
      "lastName": "Davis"
    }
  ]
}

Employees:
- Williams, James
- Jones, Robert
- Davis, Emily
- Brown, Jessica

map

map accepts an unlimited number of values and maps a specific value to a specific output.

For example, we have some property that stores delivery types and has values:

  • EmailShipping

  • ElectronicalShipping

And we want to display them in a readable format like so:

  • Email shipping

  • Electronic shipping

Template

Data

Result
{{deliveryType|map(“EmailShipping” => “Email shipping”, “ElectronicShipping” => “Electronic shipping”)}}
 
{
    "deliveryType": "EmailShipping"
}
Email shipping

Note

All values in double quotes are recognised as strings. If you want to map numbers, you don’t need to use double quotes in the condition.

For example, {{tag|map("Yes" => 1, "No" => 0)}}.

regex

regex(pattern, replacement) - returns a new string with all matches of a RegExp pattern replaced by a replacement.

Hint

Regular expressions can be created and tested using services such as Regex101 or RegExr.

Examples

Template

Data

Result

 
{{name|regex((\w+)\s(\w+), $2，$1)}}
{{accountNumber|regex(\d(?=.*\d(?:\s*\d){3}\s*$), *)}}

{
    "name": "Martin Huston",
    "accountNumber": "1234567890"
}

Huston，Martin
******7890

substring

Returns substring. You can use the function 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

sum

sum() - calculates the sum of values in an array.

  • {{items|sum()}} — sums the raw values in the array (e.g., [1, 2, 3] becomes 6),

  • {{items|sum(propertyName)}} — sums the specified property (propertyName) across all objects in the array.

Note

If you need to sum a calculated value like @value.quantity * @value.price, assign the expression to a calculated property first, then use that property with sum. See the example below.

Examples

Template

Data

Result

 
Total:
{{items|sum()}}

{
  "items": [3, 2, 7]
}

Total:
12

{{sales.totalAmount = @value.quantity * @value.price}}

Total amount:
${{sales|sum(totalAmount)}}

Total quantity:
{{sales|sum(quantity)}}

{
  "sales": [
    {
      "price": 3,
      "quantity": 90
    },
    {
      "price": 4,
      "quantity": 60
    },
    {
      "price": 5,
      "quantity": 30
    }
  ]
}

Total amount:
$660

Total quantity:
180

avg

avg() - calculates the average of values in an array.

  • {{items|avg()}} — averages raw values in a simple array (e.g., [3, 2, 7] → 4),

  • {{items|avg(propertyName)}} — averages the specified property (propertyName) across all objects in the array.

Note

If you need to average a calculated value like @value.quantity * @value.price, assign the expression to a calculated property first, then use that property with avg. See the example below.

Examples

Template

Data

Result

 
Average:
{{items|avg()}}

{
  "items": [3, 2, 7]
}

Average:
4

{{sales.amount = @value.quantity * @value.price}}

Average amount:
${{sales|avg(amount)}}

Average quantity:
{{sales|avg(quantity)}}

{
  "sales": [
    {
      "price": 3,
      "quantity": 90
    },
    {
      "price": 4,
      "quantity": 60
    },
    {
      "price": 5,
      "quantity": 30
    }
  ]
}

Average amount:
$220

Average quantity:
60

count

count() - counts the number of items in an array.

Examples

Template

Data

Result

 
{{items|count()}}
{{count(items)}}

{
  "items": [3, 2, 7]
}

3
3

join

join(separator, order, property) - joins array values with a separator (required) and sorts them in a specific order (optional). property (optional) can be used to access properties in a nested structure.

Examples

Template

Data

Result

 
{{arr|join(", ")}}

{{arr|join(", ", ASC)}}
{{arr|join("-", DESC)}}

{{arr|join(;)}}
{{arr|join(:)}}

{
    "arr": [2, 1, 3]
}

2, 1, 3

1, 2, 3
3-2-1

2;1;3
2:1:3

{{reports|join(", ", @value.year)}}
{{reports|join(", ", ASC, @value.year)}}
{{reports|join(", ", DESC, @value.year)}}

{
    "reports": [
        {
            "year": "1992"
        },
        {
            "year": "1987"
        },
        {
            "year": "2005"
        }
    ]
}

1992, 1987, 2005
1987, 1992, 2005
2005, 1992, 1987

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

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

repair-url

repair-url - this function corrects an URL to full qualified with HTTP scheme or checks correctness when a scheme is existing. When result URL is not correct - it removes it from the document.

Template

Data

Result

 
{{value|repair-url}}

{
    "value": "picturesite.com/pics/picture.png"
}

{
    "value": "google.com"
}

{
    "value": ".net"
}

https://picturesite.com/pics/picture.png

https://google.com

keep-token

The keep-token function 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.

Note

Special characters and spaces are supported, but you’ll need to enclose the tag in square brakes inside the curly braces:

{{[Sig es :+signer+:signature]|keep-token}}

Template

Result

 
{{value|keep-token}}
{{Sig_es_:signer1:signature|keep-token}}
{{[Sig es :+signer+:signature]|keep-token}}

{{value}}
{{Sig_es_:signer1:signature}}
{{Sig es :+signer+:signature}}

title-case

The title-case function capitalizes the first letter of each word in a string (title case).

Template

Data

Result

 
{{text|title-case}}

{
    "text":"plumsail documents"
}

Plumsail Documents

contains

contains(text, ignoreCase) - checks if the token value contains the specified text.

This function is case‑sensitive by default and requires an exact match. Add the optional ignoreCase parameter (a boolean value: true or false) to match regardless of letter case.

Hint

You can use this function with logical operations, such as #if and #hide-if to build conditional logic.

Examples

Template

Data

Result

 
{{clauses|contains(NDA)}}

{{warrantyApplies = clauses|contains(Warranty, true) && region == "EU"}}

{{#if warrantyApplies}}
Warranty clause included
{{/if}}

{
    "clauses": "NDA; Warranty",
    "region": "EU"
}

true

Warranty clause included

starts-with

starts-with(text, ignoreCase) - checks if the token value begins with the specified text.

This function is case‑sensitive by default and requires an exact match. Add the optional ignoreCase parameter (a boolean value: true or false) to match regardless of letter case.

Hint

You can use this function with logical operations, such as #if and #hide-if to build conditional logic.

Examples

Template

Data

Result

 
{{price|starts-with($)}}

{{usdPrice = price|starts-with($)}}

{{#if usdPrice}}
USD price: {{price}}
{{/if}}

{{#hide-if price|starts-with($)}}
Currency not specified: {{price}}

{
    "price": "1099.00"
}

false

Currency not specified: 1099.00

{{trackingNumber|starts-with(int, true)}}

{
    "trackingNumber": "INT-P20250456"
}

true

ends-with

ends-with(text, ignoreCase) - checks if the token value ends with the specified text.

This function is case‑sensitive by default and requires an exact match. Add the optional ignoreCase parameter (a boolean value: true or false) to match regardless of letter case.

Hint

You can use this function with logical operations, such as #if and #hide-if to build conditional logic.

Template

Data

Result

 
{{customerEmail|ends-with(@company.com)}}

{{isInternal = customerEmail|ends-with(@company.com)}}

{{#if isInternal}}
Internal recipient
{{/if}}

{
    "customerEmail": "John.Smith@company.com"
}

true

Internal recipient

{{documentId|ends-with(-FIN, true)}}

{
    "documentId": "Report-2025-FIN"
}

true

replace

The replace function helps you find and exchange a specific term with a new one across a tag value.

Note

This function is case-sensitive.

Template

Data

Result

 
{{text|replace(before, after)}}

{
    "text":"before using function"
}

after using function

{{text|replace(before, after)}}

{
    "text":"Before using function"
}

Before using function

{{value|replace(10000, 10)}}

{
    "value": 1000099
}

1099

is-empty

The is-empty() function simplifies conditions by evaluating the token’s content. It returns true if the value is null, an empty string, or an empty array.

Template

Data

Result

 
{{value|is-empty()}}

{
    "value":"Plumsail Documents"
}

false

{{value|is-empty()}}

{
    "value": []
}

true

{{value|is-empty()}}

{
    "value": null
}

true

length

The length() function counts the number of elements within an array or the number of characters within a string.

Template

Data

Result

 
{{value|length()}}

{
    "value":"Plumsail Documents"
}

18

{{value|length()}}

{
    "value": [1,2,3,4]
}

4
Previous
Calculated properties in DOCX templates
Next
Object operations in DOCX templates