Functions

You can call functions from within the template files and embed the call result easily by writing {%=functionName(arg1, arg2, arg3, ...)%} expression in the document template.

This is a short description of the functions implemented in Stencil.

Basic Functions

Coalesce

Accepts any number of arguments, returns the first not-empty value.

Exampe:

• to insert the first filled name value: {%=coalesce(partnerFullName, partnerShortName, partnerName)%}
• to insert the price of an item or default to zero: {%=coalesce(x.price, x.premium, 0)%}

Empty

Decides if a parameter is empty or missing. Useful in conditional statements.

Example:

{%if empty(userName) %}Unknown User{%else%}{%=userName%}{%end%}

If the value of userName is missing then Unknown User will be inserted, otherwise the value is used.

The empty() function is useful when we want to either enumerate the contents of an array or hide the whole paragraph when the array is empty.

String functions

These functions deal with textual data.

Join

Joins a list of items with an optional separator.

Example: call join(xs, ",") to join them with a comma.

Example: call join(xs) to just concatenate the items.

Format

Calls String.format function.

Example:

This example formats the value of price as a price string: {%=format("$ %(,.2f"", price) %}. It may output $ (6,217.58).

Date

Formats a date value according to a given format string.

Arguments:

1. First argument is a format string.
2. Second argument is a string containing a date value.

Example:

This example formats the value of partner.birthDate as a date string: {%=date("yyyy-MM-dd", partner.birthDate) %}

Also, try these formats strings:

• "yyyy-MM-dd HH:mm:ss" for example: 2018-02-28 13:01:31
• "EEE, dd MMM yyyy HH:mm:ss zzz" (also known as RFC1123)
• "EEEE, dd-MMM-yy HH:mm:ss zzz" (a.k.a. RFC1036)
• "EEE MMM d HH:mm:ss yyyy" (ASCTIME)
• "yyyy-MM-dd'T'HH:mm:ss.SSSXXX" (ISO8601)

HTML

It is possible to embed text with basic dynamic formatting using HTML notation. The HTML code will be converted to OOXML and inserted in the document.

Stencil uses a simple parsing algorithm to convert between the formats. At the moment only a limited set of basic formatting is implemented. You can use the following HTML tags:

• b, em for bold text.
• i for italics.
• u for underlined text.
• s for strikethrough text.
• sup for superscript and sub for subscript.
• span elements have no effects.
• br tags can be used to insert line breaks.

The rendering throws an exception on invalid HTML input or unexpected HTML tags.

Example:

Write the following to embed the content of x as HTML in the document:

• {%=html(x) %}.

Numeric functions

Round

Expects one number argument. Rounds the argument to the closest integer. Usage: round(x). For example round(1.1) returns 1.

Floor

Expects one number argument. Rounds the argument to the closest integer that is not greater than than the argument. Usage: floor(x)

Ceil

Expects one number argument. Rounds its argument to the closest integer that is not smaller than the argument. Usage: ceil(x)