Como criar um template de email personalizado no Magento 2

Contextualizando

O Magento inclui um template de e-mail padrão para o corpo de cada mensagem enviada pelo sistema. Este template de conteúdo é combinado com templates de cabeçalho (header) e rodapé (footer) para criar a mensagem completa.

A customização pelo painel administrativo é a maneira mais fácil e tem precedência sobre os templates padrão do sistema e aqueles baseados em temas.

---

Carregar o Template Padrão

No painel administrador acesse: Marketing > Communications > Email Templates > Add New Template. Na seção Load default template, selecione o template que se deseja customizar no seletor Template. O código HTML e as variáveis do template aparecerão no formulário, após clicar no botão Load Template.

Após o carregamento do conteúdo do template, é possível modificar o conteúdo do template:

• Template Name: nome do template para identificação;
• Template Subject: assunto do e-mail, que pode ser usado para organizar, classificar e filtrar os templates;
• Template Content: responsável por gerar o HTML conforme a necessidade. Deve-se ter cuidado ao remover, editar e acrescentar chaves duplas;
• Template Styles: responsável por declarações de estilo CSS necessárias para formatar o template.

Para inserir uma variável, posicione o cursor no código onde a variável deve ser inserida e clique em Insert Variable. Uma tag de marcação para a variável será inserida no código. A seleção de variáveis varia por template. Variáveis de Contato da Loja (Store Contact Information) estão disponíveis em todos os templates.

É possível pré-visualizar o e-mail através do botão Preview Template.

Criar um Template de E-mail Personalizado

Criar templates como arquivos físicos no sistema de arquivos do módulo ou tema é a abordagem recomendada para desenvolvedores. Isso permite o controle de versão e facilita a implantação.

email_templates.xml

Para criar um template de e-mail é necessário criar um arquivo chamado email_templates.xml que deve seguir a estrutura de pasta \{Vendor}{Module}\etc\email_templates.xml.xml.

<?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="{template_id}"
              label="{Email Template Label}"
              file="{path}/{file_name}.html"
              type="html"
              module="{Vendor}_{Module}"
              area="{area}"/>
</config>

Atributos template

Atributo	Descrição	Obrigatório
id	Um identificador único para o template	true
label	O nome visível no painel administrador	true
file	O caminho e nome do arquivo HTML do template	true
type	Tipo de arquivo	true
module	Nome do módulo no qual será procurado o arquivo de template.	true
area	Área responsável onde será procurado o arquivo de template (frontend ou adminhtml).	true

template.html

No arquivo de template deve seguir a estrutura de pastas \{Vendor}\{Module}\view\{area}\email\{path}\{file_name}.html.

<!--@subject {Email Subject} @-->
{{template config_path="design/email/header_template"}}
    <p>{{trans "Olá, %var_name," var_name=$var_name}}</p>
    <p>{{var var_name}}</p>
{{template config_path="design/email/footer_template"}}

Disparo de E-mail

E-mails podem ser disparados utilizando a classe \Magento\Framework\Mail\Template\TransportBuilder. Esta classe pode ser instanciada através de injeção de dependência no construtor.

Para disparar um e-mail é utilizado o método getTransport() da classe de gerenciador de e-mails, mas antes é necessário configurar os dados de remetente, recebedor e configurar as variáveis do e-mail.

<?php

namespace {Vendor}\{Module}\{Directory};

use Magento\Framework\Mail\Template\TransportBuilder;
use Magento\Framework\Translate\Inline\StateInterface;

class {ClassName}
{
    private TransportBuilder $transportBuilder;
    private StateInterface $inlineTranslation;

    public function __construct(
        TransportBuilder $transportBuilder,
        StateInterface $inlineTranslation
    ) {
        $this->transportBuilder = $transportBuilder;
        $this->inlineTranslation = $inlineTranslation;
    }

    ...
    public function {methodName}() {
        $templateOptions = [
            'area' => \Magento\Framework\App\Area::AREA_FRONTEND,
            'store' => $this->storeManager->getStore()->getId()
        ];
        $templateVars = [
            '{var_name}' => '{var value}',
        ];

        $from = ['email' => $emailSender, 'name' => $senderName];
        $to = [$recipientEmail];

        $this->inlineTranslation->suspend();
        $transport = $this->transportBuilder->setTemplateIdentifier('{template_id}')
            ->setTemplateOptions($templateOptions)
            ->setTemplateVars($templateVars)
            ->setFrom($from)
            ->addTo($to)
            ->getTransport();

        $transport->sendMessage();
        $this->inlineTranslation->resume();
    }
}

Estilização e Variáveis de Template

1. {{template config_path="..."}}: Estas diretivas carregam o header, footer e outros templates de e-mail padrões.
2. <!--@subject ... @-->: Define o assunto do e-mail.
3. {{var ...}}: Permite a inserção de variáveis passadas pelo código PHP.

Estilização (CSS)

A estilização de e-mails é um desafio no frontend devido ao suporte limitado de clientes de e-mail para tags <style> ou folhas de estilo externas.

1. Estilos Inline: A maioria dos estilos de e-mail deve ser aplicada como estilos inline (no atributo style das tags HTML). O Magento utiliza a biblioteca Emogrifier para converter os estilos CSS em estilos inline.
   • A diretiva {{inlinecss file="css/email-inline.css"}} no header.html informa ao Magento quais arquivos less/css devem ser aplicados como estilos inline.
2. Tag Style: Estilos que não podem ser aplicados inline (como media queries ou pseudo-classes :hover) devem estar dentro de uma tag <style type="text/css"></style>.
   • A diretiva {{css file="css/email.css"}} no header.html compila e insere esses estilos não-inline.
3. Estilos Customizados: Estilos adicionados no campo Template Styles do painel administrador ou em blocos de comentários <!--@styles ... @--> em arquivos HTML de template são incluídos na variável {{var template_styles|raw}}.

Variáveis e Localização

• Variáveis do Sistema: São placeholders (como {{config path="..."}} ou {{var store_email}}) que são substituídos por valores de configuração da loja no momento da geração do e-mail.
• Variáveis Customizadas: Podem ser criadas e ter seus valores definidos no painel administrador em System > Other Settings > Custom Variables. Elas podem ser inseridas no template usando comandos como {{var custom_variable}} ou {{customVar code=custom_variable}}.
• Localização (Localization): Para suportar a tradução de conteúdo, todas as strings nos e-mails devem usar a diretiva {{trans ...}}. O Magento traduzirá as strings para o locale configurado para a store view que está enviando o e-mail.
  • A diretiva trans suporta múltiplos parâmetros nomeados. Exemplo: {{trans "Dear %first_name %last_name," first_name=$first_name last_name=$last_name}}.

---

Finalizando

Valores entre chaves ({test}) devem ser alterados na implementação do código.

Habilitando as alterações

Execute o comando PHP para limpar todos os caches de armazenamento em cache do processos.

php bin/magento cache:clean
php bin/magento flush

Diretórios e Arquivos

Segue a a lista de diretórios e arquivos que devem ser criados para a criaçãod e tradução em um módulo.

- app/
  - code/
    - {Vendor}/
        - {Module}/
          - etc/
            - module.xml
            - email_templates.xml
          - view/
              - {area}/
                  - email/
                  - {fileName}.html
          - registration.php
          - composer.json