Plugin extends default email template capabilities with TWIG block so you can use advanced templating techniques like conditions, loops etc. Support has also been extended to sms templates.
For example, you need a slightly different content of your email depending on the information you already know about your contact (e.g., country, gender, whatever). Instead of creating tons of very similar emails, you can create one with conditions coded inside.
Another example: you might want to include dynamic content to your email. Let's say you are implementing an Abandoned Cart feature and you want your customers to see exact content of their cart. Again, the solution might be to push cart content in JSON format to your contact via API and then iterate through the items in your template to render picture, name and price for each one.
This plugin was tested with:
There pluggin is compatible with other 5.x versions. Will not work with versions lower than 4.x.
{% TWIG_BLOCK %}
Your template TWIG goes here....
{% END_TWIG_BLOCK %}
/plugins
folder. Make sure the name of the folder containing plugin files is MauticAdvancedTemplatesBundle
(case sensitive). Rename it if it isn't, otherwise it will not be recognized.php bin/console cache:clear
).Once installed, the plugin is ready to be used (no configuration required).
Shortly saying, the text between {% TWIG_BLOCK %}
and {% END_TWIG_BLOCK %}
in your emails will be treated as a TWIG template. Please check out TWIG official documentation to familiarize yourself with syntax and capabilities.
You can also avoid lots of copy-and-paste with include()
function available in templates. Just put reusable pieces of templates into Dynamic Content entity and use it in your main email templates (see examples below).
Note: The context will be shared with included template so each variable available outside will be available in the included snippet.
The table below explains which variables are exposed to the context. Also it contains the list of extra functions and filters available. Please note that all standard library of tags\filter\functions as per official TWIG documents is available as well.
Entity | Type | Description | Example |
---|---|---|---|
lead | Variable | Holds a Lead entity (contact). You should refer fields by alias name (see example). | {{lead.firstname}} , {{lead.country}} |
json_decode | Filter | Converts string in JSON format into object. | {% set cart = lead.cart | json_decode %} In this sample we declare variable cart which will hold deserialized cart. |
Let's say you'd like to add an extra paragraph about weather in New York for people from that area:
Put the following inside your template:
{% TWIG_BLOCK %}
<p>Hi {{lead.firstname}},</p>
{% if lead.city == 'New York' %}
<p>What a great weather is in New York this week!</p>
{% endif %}
<p>Main letter content goes here</p>
{% END_TWIG_BLOCK %}
Imaging you need to remind your prospect about incomplete purchase (Abandoned Cart feature).
We assume you have an integration with your e-commerce software which pushes cart information into Mautic contact entity in the custom field cart
.
Assume cart information is JSON and has the following format:
[
{"sku": "123456", "name": "My cool product 1"},
{"sku": "8574865", "name": "My cool product 2"}
]
Thus, in order to render all items, you should code something like this:
{% TWIG_BLOCK %}
{% set cart = lead.cart | json_decode %}
Your cart:
<ul>
{% for item in cart %}
<li>Item Name: {{ item.name }}</li>
{% endfor %}
</ul>
{% END_TWIG_BLOCK %}
It might happen you need similar blocks to be included into multiple emails. In this case, it is a good idea to improve maintainability and keep common pieces in a single place. The solution this bundle offers is to leverage Dynamic Content entity and TWIG built-in function include()
.
Let's continue with the previous example but turn template for rendering a single item into a reusable snippet.
email-cart-item
.<li>Sku: {{ item.sku }}, Name: {{ item.name }}.</li>
{% TWIG_BLOCK %}
{% set cart = lead.cart | json_decode %}
Your cart:
<ul>
{% for item in cart %}
{{ include('dc:email-cart-item') }}
{% endfor %}
</ul>
{% END_TWIG_BLOCK %}
Notice prefix dc:
which instructs template resolver to look for dynamic content instance.
{% TWIG_BLOCK %}
{% set items = 'http://domain.tld/feed/' | rss %}
<ul>
{% for item in items %}
<li>
<a href=''{{ item.link }}'>{{ item.title }}</a> ({{ item.pubDate|date('m/d/Y') }})
<br />{{ item.description|raw }}
</li>
{% endfor %}
</ul>
{% END_TWIG_BLOCK %}
{% TWIG_BLOCK %}
{% set items = 'http://domain.tld/feed/' | rss('segments') %}
<ul>
{% for item in items %}
<li>
<a href=''{{ item.link }}'>{{ item.title }}</a> ({{ item.pubDate|date('m/d/Y') }})
<br />{{ item.description|raw }}
</li>
{% endfor %}
</ul>
{% END_TWIG_BLOCK %}
lead.tags
{% TWIG_BLOCK %}
{% set tags = lead.tags %}
Tags:
<ul>
{% for item in tags %}
<li>{{item}}</li>
{% endfor %}
</ul>
{% END_TWIG_BLOCK %}
Instead of pushing data to a custom field, you can specify dynamic data when using the Email Send API. When making the API call, set your POST body to a JSON object including a tokens
key like below:
{
"tokens": {
"{cart}": [{"sku":"A100","name":"Item 1"},{"sku":"Z200","name":"Item 2"}]
}
}
To render, code something like this:
{% TWIG_BLOCK %}
Your cart:
<ul>
{% for item in cart %}
<li>Item Name: {{ item.name }} (SKU: {{ item.sku }})</li>
{% endfor %}
</ul>
{% END_TWIG_BLOCK %}
Thanks goes to these wonderful people
This plug-in is licensed under MIT. This means you are free to use it even in commercial projects.
The MIT license clearly explains that there is no warranty for this free software. Please see the included LICENSE file for details.