Utilizzo del linguaggio per modelli SendinBlue per creare modelli di email [NEW]

Quando si codificano i modelli di email in HTML per usarli sulla piattaforma SendinBlue, è possibile usare il nostro linguaggio per modelli per aggiungere funzionalità avanzate alle email transazionali o di Automation.

Il linguaggio per modelli fornisce una struttura standardizzata comune per modelli più efficaci e opzioni di design più complete.

Prima di iniziare 

Buono a sapersi: Crea e salva il tuo modello nell'area I miei modelli SMTP. I modelli che utilizzano questo linguaggio possono essere attivati per spedire tramite SendinBlue la nostra SMTP API v3 quando si fa una chiamata a v3/smtp/email fornendo il templateid o attraverso il relay SMTP fornendo l'header X-SIB-API con i parametri corretti. Attualmente non sono compatibili con la piattaforma SendinBlue Automation o con la piattaforma Campagne per l'invio di email in massa, questa funzionalità tuttavia sarà disponibile prossimamente.

Se non hai mai usato la nostra piattaforma transazionale (SMTP) prima d'ora, potresti doverne richiedere l'attivazione. Per controllare, accedi al tuo account e visita questa pagina. Se non vedi  una richiesta di attivazione del tuo account SMTP e la tua quota è superiore a 0, sei pronto per iniziare ad inviare.

Panoramica

Il linguaggio per modelli utilizza tag per controllare la logica del modello e variabili e filtri che vengono sostituiti da valori quando il modello è attivato per l'invio.

Ci sono due tipi di limitatori disponibili: {% ... %} e {{ ... }}. Il primo è usato per eseguire statement tag come i cicli for. Il secondo “stampa” o genera il risultato di una variabile o filtro nel modello.

Buono a sapersi:Il linguaggio per modelli può essere applicato per modificare numerosi elementi dell'email, inclusa la riga dell'oggetto, il preheader, all'interno dei tag HTML <body> e il campo “a” del destinatario. L'HTML fa automaticamente l'escaping come impostazione predefinita all'interno dei modelli, ma questo comportamento può essere modificato usando il tag autoescape descritto nel dettaglio in basso.

Tag  

I tag più comuni da usare nei modelli sono for, if e autoescape. Di seguito troverai le linee guida e degli esempi. 

for

Come vedremo più avanti in questa guida, for è alquanto potente se combinato con i parametri transazionali. Esso consente di eseguire facilmente operazioni complesse, come ad esempio inserire liste dinamiche di prodotti.

Il tag {% for %} consente di eseguire un ciclo, o ripetere, su ciascun elemento di una sequenza. Questo risulta particolarmente utile quando il numero di elementi della sequenza non è noto al momento della creazione del modello.

Ecco alcuni dei modi più comuni di usare for:

for, in

visualizzare una lista

<ul>
   {% for user in params.USERS %}
       <li>{{ user.username }}</li>
   {% endfor %}
</ul>

else

rendere un blocco sostitutivo se la sequenza è vuota

<ul>
   {% for user in params.USERS %}
       <li>{{ user.username }}</li>
   {% else %}
       <li><em>no user found</em></li>
   {% endfor %}
</ul>

Visualizzerebbe “no user found”.

reversed

invertire l'ordine di stampa di elementi nella sequenza

{% for country in params.countries reversed %} {% end for %}

Visualizzerebbe una lista di paesi, ma in ordine inverso rispetto alla lista originale.

 

Variabili del ciclo

All'interno di un blocco forloop puoi accedere a queste variabili speciali:

forloop.Counter

Impostare sempre un numero intero che rappresenta il numero di volte che è stato iniziato il ciclo. Questo è indicizzato su uno, pertanto la prima volta che si avvia il ciclo, il contatore forloop.Counter sarà impostato su 1.

forloop.Counter0

La ripetizione corrente del ciclo. (0 indicizzate)

forloop.Revcounter

Impostare sempre un numero intero che rappresenta il numero di elementi rimasti nel ciclo. La prima volta nel ciclo, forloop.Revcounter sarà impostato sul numero totale degli elementi della sequenza che stai attraversando. Arrivati all'ultima volta all'interno del ciclo, forloop.revcounter sarà impostato su 1.

forloop.Revcounter0

Il numero di ripetizioni dalla fine del ciclo (0 indicizzate)

forloop.First

Valore booleano impostato su True se è la prima volta che passa nel ciclo. È utile per applicare un carattere speciale al primo elemento di una lista. 

forloop.Last

Valore booleano impostato su True se è l'ultima volta che passa nel ciclo. Si usa comunemente per inserire caratteri di separazione (come , o |) in una lista di elementi.

forloop.Parentloop

Riferimenti per l'oggetto forloop per il ciclo genitore in caso di cicli  nidificati. Ecco un esempio:

{% for country in countries %}
<table>
{% for city in country.city_list %}
<tr>
<td>Country #{{ forloop.Parentloop.counter }}</td>
<td>City #{{ forloop.Counter }}</td>
<td>{{ city }}</td>
</tr>
{% endfor %}
</table>
{% endfor %}

 

Buono a sapersi:Nei nomi delle variabili di ciclo viene fatta distinzione fra maiuscole e minuscole.

Esempio: per assegnare un valore numerico (contando da 1) a ogni elemento stampato dalla ripetizione, usa {{ forloop.Counter }}:

{% for user in users %}
   {{ forloop.Counter }} - {{ user.username }}
{% endfor %}

if

La potente logica offerta da if consente di aggiungere o rimuovere interi blocchi di contenuto all'interno del modello (o di modificare il contenuto all'interno di un blocco). Ciò estende efficacemente l'utilità di un singolo modello a scenari multipli.

Il tag {% if %} consente di testare se un'espressione è vera (o se una matrice è vuota) e di modificare il contenuto dell'email in base al risultato. Inoltre puoi controllare valori falsi, condizioni multiple e rami multipli.

Ecco alcuni degli esempi più comuni per usare if:

if

Controlla se un valore è vero o se una matrice non è vuota 

{% if contact.SUBSCRIBED %}
<b>Thank you for your support!</b>
{% endif %}

 

{% if params.users %}
<ul>
{% for user in params.users %}
<li>{{ user.username }}</li>
{% endfor %}
</ul>
{% endif %}

==

controlla se un'espressione è vera 

{% if coupon == “WELCOME” %}
<p>Welcome to our list! Here’s your first coupon: WELCOME25</p>
{% endif %} 

if, in

controlla se un valore (sottostringa) esiste all'interno di una stringa o se una variabile esiste all'interno di una matrice 

{% if “@example.com" in "bob@example.com" %}
This appears since "@example.com" is a substring of "bob@example.com"
{% endif %}

 

{% if "Piano" in params.types %}
Be careful! There are heavy items in your order. You must be present to receive this delivery.
{% endif %}

not

controlla i valori falsi

{% if not user.subscribed %}
   <p>You are not subscribed to our secret sale alerts. Sign up here.</p>
{% endif %}

and / or

valuta condizioni multiple 

{% if temperature > 10 and temperature < 55 %}
   <p>Brr. It’s cold! Here’s a coupon for 20% off of any hot beverage, today only.</p>
{% endif %}

 

{% if contact.LANG == “FR” and contact.COUNTRY == “Canada” %}
{% endif %}

 

{% if contact.COUNTRY == “United States” or contact.COUNTRY == “Canada” %}
{% endif %}

elif, else

valuta rami multipli 

{% if event.paid %}
    Your spot is reserved. Thanks for submitting your payment.
{% elif event.registered %}
    Your spot is reserved but will be released without payment by January 2.
{% else %}
    There’s still time to sign up! Click here.
{% endif %}

 

autoescape

Buono a sapersi: Per impostazione predefinita SendinBlue fa l'escaping del contenuto HTML (e JS) di tutte le variabili. Ciò significa che il contenuto HTML passato all'interno di una variabile sarà processato e stampato come testo. Per esempio, se il contenuto della variabile è <h1>My title</h1>, il modello produrrà esattamente questo testo all'interno della tua email: <h1>My title</h1> anziché produrre la frase “My title” formattata come titolo H1.

Il tag autoescape controlla il comportamento auto-escaping attuale. Dato che i modelli SendinBlue fanno autoescaping dell'HTML per impostazione predefinita, solitamente dovrai applicare questo tag per disattivare l'autoescaping all'interno di un dato blocco. Il blocco dovrà essere chiuso da un tag di chiusura endautoescape.

Vedremo un esempio comune in cui è utile disattivare autoescape. Diciamo che passi i prodotti in una variabile, ma ogni prodotto richiede una formattazione unica.

Se autoescape è usato così:

{% autoescape off %}{{ params.my_html }}{% endautoescape %}

L'autoescaping sarà disattivato per la variabile {{ params.my_html }}. Se il contenuto della variabile è <h1>My title</h1>, sarà visualizzato come titolo H1. 

Le sole eccezioni sono le variabili già evidenziate come escluse dall'escaping, a causa del codice presente nella variabile o perché è stato applicato il filtro safe.

Variabili

Ci sono tre tipi di variabili disponibili e sono tutti descritti di seguito.

Buono a sapersi: Quando usi la funzionalità "Invia una prova" per inviare una versione di prova del tuo modello di email, le variabili non saranno sostituite con un contenuto specifico per il destinatario nell'email di prova. Vedrai invece le variabili esattamente così come sono codificate nel modello. 

1. Variabili predefinite  

Sono disponibili per tutti gli utenti SendinBlue:

{{ mirror }}

inserisce un link per visualizzare l'email come pagina web

Questa variabile non è obbligatoria.

Di solito si trova in alto nell'email ed è formattata come il link seguente:

<a href={{ mirror }}>Click here to view this message in your browser.</a>

{{ unsubscribe }}

inserisce un link per disiscriversi dalle tue email

Tutte le email non transazionali inviate tramite SendinBlue devono includere un link di disiscrizione.

Di solito si trova nel footer ed è formattata come il link seguente:

<a href={{ unsubscribe }}>Click here to unsubscribe.</a>

 

2. Attributi di contatto   

Questo tipo di variabile contiene due elementi ed è strutturata come segue:

{{ contact.attributeNAME }}

Attributo = il nome dell'attributo di contatto SendinBlue così come appare nella tua pagina Contatti su SendinBlue. Gli attributi sono sempre scritti in maiuscolo e non contengono spazi.

es., per inserire il numero di telefono di un contatto e l'attributo si chiama PHONE, usa: {{ contact.PHONE }}

Se il nome dell'attributo di contatto contiene un trattino, come in CELL-PHONE, formatta la variabile come segue: {{ contact|key:"ATTRIBUTE" }}.  

es. {{ contact|key:"CELL-PHONE" }}

3. Parametri transazionali

Anche le variabili dei parametri transazionali contengono due elementi e sono strutturate come segue:

{{ params.parameterNAME }}

parameterNAME = il nome del parametro transazionale, formattato e scritto esattamente così come viene passato attraverso l'API.

es., per inserire una lista di prodotti dove il parametro si chiama PRODUCTS, usa: {{ params.PRODUCTS }}.

Consideriamo ora un caso di uso comune: la generazione di una lista di prodotti acquistati da un cliente. Dato che il numero di prodotti acquistati varia in base al cliente, possiamo combinare un ciclo for con il parametro transazionale PRODUCTS come nell'esempio:  

<ul> 
{% for product in params.products %}

   <li><strong>{{ product.NAME }}</strong> - {{ product.PRICE }}</li>
{% endfor %}
</ul>

Ciò produrrà un elenco di prodotti puntato non ordinato che includerà il nome del prodotto e il prezzo come qui e la lista di ogni destinatario comprenderà un numero unico di prodotti:   

  • Prodotto 1 - $10
  • Prodotto 2 - $10
  • Prodotto 3 - $10

Buono a sapersi: Raccomandiamo di evitare l'uso di trattini o di caratteri speciali nei nomi delle variabili/parametri. Se non hai altra scelta puoi usare {{ params|key:”parameter-NAME” }}. Puoi annidare il filtro più volte, come in {{ params|key:”my-product”|key:”my-product-name” }}.

Matrici

Quando usi una matrice, puoi accedere a tutti gli elementi individuali. Specifica il loro ID come segue: params.parameterARRAY.ID.parameterNAME. For example: {{ params.PRODUCTS.1.NAME }}.

Filtri

Le variabili possono essere modificate da filtri. I filtri sono separati dalla variabile da un simbolo ad asta (|) e possono avere argomenti opzionali tra parentesi. Si possono concatenare più filtri. Il risultato di un filtro si applica al successivo.

I filtri più usati 

Modifica e formattazione di lettere maiuscole/minuscole 

capfirst

rende maiuscolo un valore

La prima lettera sarà in maiuscolo, tutte le altre in minuscolo.

{{ contact.NAME|capfirst }}

john doe produrrà John doe.

title

ritorna alla versione titolo del valore

Le parole inizieranno con una lettera maiuscola, tutte le altre lettere saranno in minuscolo.

{{ contact.NAME|title }}

john doe produrrà John Doe.

upper

converte un valore in maiuscolo 

{{ contact.NAME|upper }}

john doe produrrà JOHN DOE.

lower

converte un valore in minuscolo

{{ contact.NAME|lower }}

JOHN DOE produrrà john doe.

trunchars

Tronca una stringa se è più lunga del numero di caratteri specificato. Le stringhe trocante termineranno con una sequenza ellittica traducibile (…).

{{ value|truncatechars:9 }}

Se value = congratulazioni, produrrà congratul…

Formattazione di numeri

floatformat

arrotonda un numero a un dato livello di precisione usando la logica comune  

{{ 42.55|floatformat:0 }}

Produrrà 43

{{ 42.55|floatformat:1 }}

Produrrà 42.5

Formattazione di date

time_parse

Converte il formato della data (passata come stringa) in un formato data standard che può essere usato con altri filtri

Passa il formato data attuale come argomento: formatta la data/ora esatta come sarebbe visualizzato Lunedì, 2 gennaio 15:04:05 -0700 MST 2006 se questo fosse il valore.

Se la stringa è formattata usando RFC3339, puoi usare il parser apposito time_parse_rfc3339 senza argomenti.

{{ params.my_date|time_parse:"15:04 02/01/2006” }}

{ params.my_date|time_parse:"Monday 02 January 2006” }}

Nota: sono riconosciute solo le parole inglesi per giorno (day) e mese (month).

date

Stampa la data in un formato specificato
Per definire il tuo formato, scrivi come sarebbe visualizzata l'ora di riferimento per Lun 2 gen 15:04:05 -0700 MST 2006 con la tua formattazione.

Nota che devi passare una data per questo filtro.

Otterrai una data da una stringa usando il filtro time_parse.

{{ "14:01 01/06/2018"|time_parse:"15:04 02/01/2006"|date:"Mon Jan 2 15:04:05 2006"}}

Produrrà:

Fri Jun 1 14:01:00 2018

Nota: sono riconosciute solo le parole inglesi per giorno (day) e mese (month).

 

Nota bene:

  • Le abbreviazioni e i nomi completi per giorno e mese sono supportati solo in inglese
  • Se un valore non viene passato, sarà considerato come 0
  • Il fuso orario predefinito (se non passato) è UTC
  • Puoi usare le parole chiave am/pm 
  • I modi più comuni per definire un fuso orario sono: parole chiave apposite (MST, CET, UTC, Asia/Calcutta ecc.), o valori numerici, +0100 o -0100, per UTC.

Altri filtri

first

restituisce il primo "elemento" di una sequenza, una mappatura o una stringa

{{ [1, 2, 3, 4]|first }}

Produrrà 1

join

restituisce una stringa che è la concatenazione di elementi di una sequenza 

Per impostazione predefinita, il separatore di elementi è una stringa vuota. Puoi definirlo con il primo parametro opzionale.

{{ [1, 2, 3]|join }}

Produrrà 123  


{{ [1, 2, 3]|join('|') }}

Produrrà 1|2|3

last

restituisce l'ultimo "elemento" di una sequenza, una mappatura, o una stringa

{{ [1, 2, 3, 4]|last }}

Produrrà 4

length

restituisce il numero di elementi di una sequenza o mappatura o la lunghezza di una stringa 

{% if users|length > 10 %}
   ...
{% endif %}

slice

estrae un pezzo di sequenza, una mappatura o una stringa 

{% for i in [1, 2, 3, 4, 5]|slice(1, 2) %}
{% endfor %}

Si ripeterà per 2 e 3

{{ '12345'|slice(1, 2) }}
Produrrà 23

Documentazione supplementare

Il linguaggio per modelli usato da SendinBlue si basa sul linguaggio per modelli Django.

Questa guida tratta la struttura e gli elementi del linguaggio per modelli più importanti e usati  più di frequente. Di seguito troverai una lista esaustiva di tutti i tag e i filtri supportati. Consulta la documentazione Django per ulteriori dettagli.

Tutti i tag supportati 

autoescape, comment, cycle, filter, firstof, for, if, ifchanged, now, set, spaceless, templatetag, with

Tutti i filtri supportati

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

Da notare: Se identifichi un elemento che ti sarebbe utile e che non è ancora supportato, contatta il nostro team dell'assistenza clienti all'indirizzo contact@sendinblue.com per richiederlo.