Using Placeholders in Email Templates

Using Placeholders in Email Templates

When composing an email template you can use placeholders to save typing or to customize it for each recipient or recipient group. A few important placeholders are predefined by the system but you can define an arbitrary number of your own placeholders.

This article is organized as follows:

What is a Placeholder

A placeholder is a Mustache tag that is dynamically replaced with text when sending the email to each recipient. It has the following structure:

{{placeholder}}

System placeholders are valid in all templates' contexts. Custom placeholders are valid only in the context of the template where they are declared.

System Placeholders

The Email Notifications service comes with a set of predefined placeholders called system placeholders. These are automatically replaced with values when sending emails. You don't need to set the values in the template context.

The system placeholders can be divided into several categories:

Email Header Placeholders

The email header system placeholders are populated with built-in variables that you can manage on Emails > Settings (or if you have added the User Management service, you can also use Users > Email Settings to set the same values). They include:

  • {{DefaultFromEmail}} set using Default from email
  • {{DefaultFromName}} set using Default from name
  • {{DefaultReplyToEmail}} set using Default ReplyTo email

These come in handy when filling in the respective email header fields, as shown in the next figure, but you can also use them in the message body:

System placeholders in use

User Management Placeholders

The user management placeholders are only allowed in the context of the ResetPasswordEmail, PasswordChangedEmail, VerifyAccountEmail, and WelcomeEmail system templates. They allow you to access data from the Users content type. They must be typed in the following format:

{{User.fieldname}}

where fieldname is a name of the Users content type field that you want to access. For example:

  • {{User.DisplayName}} is replaced with the user's display name
  • {{User.Username}} is replaced with the user's username

In addition, you get a pair of user management placeholders that do not read data from the Users content type, but a closely related to each user:

  • {{VerifyAccountURL}} is replaced with the default user account verification URL for the user
  • {{PasswordResetURL}} is replaced with default password reset URL for the user

App Data Placeholders

The app data placeholders allow you to access data about your Telerik Platform app. These include:

  • {{Application.Title}} is replaced with the app name
  • {{Application.Name}} is replaced with the internal autogenerated name of your app. This name is also used by default in the DefaultFromEmail and looks like this: aBackendServicesd83ed520219646ffb017ab38e79e1180
  • {{Application.Description}} is replaced with the app description

Custom Placeholders

You can customize an email message in many ways using placeholders. A simple example is inserting a product name that your recipient has just purchased:

Thank you for purchasing {{ProductName}}.

which appears like this in the email:

Thank you for purchasing Space Rocket 3000.

You can use placeholders for more elaborate tasks such as inserting dynamic HTML code or automatically generating HTML code for an array of elements. See the following sections for examples.

Besides inserting the placeholder into the template, you need to set its value. You do this in the context payload parameter when sending the email. For details, see the respective article:

Using Flow Control Clauses

For greater flexibility you can use flow control (conditional) clauses in your template:

If Variable Exists

To display a certain piece of text only when a value for the placeholder is set in the context, use this construct:

{{#variableFromTheContext}}

Text to display

{{/variableFromTheContext}}

If Variable Does Not Exist

To display a certain piece of text only when a value for the placeholder is not set in the context, use this construct:

{{^variableFromTheContext}}

Text to display

{{/variableFromTheContext}}

If Values are Equal

To display a certain piece of text only when a pair of values are equal, use the next construct. Each of the values can be:

  • Variable from the context, formatted as: variableFromTheContext
  • Number, formatted as: N
  • String, enclosed in single quotes: 'string'
{{#if (eq val1 val2)}}

    Text to display 1

{{else if (eq val3 val4)}}

    Text to display 2

{{else}}

    Text to display 3

{{/if}}

Examples

In this example, different text is displayed depending on whether you've set {{PremiumUser}} in the context.

Context:
"PremiumUser": "John Doe"

Message Body:
{{#PremiumUser}}
    View out special offers for premium users!
{{/PremiumUser}}
{{^PremiumUser}}
    Become a paying member to get the full benefits!
{{/PremiumUser}}

The following example checks if it is April 1st and prints a customized messages if it is:

Context:
"CurrentDate": "04.01"
"CurrentYear": "2016"

Message Body:
{{#if (eq CurrentDate '04.01')}}
    Happy April Fool's Day!
{{else}}
    Today is {{CurrentYear}}.{{CurrentDate}}.
{{/if}}

Dynamically Including HTML

When composing an email body using HTML, you can insert placeholders that can be dynamically replaced with HTML code when sending the email later.

To dynamically insert HTML into your template:

  1. Insert a template placeholder enclosed in a <pre></pre> tag where you want the dynamic HTML to appear.

    In contrast to previous placeholders, this placeholder type uses triple braces.

    For example if you want to insert a customized HTML-formatted greeting into your emails, use a placeholder such as:

    <pre>{{{CustomizedGreeting}}}</pre>
    
  2. Then, in the Context object, provide a value for the placeholder.

    For example:

    var context = {
        "CustomizedGreeting": "<div><span> ... </span><img ... ></div>"
    };
    

Creating Separate HTML Tags for Array Items

Suppose you have an array of items, each of which you want to display as a separate HTML tag. You can do this using nothing more than template syntax.

For example, the Urls variable contains an array of five URL:

emailContext.Urls = [ "url1", "url2", "url3", "url4", "url5" ];

By adding the code shown below to the HTML view of your template, you will get five images in the resulting email:

{{#Urls}}
 <img src="{{.}}" />
{{/Urls}}

If you need to access the properties of objects contained in an array use the same dot (.) notation followed by the property name.

Assume that the array of objects looks like the following:

emailContext.Urls = [{"Url":"url1"},{"Url":"url2"},{"Url":"url3"},{"Url":"url4"},{"Url":"url5"}];

By adding the property name after the dot (.), you will get the Url values in the resulting email:

{{#Urls}}
 <img src="{{.Url}}" />
{{/Urls}}

See Also

Start a free trial Request a demo
Contact us: +1-888-365-2779
sales@telerik.com
Copyright © 2016-2017, Progress Software Corporation and/or its subsidiaries or affiliates. All rights reserved.