Template-Sprache Temple

Temple ist die kleine Template-Sprache von Emailit für Betreffzeilen, HTML und Nur-Text. Sie ist weder Liquid noch Handlebars: Sie unterstützt Variablen, verschachtelte Pfade, Standardwerte und if/else-Blöcke, sonst nichts. Vorlagen speichern Platzhalter so, wie Sie sie schreiben, und Temple füllt sie aus, wenn eine E-Mail per API oder über eine Automatisierung gesendet wird.

Syntax auf einen Blick

{{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 hat keine Schleifen, Filter, Helper, Partials oder eigenen Funktionen. Der einzige Operator ist der Standardwert |.

Variablen

Hello {{first_name}}

• Temple ersetzt {{first_name}} durch den Wert first_name, den Sie übergeben. Leerzeichen innerhalb der geschweiften Klammern werden ignoriert, {{ first_name }} funktioniert also auch.
• Namen unterscheiden Groß- und Kleinschreibung: {{First_Name}} passt nicht zu first_name.
• Ein fehlender Wert oder null wird zu einem leeren String. Unbekannte Platzhalter verschwinden, statt in der E-Mail aufzutauchen.
• Werte werden in Text umgewandelt. Zahlen und Booleans erscheinen so, wie sie geschrieben sind (42, true), und Listen werden mit Kommas verbunden (aus ["a","b"] wird a,b). Ein Objekt wird als [object Object] ausgegeben. Verweisen Sie daher auf eines seiner Felder.

Verschachtelte Eigenschaften und Listeneinträge

Verwenden Sie Punkte, um in Objekte zu gelangen, und Zahlen für Listenpositionen, beginnend bei 0:

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

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

Da der Punkt die Pfadsegmente trennt, lässt sich ein Schlüssel, der selbst einen Punkt enthält, nicht erreichen. Verwenden Sie Schlüssel ohne Punkte.

Standardwerte

Fügen Sie | und einen Ersatzwert hinzu, der verwendet wird, wenn der Wert fehlt oder null ist:

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

Doppelte Anführungszeichen, einfache Anführungszeichen oder gar keine funktionieren gleichermaßen. Der Standardwert wird nicht für einen leeren String, 0 oder false verwendet; diese werden als leer, 0 und false ausgegeben. Ein Standardwert darf das Zeichen } nicht enthalten.

Bedingungen

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

• {{else}} ist optional.
• Eine Bedingung ist falsch, wenn der Wert fehlt, null, false, 0, ein leerer String "" oder eine leere Liste [] ist. Alles andere ist wahr, auch der String "0", der String "false" und ein leeres Objekt.
• Eine Bedingung ist ein einzelner Variablenpfad, etwa plan oder user.is_admin. Es gibt kein ==, and, or, not oder unless. Um anhand eines Werts zu verzweigen, berechnen Sie in Ihrem Code einen Boolean und übergeben ihn, zum Beispiel "is_pro": true.
• Schreiben Sie {{else}} und {{/if}} genau wie gezeigt, ohne Leerzeichen innerhalb der geschweiften Klammern.
• Temple verarbeitet zuerst die Bedingungen, dann die Variablen.

Escaping und Sonderzeichen

Werte werden nicht HTML-escaped. Temple fügt Werte genau so ein, wie Sie sie übergeben. Ein Wert wie Tom & Jerry oder <b>Ada</b> landet unverändert im HTML. Escapen Sie daher von Nutzern stammenden Text in Ihrem Code, bevor Sie ihn übergeben. Dieselben Variablen füllen Betreff, HTML und Text, ein escapeter Wert wie Tom & Jerry erscheint also auch so in Betreff und Text. Wenn das wichtig ist, übergeben Sie für das HTML eine separate, escapete Variable.

Das bedeutet auch, dass Sie fertiges HTML, etwa eine von Ihrem Code gerenderte Tabelle mit Bestellpositionen, als einzelne Variable übergeben können.

Für doppelte geschweifte Klammern gibt es keine Escape-Syntax. Temple behandelt alles zwischen {{ und }} als Platzhalter und entfernt es, wenn kein Wert vorhanden ist. Einfache geschweifte Klammern, etwa in CSS, sind nicht betroffen. Werte werden einmal eingefügt und nicht erneut ausgewertet. Um doppelte geschweifte Klammern wörtlich anzuzeigen, legen Sie sie daher in eine Variable:

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

Wo Temple ausgeführt wird

E-Mails per API

Übergeben Sie einen Vorlagen-Alias oder eine tem_-ID und ein Objekt variables. Felder, die Sie in der Anfrage senden (subject, html, text), ersetzen die der Vorlage, dann rendert Temple Betreff, HTML und 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" }
  }
}

Die Editoren in der Weboberfläche fügen für eigene Felder von Kontakten {{cf.<key>}} ein. Bei Versänden per API wird nichts aus Ihren Kontakten nachgeschlagen. Übergeben Sie diese Werte daher selbst unter cf, wie im Beispiel. Dasselbe gilt für {{unsubscribe_url}}: Übergeben Sie Ihren eigenen Abmeldelink, wenn die Vorlage ihn verwendet.

Sie können auch Inhalte direkt in der Anfrage mit variables und ohne Vorlage senden. Siehe E-Mail senden.

E-Mails aus Automatisierungen

Bei jedem Versand rendert der Schritt Send email Betreff, HTML und Text mit Temple, ob sie aus der Vorlage oder aus Überschreibungen im Schritt stammen.

Automatisierungen mit Kontakten legen die Felder des Kontakts auf die oberste Ebene, daher funktionieren:

• {{email}}, {{first_name}} und {{last_name}}
• {{custom_fields.<key>}} für eigene Felder, zum Beispiel {{custom_fields.plan}}. Die Kampagnenform {{cf.plan}} funktioniert hier nicht.
• {{contact.*}}, derselbe Kontakt als Objekt, zum Beispiel {{contact.first_name}}

Alle Automatisierungen erhalten außerdem {{payload.*}}, die Daten des Events, das den Durchlauf ausgelöst hat, und {{meta.*}}, die Metadaten des Durchlaufs. Automatisierungen mit dem Kontext Email oder Event haben keinen Kontakt auf oberster Ebene. Verwenden Sie dort {{payload.*}} oder legen Sie Empfänger und Betreff im Schritt fest.

{{unsubscribe_url}} wird in E-Mails aus Automatisierungen nicht befüllt.

Kampagnen

Kampagnen und ihre Testversände verwenden kein Temple. Sie ersetzen nur diese Platzhalter durch die Angaben des Empfängers:

• {{first_name}}, {{last_name}} und {{email}}
• {{unsubscribe_url}}, den Abmeldelink des Empfängers
• {{cf.<key>}}, ein eigenes Feld des Kontakts, zum Beispiel {{cf.plan}}

Schreiben Sie sie ohne Leerzeichen innerhalb der geschweiften Klammern. Bei den Namen der Platzhalter spielt die Groß-/Kleinschreibung keine Rolle, die Schlüssel eigener Felder müssen aber genau übereinstimmen. Standardwerte (|) und {{#if}}-Blöcke werden nicht verarbeitet, und jeder andere {{…}}-Text bleibt unverändert in der E-Mail. Siehe Platzhalter in Kampagnen.

SMTP

Das SMTP-Relay nimmt eine fertige Nachricht an. Es gibt weder eine Vorlagensuche noch einen Durchlauf durch Temple. Erstellen Sie das endgültige HTML daher vor dem Senden, oder nutzen Sie die API oder eine Automatisierung, wenn Sie Variablen brauchen.

Vorlagen vor dem Veröffentlichen prüfen

Emailit lehnt eine Vorlage oder einen Versand nicht wegen fehlerhafter Temple-Syntax ab. Fehler zeigen sich meist als fehlender Text oder übrig gebliebene geschweifte Klammern in der zugestellten E-Mail. Vor dem Veröffentlichen:

• Prüfen Sie, ob jedes {{#if …}} ein passendes {{/if}} hat und jedes {{ ein schließendes }}.
• Senden Sie die Entwurfsversion über ihre tem_-ID mit realistischen variables an sich selbst, auch mit fehlenden und leeren Werten, um beide Seiten jeder Bedingung zu sehen. Siehe Vorlagenversionen.

Beispiele

Eine Begrüßung mit Ersatzwert:

Hi {{first_name|"there"}},

Ein Block, der vom Tarif abhängt:

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

Ein Betreff mit einem verschachtelten Wert:

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

Siehe auch

• Mit einer Vorlage senden
• Vorlagen erstellen und bearbeiten
• Platzhalter in Kampagnen
• Schritte von Automatisierungen