Este artículo pretende ofrecerte descripciones y explicaciones claras de los conceptos fundamentales del Lenguaje de Plantillas MJ. Encontrará ejemplos prácticos a lo largo del artículo, que ilustran eficazmente cómo utilizar el lenguaje en escenarios del mundo real.

Resumen

• Tipos de variables
  • Datos
  • Var
  • Valores por defecto
  • Sintaxis
• Variables predefinidas
• Objetos multidimensionales y matrices multidimensionales
• Sentencias condicionales If
• Bucles For
• Bloques de texto – Bloques HTML – Bloques de lenguaje de plantillas
• Funciones
  • Función Set
  • Función FormatNumberLocale
• Notas adicionales
• Gestión de errores de plantilla

Tipos de variables

Esendex ofrece cuatro tipos de variables, cada una de las cuales tiene un propósito diferente en el lenguaje de plantillas. Estos tipos de variables son:

1. Datos (estáticas): Estas variables se utilizan para datos estáticos que no cambian con frecuencia. Suelen ser valores predefinidos.
2. Var (dinámica): Las variables var se utilizan para datos dinámicos que pueden cambiar en función de diferentes condiciones o entradas.
3. Variables MJ predefinidas: Estas variables están predefinidas por Esendex y proporcionan información y funcionalidades útiles dentro del lenguaje de plantillas.
4. Estructuras de variables de segmentación: Estas variables se utilizan para segmentaciones complejas y no son el tema principal de este artículo.

Nos centraremos principalmente en los dos primeros tipos de variables (data y var), pero también trataremos brevemente las variables predefinidas.

Los tipos de variables más utilizados son data y var. Aunque ambas sirven para reemplazar una cadena de texto con un valor que cambia dinámicamente, difieren en cómo deben utilizarse, cómo se proporciona el valor al sistema y los tipos de mensajes en los que pueden utilizarse.

Además de las variables independientes, el lenguaje de plantillas proporciona herramientas (funciones) que permiten a los usuarios incorporar variables a operaciones lógicas y aritméticas más complejas, así como influir en el formato y la codificación. En esta guía, exploraremos específicamente el uso de funciones como ‘set’ y ‘FormatNumberLocale’. Además, profundizaremos en las sentencias condicionales if y los bucles for.

Datos

El tipo de dato variable es versátil y puede utilizarse tanto en mensajes de marketing como transaccionales. Esta flexibilidad surge del hecho de que no requiere ninguna acción por parte del usuario para proporcionar un valor para el marcador de posición variable. En su lugar, el sistema sustituye automáticamente el valor basándose en los objetos de propiedad Contacto.

Tanto si está enviando una campaña como un correo electrónico transaccional, siempre que el mensaje se dirija a un contacto existente y el nombre de la variable corresponda a una propiedad de contacto, el sistema podrá procesar la variable de datos. Si el destinatario tiene un valor asignado a esa propiedad, se mostrará en lugar del marcador de posición de la variable.

Ilustremos esto con un ejemplo. Supongamos que establezco la variable [[data:country]] en el contenido de mi mensaje y lo envío a uno de mis contactos. En este caso, se pueden producir dos resultados:

1. Si el contacto tiene un valor establecido para la propiedad de contacto «país», recibirá el mensaje con la variable [[data:country]] sustituida por el valor correspondiente.
2. Si el contacto no tiene un valor establecido para la propiedad Contacto «país», recibirá el mensaje sin ningún reemplazo para la variable [[data:country]]. Sin embargo, la propia variable no se mostrará como elemento del idioma de la plantilla en la versión final del mensaje.

Para dar un ejemplo concreto, consideremos dos contactos: user1@domain.tld, que tiene un valor de propiedad «país» de «Francia» y user2@domain.tld, que no tiene un valor establecido para la propiedad «país».

Si les envío a ambos el mismo mensaje que contiene la frase

«Hola, ¿cómo están las cosas en [[data:country]] ahora después de la pandemia?«

Ambos contactos verán contenidos diferentes:

user1@domain.tld verá: «Hola, ¿cómo están las cosas en Francia después de la pandemia?»
user2@domain.tld verá: «Hola, ¿cómo están las cosas en ahora después de la pandemia?»

En el segundo ejemplo, el sistema simplemente no imprime nada porque el usuario no tiene un valor establecido para la propiedad asociada de la variable de datos en uso.

Var

Es importante señalar que el tipo de variable var no debe utilizarse en plantillas de Marketing o borradores de Campaña. Aunque puede añadirse a estos objetos, al intentar enviar un mensaje de este tipo se producirá un evento BLOQUEADO debido a un error del lenguaje de plantillas. Normalmente, el mensaje de error indicará que no se ha proporcionado ningún valor para la variable var, lo cual es de esperar ya que no existe ningún medio para añadirle un valor.

Sin embargo, hay formas de hacer que las variables var funcionen en una plantilla de marketing o en un entorno de campaña. Los dos métodos más sencillos son:

• Añadir la variable var con un valor predeterminado.
• Definir la variable utilizando una función de conjunto.

Aunque estos enfoques técnicamente funcionan, pueden ser contraproducentes y menos útiles. Esto se debe a que requieren que establezca el valor de la variable en la propia plantilla antes de enviar, sin permitir ninguna variación en el valor mostrado en función del destinatario. Esto contradice el propósito de tener una variable y anula su flexibilidad.

La utilización adecuada de las variables var es incluirlas en las plantillas transaccionales o directamente en el contenido de los mensajes transaccionales. Los valores utilizados para sustituir estas variables son proporcionados por el usuario a través de la llamada a la API de envío (como parte del cuerpo de la solicitud) o durante la sesión de retransmisión SMTP (como una cabecera personalizada), dependiendo del canal transaccional que se esté utilizando.

Para declarar las variables y proporcionar sus respectivos valores, se utilizan pares clave-valor JSON. Por ejemplo, «nombre»: «Juan» o«testVariable123»: «testValue«, etc.

En el contexto de Send API v3, el objeto que contiene las variables se denomina «Vars» Para Send API v3.1, el principio sigue siendo el mismo, pero el objeto se denomina «Variables» Para los mensajes generados por retransmisión SMTP, la cabecera personalizada que debe contener las variables codificadas en JSON es «X-MJ-Vars»

Tenga en cuenta que para que el lenguaje de plantillas se procese correctamente y no como texto plano, el sistema Esendex se basa en propiedades específicas que indican si los elementos del lenguaje de plantillas deben tratarse como tales. Estas propiedades son de tipo booleano, y a continuación encontrará el nombre de la propiedad adecuada para cada canal transaccional:

• API de envío v3: «Mj-TemplateLanguage»
• API de envío v3.1: «TemplateLanguage»
• Enlace SMTP: «X-MJ-TemplateLanguage»

Es importante tener en cuenta que el valor por defecto de cada una de estas propiedades es «false» o «0». Si se pasa por alto este detalle, aunque las configuraciones sean correctas, es posible que la configuración del idioma de las plantillas no funcione como se espera. Esto se debe a que sin habilitar las propiedades anteriores, el sistema interpreta los elementos del lenguaje de plantillas en el mensaje enviado como cadenas de texto ordinarias sin ningún significado adicional.

Por último, en un escenario de nicho en el que los usuarios crean objetos de borrador de campaña a través de la API y pretenden utilizar el lenguaje de plantillas en el contenido del borrador de campaña, deben asegurarse de que el objeto«/campaigndraft/$ID/detailcontent» asociado a su borrador incluye la siguiente propiedad en el objeto «Headers»:

Al incluir esta propiedad, el sistema reconoce el uso de lenguaje de plantillas en el contenido del borrador de la campaña.

Valores por defecto

Tanto las variables var como data admiten el uso de valores por defecto. Un valor por defecto actúa como un valor alternativo o de red de seguridad que los usuarios proporcionan a nuestro sistema al configurar la variable en la plantilla o en el cuerpo del mensaje. Si se cumplen ciertas condiciones, nuestro sistema mostrará el valor por defecto:

• variables de datos: Si el contacto que recibe el mensaje no tiene un valor de propiedad Contacto establecido para esa variable/propiedad de contacto específica.
• variables var: Si no se envía ningún valor a través de la llamada API o la sesión SMTP.

En estos casos, el valor predeterminado sirve como sustituto para garantizar que siempre se muestre un valor para la variable, incluso cuando los datos necesarios no estén disponibles o no se hayan proporcionado.

Sintaxis

Teniendo en cuenta las consideraciones anteriores, vamos a profundizar en la sintaxis adecuada para las variables independientes (variables que no se utilizan dentro de una función).

Variables var

• Para añadir una variable var, utilice la siguiente sintaxis: {{var:nombreVariable}}
• Para proporcionar un valor por defecto junto con la variable: {{var:variableName:defaultValue}}
  Sintaxis alternativa: {{var:variableName: «defaultValue»}} (ambas opciones funcionan igual de bien)
• Para imprimir un espacio como valor por defecto, enciérrelo entre comillas: {{var:variableName:» «}}
• Para no mostrar nada como valor predeterminado, utilice comillas vacías: {{var:variableName:»»}}

Variables de datos

• Para añadir una variable de datos, utilice la siguiente sintaxis: [[data:contactPropertyName]]
• Para proporcionar un valor por defecto junto con la variable:[[data:contactPropertyName:defaultValue]]
  Sintaxis alternativa: [[data:contactPropertyName: «defaultValue»]]

Nota: Aunque las llaves dobles en lugar de los corchetes dobles también funcionan para las variables de datos, se recomienda utilizar corchetes a menos que sea necesario para funciones específicas que exijan llaves dobles.

Es importante tener en cuenta que el comportamiento del sistema difiere cuando se encuentra con una situación en la que carece de un valor para una variable de datos en comparación con una variable var. Si una variable de datos no tiene un valor por defecto y el contacto no tiene un valor establecido para la propiedad respectiva, se imprimirá un espacio en blanco en el mensaje. Sin embargo, no tener un valor por defecto para una variable var y no declararlo en la llamada a la API o en la sesión SMTP hará que el mensaje se bloquee.

Los valores por defecto no son obligatorios, pero pueden ser útiles para evitar el bloqueo de mensajes. Por defecto, cuando el sistema encuentra una variable var sin un valor proporcionado, bloquea el mensaje. Para influir en este comportamiento, puede incluir una propiedad booleana especial en su llamada a la API o en la cabecera SMTP:

• Enviar API v3: «Mj-TemplateErrorDeliver»
• Enviar API v3.1: «EntregaErrorPlantilla»
• SMTP: «X-MJ-TemplateErrorDeliver»

El valor por defecto de esta propiedad es «false», por lo que habilitarla manualmente permite que los mensajes se envíen aunque haya errores de lenguaje de plantillas. Habilitar esta propiedad evita que se bloqueen los mensajes.

Por último, los usuarios pueden elegir si desean recibir una notificación por correo electrónico cuando sus mensajes se bloqueen debido a errores de idioma en la plantilla. Esto se puede conseguir a través de otra propiedad especial:

• Send API v3: «Mj-TemplateErrorReporting» (ejemplo: «Mj-TemplateErrorReporting»: «reports@domain.tld»)
• Enviar API v3.1: «TemplateErrorReporting» (ejemplo: {«Email»: «reports@domain.tld», «Name»: «Recipient Name»})
• SMTP: «X-MJ-TemplateErrorReporting» (ejemplo de encabezado personalizado: X-MJ-TemplateErrorReporting: «reports@domain.tld»)

Variables predefinidas

En nuestro sistema, ciertos nombres de variables están reservados para variables estáticas predefinidas. Estas variables permiten a los usuarios especificar una variable que corresponde a un valor específico basado en el sistema. Algunas de las variables predefinidas más utilizadas son:

• ID del contacto del destinatario
• Dirección de correo electrónico del contacto del destinatario
• ID de la plantilla
• Enlaces compartibles en redes sociales para la versión en línea del correo electrónico (Twitter, Facebook, LinkedIn, etc.) – esto es aplicable a los boletines al igual que a las versiones en línea estándar/PERMALINKS.

La sintaxis para utilizar cualquiera de estas variables predefinidas es la siguiente: {{predefinedVarHere}}.

Ejemplo: {{mj:template.ID}} mostrará el ID de la plantilla en la versión final del mensaje si se utilizó una plantilla para enviar el correo electrónico.

Tenga en cuenta que existen otras variables reservadas, como el enlace de cancelación de suscripción o la versión en línea, que se introducen mediante corchetes dobles (por ejemplo, [[PERMALINK]]). El sistema suele añadir estas variables automáticamente, pero los usuarios también pueden introducirlas manualmente en Drag-and-Drop, HTML sin formato, plantillas MJML sin formato u objetos detailcontent de borrador de campaña. Es importante recordar que estas variables predefinidas especiales no deben introducirse entre llaves. Introducirlas con llaves hará que el sistema las trate como variables que necesitan ser definidas en una llamada API o durante una sesión SMTP (como variables «var») en lugar de variables que el sistema puede obtener por sí mismo.

Por lo tanto, cualquier variable estática predefinida especificada en la documentación de referencia mencionada anteriormente (que empiece por «mj:») debe introducirse utilizando«{{}}», mientras que cualquier variable predefinida que no aparezca en dicha documentación (que no empiece por «mj:») debe introducirse utilizando «[[]]«.

Objetos multidimensionales y matrices multidimensionales

Nuestro lenguaje de plantillas permite el uso de objetos multidimensionales y matrices multidimensionales – son útiles en varias situaciones, por ejemplo – para introducir valores que se utilizarían en un bucle for.

Un objeto o matriz multidimensional es aquel que incluye variables anidadas unas debajo de otras. Estos sólo son utilizables en plantillas/mensajes transaccionales, ya que requieren que los valores sean proporcionados por el usuario y esto debe hacerse a través de una estructura JSON específica.

Aquí hay un ejemplo de una variable multidimensional que necesitaría ser presentada como un objeto multidimensional en los datos JSON donde las variables para ese mensaje serán declaradas:

{{var:ropa.invierno.abrigo}}

Cada punto («.») representa una «capa» de anidamiento – el valor más a la izquierda indica el nivel más externo, mientras que cuanto más a la derecha nos movemos, más abajo dentro de la estructura anidada nos encontramos. Esta es la estructura JSON correcta que hay que utilizar, para que nuestro sistema localice correctamente el valor de la variable «ropa.invierno.abrigo» (el ejemplo incluye la propiedad «Variables» de la v3.1, pero eso variaría en función del canal transaccional utilizado, como se ha comentado en un apartado anterior):

La configuración anterior tendría como resultado que la palabra «blazer» se mostraría en la posición en la que «{{var:clothes.winter.coat}}» se colocó en la plantilla/contenido del correo electrónico.

En cuanto a las matrices multidimensionales, éstas se utilizan más comúnmente – específicamente en los bucles for (más sobre ellos en otra sección). La lógica detrás de cómo estructurar los datos JSON sería similar a la utilizada en el ejemplo mostrado anteriormente, con algunas adiciones a la misma (a saber, matrices JSON).

He aquí un ejemplo sencillo: {{cliente.Nombre}}

Si imaginamos que esto va a ser una variable utilizada en un bucle for (lo que significa que queremos asignar diferentes valores bajo la misma variable – en este caso «Nombre»), podríamos utilizar un array con objetos anidados para conseguirlo. Este es el aspecto que tendría el JSON:

Como puedes ver, tenemos una variable anidada llamada «Nombre» bajo la capa llamada «cliente», así que nuestra estructura JSON necesita reflejar eso. Primero definimos «cliente» y especificamos que es un array abriendo los corchetes. Dentro de los corchetes, podemos utilizar varios pares de llaves para definir diferentes valores para la variable «Nombre». Si no estuviéramos utilizando una matriz multidimensional (que en un escenario de la vida real también se combinaría con un bucle for), no habríamos sido capaces de utilizar la variable «Nombre» varias veces con diferentes valores. Habríamos tenido que utilizar algo parecido a «Nombre1», «Nombre2», «Nombre3», etc. Por lo tanto, la utilización de una matriz multidimensional nos ahorra trabajo, hace que nuestro JSON sea más fácil de manejar, al tiempo que nos permite reutilizar la misma variable Nombre con diferentes valores.

Echaremos un vistazo a otro array multidimensional simple en la sección For-loop, así como a uno más complejo (uno con más capas de anidamiento).

Sentencias condicionales

Las sentencias if-conditional se utilizan para introducir requisitos que determinan si debe mostrarse una información específica. También pueden incluir valores alternativos que se mostrarán si no se cumple el requisito inicial, utilizando sentencias else. Además, se puede introducir un requisito alternativo mediante la sentencia condicional elseif. Una sentencia if debe cerrarse con un operador endif.

Normalmente, las sentencias condicionales if se introducen utilizando bloques de lenguaje de plantilla en una plantilla Drag-and-Drop. Sin embargo, también pueden añadirse dentro de elementos de Texto. Estas sentencias pueden utilizarse tanto en plantillas de Marketing como Transaccionales, aunque las plantillas Transaccionales proporcionan más flexibilidad. En una plantilla transaccional, las condiciones if se pueden construir basándose en los valores de las variables var, que se envían a través de la API de envío o SMTP, así como en las variables de datos, que operan con los valores de las propiedades de los contactos. En una plantilla de Marketing, sólo se pueden utilizar variables de datos, ya que no hay forma de enviar valores para variables var.

Este es un ejemplo de una simple sentencia if-condicional utilizada en una plantilla de Marketing:

He aquí un ejemplo de uso del lenguaje de plantillas:

{% if datos:nombre %}
IMPRIMIR ESTO EN EL MENSAJE DE MARKETING
{% endif %}

En este ejemplo, el lenguaje de la plantilla comienza con una cláusula de apertura que contiene la condición propiamente dicha. Si se cumple la condición (es decir, el destinatario tiene un valor establecido en la propiedad «firstname»), el sistema mostrará el contenido dentro del bloque («PRINT THIS IN THE MARKETING MESSAGE»). La cláusula de cierre significa el final de la sección If-conditional.

La sentencia If-conditional se basa en una propiedad Contact («firstname»). El sistema comprobará si el destinatario tiene un valor establecido en la propiedad «firstname». Si la respuesta es afirmativa, el sistema incluirá el contenido del bloque en la versión final del correo electrónico. Si la respuesta es negativa, no se mostrará la cadena específica.

A continuación se muestra un ejemplo del aspecto que puede tener la versión final del correo electrónico para un destinatario que tenga definida la propiedad «firstname»:

A continuación se muestra un ejemplo de la versión final del correo electrónico para un destinatario que no tiene definida la propiedad «firstname»:

La condición If anterior comprueba si la propiedad está definida para el destinatario. Sin embargo, puede introducir un valor específico que debe tener la propiedad para que se imprima el contenido condicional. Por ejemplo

En este ejemplo, el contenido condicional «IMPRIMIR ESTO EN EL MENSAJE DE MARKETING» sólo estará presente en la versión del mensaje del destinatario si la propiedad de contacto «firstname» tiene el valor «Gina». Esta condición garantiza que el contenido se muestre exclusivamente a los destinatarios cuya propiedad «firstname» coincida con el valor especificado de «Gina».

Veamos con más detalle un par de ejemplos relacionados con plantillas transaccionales. Estos ejemplos demuestran el uso tanto de variables var como de elementos de lenguaje de Plantilla, y pueden aplicarse dentro de bloques de Texto o bloques de lenguaje de Plantilla.

Ejemplo 1: Utilización de una variable var en una plantilla transaccional

En este ejemplo, estamos comprobando si la «variable» var está definida. La condición es verdadera o falsa, actuando como una propiedad booleana.

Esto es lo que puede esperar en diferentes escenarios:

• Si la var «variable» no está definida en la llamada a la API de envío (SAPI) o en la sesión SMTP, se producirá un error en el lenguaje de plantillas. Si se añade un valor predeterminado en el if-conditional (var:variable:defaultValueHere), siempre se imprimirá «PRINT THIS STRING IN THE TRANSACTIONAL EMAIL» para los destinatarios en los que la variable no esté definida.
• Si la variable está definida como verdadera en la llamada SAPI o en la sesión SMTP, se cumplirá la condición.
• Si la variable se define como«anyValueYouCanThinkOtherThanFalse» en la llamada SAPI o en la sesión SMTP, se cumplirá la condición.
• Si la variable se establece como «false» en la llamada SAPI o en la sesión SMTP, la condición NO se cumplirá. Observe la diferencia entre «variable «false» (escenario anterior) y «variable»: false (escenario actual).

Ejemplo 2: Escaparate de otros operadores de comparación y lógicos (else, elseif y ifelse AND)

Este ejemplo muestra el uso de diferentes operadores de comparación y operadores lógicos. Incluye las sentencias if, else y elseif combinadas con el operador lógico AND.

Por último, aquí hay una captura de pantalla para proporcionar una referencia visual:

Estos ejemplos ilustran cómo las variables var y varios operadores pueden ser utilizados eficazmente dentro de las plantillas transaccionales para personalizar el contenido basado en condiciones específicas.

Ahora, examinemos pares de datos JSON junto con los resultados correspondientes que producen para el destinatario final:

JSON 1:

JSON 2:

JSON 3:

JSON4:

Básicamente, para que se muestre el valor «Consideraré la posibilidad de salir», necesitamos que se cumplan simultáneamente las siguientes condiciones: que el «tiempo» no sea «malo», que el valor de «saldoCuentaBanca» sea distinto de 0 y que la variable «tenerHoraLibre» sea verdadera (o esté definida). Si alguna de estas tres condiciones no se cumple, se mostrará el valor «No saldré» o «Me quedaré en casa», dependiendo de qué condición no se cumpla.

Tenga en cuenta el uso del operador lógico AND, que requiere el uso de paréntesis () para garantizar la correcta agrupación de las condiciones.

Bucles For

Los bucles For le permiten recorrer múltiples iteraciones de una variable o un bucle a través de una lista de variables, proporcionando flexibilidad y contenido dinámico. Es importante tener en cuenta que los bucles for sólo deben utilizarse en plantillas transaccionales y no en plantillas de marketing, ya que los valores o iteraciones no pueden introducirse en un mensaje de marketing.

Veamos una representación sencilla de un bucle for:

En este ejemplo, definimos un bucle for con el nombre de variable «Test» y especificamos el espacio de nombres donde el sistema debe buscarla (var:Test). Suponemos una variable simple con una iteración. La llamada a la API o las cabeceras SMTP deben incluir la siguiente estructura JSON:

Tenga en cuenta que la sección anterior «matrices multidimensionales» contiene una forma alternativa de presentar el mismo tipo de estructura que también puede utilizarse con bucles for.

El bucle for será sustituido por los valores proporcionados en la estructura JSON. He aquí un ejemplo de cómo sería el mensaje resultante.

Ahora, imaginemos un escenario en el que usted forma parte del equipo de Relaciones Públicas de una empresa y necesita enviar un correo electrónico al departamento Financiero. Desea comunicar los nombres, el país de residencia y los números de teléfono de contacto de tres clientes que han ganado un juego organizado por su empresa y necesitan que el equipo financiero revise su información de contacto.

Para lograrlo, puede utilizar un bucle for en su mensaje para recorrer diferentes iteraciones del mismo nombre de variable (por ejemplo, Nombre, Teléfono, etc.) y hacer que se muestren diferentes valores cada vez.

A continuación se muestra un ejemplo de cómo puede establecer una configuración de idioma de plantilla de este tipo:

En este caso, utilizamos el nombre de variable «cliente» para recorrer los detalles del cliente proporcionados en la llamada a la API o en las cabeceras SMTP. La estructura JSON debe seguir este formato:

Al utilizar este enfoque, se simplifica la estructura JSON y se reduce el riesgo de errores. El correo electrónico resultante mostrará los detalles del cliente en función de las iteraciones proporcionadas.

Por último, vamos a explorar un ejemplo más complejo que implica una estructura de matriz multidimensional. En este caso, supondremos un escenario relacionado con artículos de ropa de invierno.

Aquí está la configuración para el bucle for en la plantilla:

En este ejemplo, utilizamos la variable «value» situada bajo el espacio de nombres «items» en la estructura JSON. Especificamos dos tipos de artículos (abrigos y sombreros) con sus respectivas variables anidadas bajo múltiples capas de variables.

Así es como se vería la estructura JSON para este ejemplo:

El mensaje resultante mostraría los valores del abrigo y el gorro de invierno en función de las iteraciones proporcionadas.

Utilizando bucles for, puede iterar dinámicamente a través de variables y generar contenido personalizado en plantillas transaccionales. Es importante garantizar una estructura JSON adecuada y seguir la sintaxis del lenguaje de plantillas para lograr los resultados deseados.

Tabla de conclusiones clave de la sentencia If-conditional y los bucles For:

Bloques de texto – Bloques HTML – Bloques de lenguaje de plantillas

Cuando se trabaja con plantillas de correo electrónico, existen diferentes enfoques para incorporar estructuras de lenguaje de plantillas. Pueden introducirse a través de bloques de Texto, bloques HTML o bloques de Lenguaje de Plantillas en las plantillas Transaccionales DnD. Además, pueden incrustarse directamente en el contenido del correo electrónico.

Por lo general, es aconsejable separar el contenido HTML sin formato de las estructuras de lenguaje de plantillas siempre que sea posible. Cuando sea necesario combinarlos, como al crear una tabla con iteraciones variables utilizando un bucle for, suele ser más seguro utilizar un bloque HTML DnD e incorporar el lenguaje de plantillas dentro de él en lugar de añadir HTML sin procesar a un bloque de Lenguaje de Plantillas.

Los bloques de Lenguaje de Plantillas son especialmente útiles cuando se trabaja con sentencias If-conditional. Cada operador dentro de la condición If puede colocarse en un bloque de Lenguaje de Plantillas separado, con otros elementos DnD sirviendo como el contenido que se mostrará basado en una condición específica. Por ejemplo, puede mostrar un elemento de imagen, un elemento de vídeo o un botón si se cumplen ciertos criterios. Es posible abrir un bucle for o If-condicional en un bloque y cerrarlo en otro, proporcionando flexibilidad y organización.

Para mantener la claridad y la separación, se recomienda colocar las estructuras del lenguaje de plantillas en bloques dedicados al Lenguaje de Plantillas en lugar de mezclarlas con otros contenidos. Aunque se puede añadir texto sin formato dentro de un bloque de Lenguaje de plantillas, es mejor utilizar bloques separados para contenidos más complejos. Al combinar HTML sin formato con estructuras de lenguaje de plantillas, es aconsejable utilizar un bloque de HTML sin formato en el que el código se almacene junto con el lenguaje de plantillas, en lugar de incluir HTML sin formato dentro de un bloque de Lenguaje de plantillas.

Funciones

Como se ha comentado anteriormente, las Funciones son una parte esencial del lenguaje de plantillas de Esendex, ya que ofrecen una serie de operaciones que puede realizar el sistema. Estas funciones permiten efectos de formateo a través de diferentes áreas, tales como:

• Operaciones matemáticas: redondeo de valores numéricos.
• Manipulación de cadenas: conversión de cadenas a mayúsculas o minúsculas, o capitalización de la primera letra.
• Formateo de números: formateo de números según reglas específicas.
• Codificación de URL: conversión de una cadena a un formato seguro para URL.
• Escape de cadenas: codificación correcta de los caracteres especiales de una cadena.

Combinando estas funciones con variables, sentencias condicionales if y los operadores mencionados en la referencia del lenguaje de plantillas de Esendex, puede crear contenidos altamente personalizables y dinámicos.

En esta sección, exploraremos dos funciones específicas: la función Set y la función FormatNumberLocale.

Función Set

La función Set es una potente función que nos permite asignar un valor directamente a una variable dentro de la plantilla o del contenido del correo electrónico, eliminando la necesidad de declarar la variable en la llamada SAPI o en la sesión SMTP.

Veamos un ejemplo:

En el ejemplo anterior, utilizamos la función Set para asignar un valor a la variable «testVar» dentro de la propia plantilla. En la línea siguiente, estamos utilizando la misma variable dentro de una sentencia.

Usando la función Set, puedo enviar un mensaje con un objeto Variables vacío como este:

Este enfoque nos permite enviar mensajes sin definir explícitamente la variable en la llamada a la API, y el mensaje no se bloqueará. Este es el resultado cuando se envía el mensaje:

Uno de los aspectos interesantes de la función Set es que puede utilizarla varias veces dentro del mismo contenido para actualizar el valor de la misma variable. Veamos un ejemplo que corrige una sentencia:

En el ejemplo anterior, actualizamos el valor de la variable «testVar» dentro de la plantilla. La segunda asignación anula el valor inicial, dando como resultado la siguiente salida:

Es importante tener en cuenta que si pasa un valor para la misma variable a través de la llamada API o la sesión SMTP, no anulará el valor establecido mediante la función Set dentro de la plantilla.

Función FormatNumberLocale

La función FormatNumberLocale le permite formatear números de coma flotante (números con fracciones decimales) de acuerdo con reglas específicas. Se basa en tres propiedades:

• Formato: Especifica el formato deseado para el número.
• Número: Proporciona el número al que se desea dar formato.
• Configuración regional: Selecciona la configuración regional para determinar el punto decimal y el separador de miles.

Por ejemplo, considere el siguiente código de plantilla:

En este ejemplo, utilizamos la configuración regional francesa («fr_FR») para formatear el número 3500 utilizando el formato «#,###.00». El resultado será:

Puede ver que el número incluye ahora separadores de miles y puntos decimales según el formato francés.

La función FormatNumberLocale también admite otras variaciones de formato, como:

Estos ejemplos demuestran cómo ligeras variaciones en el formato pueden afectar al resultado. Se utiliza la configuración regional «en_GB» para el formato. Los resultados serán:

Cuando utilice variables dinámicas con la función FormatNumberLocale, asegúrese de seguir la sintaxis correcta:

Asegúrese de que la variable «var:VarName» se proporciona sin comillas ni corchetes. Además, proporcione el valor de la variable como un número entero en la llamada a la API o en la sesión SMTP:

El uso de comillas alrededor del valor provocará errores en el lenguaje de plantillas.

Estas funciones, junto con las amplias capacidades del lenguaje de plantillas de Esendex, le permiten crear contenidos altamente personalizados y dinámicos en sus correos electrónicos.

Notas adicionales

Vale la pena mencionar que las variables pueden añadirse fuera de los cuadros de texto, HTML o bloques de Lenguaje de Plantilla. Puede introducir variables en otros elementos, como hipervínculos, botones y URLs de imágenes en elementos Image DnD.

Cuando utilice una variable dentro de un hipervínculo o de la URL de un botón, puede utilizar un valor de variable predeterminado. Sin embargo, es importante tener en cuenta que no se puede utilizar una variable por defecto dentro de la URL asociada a un elemento de Image DnD. El sistema le permitirá guardar la variable en el campo URL con un valor por defecto, pero la eliminará inmediatamente.

Por favor, tenga en cuenta que al añadir una variable por defecto dentro del enlace de un elemento Botón o un hipervínculo, es posible y funciona correctamente. Sin embargo, es posible que aparezca una notificación de error en el editor, que puede ignorarse. Asegúrese de que el valor por defecto se añade sin comillas y sin protocolo HTTP/HTTPS al principio. Por ejemplo {{var:Enlace:www.esendex.com}}

Gestión de errores de plantilla

Explore este completo artículo que le guiará a través del proceso de aprovechamiento de la función de gestión de errores de plantillas de Esendex. Esta potente función automatiza la verificación de sus plantillas, ahorrándole un tiempo valioso y eliminando la necesidad de comprobaciones manuales. Despídase de la tediosa tarea de revisar individualmente cada plantilla y dé la bienvenida a un enfoque racionalizado para una gestión eficaz de los errores.

Otro punto importante a tener en cuenta es la declaración de variables en la llamada SAPI/sesión SMTP. Debe coincidir exactamente con cómo se han añadido en el contenido del mensaje. La distinción entre mayúsculas y minúsculas desempeña un papel crucial, así que esté atento a cualquier discrepancia en las mayúsculas y minúsculas. Además, cuando se utiliza un punto (.) en variables, indica objetos multidimensionales o matrices. Si se necesita un separador en lugar de indicar una estructura multidimensional, un guión bajo (_) es una mejor opción que un punto.