Programming

This page gives a syntax overview for writing a template that can be used to personalize your mail. Note that although the syntax is quite easy, you can build complicated concepts, which brings the danger of bugs (heck, even simple stuff can have bugs).

Variables

Let's just start with the basics of printing a user-supplied variable. A variable looks like {$name}, {$city} or {$country}: it starts with a {$, followed by the variable name and is closed with a }. Formally, a variable in personalization:

• must start with a dollar sign;
• must be surrounded by curly braces;
• may contain alphanumeric characters and underscores (_);
• must not start with a number or underscore;
• is case sensitive, meaning that {$NAME} is different from {$name}.

The next table gives all variable notations:

With these notations you may make combinations. Examples of combinations are:

If a variable happens to be an object where the index are keys, you can still access elements in the array with an index number (starting from 0).

Dashes and underscores

While you have to use underscores (_) in your templates when using variable names, you must supply these in the JSON with dashes (-). These are converted automatically. Example: When using {$total_price} in your template, you have to supply this in JSON with "data": { "total-price": 10 }.

Dashes in the template will be interpreted as the subtract operator. Variables with underscores in the JSON won't be accessible in the templates.

Modifying your variables

You can alter the content of your variables by applying modifiers to them. E.g. you can capitalize the content, calculate the length of a string, or calculating a hash sum. A list of all modifiers and an explanation about their usage can be found here.

Simple calculations

Variables containing a numerical value can be used to do some simple math. Just like with normal variables, all math should be done within the {} brackets. So you can for example do the following:

{$var + 10}

Besides the surrounding of curly braces, all standard math rules apply. The standard math operators (+, -, *, /) and the modulo operator (%) are available. Note that if a value does not exist or does not contain a numeric value, it will behave as the value zero.

Conditional statements

One of the key concepts of any programming language are conditional statements. A conditional block always starts with the {if} keyword (always with the curly braces) followed by the statement that is tested. A conditional block always ends with the if closing tag {/if}. A conditional block is only executed if the statement in the {if} part is true.

In the next example, the text 'Hello John' is only displayed when the value of the variable $name is equal to 'john'.

{if $name == 'john'}Hello John{/if}

But what if there's also a Sarah in your mailing list. You wouldn't want to display nothing to her, would you? That's where the {elseif} becomes the protagonist.

{if $name == 'john'}Hello John{elseif $name == 'sarah'}Hello Sarah{/if}

Now, if we want to say something to anyone except to John and Sarah, we will use the {else} keyword. The code after the {else} keyword will be executed if none of the preceeding statements returned true.

    {if $name == 'john'}
        Hello John
    {elseif $name == 'sarah'}
        Hello Sarah
    {else}
        Hello anybody else
    {/if}

This is of course a very bad example of how you should write your personal salutation because your conditional block would need to be as long as the list of all names in the world.

A much better example would obviously be:

    {if $name == ''}
        Dear subscriber,
    {else} 
        Dear {$name},
    {/if}

The code snippet above means: if the value of name is empty, show 'Dear subscriber', otherwise, show Dear John (or Sarah, or what is in the {$name} variable).

In the preceeding example, the operator == was used. This operator means 'is equal to'. It will evaluate to true if the left hand side of the == is exactly equal to the right hand side. Operator == is just one of the many operators that you can use to test the statements. Here's the complete list:

With the first six operators ("==" to "<=") you compare the values of variables $a and $b. If the comparison holds, a true will be returned. If the comparison does not hold, you will get a false. The regular expression operator is special and powerful, and allows you to check if the variable matches a certain pattern.

With the next two operators in the table above (AND and OR) you can combine statements. If you are writing conditional blocks, you will sometimes find yourself ending up with blocks that become too long or complex. To shorten long or more complex conditional blocks, you can put multiple statements in one single {if} block using the AND and/or OR operators. The AND and/or OR operators combine the value of $a and $b into a true or a false.

E.g. you can use AND like:

{if $a >= $b AND $b <= $c}true{else}false{/if}

In the above snippet first $a >= $b will be tested. Only if this is true, $b <= $c will be tested. If this happens to be true as well, true will be printed, else, false will be printed.

Subsequently there is the not operator. This operator will invert the value that is given. So true becomes false and false becomes true. Finally it is good to know that a variable itself will be converted to a boolean when used in an if statement. If the variable contains an empty string or the value 0, it will be evaluated as false. If it is not an empty string and it isn't zero, it will be evaluated as true.

Foreach

If you have a collection of data (an array), and want to see if a specific something is inside that collection, you'll have to loop through all the items in this collection.

Let's use a real world example and display all members of a soccer team, stored in an array called $soccerTeam.

To get the members of the team, the foreach statement is used. Its syntax is fairly straightforward:

{foreach $player in $soccerTeam}
    {$player.name}
{/foreach}

This will loop over the items (team members) in $soccerTeam and assign each player to the variable $player in each iteration. Inside this foreach block you can do whatever you want with the outputted information. You can for example generate an HTML list with soccer players from that team.

It becomes a little bit more technical now...

Of course we also support looping over arrays that have non-standard keys.

    {foreach $list as $key => $value}
       Key {$key} contains {$value}.
    {/foreach}

As you can see here, you specify both a $key and a $value which will be used to store these values on each iteration.

And finally, sometimes you want certain code to execute if there is no data at all, this is done using the {foreachelse} statement.

    {foreach $item in $list}
       {$item.name}
    {foreachelse}
        No items in list.
    {/foreach}

This foreachelse statement is only executed in case of no data. It is completely ignored otherwise.

Assigning variables

It is possible to assign values on runtime. You can for example use this to calculate the total price of a set of purchased items. Or to remember a certain item inside a foreach statement. Assigning variables is done as follows:

{assign $item to $topitem}

After this statement the variable $topitem is available and it will contain what $item contained when the email was being compiled and sent to the user.

This will allow you to do things like the following.

  {foreach $item in $list}
    {assign $total + $item.price to $total}
    {if $item.price > $topitem.price}
      {assign $item to $topitem}
    {/if}
  {/foreach}

Which will eventually have the most expensive item in the $topitem variable and the total price in $total.

Using curly braces in your text

As you can see above the syntax heavily depends on the curly braces {}. Therefore, these braces cannot appear in the text without leading to a valid syntax. If you do need these braces in you text, you can use: {ldelim} to get a { and {rdelim} to get a }. If you have a large text with these braces you can enclose the text in {literal} and {/literal}. This text will then not be processed.

Layout issues

The code snippets above are formatted in a way to make them readable: we used newlines, indentation, etc. When you are generating text for the html part of your mail this is advisable since it is easier to capture mistakes. However, if you are generating content for the text part of your mail, you should be aware that the formatting of your template code affects the format of your text.

E.g. above we gave a snippet that prints out names of players in a soccer team

If the soccerTeam array looks like: ["Ronaldo", "Messi", "Ibrahimovic"]

The output that we get in the text section will be:

    Ronaldo

    Messi

    Ibrahimovic

This is probably not what you had in mind while typing the foreach loop. But this is what you get since there is a new line before and after the variable and there are some spaces in front of it used as indentation. To get a list of the names without the extra whitespace you should write:

{foreach $player in $soccerTeam}{$player}
{/foreach}

This is less readable but gives what you want

Ronaldo
Messi
Ibrahimovic