Šablonovací jazyk Temple

Temple je malý šablonovací jazyk Emailitu pro předměty, HTML a prostý text. Není to Liquid ani Handlebars: podporuje proměnné, vnořené cesty, výchozí hodnoty a bloky if/else a nic dalšího. Šablony ukládají proměnné tak, jak je napíšete, a Temple je vyplní při odeslání e-mailu přes API nebo automatizaci.

Přehled syntaxe

{{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 nemá cykly, filtry, pomocné funkce, dílčí šablony ani vlastní funkce. Jediným operátorem je výchozí hodnota |.

Proměnné

Hello {{first_name}}

• Temple nahradí {{first_name}} hodnotou first_name, kterou předáte. Mezery uvnitř závorek se ignorují, takže funguje i {{ first_name }}.
• Názvy rozlišují velká a malá písmena: {{First_Name}} neodpovídá first_name.
• Chybějící hodnota nebo null se změní na prázdný řetězec. Neznámé proměnné zmizí, místo aby se v e-mailu zobrazily.
• Hodnoty se převádějí na text. Čísla a logické hodnoty se zobrazí tak, jak jsou zapsané (42, true), a seznamy se spojí čárkami (z ["a","b"] vznikne a,b). Objekt se vykreslí jako [object Object], takže místo něj odkazujte na některé z jeho polí.

Vnořené vlastnosti a položky seznamu

Do objektů se dostanete tečkami a k pozicím v seznamu čísly od 0:

{{user.name}}
{{order.items.0.sku}}

{
  "user": { "name": "Ada" },
  "order": { "items": [{ "sku": "A1" }, { "sku": "B7" }] }
}

Protože tečka odděluje části cesty, ke klíči, který sám obsahuje tečku, se dostat nelze. Používejte klíče bez teček.

Výchozí hodnoty

Přidejte | a náhradní hodnotu, která se použije, když hodnota chybí nebo je null:

Hi {{first_name|"there"}},
Your company: {{company|'Not set'}}

Fungují dvojité uvozovky, jednoduché uvozovky i zápis bez uvozovek. Výchozí hodnota se nepoužije pro prázdný řetězec, 0 ani false; ty se vykreslí jako prázdný text, 0 a false. Výchozí hodnota nesmí obsahovat znak }.

Podmínky

{{#if plan}}
Thanks for being on the {{plan}} plan.
{{else}}
You're on the free plan. Upgrade anytime from your dashboard.
{{/if}}

• {{else}} je volitelné.
• Podmínka je nepravdivá, když hodnota chybí, je null, false, 0, prázdný řetězec "" nebo prázdný seznam []. Cokoli jiného je pravdivé, včetně řetězce "0", řetězce "false" a prázdného objektu.
• Podmínkou je jediná cesta k proměnné, například plan nebo user.is_admin. Neexistuje ==, and, or, not ani unless. Pokud chcete větvit podle hodnoty, vypočítejte ve svém kódu logickou hodnotu a předejte ji, například "is_pro": true.
• {{else}} a {{/if}} pište přesně tak, jak je uvedeno, bez mezer uvnitř závorek.
• Temple nejdřív zpracuje podmínky a pak proměnné.

Escapování a speciální znaky

Hodnoty se pro HTML neescapují. Temple vkládá hodnoty přesně tak, jak je předáte. Hodnota jako Tom & Jerry nebo <b>Ada</b> se do HTML vloží beze změny, proto text od uživatelů escapujte ve svém kódu, než ho předáte. Stejné proměnné plní předmět, HTML i text, takže escapovaná hodnota jako Tom & Jerry se tak zobrazí i v předmětu a textu. Pokud na tom záleží, předejte pro HTML samostatnou escapovanou proměnnou.

Znamená to také, že můžete jako jednu proměnnou předat hotové HTML, například tabulku položek objednávky, kterou vykreslí váš kód.

Pro dvojité složené závorky neexistuje escapovací syntaxe. Temple považuje cokoli mezi {{ a }} za proměnnou, a pokud pro ni nemá hodnotu, odstraní ji. Jednoduchých závorek, například v CSS, se to netýká. Hodnoty se vkládají jednou a znovu se nezpracovávají, takže pokud chcete zobrazit doslovné dvojité závorky, vložte je do proměnné:

{
  "html": "<p>Write {{example}} in your template to show the first name.</p>",
  "variables": { "example": "{{first_name}}" }
}

Kde Temple běží

E-maily z API

Předejte alias šablony nebo ID tem_ a objekt variables. Pole, která pošlete v požadavku (subject, html, text), nahradí pole šablony a pak Temple vykreslí předmět, HTML a text.

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

Editory ve webovém rozhraní vkládají pro vlastní pole kontaktů {{cf.<key>}}. Při odesílání přes API se z vašich kontaktů nic nedohledává, takže tyto hodnoty předejte sami pod cf, jako v příkladu. Totéž platí pro {{unsubscribe_url}}: pokud ho šablona používá, předejte vlastní odkaz pro odhlášení.

Můžete také poslat vložený obsah s variables a bez šablony. Viz Odeslání e-mailu.

E-maily z automatizací

Krok Send email při každém odeslání vykreslí předmět, HTML a text jazykem Temple, ať pocházejí ze šablony, nebo z přepsání v kroku.

Automatizace kontaktů dávají pole kontaktu na nejvyšší úroveň, takže funguje:

• {{email}}, {{first_name}} a {{last_name}}
• {{custom_fields.<key>}} pro vlastní pole, například {{custom_fields.plan}}. Zápis z kampaní {{cf.plan}} tady nefunguje.
• {{contact.*}}, tentýž kontakt jako objekt, například {{contact.first_name}}

Všechny automatizace navíc dostávají {{payload.*}}, data události, která spuštění vyvolala, a {{meta.*}}, metadata spuštění. Automatizace typu Email a event nemají kontakt na nejvyšší úrovni, takže použijte {{payload.*}}, nebo příjemce a předmět nastavte v kroku.

{{unsubscribe_url}} se v e-mailech z automatizací nevyplňuje.

Kampaně

Kampaně a jejich testovací e-maily Temple nepoužívají. Nahrazují údaji příjemce jen tyto slučovací značky:

• {{first_name}}, {{last_name}} a {{email}}
• {{unsubscribe_url}}, odkaz příjemce pro odhlášení
• {{cf.<key>}}, vlastní pole kontaktu, například {{cf.plan}}

Pište je bez mezer uvnitř závorek. Názvy značek nerozlišují velikost písmen, ale klíče vlastních polí musí odpovídat přesně. Výchozí hodnoty (|) a bloky {{#if}} se nezpracovávají a jakýkoli jiný text {{…}} zůstane v e-mailu tak, jak je napsaný. Viz Slučovací značky.

SMTP

SMTP relay přijímá hotovou zprávu. Žádná šablona se nedohledává a Temple se nespouští, takže finální HTML sestavte před odesláním, nebo použijte API či automatizaci, pokud potřebujete proměnné.

Zkontrolujte šablony před publikováním

Emailit kvůli chybné syntaxi Temple neodmítne šablonu ani odeslání. Chyby se obvykle projeví jako chybějící text nebo zbylé závorky v doručeném e-mailu. Před publikováním:

• Zkontrolujte, že každé {{#if …}} má odpovídající {{/if}} a každé {{ uzavírací }}.
• Pošlete si koncept verze podle jeho ID tem_ s realistickými variables, včetně chybějících a prázdných hodnot, abyste viděli obě větve každé podmínky. Viz Verze šablon.

Příklady

Pozdrav s náhradní hodnotou:

Hi {{first_name|"there"}},

Blok, který závisí na tarifu:

{{#if plan}}
Your plan: {{plan}}
{{else}}
Upgrade anytime from your dashboard.
{{/if}}

Předmět s vnořenou hodnotou:

Order {{order.number}} has shipped, {{user.first_name|"friend"}}

Související

• Odeslání se šablonou
• Vytváření a úprava šablon
• Slučovací značky
• Kroky automatizací