Riferimento
Il linguaggio di template Temple
Temple inserisce variabili, valori predefiniti e condizioni negli oggetti, nell’HTML e nel testo delle email al momento dell’invio. Sintassi, valori veri e falsi, escaping e dove viene eseguito Temple.
Temple è il piccolo linguaggio di template di Emailit per oggetti, HTML e testo semplice. Non è Liquid né Handlebars: supporta variabili, percorsi annidati, valori predefiniti e blocchi if/else, e nient’altro. I template memorizzano i segnaposto così come li scrivi, e Temple li compila quando un’email viene inviata tramite l’API, un’automazione o una campagna.
Sintassi in breve
{{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 elseTemple non ha cicli, filtri, helper, partial né funzioni personalizzate. L’unico operatore è il valore predefinito |.
Variabili
Hello {{first_name}}- Temple sostituisce
{{first_name}}con il valore difirst_nameche fornisci. Gli spazi dentro le parentesi graffe vengono ignorati, quindi funziona anche{{ first_name }}. - I nomi distinguono tra maiuscole e minuscole:
{{First_Name}}non corrisponde afirst_name. - Un valore mancante o
nulldiventa una stringa vuota. I segnaposto sconosciuti spariscono invece di comparire nell’email. - I valori vengono convertiti in testo. Numeri e booleani compaiono così come sono scritti (
42,true), e gli elenchi vengono uniti con virgole (["a","b"]diventaa,b). Un oggetto viene mostrato come[object Object], quindi punta invece a uno dei suoi campi.
Proprietà annidate ed elementi di elenchi
Usa i punti per accedere agli oggetti e i numeri per le posizioni negli elenchi, a partire da 0:
{{user.name}}
{{order.items.0.sku}}{
"user": { "name": "Ada" },
"order": { "items": [{ "sku": "A1" }, { "sku": "B7" }] }
}Poiché il punto separa i segmenti del percorso, una chiave che contiene a sua volta un punto non è raggiungibile. Usa chiavi senza punti.
Valori predefiniti
Aggiungi | e un valore di riserva da usare quando il valore manca o è null:
Hi {{first_name|"there"}},
Your company: {{company|'Not set'}}Funzionano le virgolette doppie, quelle singole o nessuna virgoletta. Il valore predefinito non viene usato per una stringa vuota, 0 o false, che vengono mostrati rispettivamente come vuoto, 0 e false. Un valore predefinito non può contenere il carattere }.
Condizioni
{{#if plan}}
Thanks for being on the {{plan}} plan.
{{else}}
You're on the free plan. Upgrade anytime from your dashboard.
{{/if}}{{else}}è facoltativo.- Una condizione è falsa quando il valore manca o è
null,false,0, una stringa vuota""o un elenco vuoto[]. Tutto il resto è vero, comprese la stringa"0", la stringa"false"e un oggetto vuoto. - Una condizione è un singolo percorso di variabile, come
planouser.is_admin. Non esistono==,and,or,notnéunless. Per creare una diramazione in base a un valore, calcola un booleano nel tuo codice e passalo, ad esempio"is_pro": true. - Scrivi
{{else}}e{{/if}}esattamente come mostrato, senza spazi dentro le parentesi graffe. - Temple elabora prima le condizioni, poi le variabili.
I blocchi si possono annidare. Temple risolve prima i blocchi più interni, quindi ogni {{else}} e {{/if}} appartiene al proprio {{#if}}:
{{#if plan}}
{{#if annual}}Billed yearly.{{else}}Billed monthly.{{/if}}
{{else}}
You're on the free plan.
{{/if}}L’annidamento funziona fino a 10 livelli di profondità.
Escaping e caratteri speciali
I valori non subiscono l’escaping HTML. Temple inserisce i valori esattamente come li passi. Un valore come Tom & Jerry o <b>Ada</b> entra nell’HTML senza modifiche, quindi applica l’escaping a qualsiasi testo fornito dagli utenti nel tuo codice prima di passarlo. Le stesse variabili compilano oggetto, HTML e testo, quindi un valore con escaping come Tom & Jerry compare così anche nell’oggetto e nel testo. Se è un problema, passa una variabile separata, con escaping, per l’HTML.
Questo significa anche che puoi passare HTML già pronto, come una tabella delle righe di un ordine generata dal tuo codice, come singola variabile.
Non esiste una sintassi di escape per le doppie parentesi graffe. Temple tratta tutto ciò che si trova tra {{ e }} come un segnaposto e lo rimuove se non c’è un valore. Le parentesi graffe singole, come quelle del CSS, non sono interessate. I valori vengono inseriti una volta e non vengono analizzati di nuovo, quindi per mostrare doppie parentesi graffe letterali, mettile in una variabile:
{
"html": "<p>Write {{example}} in your template to show the first name.</p>",
"variables": { "example": "{{first_name}}" }
}Dove viene eseguito Temple
| Dove | Temple viene eseguito? | Cosa puoi usare |
|---|---|---|
API email con un template |
Sempre | Le variables che passi, e global |
API email con subject, html o text inline |
Quando variables ha almeno una chiave, o il contenuto usa {{global.…}} |
Le variables che passi, e global |
| Automazioni, passaggio Send email | A ogni invio | Campi del contatto, tags, score, contact, global, unsubscribe_url, manage_subscriptions_url, payload, meta, run, automation e step, più email nelle automazioni Email. Vedi Email delle automazioni. |
| Campagne, invii di prova e Preview as contact | Sempre | Campi del contatto, cf, custom_fields, tags, score, global, unsubscribe_url, manage_subscriptions_url, webview_url e contact. Vedi Campagne. |
| SMTP relay | No | Niente. Il messaggio viene inviato così come l’hai costruito. |
| Editor del pannello e relative anteprime | No | Gli editor inseriscono i segnaposto, e le loro anteprime li mostrano non elaborati. Gli editor MJML (alpha) mostrano anche l’anteprima di Temple con dati di esempio. Per vedere una campagna elaborata per un singolo contatto, usa Preview as contact. |
Email inviate con l’API
Passa un alias di template o un ID tem_ e un oggetto variables. I campi che invii nella richiesta (subject, html, text) sostituiscono quelli del template, poi Temple elabora oggetto, HTML e testo.
{
"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" }
}
}Gli editor del pannello inseriscono {{cf.<key>}} per i campi personalizzati dei contatti. Negli invii con l’API non viene cercato nulla tra i tuoi contatti, quindi fornisci tu quei valori sotto cf, come nell’esempio. Lo stesso vale per {{unsubscribe_url}}: passa il tuo link di disiscrizione se il template lo usa. I valori globali sono l’eccezione: {{global.<key>}} viene compilato dal workspace, a meno che le tue variables abbiano una propria chiave global.
Puoi anche inviare contenuto inline con variables e senza template. Vedi Invia un’email.
Email delle automazioni
A ogni invio, il passaggio Send email elabora con Temple oggetto, HTML e testo, che provengano dal template o da sovrascritture impostate nel passaggio.
Le automazioni sui contatti mettono i campi del contatto al livello principale, quindi funzionano:
{{email}},{{first_name}}e{{last_name}}{{cf.<key>}}o{{custom_fields.<key>}}per i campi personalizzati, ad esempio{{cf.plan}}.{{cf.<key>}}è la forma che usano le campagne e gli editor.{{tags}}, i tag del contatto nella formavip, customer, e{{#if tags}}…{{/if}};{{score}}, il lead score{{unsubscribe_url}}, il link di disiscrizione del contatto, inviato anche negli headerList-Unsubscribeper la disiscrizione con un clic nelle email di marketing, e{{manage_subscriptions_url}}, la sua pagina di gestione delle iscrizioni{{contact.*}}, lo stesso contatto come oggetto, ad esempio{{contact.first_name}}
Tutte le automazioni ricevono anche {{global.*}}, i valori globali del workspace, {{payload.*}}, i dati dell’evento che ha avviato l’esecuzione, e {{meta.*}}, i metadati dell’esecuzione. Ricevono anche {{run.id}}, {{automation.id}}, {{automation.name}} e {{step.key}}, la chiave del passaggio Send email. Le automazioni Email aggiungono {{email.*}}, l’email che ha avviato l’esecuzione, ad esempio {{email.mail_from}}. Le automazioni Email ed Event non hanno un contatto al livello principale, quindi usa {{payload.*}} o imposta destinatario e oggetto nel passaggio.
Campagne
Le campagne elaborano con Temple oggetto, HTML e testo per ogni destinatario, qualunque sia l’editor con cui sono state create. Gli invii di prova e Preview as contact li elaborano allo stesso modo. Le variabili provengono dal contatto del destinatario:
{{first_name}},{{last_name}}e{{email}}{{unsubscribe_url}}, il link di disiscrizione del destinatario, e{{manage_subscriptions_url}}, la sua pagina di gestione delle iscrizioni{{cf.<key>}}o{{custom_fields.<key>}}per i campi personalizzati, ad esempio{{cf.plan}}{{tags}}, i tag del contatto nella formavip, customer, e{{score}}, il lead score{{global.<key>}}, un valore globale, ad esempio{{global.offer_url}}{{contact.*}}, gli stessi campi come oggetto, ad esempio{{contact.first_name}}
I campi vuoti del contatto contano come mancanti, quindi si applicano i valori predefiniti: {{first_name|"there"}} diventa there per un contatto senza nome. Gli invii di prova a un indirizzo che appartiene a un contatto del workspace usano i dati di quel contatto. Per gli altri indirizzi, {{email}} viene compilato con l’indirizzo di prova e nomi e campi personalizzati restano vuoti.
I tag di unione delle campagne scritti prima che le campagne usassero Temple continuano a funzionare. I nomi first_name, last_name, email e unsubscribe_url, e il prefisso cf., corrispondono con qualsiasi combinazione di maiuscole e minuscole, quindi {{FIRST_NAME}} funziona ancora. Le chiavi dei campi personalizzati devono corrispondere esattamente. Vedi Tag di unione.
SMTP
L’SMTP relay accetta un messaggio già completo. Non c’è ricerca di template né passaggio di Temple, quindi costruisci l’HTML finale prima di inviare, oppure usa l’API o un’automazione se ti servono le variabili.
Controlla i template prima di pubblicarli
Emailit non rifiuta un template o un invio per una sintassi Temple errata. Gli errori di solito si manifestano come testo mancante o parentesi graffe rimaste nell’email consegnata. I template MJML (alpha) fanno eccezione: quando ne salvi uno, Emailit ne controlla la sintassi Temple e rifiuta i blocchi non bilanciati. Prima di pubblicare:
- Controlla che ogni
{{#if …}}abbia il suo{{/if}}e ogni{{abbia la sua chiusura}}. - Invia a te stesso la versione in bozza tramite il suo ID
tem_convariablesrealistiche, compresi valori mancanti e vuoti, per vedere entrambi i rami di ogni condizione. Vedi Versioni dei template. - Per una campagna, usa Preview as contact con contatti che hanno e che non hanno ciascun valore, poi invia un’email di prova. Vedi Testa e programma una campagna.
Esempi
Un saluto con un valore di riserva:
Hi {{first_name|"there"}},Un blocco che dipende dal piano:
{{#if plan}}
Your plan: {{plan}}
{{else}}
Upgrade anytime from your dashboard.
{{/if}}Un oggetto con un valore annidato:
Order {{order.number}} has shipped, {{user.first_name|"friend"}}