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:
- Mautic v4.4.0
- PHP v8.0
There pluggin is compatible with other 5.x versions. Will not work with versions lower than 4.x.
- Mautic 4.x - Release 1.2
- TWIG templates could be used in the emails. Just create an email and put your TWIG template between special tags:
{% TWIG_BLOCK %} Your template TWIG goes here.... {% END_TWIG_BLOCK %} - Reusable TWIG snippets could be loaded form Dynamic Content entities.
- TWIG extended with some useful functions and filters (see below).
- RSS support
- RSS items related to contact's segment preferences center and RSS category
- json_encode, json_decode twig implementations
- Download or clone this bundle into your Mautic
/pluginsfolder. Make sure the name of the folder containing plugin files isMauticAdvancedTemplatesBundle(case sensitive). Rename it if it isn't, otherwise it will not be recognized. - Delete your cache with the command (
php bin/console cache:clear). - In the Mautic GUI, go to the gear and then to Plugins.
- Click "Install/Upgrade Plugins".
- You should see the Advanced Templates Bundle in your list of plugins.
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 |
Let's say you'd like to add an extra paragraph about weather in New York for people from that area:
- Navigate to the Channels / Emails / New / Builder
- Open the editor for the slot you need to update (Source code mode is preferable)
- 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.
- Navigate to Components / Dynamic Content
- Create new entity with name
email-cart-item. - Put the following into Content area:
<li>Sku: {{ item.sku }}, Name: {{ item.name }}.</li>
- Update your email template with the following:
Notice prefix
{% 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 %}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 %}- Add one or more categories to item https://www.w3schools.com/xml/rss_tag_category_item.asp
- Each contact receive personalized items based on segment assignemnt.
- Matching between item categories and segment aliases
{% 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 %} {% 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 %}- Dmitry Berezovsky, Logicify (http://logicify.com/)
- Luis Rodriguez, ldrrp/MarketSmart (https://github.com/ldrrp) - Contact me on slack
Thanks goes to these wonderful people
- Leo Giovanetti, leog - Lead tags implementation
- Ben U, bobsburgers - SMS implementation
- Felipe J. L. Rita, zerodois - Mautic 4.x compatibility
- Nick Pappas, radicand - Arbritrary Send Mail API tokens
- Pablo Veintimilla, pabloveintimilla - Mautic 5 support
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.
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent