Nossa linguagem de modelo inclui placeholders e lógica pré-definidos que podem ser usados para inserir conteúdo dinâmico em seu e-mail e modificar como este conteúdo é exibido para o destinatário.
A linguagem do modelo fornece uma estrutura padronizada e comum para criar modelos eficientes e opções de design poderosos.
Dica: a Nova linguagem de modelo substitui uma antiga versão de Linguagem de modelo SendinBlue que usava diferentes sintaxes e a qual era menos robusta. Neste guia, vamos nos referir à Nova linguagem de modelo simplesmente como "a linguagem de modelo".
Antes de começar
Ao criar um e-mail único para enviar para vários destinatários ao mesmo tempo, crie seu e-mail como uma Campanha.
Ao criar um modelo para enviar como e-mail transacional ou a partir de um fluxo de trabalho de Automation, construa e salve como um Modelo.
E-mails usando a linguagem de modelo podem ser ativados para serem enviados pelos seus SendinBlue API v3 calls respectivos (para campanhas ou para e-mails transacionais), fornecendo a ID da campanha ou do modelo. Eles também podem ser enviados por meio do relé SMTP, fornecendo o cabeçalho X-SIB-API com os parâmetros corretos.
Dica: se você não utilizou nossa plataforma transacional (SMTP) antes, você deve solicitar sua ativação. Para verificar, entre em sua conta e acesse esta página. Se você não vir uma tela pedindo para ativar sua conta SMTP e se sua cota for maior que 0, então você está pronto para começar a enviar.
Visão geral
A linguagem de modelo faz uso de variáveis e filtros, os quais são substituídos por valores específicos quando o e-mail é ativado para ser enviado, além de tags, que adicionam lógica para controlar como e se o conteúdo é exibido.
Existem dois tipos de delimitadores disponíveis:
{{ ... }} - “imprime” ou apresenta o resultado de uma variável ou filtro no e-mail{% ... %} - executa a lógica de uma tag, tal como loop-for.
Dica: a linguagem de modelo pode ser aplicada para modificar diversos aspectos de seu e-mail, incluindo a linha de assunto, cabeçalho, as tags <body> dentro do HTML, e o campo de destinatário "para". O HTML é automaticamente escapado por padrão dentro dos modelos, mas este comportamento pode ser mudado usando a tag autoescape descrita em detalhes abaixo.
Variáveis
Existem três tipos de variáveis disponíveis e cada uma delas está descrita abaixo.
1. Variáveis pré-definidas
Estão disponíveis para todos os usuários SendinBlue:
|
{{ mirror }} |
insere um link para visualizar seu e-mail como uma página de internet Esta variável não é obrigatória. |
Normalmente colocada na parte de cima de um e-mail e formatada como um link deste tipo: <a href={{ mirror }}>Click here to view this message in your browser.</a> |
|
{{ unsubscribe }} |
insere um link para cancelar a inscrição a partir dos seus e-mails Qualquer e-mail não-transacional enviado via SendinBlue deve incluir um link de cancelamento de inscrição. |
Normalmente colocada no rodapé e formatada como um link deste tipo: <a href={{ unsubscribe }}>Click here to unsubscribe.</a> |
2. Atributos de contato
Este tipo de variável contém dois elementos e é estruturada da seguinte forma:
{{ contact.attributeNAME }}
Atributo = nome do seu atributo de contato SendinBlue como aparece em sua Página de contatos na SendinBlue. Atributos são sempre escritos em MAIÚSCULAS e nunca contém espaços.
P. ex.:, para inserir o telefone de um contato, onde o atributo é chamado PHONE, use: {{ contact.PHONE }}
Se o nome do atributo de contato contiver um hífen, por exemplo, CELL-PHONE, formate sua variável da seguinte forma, então: {{ contact|key:"ATTRIBUTE" }}.
p. ex.: {{ contact|key:"CELL-PHONE" }}
3. Parâmetros transacionais
Dica: ao usar o recurso "Enviar um teste" para enviar uma versão de teste do seu modelo de e-mail, as variáveis dos parâmetros transacionais não serão substituídas por conteúdo específico do destinatário neste e-mail de teste. Em vez disso, você verá as variáveis dos parâmetros transacionais exatamente como elas foram codificadas no seu modelo.
As variáveis dos parâmetros transacionais também contém dois elementos e são estruturadas da seguinte forma:
{{ params.parameterNAME }}
parameterNAME = nome do seu parâmetro transacional, formatado e escrito exatamente como transmitido via o API.
P. ex.: para inserir uma lista de produtos onde o parâmetro é chamado de PRODUCTS, use: {{ params.PRODUCTS }}.
Agora, vamos considerar um caso comum de uso: a geração de uma lista de produtos comprados por um cliente. Uma vez que o número de produtos comprados varia de acordo com o cliente, podemos combinar um for-loop com seu parâmetro transacional PRODUCTS, como neste exemplo:
<ul>
{% for product in params.products %}
<li><strong>{{ product.NAME }}</strong> - {{ product.PRICE }}</li>
{% endfor %}
</ul>
Isto produziria uma lista desordenada, em tópicos de produtos, incluindo nome e preço, como esta e a lista de cada destinatário poderia incluir um número único de produtos:
- Product 1 - $10
- Product 2 - $10
- Product 3 - $10
Dica: recomendamos evitar o uso de hífens ou de quaisquer caracteres especiais no nome de sua variável/parâmetro. Se não puder evitar, você pode usar {{ params|key:”parameter-NAME” }}. Você pode aninhar filtros diversas vezes, como em {{ params|key:”my-product”|key:”my-product-name” }}.
Matrizes
Ao usar uma matriz, você pode acessar todos os elementos individualmente. Especifique suas IDs da seguinte forma: params.parameterARRAY.ID.parameterNAME. Por exemplo: {{ params.PRODUCTS.1.NAME }}.
Tags
As tags mais comuns disponíveis para uso nos modelos são if, for e autoescape. Orientações e exemplos para cada uma delas estão incluídas abaixo.
if
A lógica poderosa oferecida pelo if permite que você adicione ou remova blocos inteiros de conteúdo dentro do seu modelo (ou modifique conteúdos dentro de um bloco). Efetivamente, isso expande a utilidade de um simples modelo para múltiplos cenários.
A tag {% if %} permite que você teste se uma expressão é verdadeira (ou se uma matriz está vazia), e modifique o conteúdo do e-mail com base no resultado. Você também pode testar por valores falsos, múltiplas condições e múltiplos ramos.
Aqui estão diversas formas comuns de se usar o if:
|
if |
Verifica se um valor é verdadeiro ou se uma matriz não está vazia |
{% if contact.ACTIVE %} --- {% if params.tutors %} {% for tutor in params.tutors %} |
|
== |
verifica se uma expressão é verdadeira |
{% if coupon == “WELCOME” %} --- {% if contact.DONOR == true %} |
|
if, in |
verifica se um valor (substring) existe dentro de uma string ou dentro de uma matriz |
{% if “@example.com" in "bob@example.com" %}
{% if "Piano" in params.types %} |
|
not |
procura por valores falsos |
{% if not user.subscribed %} |
|
and / or |
avalia múltiplas condições |
{% if temperature > 10 and temperature < 55 %}
{% if contact.LANG == “FR” and contact.COUNTRY == “Canada” %}
{% if contact.COUNTRY == “United States” or contact.COUNTRY == “Canada” %} |
|
elif, else |
avalia múltiplos ramos |
{% if contact.GENERO == "Masculino" %} Prezado Sr. {{ contact.SOBRENOME }}, --- {% if event.paid %} |
Dica: não recomendamos aplicar a tag de comparação if para variáveis que contenham valores “flutuantes” uma vez que eles podem não produzir resultados precisos (Valores flutuantes são aqueles que contêm um número fracionário ao invés de um número inteiro). No entanto, eles podem ser aplicados se o valor por passado como uma string (entre aspas, “assim”).
for
Como exploraremos mais adiante neste guia, for é bastante poderoso quando combinado com seus parâmetros transacionais. Isso permite que você realize trabalhos complexos, como inserção de listas dinâmicas de produtos.
A tag {% for %} for permite que você faça loop, ou repita sobre cada item em uma sequência. Isto é particularmente útil quando o número de itens na sequência é desconhecido no momento de criação de um modelo.
Aqui estão diversas formas comuns de se usar o for:
|
for, in |
exibe uma lista |
<ul> |
|
else |
renderiza um bloco de substituição se sua sequência estiver vazia |
<ul> Exibiria “nenhum usuário encontrado”. |
|
reversed |
inverte a ordem de impressão dos itens em sua sequência |
{% for country in params.countries reversed %} {% end for %} Exibiria uma lista de países, mas em ordem inversa, se comparada com a lista original. |
Variáveis Loop
Dentro de um bloco for-loop você também pode acessar estas variáveis especiais:
|
forloop.Counter |
Sempre define um inteiro que representa o número de vezes que o loop foi inserido. Este é um indexado único, assim, o primeiro tempo através do loop, forloop.Counter será ajustado como 1. Pode ser facilmente usado para itens numéricos em um loop: {% for product in params.products %} resultará em uma lista como esta: 1. Produto a |
|
forloop.Counter0 |
A repetição atual do loop. (0 indexado) |
|
forloop.Revcounter |
Sempre define um inteiro que representa o número de itens restantes no loop. O primeiro tempo através do loop, forloop.Revcounter será ajustado para o número total de itens na sequência que você está atravessando. A última vez no loop, forloop.revcounter será ajustada para 1. |
|
forloop.Revcounter0 |
O número de repetições a partir do final do loop (0 indexado) |
|
forloop.First |
Valor booleano configurado para Verdadeiro se esta for a primeira vez no loop. Isso é conveniente para casos especiais de primeiro item em uma lista, tal como adicionar o filtro "superior" (descrito na seção "Filtros" abaixo) apenas para o primeiro item na lista de exemplo de produtos. {% for product in params.products %} Pode apresentar uma lista de produtos como esta: 1. PRIMEIRO PRODUTO - $5.00 |
|
forloop.Last |
Valor booleano ajustado para Verdadeiro se esta for a última vez através do loop. Um uso comum para isto é colocar caracteres separadores (como , ou |) em uma lista de itens. |
|
forloop.Parentloop |
Referencia o objeto forloop para o parent loop, no caso de loops aninhados. Aqui está um exemplo: {% for country in countries %} |
Dica: nomes de variáveis de loop distinguem entre maiúsculas e minúsculas.
p. ex.: para atribuir um valor numérico (contando a partir do 1) para cada item impresso a partir da sua repetição, use {{ forloop.Counter }}:
{% for user in users %}
{{ forloop.Counter }} - {{ user.username }}
{% endfor %}
autoescape
Dica: por padrão, a SendinBlue libera o conteúdo HTML (e JS) de todas as variáveis. Isso significa que qualquer HTML dentro de uma variável será executado e impresso como texto. Por exemplo, se o conteúdo da sua variável for <h1>Meu título</h1>, então seu modelo resultaria exatamente neste texto dentro do seu e-mail: <h1>Meu título</h1>, em vez de resultar na frase “Meu título” formatada como um título H1.
A tag autoescape controla o comportamento atual do auto-escaping. Uma vez que os modelos SendinBlue realizam o autoescape do HTML por padrão, você precisará aplicar esta tag normalmente para desabilitar o auto-escaping dentro de um bloco específico. O bloco deve ser fechado com uma tag de encerramento endautoescape.
Vamos rever um exemplo comum quando desabilitar o autoescape pode ser útil. Vamos dizer que você transmita produtos em uma variável, mas que cada produto requeira formatação única.
Se autoescape for usada desta forma:
{% autoescape off %}{{ params.my_html }}{% endautoescape %}
Então o auto-escaping será desabilitado para a variável {{ params.my_html }}. Agora, se o conteúdo da sua variável for <h1>Meu título</h1>, ele será exibido como um título H1.
As únicas exceções são variáveis já marcadas como seguras do escaping, seja pelo código que faz parte da variável ou porque o filtro safe foi aplicado.
verbatim
A tag verbatim permite que você use use chaves duplas {{ like this }} em seu e-mail sem que sejam reconhecidas como um elemento de linguagem de modelo. Para escapar {{ }} e imprimir estes símbolos diretamente em seu e-mail, envolva-os nesta tag:
{% verbatim %}
{{ Print variable }}
{% endverbatim %}
Este texto aparecerá completo em seu e-mail como:
{{ Print variable }}
Filtros
Variáveis podem ser modificadas por filtros. Filtros são separados da variável por um símbolo de barra vertical (|) e pode apresentar argumentos opcionais entre parênteses. Diversos filtros podem ser encadeados. O resultado de um filtro é aplicado ao próximo.
Filtros mais usados
Alterando e formatando a capitalização das palavras
|
capfirst |
capitaliza um valor O primeiro caractere será colocado em maiúscula, todos os outros ficarão em minúsculas. |
{{ contact.NAME|capfirst }} john doe resultará em John doe. |
|
title |
retorna uma versão título do valor As palavras começarão com letras maiúsculas, todos os outros caracteres permanecendo em minúsculas. |
{{ contact.NAME|title }} john doe resultará em John Doe. |
|
upper |
converte um valor para maiúsculas |
{{ contact.NAME|upper }} john doe resultará em JOHN DOE. |
|
lower |
converte um valor para minúsculas |
{{ contact.NAME|lower }} JOHN DOE resultará em john doe. |
|
trunchars |
Trunca uma string se ela for maior que o número específico de caracteres. Strings trucadas terminarão com uma sequência de reticências (…). |
{{ value|truncatechars:9 }} If value = congratulations, it would output as congratul… |
Formatando números
|
floatformat |
Arredonda o resultado dos valores flutuantes do atributo ou parâmetro de seu contato para a casa decimal especificada. |
Se seu modelo contém {{ contact.BALANCE | floatformat: 2}} {{ contact.BALANCE | floatformat: 0}} |
Formatando datas
|
time_parse |
Converte seu formato de data (transmitido como uma string) para um formato de data padrão, o qual pode ser usado com outros filtros Transforma o formato da sua data atual como em um argumento: formata exatamente data/hora como Monday, January 2 15:04:05 -0700 MST 2006 seria exibido se este fosse o valor. Se sua string for formatada usando RFC3339, você pode usar o parser dedicado time_parse_rfc3339 sem um argumento. |
{{ params.my_date|time_parse:"15:04 02/01/2006” }} { params.my_date|time_parse:"Monday 02 January 2006” }} Observação: apenas as palavras em inglês para dia e mês são reconhecidas. |
|
date |
Imprime a data no formato especificado Observe que você deve transmitir uma data para este filtro. Você vai obter uma data a partir de uma string usando o filtro time_parse. |
{{ "14:01 01/06/2018"|time_parse:"15:04 02/01/2006"|date:"Mon Jan 2 15:04:05 2006"}} Resultará em: Fri Jun 1 14:01:00 2018 Observação: apenas as palavras em inglês para dia e mês são reconhecidas.
|
Atenção:
- Abreviações e nomes completos de dia e mês só são reconhecidos em inglês
- Se um valor não for transmitido, ele será considerado igual a 0
- O fuso-horário padrão (se não transmitido) é o UTC
- Você pode usar as palavras-chave am/pm
- As formas mais comuns de definir o fuso-horário são: palavras-chave dedicadas (MST, CET, UTC, Asian/Kolkata etc.), ou como números, +0100 ou -0100, para UTC.
Outros filtros
|
first |
retorna o primeiro "elemento" de uma sequência, um mapeamento ou uma string |
Se seu modelo contém {{params.array|first}} seu pedido da API contém: “params” : Resultará em 1 |
|
join |
retorna uma string que é a concatenação dos itens de uma sequência Por padrão, o separador entre elementos é uma string vazia. Você pode definir isso com o primeiro parâmetro opcional. |
{{ [1, 2, 3]|join }} Resultará em 123 {{ [1, 2, 3]|join('|') }} Resultará em 1|2|3 |
|
last |
retorna o último "elemento" de uma sequência, um mapeamento ou uma string |
{{ [1, 2, 3, 4]|last }} Resultará em 4 |
|
length |
retorna o número de itens de uma sequência de mapeamento ou o comprimento de uma string |
{% if users|length > 10 %} |
|
safe |
marca uma string como não requerendo escape de HTML adicional antes da apresentação
|
{{ params.htmltest | safe }} "params" :{HtmlTest: "<p>This is my test sentence.</p>"} Apresentará um parágrafo formatado no e-mail de cliente do destinatário.
{{ params.html }} Sem o filtro safe, ele exibirá a tag HTML como uma string normal no e-mail de cliente do destinatário: <p>This is my test sentence</p> |
|
slice |
extrai um pedaço de uma sequência, um mapeamento ou uma string Este filtro pode ser configurado para: A. Loop entre apenas o primeiro número "n" de elementos em uma matriz B. Loop entre elementos entre duas posições específicas ("n" e "m") em uma matriz Em ambos os casos, lembre-se que a elementos em uma matriz são atribuídos número de posição única começando com "0" como a primeira posição (eles são "0 indexado"). C. O filtro também pode ser configurado para fazer loop entre dois elementos específicos em uma matriz. |
Em cada exemplo, considere que sua matriz contém o seguinte: ["a","b","c","d","e","f","g","h",...] A. B. C. |
Teste e resolução de problemas em seu modelo
Para testar e resolver quaisquer problemas básicos em seu modelo, consulte este guia ou entre em contato com nossa equipe de atendimento ao cliente.
Dica: ao usar o recurso "Enviar um teste" para enviar uma versão de teste do seu modelo de e-mail, variáveis de atributo do contato serão substituídas com conteúdo específico para o destinatário no e-mail de teste, enquanto variáveis do parâmetro transacional aparecerão em branco.
Fontes adicionais de documentação
A linguagem de modelo usada pela SendinBlue é baseada na Linguagem de modelo Django.
Este guia engloba as estruturas e elementos mais relevantes e frequentemente usadas em linguagem de modelos. Abaixo, você encontra uma lista exaustiva de todas as tags e filtros suportados. Consulte esta documentação Django para mais detalhes.
Todas as tags reconhecidas
autoescape, comment, cycle, filter, firstof, for, if, ifchanged, now, set, spaceless, templatetag, with
Todos os filtros compatíveis
escape, safe, escapejs, add, addslashes, capfirst, center, cut, date, default, default_if_none, divisibleby, first, floatformat, get_digit, iriencode, join, last, length, length_is, linebreaks, linebreaksbr, linenumbers, ljust, lower, make_list, phone2numeric, pluralize, random, removetags, rjust, slice, stringformat, striptags, time, title, truncatechars, truncatechars_html, truncatewords, truncatewords_html, upper, urlencode, urlize, urlizetrunc, wordcount, wordwrap, yesno (Referência: https://djangobook.com/builtin-template-tags-filters/)
Observação: caso identifique um elemento desejável ainda não compatível, entre em contato com nossa equipe de atendimento ao cliente por meio do contact@sendinblue.com para fazer sua solicitação.