- 22 Minutes to read
- Print
- DarkLight
Notation
- 22 Minutes to read
- Print
- DarkLight
Email messages are created and sent in HTML format. Different frameworks and blocks allow you to set up email templates and email messages with different layouts and styles.
The Content Management (Email) feature uses Velocity Template Language (VTL) to build the HTML code of your individual frameworks and blocks. We have added some customised information to VTL that provides more flexibility for both emails developers and email marketing managers.
When you edit an email template or email message, Mapp Engage resolves the underlying HTML and notation code of the blocks and frameworks for display.
This document explains which elements you can use to set up your frameworks and blocks. Elements and parameters that are not listed here are not yet supported for Mapp Engage blocks and frameworks.
Required parameters are marked with an asterisk.
Advantages
Our notation gives you many ways to set up blocks and frameworks.
Define where a block can be added to an email template or email message.
Control which text can be edited in a block.
Define which text formatting options are available (rich text, plain text, or styled text).
Define which images and links can be edited in a block.
Decide which editors, toolbars, and style sets are available for an email message
Provide message creators a selection of global and block level variables.
Provide message creators different layout options within blocks.
Related Topics
Notation Syntax
Unless otherwise noted, the language elements in our notation use the same syntax as VTL. For more information, see http://velocity.apache.org/engine/devel/vtl-reference-guide.html.
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. |
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. For more information, see http://velocity.apache.org/engine/devel/vtl-reference-guide.html. |
#if #elseif #else | Velocity uses #if/#elseif/#else directives to insert conditions for inserting variable content. For more information, see http://velocity.apache.org/engine/devel/vtl-reference-guide.html. 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. For more information, see http://velocity.apache.org/engine/devel/vtl-reference-guide.html. |
Notation Parameters
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"'
Notation for 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.
Parameters
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. |
Notation for 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 Anthor 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
Notation for Mobile Editing Mode 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.
Parameters
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>
Notation for Element Values
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. |
Type Parameters for Element Values in the Visual Editor
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.
|
Type Parameters for Element Values (Right Panel)
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.
|
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 food
Image 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>
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.
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.
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]
#end
In 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>
Notation for Conditional Inclusion of 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**
#end
The output of this code renders as shown:
Go South
Example 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>
#end
When $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>