Il linguaggio di template 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 o un’automazione.

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 else

Temple 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 di first_name che 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 a first_name.
• Un valore mancante o null diventa 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"] diventa a,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 plan o user.is_admin. Non esistono ==, and, or, not né 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.

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

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.

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}}
• {{custom_fields.<key>}} per i campi personalizzati, ad esempio {{custom_fields.plan}}. La forma delle campagne {{cf.plan}} qui non funziona.
• {{contact.*}}, lo stesso contatto come oggetto, ad esempio {{contact.first_name}}

Tutte le automazioni ricevono anche {{payload.*}}, i dati dell’evento che ha avviato l’esecuzione, e {{meta.*}}, i metadati dell’esecuzione. Le automazioni Email ed Event non hanno un contatto al livello principale, quindi usa {{payload.*}} o imposta destinatario e oggetto nel passaggio.

{{unsubscribe_url}} non viene compilato nelle email delle automazioni.

Campagne

Le campagne e i loro invii di prova non usano Temple. Sostituiscono solo questi tag di unione con i dati del destinatario:

• {{first_name}}, {{last_name}} e {{email}}
• {{unsubscribe_url}}, il link di disiscrizione del destinatario
• {{cf.<key>}}, un campo personalizzato del contatto, ad esempio {{cf.plan}}

Scrivili senza spazi dentro le parentesi graffe. I nomi dei tag non distinguono tra maiuscole e minuscole, ma le chiavi dei campi personalizzati devono corrispondere esattamente. I valori predefiniti (|) e i blocchi {{#if}} non vengono elaborati, e qualsiasi altro testo {{…}} resta nell’email così com’è scritto. 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. 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_ con variables realistiche, compresi valori mancanti e vuoti, per vedere entrambi i rami di ogni condizione. Vedi Versioni dei template.

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

Vedi anche

• Invia con un template
• Crea e modifica i template
• Tag di unione
• Passaggi delle automazioni