Overview

Cordial's template syntax is built on Smarty, a powerful scripting language that can be used to add logic, dynamic data, and personalization rules to your HTML templates.

This article provides information on how Smarty is used in Cordial. For general instructions about the Smarty language, visit http://www.smarty.net.

Tag delimiters

All Smarty code is enclosed in curly brace tag delimiters: {and}. When these delimiters are present in the code, Cordial will handle these as Smarty.

CSS also uses curly braces for style definitions. It's important to either escape these with {literal} tags or surround them with whitespace so they are not mistaken as Smarty. Learn more about CSS syntax conflicts below.

Where Smarty is supported

You can use Smarty in:

• Any message body
  • Automation templates: recurring
  • Automation templates: transactional
  • Automation templates: triggered
  • Batch messages
  • HTML Includes
• Message header fields
  • Message subject
  • From address
  • From description
  • Reply email

When Smarty compiles/renders

The script executes at send time and is compiled and rendered uniquely for each individual contact (1:1). You can also check the template rendering in the HTML Message Editor by clicking the Preview button. The preview screen gives you the ability to select any contact address to view rendering for that particular individual. This is especially useful for testing your template in the application.

If you're just familiarizing yourself with Smarty, we recommend that you open the HTML message editor and paste in each of the examples below. For each example, click Preview to view the output and then Edit to move on to another example. It's a great way to get comfortable with the message editor and Smarty at the same time.

Comments

Cordial's template syntax has a method for adding comments to the code, which, unlike the <!-- HTML comment-->, will not be part of the compiled output. This is useful for adding comments to your templates that will never be seen in the source code of the output.

{* this is a comment *}

Text strings

Any strings in quotes within a Smarty tag will be rendered in the output exactly as the string appears between the quotes.

{"This is a text string."}

Output:

This is a text string.

Math operations

Cordial templates support a robust assortment of math operations. Examples:

You can test Smarty output in your Cordial account by pasting into the edit message field and clicking the Preview button.

Solve equations with {math}

You can also use the {math} function to solve math equations.

The {math} function and related operators are not officially supported by Cordial. Additional documentation for this function is available on the official Smarty website. Please see the supported Smarty functions and modifiers page.

Calculate the percentage discount between two prices:

{$regular_price = 220} 
{$sale_price = 175.99} 
{* DO NOT EDIT BELOW *}
{$data.percentage_discount = {math equation="((x - y)/x) * 100" x=$regular_price y=$sale_price format="%d"}}
{$utils->jsonPrettyPrint($data)}

Randomly select a number between min and max values:

{$min = 1} {* do not change *}
{$max = 2} {* 1 = a, 26 = z *}
{* DO NOT EDIT BELOW *}
{$data.randomNumber = {math equation='(rand(min, max))' min=$min max=$max}} {* randomly select a number 1 thru MAX *}
{$utils->jsonPrettyPrint($data)}

Comparison operators

You can use comparison operators in Smarty to create statements that result in a boolean value of true (1) or false (0).

These are useful when writing conditional {if} statements to render content in a message based on a contact's attribute.

Variables and notation

Smarty variables are used to render dynamic content in a message.

The dollar sign prepended to the variable name will be replaced by the stored value when the message is sent or previewed.

Throughout our tutorial articles, we use dot notation because it's easier to read and write: {$contact.first}. Spaces or math operators (-, *, +, etc.) that are present in attribute names can cause errors in Smarty. This is true for attributes in the contact collection as well as attribute/property names in other data collections (orders, products, supplements, events, and external JSON). If math operators are present in attribute/property names, use the following array notation instead: {$contact['first name']} or {$contact['first-name']}

• Learn more about using Smarty variables here.

Conditional statements: {if}, {elseif}, {else}

{if} statements are used to render data based on a condition.

{else} and {elseif} statements give you more options for rendering the conditional content.

• Learn more about conditional statements using {if} here.

Loop through data: {foreach}

Smarty allows for looping through sets of data and rendering the results in a message.

For example, if you have the following supplement data available:

[
  {
    "id": "123",
    "model": "A4",
    "brand": "Audi",
    "price": 5000,
    "mileage": 152158
  },
  {
    "id": "124",
    "model": "A4",
    "brand": "Audi",
    "price": 5500,
    "mileage": 130154
  },
  {
    "id": "125",
    "model": "A4",
    "brand": "Audi",
    "price": 5900,
    "mileage": 120158
  }
]

You would write the following Smarty to output the data:

{$cars=$supplements->getRecords('cars') } 
{foreach $cars as $car}  
 <strong>{$car.brand} {$car.model}</strong><br />
   ${$car.price}<br /> 
  Mileage: {$car.mileage}<br /> 
  <a href="http://example.com/cars/{$car.id}">View details</a><br /><br />
 {/foreach}

Resulting output:

Audi A4
$5000
Mileage: 152158
View Details 

Audi A4
$5500
Mileage: 130154
View Details 

Audi A4
$5900
Mileage: 120158
View Details 

• Learn more about using {foreach} statements here.

Avoid CSS syntax conflicts

CSS uses curly braces for style definitions. These can be mistaken for Smarty and produce errors when attempting to save or preview your code.

The following formatting will cause a syntax error:

<style type="text/css">body{background:#ccc;}</style>

There are several ways that you can avoid these syntax errors when working with CSS curly braces.

Add white space around CSS curly braces

Smarty ignores delimiters that are surrounded by whitespace.

<style type="text/css">body { background:#ccc; } </style>

Or

<style type="text/css">
body{ 
   background:#ccc; 
}
</style>

Use the {literal} tag

{literal} tags allow a block of data to be taken literally. Anything within {literal}{/literal} tags is not interpreted by Smarty, but displayed as is.

Without the literal tag around your CSS, you might get an error like: unexpected one of }

{literal}
<style type="text/css">body{background:#ccc;}</style> 
{/literal}

Use Smarty notation for curly braces

You can also use Smarty notation for curly braces to avoid conflicts.

<style type="text/css">body{ldelim}background:#ccc;{rdelim}</style> 

Avoid additional spaces in email

It can be easier to read Smarty code when it's indented and has new lines. You can remove these additional characters from your email with {strip}.

In the following example, if we run logic but don't output any HTML, the strip tag will remove all the whitespace.

Example with {strip} tag

{strip}
{for $i=0 to 100 max=100}
  {if $i is even}
    {$foo[] = $i}
  {/if}
{/for}
{/strip}

• Learn more about the {strip} tag here.

In the next article, you can learn about Smarty variables.