Value functions in DOCX 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.

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

• {{date|format(hh\:mm)}}

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:

• Numeric format strings

• Date and time format strings

Date: {{date|format(dd.MM.yyyy)}}
Date: {{date|format(MM/dd)}}
Date: {{date|format(U)}}
Number: {{num|format(C)}}
Number: {{num|format(C, fr-FR)}}
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: 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.

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

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

{
    "deliveryType": "EmailShipping"
}

regex

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

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

{{stringVal|substring(6)}}
{{stringVal|substring(0, 5)}}

{
    "stringVal": "Derek Clark"
}

Clark
Derek

sort

This function sorts items in the array of objects and may be used either separately or with calculated properties.

Syntax

Usage with the calculated properties:

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

{{sorted.property}}

Separate usage:

{{items|sort(property).property}}

{{items|sort(property1, ASC).property2}}

Sorting parameters

• ASC ascending order (applied by default, may be skipped),

• DESC descending order.

{{sorted = customers|sort(lastName, ASC)}}

Customers:
- {{sorted.lastName}}, {{sorted.firstName}}

{
  "customers": [
    {
      "firstName": "Adele",
      "lastName": "Vance"
    },
    {
      "firstName": "Diego",
      "lastName": "Siciliani"
    },
    {
      "firstName": "Johanna",
      "lastName": "Lorenz"
    }
  ]
}

Customers:
- Lorenz, Johanna
- Siciliani, Diego
- Vance, Adele

sum

It calculates a sum of the values in an array:

• {{items|sum()}} for items in the array,

• {{items|sum(@value.property)}} for a property in the array of objects,

• {{items|sum(@value.property1 * @value.property2)}} for arithmetical actions with the properties in the array of objects.

The following operators are available:

• + addition,

• - subtraction,

• * multiplication,

• / division,

• % remainder of division.

Total:
{{items|sum()}}

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

Total:
12

Total quantity:
{{sales|sum(@value.quantity)}}

Total amount:
${{sales|sum(@value.quantity * @value.price)}}

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

Total quantity:
180

Total amount:
$660

avg

It calculates an average of the values in an array:

• {{items|avg()}} for items in the array,

• {{items|avg(@value.property)}} for a property in the array of objects,

• {{items|avg(@value.property1 * @value.property2)}} for arithmetical actions with the properties in the array of objects.

The following operators are available:

• + addition,

• - subtraction,

• * multiplication,

• / division,

• % remainder of division.

Average:
{{items|avg()}}

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

Average:
4

Average quantity:
{{sales|avg(@value.quantity)}}

Average amount:
${{sales|avg(@value.quantity * @value.price)}}

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

Average quantity:
60

Average amount:
$220

count

It counts the number of values in an array, total or only those that meet a condition:

• {{items|count()}} or {{items|count(@value > 10)}} for items in the array,

• {{items|count(@value.property)}} or {{items|count(@value.property > 10)}} for a property in the array of objects,

• {{items|count(@value.property1 > @value.property2)}} for several properties in the array of objects.

The following operators are available:

• > greater than,

• >= greater than or equal to,

• < less than,

• <= less than or equal to,

• == equal to,

• != not equal to,

• && logical AND,

• || logical OR.

Items:
{{items|count()}}

Items greater than 3:
{{items|count(@value > 3)}}

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

Items:
3

Items greater than 3:
1

Sales reports:
{{sales|count()}}

Quantity greater than 40:
{{sales|count(@value.quantity > 40)}}

Amount greater than $200 and less than $250:
{{sales|count(@value.quantity * @value.price > 200
&& @value.quantity * @value.price < 250)}}

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

Sales reports:
3

Quantity greater than 40:
2

Amount greater than $200 and less than $250:
1

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.

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

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

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

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

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.

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.

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

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

{{value|keep-token}}
{{Sig_es_:signer1:signature|keep-token}}

{{value}}
{{Sig_es_:signer1:signature}}