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

Il nostro linguaggio per modelli include segnaposto predefiniti e una logica che può essere usata per inserire contenuti dinamici nelle email e modificare il modo in cui sono visualizzati i contenuti dal destinatario. 

Il linguaggio per modelli fornisce una struttura comune e standardizzata per creare modelli efficaci e opzioni di progettazione elevate.

Buono a sapersi: Il nuovo linguaggio per modelli sostituisce una versione precedente del linguaggio per modelli di SendinBlue, che usava una sintassi diversa ed era meno solido. In questa guida, ci riferiremo al nuovo linguaggio per modelli semplicemente con l'espressione "linguaggio per modelli". 

Prima di iniziare 

Quando si crea un'email singola da inviare a molti destinatari in una sola volta, l'email viene creata come Campagna.

Quando si crea un modello da inviare come email transazionale o in un workflow Automation, esso va progettato e salvato come modello.

L'invio delle email che usano il linguaggio per modelli può essere attivato attraverso le rispettive chiamate SendinBlue API v3 (per le campagne) o (per le email transazionali) indicando l'ID della campagna o l'ID del modello. Inoltre possono essere inviate attraverso l'SMTP relay indicando l'header X-SIB-API con i parametri corretti.

Buono a sapersi: Se non hai mai usato la nostra piattaforma transazionale (SMTP) prima, è possibile che tu debba richiederne 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 a inviare.

Panoramica

Il linguaggio per modelli utilizza variabili e filtri che vengono sostituiti da valori specifici quando l'email è attivata per l'invio e tag che aggiungono logica per controllare come e se il contenuto è visualizzato.

Ci sono due tipi di delimitatori disponibili:

{{ ... }} - “stampa” o trasferisce il risultato di una variabile o filtro nell'email
{% ... %} - esegue la logica di un tag, come i cicli for.

Buono a sapersi: Il linguaggio per modelli può essere applicato per modificare vari aspetti dell'email, quali la riga dell'oggetto, il preheader, all'interno dei tag HTML <body> e il campo “a” del destinatario. L'HTML è sottoposto automaticamente all'escape come modalità predefinita all'interno dei modelli, ma questo comportamento può essere modificato usando il tag autoescape descritto nei dettagli in seguito.

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 }}.

 

Tag  

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

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.ACTIVE %}
Congrats! You achieved your goal this month.
{% endif %}
{% endif %}

---

{% if params.tutors %}

{% for tutor in params.tutors %}
The following tutors are available to help you:
<ol>
<li>{{ tutor.name }}</li>
{% endfor %}
</ol>
{% endif %}

==

controlla se un'espressione è vera 

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

---

{% if contact.DONOR == true %}
<b>Thank you for your support!</b>
{% 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 contact.GENERE== "Maschile" %} Gentile Sig. {{ contact.COGNOME }},
{% elif contact.GENERE == "Femminile" %} 
Gentile Sig.ra {{ contact.COGNOME }},
{% else %} Buongiorno, {% endif %}

---

{% 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 %}

 

Buono a sapersi: Non raccomandiamo di applicare dei confronti utilizzando il tag if alle variabili che contengono valori di tipo “float” perché potrebbero produrre risultati non precisi (i valori float sono quelli che contengono un valore frazionario anziché un numero intero). Tuttavia, questi confronti possono essere utilizzati se il valore è una stringa di caratteri (tra virgolette “come questa”).

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.

Può essere usato facilmente per enumerare elementi in un ciclo:

{% for product in params.products %}
{{ forloop.Counter }}. {{ product.name }} {% endfor %}

produrrà una lista come questa:

1. Prodotto a
2. Prodotto b
3. Prodotto c, ecc.

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 configurato come True se questa è la prima volta che appare nel ciclo.

Adatto per applicare un formato particolare al primo elemento di una lista, come ad esempio per applicare un filtro “upper” (descritto nella sezione “Filtri” più oltre) solo al primo elemento di una lista di prodotti.

{% for product in params.products %}
{{ forloop.Counter }}. {% if forloop.First %} {{ product.name|upper }} {% else %} {{ product.name }} {% endif %} - {{ product.price }}
{% endfor %}

Può generare una lista di prodotti come questa:

1. PRIMO PRODOTTO - € 5,00
2. Secondo prodotto - € 2,00
3. Terzo prodotto - € 4,00

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 %}

  

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.

verbatim

Il tag verbatim ti consente di usare la doppia parentesi graffa {{ come questa }} nella tua email senza che venga riconosciuta come elemento del linguaggio per modelli. Per eseguire l'escape {{ }} e stampare questi simboli direttamente nella tua email, integrali in questo tag:

{% verbatim %}
{{ Print variable }}
{% endverbatim %}

Questo testo apparirà integralmente nella tua email come:

{{ Print variable }}

 

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 il risultato dell'attributo di contatto o dei valori float del parametro al decimale specificato.
Per funzionare correttamente, i valori devono essere passati come numero e non come stringa (i valori non devono essere passati tra virgolette come “valore”).  

Se il modello contiene 
{{ contact.BALANCE }} e il valore ottenuto sarebbe 40,320000, il float può essere arrotondato al “n” decimale usando:
{{ contact.BALANCE | floatformat: n}}

{{ contact.BALANCE | floatformat: 2}}
darà come risultato 40,32 anziché 40,320000

{{ contact.BALANCE | floatformat: 0}}
darà come risultato 40 anziché 40,320000

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

Se il modello contiene {{params.array|first}}

contiene la tua richiesta di API

“params” :
{
“array” : [ 1,2,3,4 ]
}

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 %}

safe

contrassegna una stringa che non richiede un ulteriore escape dell'HTML prima del risultato

{{ params.htmltest | safe }}

"params" :{HtmlTest: "<p>Questa è la mia frase di prova.</p>"}

darà come risultato un paragrafo formattato nel client di posta del destinatario.

 

{{ params.html }}
"params" :{HtmlTest: "<p>html para</p>"}

Senza filtro safe, visualizzerà il tag HTML come stringa normale nel client di posta del destinatario:

<p>Questa è la mia frase di prova.</p>

slice

estrae una porzione di una sequenza, una mappatura o una stringa 

Questo filtro può essere configurato per:

A. Inserire solo i primi ‘n’ elementi di una matrice

B. Inserire elementi tra due date posizioni (‘n’ e ‘m’) della matrice

In entrambi i casi, ricorda che a ciascun elemento della matrice è assegnao un numero di posizione univoco con uno ‘0’ per la prima posizione (sono “indicizzati zero”).

C. Il filtro può essere configurato anche per inserire elementi tra due elementi specificati di una matrice. 

In ogni esempio, tenere conto che la matrice contiene quanto segue:

["a","b","c","d","e","f","g","h",...]

A.
{% for product in params.products|slice:’:5’ %}
{{ product.name - {{ product.price }}
{% endfor %}
Restituisce le prime 5 posizioni  (0-4) che sono: ["a","b","c","d","e"}

B.
{% for product in params.products|slice:’2:3’ %}
{{ product.name - {{ product.price }}
{% endfor %}
Restituisce le posizioni (2-3) che sono: ["c","d"]

C.
{% for product in params.products|slice:’b:d’ %}
{{ product.name - {{ product.price }}
{% endfor %}
Restituisce gli elementi specificati, ["b","c","d"]

Test e risoluzione dei problemi del tuo modello

Per testare e risolvere i problemi di base del tuo modello, consulta questa guida o contatta il nostro team dell'assistenza clienti.

Buono a sapersi: Quando usi la funzionalità "Invia una prova" per inviare una versione di prova del tuo modello email, le variabili dell'attributo di contatto saranno sostituite da contenuto specifico del destinatario nell'email di prova, mentre le variabili dei parametri transazionali appariranno vuote.

 

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  (Riferimento: https://djangobook.com/builtin-template-tags-filters/)

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.