This guide is designed for developers working with Mapp Engage's Content Management System (CMS). It explains how to use the Velocity Template Language (VTL) and Mapp-specific notation to build reusable and dynamic email templates and blocks.
You’ll find practical examples and syntax references to help you set up:
Editable areas in HTML
Conditional rendering with Velocity
Custom styles and device previews
Variables and placeholders for flexible content editing
If you're looking for general instructions on how to build and send messages, see the Creating Email Messages from Templates page.
Most notations use Velocity Template Language (VTL). You can find the full reference here: Velocity VTL Reference Guide.
1. Methods
You can use the following elements to add placeholders to your HTML code:
Element | Functionality |
|---|---|
Notation for Block Areas | Indicates where one or more blocks can be added to an email template. |
Notation for Element Values |
|
Notation for Editor Styles | Determines which styles can be used to format text in the styled text editor and the rich text editor. |
2. Directives
With VTL, you use a library of script elements to manage content in HTML code. Velocity lets you create placeholders that are replaced with actual content such as texts or images. Since VTL placeholders are treated as independent references, you can combine different content elements without changing the framework of your email template.
In Velocity, references begin with $ and are used to get something. Directives begin with # and are used to do something.
Directive | Description |
|---|---|
#set | Velocity uses the #set directive to assign values to variables. |
#if #elseif #else | Velocity uses #if/#elseif/#else directives to insert conditions for inserting variable content. Mapp Engage personalisation placeholders, personalisation rules, and Mapp Engage Variables are also supported. |
#forEach | Velocity uses the #forEach directive to iterate over a list of objects. You can iterate over any object that contains more than one target value. |
3. Syntax Details
Some notation passes parameters. Our parameters are structured to resemble JSON format. Parameter identifiers are quoted and separated from the values they define by a colon. Multiple parameters are separated from each other by commas.
Example
This structure passes the value "123" as an ID parameter and "MyName" as a name parameter.
'"id" : "123","name":"MyName"'3.1 Block Areas
tplBlockArea.begin(parameters)
This element indicates the beginning of an area where one or more blocks can be inserted in the template.
To enclose the area in which blocks can be placed, pair the begin element with a tplBlockArea.end() element.
When you insert a block, the editor tool of the template tracks where the inserted block begins and ends. This information makes it possible to remove or replace blocks later.
Do not place any additional HTML code between the begin tag and the end tag of the block area.
Parameter | Description |
|---|---|
id | An optional identifier for the block area. |
name* | The name of the block area. The block-name parameter is required and must be unique within the HTML code. |
3.2 Editor Styles
tplEditor.styles('[array of CSS selectors]')
This element defines which styles appear in the Paragraph drop-down list of the styled-text editor and rich-text editor. To specify which styles are available, create a JSON array.
Define all styles that are referenced in the array in the header of the framework. The referenced styles must match the CSS selectors exactly.
Currently, tags and classes are supported. Begin your classes with a "." (dot). CSS id selectors are not supported.
Three Styles Example
This code defines three styles.
<html>
<head>
<style>
h1 {
font-size: 24px;
}
.myStyle {
background-color:#CCCCCC;
color:#0000CC;
}
.anotherStyle a {
color:#CC0000
}
</style>
$tplEditor.styles('["h1", ".myStyle", ".anotherStyle a"]')
</head>...This code renders as shown:
<html>
<head>
<style>
h1 {
font-size: 24px;
}
.myStyle {
background-color:#CCCCCC; color:#0000CC;
}
.anotherStyle a {
color:#CC0000
}
</style>
</head>...The code adds three styles to the Style drop-down menu:
h1
myStyle
anotherStyle
Custom Labels Example
This code defines custom labels.
<html>
<head>
<style>
h1 {
font-size: 24px;
}
.myStyle {
background-color:#CCCCCC; color: #0000CC;
}
.anotherStyle a {
color:#CC0000
}
</style>
$tplEditor.styles('[{"label":"Header 1","selector":"h1"}, {"label":"My Style","selector":".myStyle"},
{"label":"Link Another Style","selector":".anotherStyle a"}]')
</head>....This code renders as shown:
<html>
<head>
<style>
h1 {
font-size: 24px;
}
.myStyle {
background-color:#CCCCCC; color:#0000CC;
}
.anotherStyle a {
color:#CC0000
}
</style>
</head>....The code adds a custom label to the three styles that you add to the Styles drop-down menu:
Header 1
My Style
Link Another Style
3.3 Mobile and Tablet Editing Mode
$tplMedia.view(parameters)
This element indicates the start of an area that wraps a media query declaration with a CSS style. The notation adjusts what you see in our visual template and message editors to simulate the selected device type. Currently, you can select Desktop, Tablet, or Mobile in the Type field.
To enclose the area, pair the media view element with a $tplMedia.end() element.
When you create a message for different devices, you can review and edit the rendered message at a specific width. It is possible that some responsive blocks are not visible for all screen widths. This notation allows you to see and edit placeholders that are otherwise hidden in a desktop view.
You access preview options from the Compose Email Message and Compose Email Template windows.
The tplMedia.view notation only affects the visual editors for your templates and messages, it is not included in the sent message.
Parameter | Description |
|---|---|
type* | Defines the device icon that Mapp Engage displays in the visual editor that activates the simulation. Currently, you can select Desktop, Tablet, or Mobile. |
width* | Defines the width in pixels that Mapp Engage imposes on the media queries of the message or template. The visual editor adjusts to display content at the specified screen width. |
Example
This code is the basic notation of the edit mode that simulates a mobile device.
$tplMedia.view('"type":"mobile","width":"480px"')
...
...
$tplMedia.end()Example
This code shows the tplMedia.view element in a style tag. When this notation is added to a template or message, a mobile device symbol displays at the top of the editor. To apply the defined CSS and alter the width of the content area, you click the symbol.
<style type="text/css">
#outlook a {
padding: 0;
}
.ExternalClass {
width: 100% !important;
line-height: 100%;
background-color: #353535;
}
.ExternalClass img[class^=Emoji] {
width: 10px !important;
height: 10px !important;
display: inline !important;
}
img {
outline: none;
text-decoration: none;
-ms-interpolation-mode: bicubic;
}
body,
p {
margin: 0;
padding: 0;
margin-bottom: 0;
-webkit-text-size-adjust: 100%;
-ms-text-size-adjust: 100%;
}
table td {
border-collapse: collapse;
}
.tablefixed {
table-layout: fixed;
}
$tplMedia.view('"type":"mobile", "width":"630"')
@media screen and (max-width:639px) {
*[class].mw0px {
min-width: 0px !important;
}
*[class].w100pc {
width: 100% !important;
max-width: none !important;
}
}
$tplMedia.end()
...
...
</style>4. Element Placeholders and Fields
4.1 Element Placeholders
tplPlaceholder.element(parameters)
Element values indicate where editable values can be inserted in the HTML code. For example, a field to enter text or an image. The person who creates the message enters content for these values through input fields in the Email Message Composition window.
Parameters are specified as a string with a structure that is similar to JSON format.
The tplPlaceholder.literal(parameters) placeholder is deprecated. For compatibility reasons, Mapp Engage converts this placeholder automatically to a tplPlaceholder.element(parameters) placeholder when the email template is opened.
Tab. : Parameters for Element Values
Parameter | Description |
|---|---|
id | Defines an optional identifier for the element. |
name | Defines the name of the element. |
inline | Defines a boolean value that indicates whether the editor for the field appears inline or on a separate form. The default value is true. If global values are set in the framework, the inline value is false. If you do not specify an inline parameter, the behaviour of the system is the same as when you set the parameter value to false. |
group | When the inline parameter is false, you can use this value to group similar form fields in the UI. If left blank, Mapp Engage assigns parameters to the "General" group. |
type | Defines the type of field. This value determines which toolbars the message creator can use to format the content. Each type parameter has associated attributes. |
4.2 Visual Editor Fields
Type parameters define the type of field. When you allow the message creator to format content, Mapp Engage provides different toolbars with predefined editing actions and formatting options. Each field type can have additional, case-sensitive attributes that define which controls Mapp Engage displays in the editor.
Parameter | Description |
|---|---|
text | Inserts a text field that can be modified with a plain text editor.
|
styledtext | Inserts a styled-text field that can be modified with a text editor. The formatting options and styles are predefined with the tplEditor.styles element.
|
richtext | Inserts a text field that can be modified with a rich text editor.
|
image | Inserts an image tag that can be modified with an image editor.
|
code | Allows full access to the html source code at this location.
|
4.3 Right Panel Fields
These parameters apply to global or block level elements that appear in the panel on the right side of the visual editor.
Parameter | Description |
|---|---|
text | Inserts a text field that can be modified with a plain text editor.
|
list | Defines a set of elements from which a value can be selected. Do not use this element with the inline parameter set to true.
|
url | Defines text that is validated as a proper URL. Do not use this element with the inline parameter set to true.
|
toggle | Defines a switch to turn variables on or off. Do not use this element with the inline parameter set to true.
|
5. Examples
Plain Text Example
${tplPlaceholder.element('"name":"saleItem", "type":"text", "value":"Sale Item Name"')}
Rich Text:
${tplPlaceholder.element('"name":"saleItem", "type":"richText", "value":"Sale Item Name"')}The plain-text example renders as shown:
Sale Item Name
Rich Text:
Dog foodImage Examples
Simple:
${tplPlaceholder.element('"name":"company-logo", "type":"image",
"src":"http://mappnet.mapp.com/image/company_logo?img_id=11331&t=1442589977545"')}The simple-image example renders as shown:
<img src="http://mappnet.mapp.com/image/company_logo?img_id=11331&t=1442589977545">Advanced: + Dimensions & Class
${tplPlaceholder.element('"type":"image", "name":"Image_links", "src":"http://imagestore.com/220x434", "width":"220",
"height":"434", "style":"width: 220px; height:434px", "class":"Someclass"')}The advanced-image example renders as shown:
<img src="http://imagestore.com/220x434" width="220" height="434"
class="Someclass">Link Examples
Plain Text Link:
${tplPlaceholder.element('"name":"saleItem", "type":"text", "value":"Sale Item Name", "href": "http://yourlinkhere.com",
"target":"_self","linkstyles":"font-size: 24px; color: #5C5D5F; text-decoration: none;","linkclass": "linkClass"')}The plain-text link example renders as shown:
<a href="http://yourlinkhere.com" target="_self"
class="linkClass">Sale Item Name</a>Rich Text Link:
${tplPlaceholder.element('"name":"saleItem", "type":"richText", "value":"Sale Item Name",
"href": "http://yourlinkhere.com", "linkstyles":"font-size: 24px; color: #5C5D5F; text-decoration: none;","linkclass": "linkClass"')}The rich-text example code renders as shown:
<a href="http://yourlinkhere.com" target="_blank"
class="linkClass">Sale Item Name</a>Image Link:
${tplPlaceholder.element('"type":"image", "name":"Image_links", "src":"http://placehold.it/220x434", "width":"220",
"height":"434", "style":"width: 220px; height:434px", "class":"Someclass", "href": "http://yourlinkhere.com"')}The image-link example renders as shown:
<a href="http://yourlinkhere.com" target="_blank"><img src="http://placehold.it/220x434" width="220" height="434"
class="Someclass"></a>List Example
This code creates a drop-down menu field in the right panel:
/* defined in block or framework */
#set ($bgColor = ${tplPlaceholder.element('"name":"Background Color", "type":"list", "value":"blue",
"options": [{"name":"Blue", "value": "blue"},{"name":"Red", "value": "red"}],"inline":"false", "group":"Colors"')})
/*******************************/
<table >...</table>This list example renders as shown:
<table >...</table>Toggle Example
This code creates a toggle form field in the right panel:
/* defined in block or framework */
#set ($hideShowImg = ${tplPlaceholder.element('"name":"Hide/Show Image", "type":"toggle", "value":"block",
"trueValue":"block", "falseValue":"none", "inline":"false", "group":"Block Variables"')})
/*******************************/
<table >...</table>The toggle example renders as shown:
<table >...</table>URL Example
This code creates a form field in the right panel that verifies whether the entered URL is valid.
/* defined in block or framework */
#set ($linkURL= ${tplPlaceholder.element('"name":"linkUrl", "type":"url", "value":"[https://mapp.com]", "inline":"false", "group":"links"')})
/*******************************/
<a href = "${linkUrl}">...</a>The URL example renders as shown:
<a href="[Valid URL]">...</a>6. Variables
You can declare variables in a block or framework to add customization options for templates and messages that cannot be accomplished with inline editing. For example, set an alternative background color for blocks in a template.
When you declare a variable in a framework, you can refer to that variable elsewhere in the framework. For example, in CSS style values or body tag attributes. The template or message creator can modify these values later. All references of the variable in blocks that are added to the template that use the framework inherit the same value.
For example, the framework of your template contains a $tableWidth variable that is set to 600. If you add a block that contains a $tableWidth variable, the references to that variable in the block resolve as 600. This inheritance allows the block to adapt to the framework in which it is placed.
If you declare a variable in a block, only references to that variable within the single instance of the block inherit the defined value.
Block level variables take precedence over framework variables. For example, a template uses a framework with a variable named $tableWidth that is set to 600. If you add a block with a $tableWidth variable that is set to 500, references to $tableWidth in the block resolve as 500.
6.1 Variable Declaration
#set ($variableName = variableValue)
Usually, you declare the variableValue as a placeholder with inline set to false. Setting a variable to a placeholder allows the template or message creator to edit the value of the variable on the UI. The variableValue can also be set to a static text value. A static value allows references across different blocks to inherit the value that the parent framework defines. A static value prevents edits by the template or message creator. In either case, the text value that is assigned to variable replaces the variable references in the template or message code.
6.2 Variable Reference
${variableName}
The #set directive is used to assign the value of a reference. For more information, see http://velocity.apache.org/engine/1.7/user-guide.html#set.
Variable Reference Format Example
/*
* Variable Reference - your reference must refer to an existing variable that is defined in the associated framework or block
* Operator - use an operator to compare your variable to the comparision value(supported operators are: ==, !=, <, >, <=, >=.
Velocity does not support NOTE: === and !==.
* Comparision Value - the value to which the variable reference is compared. The comparison value must be enclosed with double quotation marks.
*/
#if ([Variable Reference] [Operator] "[Comparision Value]")
[htmlContent]
#endIn a variable declaration, the dollar sign is directly next to the variable name. In a variable reference, the dollar sign is separated from the variable name by a curly bracket.
Variable Usage Example
In this example, the template or message creator is able to change $tableClass and $tableWidth. The template or message creator cannot change $tableHeight.
#set ($tableClass = ${tplPlaceholder.element('"id": "0", "name":"tableClass", "type":"text", "value":"myClass", "inline":"false", "group":"Classes"')})
#set ($tableWidth = ${tplPlaceholder.element('"id": "tw1", "name":"table width", 'type':"text", "value":"500", "inline":"false", "group":"Widths"')})
#set ($tableHeight = 300)
<table class="${tableClass}" >...</table>This code resolves as shown:
<table class="myClass" >...</table>7. Conditional Content
You can use conditionals to display different information that reflects the variable that is set. Conditionals provide flexibility. However, the use of conditional has some limitations:
Conditionals only support one top-level element.
One table
One div
One insert tag
You cannot place a conditional in a tplPlaceholder
You cannot place variables in atplPlaceholder for attributes that a system user can edit. For example:
href
value
image src
One tplPlaceholder cannot be placed inside another tplplaceholder.
Variables that conditionals evaluate cannot dictate the options or display of other variables in the right-hand panel of the visual editor.
Personalization variables are not supported for comparisons. Use the personalization InsertIf logic to build the comparison.
If you nest many conditionals, the effect on your blocks is difficult to predict.
Velocity #if/elseif/else directives allow you to add content when predefined conditions are met. You can combine these VTL directives with Mapp Engage personalization attributes and expressions (InsertIf).
An #elseif or #else element can be used with an #if element. The #if directive controls whether content renders when the web page is generated. For more information, see: http://velocity.apache.org/engine/1.7/user-guide.html#if-elseif-else.
Example
When the evaluation is true, the content between the #if statement and the #end statement renders.
#if( $foo < 10 )Calendar
**Go North**
#elseif( $foo == 10 )
**Go East**
#elseif( $bar == 6 )
**Go South**
#else
**Go West**
#endThe output of this code renders as shown:
Go SouthExample of $defaultBGColor Defined in a Framework as #FFFFFF
#set ($defaultTableWidth = ${tplPlaceholder.element('"id": "def-tableWidth", "name":"Default Table Width", "type":"text", "value":"660", "inline":"false", "group":"System Defaults"')})
#set ($layoutChoice = ${tplPlaceholder.element('"id": "def-bgColor", "name":"Layout Choice", "type":"list", "value":"image", "options": [{"name":"Image", "value": "image"},{"name":"Text", "value": "text"}],"inline":"false", "group":"Layout"')})
#set ($blockUrl= ${tplPlaceholder.element('"id": "blockUrl", "name":"Block URL", "type":"URL", "value":"http://yahoo.com", "inline":"false", "group":"Block Level"')})
#if (${layoutChoice} == "image")
<table bgcolor="${defaultBGColor}" border="0" cellpadding="0" cellspacing="0" width="${defaultTableWidth}" class="w100pc" align="center" y.id="cosima_default_id_0101010101010101" y.linktarget="true" y.validity.allowed="true" y.validity.mode="positive">
<tr>
<td height="30" > </td>
</tr>
<tr>
<td>
${tplPlaceholder.element('"type":"image", "id":"1", "name":"Image", "src":"http://placehold.it/660x150","width":"660", "height":"150", "style":"width: 660px; height:150px", "class":"w100pc", "editorstyle": "width: 660px; height:150px", "editorclass ": "w100pc", "href": "http://teradata.com/IMAGE_LINK"')}
</td>
</tr>
#if (${defaultBGColor} == "#FFFFFF")
<tr><td>I am white Background Color on image block</td></tr>
#end
<tr>
<td class="padLR9">
<table border="0" cellpadding="0" cellspacing="0" width="100%" align="center" y.id="cosima_default_id_0101010101010101" y.linktarget="true" y.validity.allowed="true" y.validity.mode="positive">
<tr>
<td class="NoMob" height="30" width="12" > </td>
<td height="30" > </td>
<td class="NoMob" height="30" width="12" > </td>
</tr>
</table>
</td>
</tr>
</table>
#end
#if (${layoutChoice} == "text")
<table bgcolor="${defaultBGColor}" border="0" cellpadding="0" cellspacing="0" width="${defaultTableWidth}" class="w100pc" align="center" y.id="cosima_default_id_0101010101010101" y.linktarget="true" y.validity.allowed="true" y.validity.mode="positive">
<tr>
<td height="30" > </td>
</tr>
<tr>
<td>
${tplPlaceholder.element('"type" : "richtext", "id" : "rt3", "name" : "rt_3", "editorstyle" : "height: 100px", "value" : "Lorem ipsum dolor sit amet, verear molestie ne nam. Ei vix vidit volutpat quaerendum"')}
</td>
</tr>
#if (${defaultBGColor} == "#FFFFFF")
<tr><td>I am white Background Color on text block</td></tr>
#end
<tr>
<td class="padLR9">
<table border="0" cellpadding="0" cellspacing="0" width="100%" align="center" y.id="cosima_default_id_0101010101010101" y.linktarget="true" y.validity.allowed="true" y.validity.mode="positive">
<tr>
<td class="NoMob" height="30" width="12" > </td>
<td height="30" > </td>
<td class="NoMob" height="30" width="12" > </td>
</tr>
</table>
</td>
</tr>
</table>
#endWhen $layoutChoice is an Image, the code resolves as shown.
<table bgcolor="#FFFFFF" border="0" cellpadding="0" cellspacing="0" width="660"
class="w100pc" align="center" >
<tr>
<td height="30" > </td>
</tr>
<tr>
<td>
<a href="http://teradata.com/IMAGE_LINK" target="_blank"><img src="http://placehold.it/660x150"
width="660" height="150" class="w100pc"></a>
</td>
</tr>
<tr><td>I am white Background Color on image block</td></tr>
<tr>
<td class="padLR9">
<table border="0" cellpadding="0" cellspacing="0" width="100%" align="center" >
<tr>
<td class="NoMob" height="30" width="12" > </td>
<td height="30" > </td>
<td class="NoMob" height="30" width="12" > </td>
</tr>
</table>
</td>
</tr>
</table>