Magento 2 email template layout directives

Instead of just including a block into an email template, Magento makes it possible to load a hole tree of blocks or just in other words a layout. Here a small post about the the layout directive in Magento 2 email templates with source code examples from Magento.

Layout directive

A pretty popular example can be found inside of the Magento_Sales::email/invoice_new.html template.

{{layout area="frontend" handle="sales_email_order_invoice_items" invoice=$invoice order=$order}}


The keyword area is needed to find the right XML files for the handle. But in the case from above it is superfluous, cause Magento will always set area frontend if no area is given.


The keyword handle will guide Magento to all XML files that have a path like <vendor_name>/<module_name>/view/frontend/layout/sales_email_order_invoice_items.xml for example for the example from above. All those XML files will be merged the same way as normal layouts XML files.

Layout XML

Here for example the content of sales_email_order_invoice_items.xml contained in the Magento Sales module.

<?xml version="1.0"?>
 * Copyright © 2016 Magento. All rights reserved.
 * See COPYING.txt for license details.
<page xmlns:xsi="" xsi:noNamespaceSchemaLocation="urn:magento:framework:View/Layout/etc/page_configuration.xsd" label="Email Invoice Items List" design_abstraction="custom">
    <update handle="sales_email_order_invoice_renderers"/>
    <update handle="sales_email_item_price"/>
        <block class="Magento\Sales\Block\Order\Email\Invoice\Items" name="items" template="email/invoice/items.phtml">
            <block class="Magento\Framework\View\Element\RendererList" name="" as="renderer.list"/>
            <block class="Magento\Sales\Block\Order\Invoice\Totals" name="invoice_totals" template="order/totals.phtml" cacheable="false">
                    <argument name="label_properties" xsi:type="string">colspan="2"</argument>
                <block class="Magento\Tax\Block\Sales\Order\Tax" name="tax" template="order/tax.phtml"/>
        <block class="Magento\Framework\View\Element\Template" name="" template="Magento_Theme::template.phtml"/>


We have order and invoice variables in the example above. Those variables will be accessible for the root block of the layout with magic getters like the following example from Magento\Sales\Block\Order\Email\Invoice\Items::_prepareItem.

 * Prepare item before output
 * @param \Magento\Framework\View\Element\AbstractBlock $renderer
 * @return \Magento\Sales\Block\Items\AbstractItems
protected function _prepareItem(\Magento\Framework\View\Element\AbstractBlock $renderer)
Next Previous