Lenguaje de plantillas Temple

Temple es el pequeño lenguaje de plantillas de Emailit para las líneas de asunto, el HTML y el texto plano. No es Liquid ni Handlebars: admite variables, rutas anidadas, valores por defecto y bloques if/else, y nada más. Las plantillas guardan los marcadores tal como los escribes, y Temple los rellena cuando se envía un email con la API o con una automatización.

La sintaxis de un vistazo

{{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 no tiene bucles, filtros, helpers, parciales ni funciones personalizadas. El único operador es el valor por defecto |.

Variables

Hello {{first_name}}

• Temple sustituye {{first_name}} por el valor de first_name que proporcionas. Los espacios dentro de las llaves se ignoran, así que {{ first_name }} también funciona.
• Los nombres distinguen entre mayúsculas y minúsculas: {{First_Name}} no coincide con first_name.
• Un valor ausente o null se convierte en una cadena vacía. Los marcadores desconocidos desaparecen en lugar de mostrarse en el email.
• Los valores se convierten en texto. Los números y los booleanos aparecen tal como están escritos (42, true), y las listas se unen con comas (["a","b"] se convierte en a,b). Un objeto se muestra como [object Object], así que apunta a uno de sus campos.

Propiedades anidadas y elementos de listas

Usa puntos para acceder a los objetos y números para las posiciones de las listas, empezando por 0:

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

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

Como el punto separa los segmentos de la ruta, no se puede acceder a una clave que contenga un punto. Usa claves sin puntos.

Valores por defecto

Añade | y un valor alternativo para usarlo cuando el valor falte o sea null:

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

Funcionan las comillas dobles, las simples y la ausencia de comillas. El valor por defecto no se usa con una cadena vacía, 0 o false; estos valores se muestran vacíos, como 0 y como false. Un valor por defecto no puede contener el carácter }.

Condicionales

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

• {{else}} es opcional.
• Una condición es falsa cuando el valor falta o es null, false, 0, una cadena vacía "" o una lista vacía []. Cualquier otro valor es verdadero, incluidas la cadena "0", la cadena "false" y un objeto vacío.
• Una condición es una única ruta de variable, como plan o user.is_admin. No hay ==, and, or, not ni unless. Para ramificar según un valor, calcula un booleano en tu código y pásalo, por ejemplo "is_pro": true.
• Escribe {{else}} y {{/if}} exactamente como se muestran, sin espacios dentro de las llaves.
• Temple procesa primero los condicionales y después las variables.

Escape y caracteres especiales

Los valores no se escapan como HTML. Temple inserta los valores exactamente como los pasas. Un valor como Tom & Jerry o <b>Ada</b> entra en el HTML sin cambios, así que escapa en tu código cualquier texto que aporten los usuarios antes de pasarlo. Las mismas variables rellenan el asunto, el HTML y el texto, así que un valor escapado como Tom & Jerry también aparece así en el asunto y en el texto. Si eso te importa, pasa una variable escapada aparte para el HTML.

Esto también significa que puedes pasar HTML ya preparado, como una tabla de líneas de pedido que renderiza tu código, en una sola variable.

No hay sintaxis de escape para las llaves dobles. Temple trata todo lo que hay entre {{ y }} como un marcador y lo elimina si no tiene valor. Las llaves simples, como las del CSS, no se ven afectadas. Los valores se insertan una sola vez y no se vuelven a analizar, así que, para mostrar llaves dobles literales, ponlas en una variable:

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

Dónde se ejecuta Temple

Emails de la API

Pasa un alias de plantilla o un ID tem_, y un objeto variables. Los campos que envías en la petición (subject, html, text) sustituyen a los de la plantilla, y después Temple renderiza el asunto, el HTML y el texto.

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

Los editores del panel insertan {{cf.<key>}} para los campos personalizados de los contactos. En los envíos por API no se consulta nada de tus contactos, así que proporciona tú esos valores en cf, como en el ejemplo. Lo mismo ocurre con {{unsubscribe_url}}: pasa tu propio enlace de baja si la plantilla lo usa.

También puedes enviar contenido en línea con variables y sin plantilla. Consulta Enviar un email.

Emails de las automatizaciones

En cada envío, el paso Send email renderiza el asunto, el HTML y el texto con Temple, tanto si vienen de la plantilla como si se sobrescriben en el paso.

Las automatizaciones de contactos colocan los campos del contacto en el nivel superior, así que funcionan estos:

• {{email}}, {{first_name}} y {{last_name}}
• {{custom_fields.<key>}} para los campos personalizados, por ejemplo {{custom_fields.plan}}. La forma de las campañas, {{cf.plan}}, no funciona aquí.
• {{contact.*}}, el mismo contacto como objeto, por ejemplo {{contact.first_name}}

Todas las automatizaciones reciben además {{payload.*}}, los datos del evento que disparó la ejecución, y {{meta.*}}, los metadatos de la ejecución. Las automatizaciones de tipo Email y event no tienen un contacto en el nivel superior, así que usa {{payload.*}} o define el destinatario y el asunto en el paso.

{{unsubscribe_url}} no se rellena en los emails de las automatizaciones.

Campañas

Las campañas y los envíos de prueba de campañas no usan Temple. Solo sustituyen estas etiquetas de combinación por los datos del destinatario:

• {{first_name}}, {{last_name}} y {{email}}
• {{unsubscribe_url}}, el enlace de baja del destinatario
• {{cf.<key>}}, un campo personalizado del contacto, por ejemplo {{cf.plan}}

Escríbelas sin espacios dentro de las llaves. Los nombres de las etiquetas no distinguen entre mayúsculas y minúsculas, pero las claves de los campos personalizados deben coincidir exactamente. Los valores por defecto (|) y los bloques {{#if}} no se procesan, y cualquier otro texto {{…}} se queda en el email tal como está escrito. Consulta Etiquetas de combinación de las campañas.

SMTP

El SMTP relay acepta un mensaje terminado. No se busca ninguna plantilla ni se pasa por Temple, así que crea el HTML final antes de enviar, o usa la API o una automatización si necesitas variables.

Comprobar las plantillas antes de publicarlas

Emailit no rechaza una plantilla ni un envío por una sintaxis de Temple incorrecta. Los errores suelen notarse como texto que falta o llaves sobrantes en el email entregado. Antes de publicar:

• Comprueba que cada {{#if …}} tiene su {{/if}} y que cada {{ tiene su }} de cierre.
• Envíate la versión en borrador por su ID tem_ con variables realistas, incluidos valores ausentes y vacíos, para ver las dos ramas de cada condición. Consulta Versiones de plantilla.

Ejemplos

Un saludo con un valor alternativo:

Hi {{first_name|"there"}},

Un bloque que depende del plan:

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

Un asunto con un valor anidado:

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

Ver también

• Enviar con una plantilla
• Crear y editar plantillas
• Etiquetas de combinación de las campañas
• Pasos de las automatizaciones