Langage de templates Temple

Temple est le petit langage de templates d’Emailit pour les lignes d’objet, le HTML et le texte brut. Ce n’est ni Liquid ni Handlebars : il prend en charge les variables, les chemins imbriqués, les valeurs par défaut et les blocs if/else, et rien d’autre. Les modèles stockent les variables telles que vous les écrivez, et Temple les remplit quand un e-mail est envoyé via l’API ou par une automatisation.

Syntaxe en bref

{{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 n’a ni boucles, ni filtres, ni helpers, ni partials, ni fonctions personnalisées. Le seul opérateur est |, pour la valeur par défaut.

Variables

Hello {{first_name}}

• Temple remplace {{first_name}} par la valeur first_name que vous fournissez. Les espaces à l’intérieur des accolades sont ignorés : {{ first_name }} fonctionne donc aussi.
• Les noms sont sensibles à la casse : {{First_Name}} ne correspond pas à first_name.
• Une valeur manquante ou null devient une chaîne vide. Les variables inconnues disparaissent au lieu d’apparaître dans l’e-mail.
• Les valeurs sont converties en texte. Les nombres et les booléens apparaissent tels quels (42, true), et les listes sont jointes par des virgules (["a","b"] devient a,b). Un objet s’affiche sous la forme [object Object] : ciblez plutôt l’un de ses champs.

Propriétés imbriquées et éléments de liste

Utilisez des points pour accéder à l’intérieur des objets, et des nombres pour les positions dans une liste, à partir de 0 :

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

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

Comme le point sépare les segments du chemin, une clé qui contient elle-même un point est inaccessible. Utilisez des clés sans point.

Valeurs par défaut

Ajoutez | suivi d’une valeur de repli à utiliser quand la valeur est manquante ou null :

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

Les guillemets doubles, les guillemets simples ou l’absence de guillemets fonctionnent tous. La valeur par défaut n’est pas utilisée pour une chaîne vide, 0 ou false : ces valeurs s’affichent respectivement vide, 0 et false. Une valeur par défaut ne peut pas contenir le caractère }.

Conditions

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

• {{else}} est facultatif.
• Une condition est fausse quand la valeur est manquante, null, false, 0, une chaîne vide "" ou une liste vide []. Tout le reste est vrai, y compris la chaîne "0", la chaîne "false" et un objet vide.
• Une condition est un unique chemin de variable, comme plan ou user.is_admin. Il n’existe ni ==, ni and, or, not ou unless. Pour créer une branche selon une valeur, calculez un booléen dans votre code et transmettez-le, par exemple "is_pro": true.
• Écrivez {{else}} et {{/if}} exactement comme indiqué, sans espace à l’intérieur des accolades.
• Temple traite d’abord les conditions, puis les variables.

Échappement et caractères spéciaux

Les valeurs ne sont pas échappées en HTML. Temple insère les valeurs exactement telles que vous les transmettez. Une valeur comme Tom & Jerry ou <b>Ada</b> est insérée telle quelle dans le HTML : échappez donc dans votre code tout texte fourni par l’utilisateur avant de le transmettre. Les mêmes variables remplissent l’objet, le HTML et le texte : une valeur échappée comme Tom & Jerry apparaît donc aussi sous cette forme dans l’objet et le texte. Si c’est gênant, transmettez une variable distincte, échappée, pour le HTML.

Cela signifie aussi que vous pouvez transmettre du HTML tout prêt, comme un tableau de lignes de commande généré par votre code, dans une seule variable.

Il n’existe pas de syntaxe d’échappement pour les doubles accolades. Temple considère tout ce qui se trouve entre {{ et }} comme une variable et le supprime en l’absence de valeur. Les accolades simples, comme celles du CSS, ne sont pas concernées. Les valeurs sont insérées une seule fois et ne sont pas réanalysées : pour afficher des doubles accolades littérales, placez-les dans une variable :

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

Où Temple s’exécute

E-mails envoyés via l’API

Transmettez l’alias d’un modèle ou un ID tem_, ainsi qu’un objet variables. Les champs que vous envoyez dans la requête (subject, html, text) remplacent ceux du modèle, puis Temple effectue le rendu de l’objet, du HTML et du texte.

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

Les éditeurs du tableau de bord insèrent {{cf.<key>}} pour les champs personnalisés des contacts. Lors des envois via l’API, rien n’est récupéré depuis vos contacts : fournissez donc vous-même ces valeurs sous cf, comme dans l’exemple. Il en va de même pour {{unsubscribe_url}} : transmettez votre propre lien de désinscription si le modèle l’utilise.

Vous pouvez aussi envoyer du contenu direct avec variables, sans modèle. Consultez Envoyer un e-mail.

E-mails des automatisations

À chaque envoi, l’étape Send email effectue le rendu de l’objet, du HTML et du texte avec Temple, qu’ils proviennent du modèle ou de valeurs remplacées dans l’étape.

Les automatisations de contact placent les champs du contact au premier niveau : ces variables fonctionnent donc :

• {{email}}, {{first_name}} et {{last_name}}
• {{custom_fields.<key>}} pour les champs personnalisés, par exemple {{custom_fields.plan}}. La forme {{cf.plan}} des campagnes ne fonctionne pas ici.
• {{contact.*}}, le même contact sous forme d’objet, par exemple {{contact.first_name}}

Toutes les automatisations disposent aussi de {{payload.*}}, les données de l’événement qui a déclenché l’exécution, et de {{meta.*}}, les métadonnées de l’exécution. Les automatisations Email et event n’ont pas de contact au premier niveau : utilisez {{payload.*}} ou définissez le destinataire et l’objet dans l’étape.

{{unsubscribe_url}} n’est pas rempli dans les e-mails des automatisations.

Campagnes

Les campagnes et les envois de test de campagne n’utilisent pas Temple. Ils remplacent uniquement ces balises de fusion par les informations du destinataire :

• {{first_name}}, {{last_name}} et {{email}}
• {{unsubscribe_url}}, le lien de désinscription du destinataire
• {{cf.<key>}}, un champ personnalisé du contact, par exemple {{cf.plan}}

Écrivez-les sans espace à l’intérieur des accolades. Les noms de balises ne sont pas sensibles à la casse, mais les clés des champs personnalisés doivent correspondre exactement. Les valeurs par défaut (|) et les blocs {{#if}} ne sont pas traités, et tout autre texte {{…}} reste tel quel dans l’e-mail. Consultez Balises de fusion des campagnes.

SMTP

Le relais SMTP accepte un message terminé. Il n’y a ni recherche de modèle ni passage de Temple : construisez donc le HTML final avant d’envoyer, ou utilisez l’API ou une automatisation si vous avez besoin de variables.

Vérifier les modèles avant de les publier

Emailit ne rejette ni un modèle ni un envoi à cause d’une syntaxe Temple incorrecte. Les erreurs se traduisent généralement par du texte manquant ou des accolades restantes dans l’e-mail livré. Avant de publier :

• Vérifiez que chaque {{#if …}} a son {{/if}} correspondant, et que chaque {{ a son }} fermant.
• Envoyez-vous la version brouillon par son ID tem_ avec des variables réalistes, y compris des valeurs manquantes et vides, pour voir les deux branches de chaque condition. Consultez Versions de modèle.

Exemples

Une formule d’accueil avec une valeur de repli :

Hi {{first_name|"there"}},

Un bloc qui dépend du forfait :

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

Un objet avec une valeur imbriquée :

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

Voir aussi

• Envoyer avec un modèle
• Créer et modifier des modèles
• Balises de fusion des campagnes
• Étapes d’automatisation