Get to Know Guide Template Language
Learning Objectives
After completing this unit, you'll be able to:
- Introduce the fundamentals and syntax for Guide Template Language (GTL).
- Create data-driven message templates using data sources, templates, and tags.
- Work with GTL examples and best practices.
Guide Template Language is Marketing Cloud Engagement’s newest programmatic language, and it’s customized to work within messages to provide personalized content. GTL takes data from specified data sources and applies it within templates used to render the content. Those templates contain tags that determine where to insert data.
If you’ve used templating libraries like Mustache.js or Handlebars.js, GTL will look familiar. In fact, GTL supports templates from those sources, but Marketing Cloud Engagement provides the data instead of scripts.
GTL Syntax
Let’s get started by looking at some tags. Some of the tags are so simple that we just call them simple tags. Want to include someone’s first name in an email? Use this tag.
{{FirstName}}
You can also add prefixes and suffixes to a tag to identify what kind of tag you’re putting in a template.
Prefixes include these characters.
| Tag Type |
Prefix Symbol |
| Section Tag |
# |
| Function or Set Delimiter Tag |
= |
| Inverted Section Tag |
^ |
| Comment Tag |
! |
| Partial Tag |
> |
| Block Helper |
#= |
| Data |
{ |
Suffixes include these characters.
| Tag Type |
Suffix Symbol |
| Close Data Tag |
} |
| Close Set Delimiter Tag |
= |
You can also create block tags in GTL. This example shows a block tag nested inside another block tag, along with some examples of simple tags that bring data in from a data extension containing product information.
{{#Products}} <strong>Product Name:</strong> {{Product_Name}}<br /> <strong>SKU:</strong>{{sku}}<br /> <img src="{{Thumbnail_URL}}" /><br /> {{#Product_Ratings}} <strong>Most Recent Review: </strong>{{Last_Review_Text}}<br /> <strong># of Ratings: </strong>{{Number_of_Ratings}}<br /> <strong>Ave Rating: </strong>{{Average_Rating}}<br /><br /><br /> {{/Product_Ratings}}
{{/Products}}
Notice how the hashtags at the beginning of the block tags indicate section tags. Use block tags to create and use data sources, access helper functions, and provide template logic.
Speaking of helper functions, GTL handles common functions like Each, If, Switch, Unless, and With. For example, this If function provides text about whether an order is ready or not.
{{#if order=="1234"}}Your order is ready{{.else}}Your order is not ready{{/if}}
Blocks and Slots
GTL templates use blocks and slots to organize data for messages. This example shows a sample HTML email message.
<html>
<body>
<style type="text/css">
.tftable {font-size:12px;color:#333333;width:100%;border-width: 1px;border-color: #ebab3a;border-collapse: collapse;}
.tftable th {font-size:12px;background-color:#e6983b;border-width: 1px;padding: 8px;border-style: solid;border-color: #ebab3a;text-align:left;}
.tftable tr {background-color:#ffffff;}
.tftable td {font-size:12px;border-width: 1px;padding: 8px;border-style: solid;border-color: #ebab3a;}
</style>
<table class="tftable" border="1">
<tr>
<th colspan="2">TITLE OF MESSAGE</th>
</tr>
<tr>
<td rowspan="3">
{{.slot slot1}}
{{.block mytext+imageblock textimage}}Block Goes Here
<br />
{{.default}}I am a Text and Image Block - Hello World!{{/default}}
{{/block}}
{{/slot}}
</td>
<td>
{{.slot slot2}}
{{.default}}This slot is available for anything{{/default}}
{{/slot}}
</td>
</tr>
<tr>
<td>
{{.slot slot3}}
{{.block mytextblock text}}Block Goes Here
<br />
{{.default}}I am a Text only Block - Hello World!{{/default}}
{{/block}}
{{/slot}}
</td>
</tr>
<tr>
<td>
{{.slot slot4}}
{{.block myimageblock image}}Block Goes Here
<br />
{{.default}}I am an Image only Block - Hello World!{{/default}}
{{/block}}
{{/slot}}
</td>
</tr>
</table>
</body>
</html>
The rendered template looks like this.
Blocks and slots can contain meta information, default content, and content to render. Blocks also contain JSON objects used to provide data during rendering.
Dataobject and Datasource
All the data you’re pulling into your template has to come from somewhere, right? To replace tags with personalized data within a template, GTL draws information from either a dataobject or a datasource. So what’s the difference?
- Dataobjects must be declared before referencing them, but you can use that information anywhere within your template.
- Datasources appear within tags in the template and provide data for only that scope.
Dataobjects
Dataobjects must include a name, a type value (inline, variable, or list), and a maxRows integer value. This example includes a dataobject that places product information inside a personalized template.
{{.dataobject RecProds type=list maxRows = 2}}
{{.data}} { "target" : "name:Products", "filter" : "Product_Category == Category_Preference" } {{/data}}
{{/dataobject}}
{{!if data is found we'll execute the code in the Sections tag}}
{{#RecProds}}
{{First_Name}} {{Last_Name}}, based on your preference of {{Category_Preference}}, we suggest the following products… SKU: {{sku}} Product Name: {{Product_Name}} <img src="{{Thumbnail_URL}}" alt="" /> {{/RecProds}}
{{!if no data is found we'll execute the code in the Inverted Sections tag}}
{{^RecProds}}
{{First_Name}} {{Last_Name}}, we do not have any product recommendations for you at this time. {{/RecProds}}
Datasources
Like dataobjects, datasources require a name and maxRows value. You can also specify a Boolean global value that sets values back to the parent context after the block processes. You can also specify five types of blocks.
- query
- inline
- list
- variable
- nested
Datasources allow for nested information. This example shows information stored in an AMPscript variable (that’s right, GTL accepts information from AMPscript and SSJS!) and uses it to populate subscriber information.
%%[ var @Json set @Json = ' [{ "emailaddress": "john@example.com", "Region": "West", "State": "California", "City": "San Francisco", "PhoneNumbers": [{ "Type": "Home", "Number": "555-555-1111" }, { "Type": "Cell", "Number": "555-555-2222" }]}, { "emailaddress": "carla@example.com", "Region": "Central", "State": "Indiana", "City": "Indianapolis", "PhoneNumbers": [{ "Type": "Home", "Number": "555-555-4444" }, { "Type": "Cell", "Number": "555-555-5555" }]}]' ]%%
{{.datasource JSONVar type=variable maxRows = 20}}
{{.data}}
{ "target" : "@Json" }
{{/data}}
Email Address: {{emailaddress}}
Region: {{region}}
State: {{STATE}}
City: {{JSONVar.City}}
{{.datasource JSONPhone type=nested maxRows = 10}}
{{.data}}
{ "target" : "JsonVar.PhoneNumbers" }
{{/data}}
{{JSONPhone.Type}}: {{JSONPhone.Number}}
{{/datasource}}
{{/datasource}}
To test this example, change the email addresses to real addresses to pass validation.
Partials
If you need to pull information in from your Portfolio or Content Builder, partials give you a handy shortcut. Just specify a key, ID, or name value inside a {{>}} tag, and you're ready to go. This tag pulls in a content area specified by a key.
{{>id:purchased_shoes refresh}}
The optional refresh tag forces the content to refresh at send time.
This example pulls in information from a variable.
{{>var:contentField}}
And this example syndicates content from a website.
{{>get:http://www.example.com}}
Now that you know more about Marketing Cloud Engagement’s programmatic languages, let’s cover how and when to use them.