Magento 2 email template template directives

Oct 12, 2016 Email Magento

The title is maybe a little bit confusing, better would be maybe child template directives. This post explains how to include a child template in a Magento email template. Pretty popular examples are Magento_Email::email/footer.html and Magento_Email::email/header.html.

Basic usage of a child email template

I will make a short example that will create a middle template (header and footer are already gone).

Creating a child template

Create a file view/frontend/email/middle.html in your module.

<!--@subject {{trans "Middle"}} @-->
<!--@vars {
"var store.getFrontendName()":"Store Name"
} @-->
<h1>{{trans "I'm a middle template"}}</h1>
<p>
    {{trans "Something between Header and Footer, a Hooter?"}}
</p>

Register an email template

You can register a new email template with a etc/email_templates.xml file. So let us create that file.

<?xml version="1.0"?>
<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:module:Magento_Email:etc/email_templates.xsd">
    <template id="design_email_middle_template" label="Middle" file="middle.html" type="html" module="Lesti_Example" area="frontend"/>
</config>

I hope the most things are self explaining. The id is just an identifier, the label is for the select that the admin user uses if he loads a template, the file is the path to the template file from view/frontend/email and the type can be html or text. The area could also be adminhtml instead of frontend. It that case you should also change the path to the email template to adminhtml. The module is the option group of the select for the admin user. But you have to follow the Magento naming convention Vendorname_Modulename so that Magento finds your template.

Set config path for child template

It should be possible at this point to load the template on the admin page New Template. But it isn't possible to include the template as child template. We need to add a config path to the default values. Let's add the following default values to our etc/config.xml.

<?xml version="1.0"?>
<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:module:Magento_Store:etc/config.xsd">
    <default>
        <design>
            <email>
                <middle_template>design_email_middle_template</middle_template>
            </email>
        </design>
    </default>
</config>

The value in the middle_template has to be the id from above.

Including the child template

We can include the child template with two opening curly brackets {{, the string template, whitespace, followed by the config_path parameter and two closing curly brackets }}. The child template can be used in a email template with the following code.

{{template config_path="design/email/middle_template"}}

Injecting variables into child email templates

A nice thing is that every parameter in the curly brackets will be injected into the child template. For example can we inject the string Bruce Wayne as variable batman.

{{template config_path="design/email/middle_template" batman="Bruce Wayne"}}

We can use that variable in our child template like this.

<!--@subject {{trans "Middle"}} @-->
<!--@vars {
"var store.getFrontendName()":"Store Name"
} @-->
<h1>{{trans "Secret"}}</h1>
<p>
    {{trans "The real name of Batman is %name" name=$batman}}
</p>

We can also inject more advanced variables like $customer.