Email templates
Email templates are prepared email messages, containing subject, HTML and text content, with variables, placeholders and template code that get processed and replaced when an email is sent. A template can preview its own rendered output, and a preview of the current subject, HTML and text content is shown directly on the template's edit page.
Import/Export
Email templates can be imported and exported as JSON files from the template editor. All field names in the JSON file correspond to the fields found in the Email template editor.
Example
{
"meta" : { },
"name" : "Hello world",
"description" : "Test",
"templateEngine" : "VELOCITY",
"defaultLocale" : "fi",
"defaultTimeZone" : "Europe/Helsinki",
"subjectTemplate" : "$subject",
"htmlTemplate" : "<html><body><h1>Dear recipient</h1></body></html>\n$recipientUser\n\n$verificationUrl",
"textTemplate" : "$heading\n\n$content",
"localeProperties" : {
"fi" : {
"heading" : "Hei",
"subject" : "Mitä kuuluu",
"content" : "No eipä mitään tässä."
},
"en" : {
"heading" : "Hi",
"subject" : "How are you",
"content" : "Eh, nothing much going on."
}
},
"namespaceIds" : [ ]
}
Locale = Language
During template processing the used Locale becomes important. It is used for example when choosing a translation, or how a date or time representation is generated.
A locale can consist of several parts, but the most important is Language. It can also contain a
Country. These parts are often shown like this: en or en_US. The first locale contains only a
language (English) while the second locale specifies also a country (American English). If you
need to customise the translations for different regions, you can do that by adding the country
to the locale.
If you add Locale specific properties, you should also specify a default Locale in your template. It is used if no other locale is selected when the email is being processed. Using locales and properties allows for easier creation of email templates as a single property can have multiple languages.
Built-in properties
In addition to the locale-specific properties you define yourself, every template can use these built-in properties:
| Property | Data type | Description |
|---|---|---|
${serviceBrand} | String | Service brand name |
${recipientEmailAddress} | String | Email address used in the "To" field, if specified when sending |
${recipientUser} | UserWrapper | User details of the message recipient, if a user is specified when sending |
${senderUser} | UserWrapper | User details of the message sender, if a user is specified when sending. When the message is sent via the API, this is likely not available |
A template's Common content field holds macros shared across that template's own subject, HTML and text content — it isn't shared between different templates.
Template engine
The subject, HTML and text content you write are processed with a template engine. Apache Velocity is currently the only supported template format.
You can use templates in the subject, HTML and text content. They will all be processed identically. It is up to you to make sure the templates are valid and produce valid output.
Apache Velocity
Trivore ID supports templates written for Apache Velocity 2.2. The Generic Tools 3.0 package is included with standard tool names.
You can reference properties using the $ prefix followed by the property name. If the property
has sub-properties, you can chain the names together separated by . period characters.
Because periods separate chained property names, you cannot have period characters in your own property names.
Example:
Hi ${recipientUser.firstName}!
The time and date is currently ${date.systemDate}.
Your email is $recipientEmailAddress.
Hi Sue!
The time and date is currently Fri Mar 13 14:42:23 EET 2020.
You email is [email protected]
There are many options and tools you can use to create dynamic content. Check the links below for more information.
Variables in translations
With Velocity you can have property references and dynamic content in properties, including
locale properties (the translations). You can use the $render.eval() method to evaluate these
parts in properties before they are displayed.
Example:
firstname=Sue
subject=How are you ${firstname}?
<h1>
$render.eval($subject)
</h1>
<h1>
How are you Sue?
</h1>