Linguagem de templates Temple

O Temple é a pequena linguagem de templates do Emailit para linhas de assunto, HTML e texto simples. Ele não é Liquid nem Handlebars: tem suporte a variáveis, caminhos aninhados, valores padrão e blocos if/else, e nada mais. Os templates guardam os placeholders como você os escreve, e o Temple os preenche quando um e-mail é enviado pela API ou por uma automação.

A sintaxe em resumo

{{first_name}}                      Variable
{{user.name}}   {{items.0.sku}}     Nested property and list item
{{first_name|"there"}}              Default when the value is missing or null
{{#if plan}} … {{else}} … {{/if}}   Conditional, with an optional else

O Temple não tem loops, filtros, helpers, partials nem funções personalizadas. O único operador é o | de valor padrão.

Variáveis

Hello {{first_name}}

• O Temple substitui {{first_name}} pelo valor de first_name que você fornece. Os espaços dentro das chaves são ignorados, então {{ first_name }} também funciona.
• Os nomes diferenciam maiúsculas de minúsculas: {{First_Name}} não corresponde a first_name.
• Um valor ausente ou null vira uma string vazia. Os placeholders desconhecidos desaparecem em vez de aparecer no e-mail.
• Os valores são convertidos em texto. Números e booleanos aparecem como foram escritos (42, true), e as listas são unidas com vírgulas (["a","b"] vira a,b). Um objeto é renderizado como [object Object], então aponte para um dos campos dele.

Propriedades aninhadas e itens de lista

Use pontos para acessar objetos e números para posições em listas, começando em 0:

{{user.name}}
{{order.items.0.sku}}

{
  "user": { "name": "Ada" },
  "order": { "items": [{ "sku": "A1" }, { "sku": "B7" }] }
}

Como o ponto separa os segmentos do caminho, não é possível acessar uma chave que contenha um ponto. Use chaves sem pontos.

Valores padrão

Adicione | e um valor alternativo para usar quando o valor estiver ausente ou for null:

Hi {{first_name|"there"}},
Your company: {{company|'Not set'}}

Aspas duplas, aspas simples ou nenhuma aspa funcionam. O valor padrão não é usado para uma string vazia, 0 ou false; esses valores são renderizados como vazio, 0 e false. Um valor padrão não pode conter o caractere }.

Condicionais

{{#if plan}}
Thanks for being on the {{plan}} plan.
{{else}}
You're on the free plan. Upgrade anytime from your dashboard.
{{/if}}

• {{else}} é opcional.
• Uma condição é falsa quando o valor está ausente ou é null, false, 0, uma string vazia "" ou uma lista vazia []. Qualquer outro valor é verdadeiro, incluindo a string "0", a string "false" e um objeto vazio.
• Uma condição é um único caminho de variável, como plan ou user.is_admin. Não existem ==, and, or, not nem unless. Para criar uma ramificação com base em um valor, calcule um booleano no seu código e passe-o, por exemplo "is_pro": true.
• Escreva {{else}} e {{/if}} exatamente como mostrado, sem espaços dentro das chaves.
• O Temple processa primeiro as condicionais e depois as variáveis.

Escape e caracteres especiais

Os valores não passam por escape de HTML. O Temple insere os valores exatamente como você os passa. Um valor como Tom & Jerry ou <b>Ada</b> entra no HTML sem alterações, então faça o escape de qualquer texto fornecido por usuários no seu código antes de passá-lo. As mesmas variáveis preenchem o assunto, o HTML e o texto, então um valor com escape como Tom & Jerry também aparece assim no assunto e no texto. Se isso importar, passe uma variável separada, com escape, para o HTML.

Isso também significa que você pode passar HTML pronto, como uma tabela com as linhas de um pedido renderizada pelo seu código, como uma única variável.

Não existe sintaxe de escape para chaves duplas. O Temple trata qualquer coisa entre {{ e }} como um placeholder e a remove se não houver valor. As chaves simples, como as do CSS, não são afetadas. Os valores são inseridos uma vez e não são interpretados de novo, então, para mostrar chaves duplas literais, coloque-as em uma variável:

{
  "html": "<p>Write {{example}} in your template to show the first name.</p>",
  "variables": { "example": "{{first_name}}" }
}

Onde o Temple é executado

E-mails da API

Passe o alias de um template ou um ID tem_ e um objeto variables. Os campos que você envia na requisição (subject, html, text) substituem os do template, e depois o Temple renderiza o assunto, o HTML e o texto.

{
  "from": "Acme <hello@acme.com>",
  "to": "ada@example.com",
  "template": "welcome-email",
  "variables": {
    "first_name": "Ada",
    "plan": "Pro",
    "activation_url": "https://acme.com/activate?token=8f3k2",
    "cf": { "company": "Analytical Engines Ltd" }
  }
}

Os editores do painel inserem {{cf.<key>}} para os campos personalizados dos contatos. Nos envios pela API, nada é buscado nos seus contatos, então forneça você mesmo esses valores em cf, como no exemplo. O mesmo vale para {{unsubscribe_url}}: passe o seu próprio link de descadastro se o template o usar.

Você também pode enviar conteúdo inline com variables e sem template. Consulte Enviar um e-mail.

E-mails de automações

Em todos os envios, a etapa Send email renderiza o assunto, o HTML e o texto com o Temple, venham eles do template ou de substituições definidas na etapa.

As automações de contatos colocam os campos do contato no nível superior, então estes funcionam:

• {{email}}, {{first_name}} e {{last_name}}
• {{custom_fields.<key>}} para os campos personalizados, por exemplo {{custom_fields.plan}}. A forma das campanhas, {{cf.plan}}, não funciona aqui.
• {{contact.*}}, o mesmo contato como objeto, por exemplo {{contact.first_name}}

Todas as automações também recebem {{payload.*}}, os dados do evento que disparou a execução, e {{meta.*}}, os metadados da execução. As automações de e-mail e de evento não têm um contato no nível superior, então use {{payload.*}} ou defina o destinatário e o assunto na etapa.

{{unsubscribe_url}} não é preenchido nos e-mails de automações.

Campanhas

As campanhas e os envios de teste de campanhas não usam o Temple. Eles substituem apenas estas tags de mesclagem pelos dados do destinatário:

• {{first_name}}, {{last_name}} e {{email}}
• {{unsubscribe_url}}, o link de descadastro do destinatário
• {{cf.<key>}}, um campo personalizado do contato, por exemplo {{cf.plan}}

Escreva-as sem espaços dentro das chaves. Os nomes das tags não diferenciam maiúsculas de minúsculas, mas as chaves dos campos personalizados precisam corresponder exatamente. Os valores padrão (|) e os blocos {{#if}} não são processados, e qualquer outro texto {{…}} fica no e-mail como foi escrito. Consulte Tags de mesclagem de campanhas.

SMTP

O SMTP relay aceita uma mensagem pronta. Não há busca de template nem passagem pelo Temple, então monte o HTML final antes de enviar, ou use a API ou uma automação se precisar de variáveis.

Conferir os templates antes de publicar

O Emailit não rejeita um template nem um envio por causa de sintaxe do Temple quebrada. Os erros normalmente aparecem como texto faltando ou chaves sobrando no e-mail entregue. Antes de publicar:

• Confira se cada {{#if …}} tem um {{/if}} correspondente e se cada {{ tem um }} de fechamento.
• Envie a versão em rascunho para você mesmo pelo ID tem_ dela, com variables realistas, incluindo valores ausentes e vazios, para ver os dois lados de cada condição. Consulte Versões de templates.

Exemplos

Uma saudação com valor alternativo:

Hi {{first_name|"there"}},

Um bloco que depende do plano:

{{#if plan}}
Your plan: {{plan}}
{{else}}
Upgrade anytime from your dashboard.
{{/if}}

Um assunto com um valor aninhado:

Order {{order.number}} has shipped, {{user.first_name|"friend"}}

Veja também

• Enviar com um template
• Criar e editar templates
• Tags de mesclagem de campanhas
• Etapas de automação