Advanced templating

There are a few scenarios where advance/extra control is needed with variables. Antavo provides access to a subset of Volt functionality, a Jinja-based templating engine, in order to provide extra functionality.

Warning

Volt templating provides a very powerful extra level of control to the Antavo loyalty platform. However, volt returns extremely limited debugging information, if any. Volt should only be used when there is no other option is possible and must be very thoroughly tested before use on a live environment.

Volt basics

Volt functionality is enabled in the flow using the volt: precursor and encapsulating the target code with double braces {{ }}. Variables can be simply stated. This is only way to effectively statically cast variables and their type. This approach is particularly useful for ensuring the type of Boolean variables. This is the only way to make a variable null (so the exist attribute is equal to false).

volt:{{ variable }}

# Boolean
volt:{{ true }}
volt:{{ FALSE }}

# Null values
volt:{{ NULL }}

Volt is more specific regarding data types than the standard Antavo workflow parser. Array elements have to be accessed by the individual key value and list elements can be accessed by the corresponding position (starting from zero).

# Accessing an element stored in the customer properties array

# standard parser
        {customer.properties.element}
        {event.points}

# volt
    volt: {{ customer.properties["element"] }}
    volt: {{ event.properties["element"] }}
    volt: {{ customer.list[1] }}

Only the customer object is available in the workflow for an ondate trigger. The customer and event object is available for an event trigger in the workflow. The corresponding data structures are accessible from /customers/{customer_id} Customer API and the /customer/{customer_id}/events Display API.

It is also possible to access some customer transactional data using the customer purchase extension .

Strings can be concatenated using the ~ operator and also sliced, for individual elements and ranges.

# concatenation
volt: {{ "This "~"is "~"joined together" }}
# returns "This is joined together"

# Slicing
volt: {{ "This is an example"[1] }}
# returns "h"

volt: {{ "This is an example"[1:3] }}
# returns "his"

Mathematical functionality can also be performed on suitable variables, e.g.,

volt:{{ age + 1 }}

Operators and tests

Standard operators can be used withing a volt expression. These return TRUE/FALSE, depending on the evaluation.

Operator	Description
==	both operands are equal
<> or !=	both operands are not equal
>	left operand is greater than right operand
<	left operand is less than right operand
<=	left operand is less or equal than right operand
>=	left operand is greater or equal than right operand
===	both operands are identical
!==	both operands are not identical
or	returns true if the left or right operand is evaluated as true
and	returns true if both left and right operands are evaluated as true
is	same as == (equals), also performs tests
is not	Same as != (not equals)
..	Creates an array populated with a range {{ ‘a’..’z’ }} {{ 1..10 }}

Note

equal means that the two compared operands have the same value. identical means that two compared operands have the same value and type

These operators can be used in conjunction with the following tests:

Test	Description
defined	Checks if a variable is defined (isset())
divisibleby(value)	Checks if a value is divisible by other value
empty	Checks if a variable is empty
even	Checks if a numeric value is even
iterable	Checks if a value is iterable.
numeric	Checks if value is numeric
odd	Checks if a numeric value is odd
sameas(value)	Checks if a value is identical to other value
scalar	Checks if value is scalar (not an array or object)
type(value)	Checks if a value is of the specified type

Ternary functions

PHP ternary functions can be performed within a volt expression and has the following generic form.

query_1 ? result_1 : result_2

Note

This functionality can be used to check the status of variables by using is defined e.g. customer.original is defined

If the query is true, the first results will be used otherwise the second results will be returned. Any standard PHP comparison operator can be used. This functionality is usually used for provide mapping functionality based upon a logical constraint. Ternary functions are usually used in workflow nodes which connect to external systems and where using workflow attribute filters would create a large complex system to maintain.

Caution must be taken with nested function to ensure that the function is evaluated as expected.

// Bad code results in an uncertain performance
query_1 ? result_1 : query_2 ? result_2 : result_3

// Adding brackets removes ambiguity
query_1 ? result_1 : (query_2 ? result_2 : result_3)

Volt functions

Function	Description
apple_pass_v2_api_url(passId, redirectUrl)	Returns the Apple wallet url for the customer’s membership wallet pass where passId is the Antavo ID for the pass. An optional redirection URL can be supplied for an unsuccessful retrieval e.g., apple_pass_v2_api_url("aabbccddeeffgghh", "http://redirecttarget.com")
apple_pass_api_url(templateId, redirectUrl)	Warning This function is deprecated, use apple_pass_v2_api_url
barcode_url	Return the barcode url (https://services.antavo.com/barcodes/%s%s).
capitalize	Capitalizes a string by applying the ucwords PHP function to the value.
ceil	Round fractions up. Returns the next highest integer value by rounding up value if necessary.
customer_token	Sets unique customer ID for payload.
date	The standard PHP date function can be called.
floor	Round fractions down. Returns the next lowest integer value (as float) by rounding down value if necessary.
format	The php sprintf function
generate	Generates a coupon code from pattern.
getImageUrl	Returns the url(string) of the associated image for given entity.
google_pass_api_url(templateId, redirectUrl)	Warning This function is deprecated, use google_pass_v2_api_url
google_pass_v2_api_url(passId, redirectUrl)	Returns the Google Pay url for the customer’s membership wallet pass where passId is the Antavo ID for the pass. An optional redirection URL can be supplied for an unsuccessful retrieval e.g., google_pass_v2_api_url("aabbccddeeffgghh", "http://redirecttarget.com")
length	Returns the length of a string or array e.g., {{length(entry.name)}}
lower	Change the case of a string to lowercase.
pad_left(string,total string length,padding character)	Adds padding to the left to create a string of a specified total length. e.g., pad_left("123", 10, "0") results in "0000000123"
parent	Triggered events can access the parent object and associated properties.
pop	Removes and returns the last element from an array e.g., {% let last = pop(elements) %}
qrcode_url	Return the qrcode url (https://services.antavo.com/barcodes/%s%s).
rand	Generates a random number: Format (start, end,decimal precision) e.g., rand(0,1000,0)
replace	The first argument is replaced with the second argument in the third argument.
round	Returns the rounded value of val to specified precision (number of digits after the decimal point). precision can also be negative or zero (default). If the precision is negative, val is rounded to precision significant digits before the decimal point, e.g. -1 rounds to tens, -2 to hundreds
rsort	Sorts an array in descending order. If not an array given it returns FALSE e.g., {% let ordered = rsort(elements) %}
sort	Sorts an array in ascending order. If not an array given it returns FALSE e.g., {% let ordered = sort(elements) %}
split	Splits string by comma. The split filter should be used for custom separators. Non-scalars (array/object) will be returned unaffected e.g., {% let tags = split(entry.tags) %}
upper	Applies the strtoupper PHP function to the value.
uuid	Generates RFC 4122 compliant Version 4 UUIDs. Generate 16 bytes (128 bits) of random data.

Volt filters

Volt filters are special functions which modify/format variables. These are activated by using the pipe operator | and can be chained together.

volt: {{ name | capitalize }}

Filter	Description
cdn_path	This gives a cdn url.
date_format	Format a timestamp to Date object.
format_date	Format a date to unix timestamp.
hash	Calculate the sha1 hash of a string.
join	Combines list elements into a string with predefined separator e.g., {{ ['a','b','c','d'] | join('|') }}
length	Gets the length of a string or array e.g., {{ entry.name | length }}
number_format	Formats a number with grouped thousands and optionally decimal digits and optional decimal and thousand separator.
pop	Removes and returns the last element from an array e.g., {% let last = elements|pop %}
render_attributes	Renders associative array into a HTML attribute list.
replace	This function can be used in conjunction with a filter, see the Examples
rsort	Sorts an array in descending order. If not an array given it returns FALSE e.g., {% let ordered = elements|rsort %}
sort	Sorts an array in ascending order. If not an array given it returns FALSE e.g., {% let ordered = elements|sort %}
split	Splits string by separator. Default separator: comma. If a non-scalar e.g., array/object, the original is returned e.g., {{ entry.tags | split("|") }}
translate	Wraps a singleton class around PHP gettext functionality. The gettext functions implement an NLS (Native Language Support) API which can be used to internationalize your PHP applications.
ul2sp	Replaces underlines with spaces in a text.
lower	Change the case of a string to lowercase.
upper	Change the case of a string to uppercase.

Examples

# replace
{{ value |replace("match","replace", "target") }}

# e.g.,
volt: {{ "cheese"|replace("hee","HEE", value) }}
# returns cHEEse

# split
volt: {{ "something;split" | split(";") }}
# returns ["something", "split"]

#convert a number into a string
volt: {{"%d"|format(11) }}
#returns 11 as a string and can be concatenated with other strings

Exports

The format options of exports can also use volt functionality.

{{ value | date_format('Y-m-d H:i:s') }}

Datetime formats

The date_format filter sets the returned datetime according to the PHP date_format options.

Letter	Description	example
d	Day of the month, 2 digits with leading zeros	01 to 31
D	A textual representation of a day, three letters	Mon through Sun
j	Day of the month without leading zeros	1 to 31
l (lowercase ‘L’)	A full textual representation of the day of the week	Sunday through Saturday
N	ISO 8601 numeric representation of the day of the week	1 (for Monday) through 7 (for Sunday)
S	English ordinal suffix for the day of the month, 2 characters	st, nd, rd or th. Works well with j
w	Numeric representation of the day of the week	0 (for Sunday) through 6 (for Saturday)
z	The day of the year (starting from 0)	0 through 365
W	ISO 8601 week number of year, weeks starting on Monday	42 (the 42nd week in the year)
F	A full textual representation of a month, such as January or March	January through December
m	Numeric representation of a month, with leading zeros	01 through 12
M	A short textual representation of a month, three letters	Jan through Dec
n	Numeric representation of a month, without leading zeros	1 through 12
t	Number of days in the given month	28 through 31
L	Whether it’s a leap year	1 if it is a leap year, 0 otherwise.
o	ISO 8601 week-numbering year. This has the same value as Y, except that if the ISO week number (W) belongs to the previous or next year, that year is used instead.	1999 or 2003
X	An expanded full numeric representation of a year, at least 4 digits, with - for years BCE, and + for years CE.	-0055, +0787, +1999, +10191
x	An expanded full numeric representation if required, or a standard full numeral representation if possible (like Y). At least four digits. Years BCE are prefixed with a -. Years beyond (and including) 10000 are prefixed by a +.	-0055, 0787, 1999, +10191
Y	A full numeric representation of a year, at least 4 digits, with - for years BCE.	-0055, 0787, 1999, 2003, 10191
y	A two digit representation of a year	99 or 03
a	Lowercase Ante meridiem and Post meridiem	am or pm
A	Uppercase Ante meridiem and Post meridiem	AM or PM
B	Swatch Internet time	000 through 999
g	12-hour format of an hour without leading zeros	1 through 12
G	24-hour format of an hour without leading zeros	0 through 23
h	12-hour format of an hour with leading zeros	01 through 12
H	24-hour format of an hour with leading zeros	00 through 23
i	Minutes with leading zeros	00 to 59
s	Seconds with leading zeros	00 through 59
u	Microseconds. Note that date() will always generate 000000 since it takes an int parameter
v	Milliseconds. Same note applies as for u.	654
e	Timezone identifier	UTC, GMT, Atlantic/Azores
I (capital i)	Whether or not the date is in daylight saving time	1 if Daylight Saving Time, 0 otherwise.
O	Difference to Greenwich time (GMT) without colon between hours and minutes	+0200
P	Difference to Greenwich time (GMT) with colon between hours and minutes	+02:00
p	The same as P, but returns Z instead of +00:00 (available as of PHP 8.0.0)	Z or +02:00
T	Timezone abbreviation, if known; otherwise the GMT offset.	EST, MDT, +05
Z	Timezone offset in seconds. The offset for timezones west of UTC is always negative, and for those east of UTC is always positive.	-43200 through 50400
c	ISO 8601 date	2004-02-12T15:19:21+00:00
r	RFC 2822 / RFC 5322 formatted date	Thu, 21 Dec 2000 16:01:07 +0200
U	Seconds since the Unix Epoch (January 1 1970 00:00:00 GMT)	S