Cet article a pour but de vous fournir des descriptions et des explications claires des concepts fondamentaux du langage MJ Templating. Vous trouverez des exemples pratiques tout au long de l’article, qui illustrent efficacement la façon d’utiliser le langage dans des scénarios réels.

Résumé

• Types de variables
  • Données
  • Var
  • Valeurs par défaut
  • Syntaxe de la variable
• Variables prédéfinies
• Objets multidimensionnels et tableaux multidimensionnels
• Énoncés conditionnels de type « si » (If)
• Boucles « pour » (For-loops)
• Blocs de texte – Blocs HTML – Blocs de langage modèle
• Fonctions
  • Fonction Set
  • Fonction FormatNumberLocale
• Notes supplémentaires
• Gestion des erreurs de modèle

Types de variables

Esendex propose quatre types de variables, chacune ayant une fonction différente dans le langage de modélisation. Ces types de variables sont les suivants :

1. Données (statiques): Ces variables sont utilisées pour les données statiques qui ne changent pas fréquemment. Il s’agit généralement de valeurs prédéfinies.
2. Var (dynamique) : Les variables Var sont utilisées pour les données dynamiques qui peuvent changer en fonction de différentes conditions ou entrées.
3. Variables MJ prédéfinies : Ces variables sont prédéfinies par Esendex et fournissent des informations et des fonctionnalités utiles dans le langage de modélisation.
4. Structures de variables de segmentation : Ces variables sont utilisées à des fins de segmentation complexe et ne sont pas l’objet principal de cet article.

Nous nous concentrerons principalement sur les deux premiers types de variables (data et var), mais nous aborderons également brièvement les variables prédéfinies.

Les types de variables les plus couramment utilisés sont data et var. Bien qu’ils servent tous deux à remplacer une chaîne de caractères par une valeur changeant dynamiquement, ils diffèrent quant à leur mode d’utilisation, à la manière dont la valeur est fournie au système et aux types de messages dans lesquels ils peuvent être utilisés.

Outre les variables autonomes, le langage de modélisation fournit des outils (fonctions) qui permettent aux utilisateurs d’incorporer des variables dans des opérations logiques et arithmétiques plus complexes, ainsi que d’influencer le formatage et l’encodage. Dans ce guide, nous explorerons plus particulièrement l’utilisation de fonctions telles que « set » et « FormatNumberLocale ». En outre, nous nous pencherons en détail sur les instructions if-conditionnelles et les boucles for.

Données

Le type de données variable est polyvalent et peut être utilisé dans les messages marketing et transactionnels. Cette flexibilité est due au fait qu’aucune action de l’utilisateur n’est nécessaire pour fournir une valeur à l’espace réservé de la variable. Au lieu de cela, le système remplace automatiquement la valeur en fonction des objets de propriété du contact.

Que vous envoyiez une campagne ou un courriel transactionnel, tant que le message est adressé à un contact existant et que le nom de la variable correspond à une propriété de contact, le système sera en mesure de traiter la variable de données. Si le destinataire a une valeur attribuée à cette propriété, celle-ci sera affichée à la place du caractère générique de la variable.

Illustrons cela par un exemple. Supposons que je définisse la variable [[data:country]] dans le contenu de mon message et que je l’envoie à l’un de mes contacts. Dans ce scénario, deux résultats sont possibles :

1. Si le contact a défini une valeur pour la propriété « country » Contact, il recevra le message avec la variable [[data:country]] remplacée par la valeur correspondante.
2. Si le contact n’a pas de valeur définie pour la propriété Contact « country », il recevra le message sans que la variable [[data:country]] soit remplacée. Toutefois, la variable elle-même ne sera pas affichée en tant qu’élément linguistique du modèle dans la version finale du message.

Pour donner un exemple concret, considérons deux contacts : user1@domain.tld, dont la valeur de la propriété « country » est « France » et user2@domain.tld, dont la valeur de la propriété « country » n’est pas définie.

Si je leur envoie à tous les deux le même message contenant la phrase :

« Bonjour, comment vont les choses en [[data:pays]] après la pandémie ? »

Les deux contacts verront un contenu différent :

user1@domain.tld verra: « Bonjour, comment vont les choses en France après la pandémie ? »
user2@domain.tld verra le contenu suivant : « Bonjour, comment vont les choses en France après la pandémie ? « Bonjour, comment vont les choses en France après la pandémie ? »

Dans le deuxième exemple, le système n’imprime tout simplement rien parce que l’utilisateur n’a pas défini de valeur pour la propriété associée de la variable de données utilisée.

Var

Il est important de noter que la variable de type var ne doit pas être utilisée dans les modèles de marketing ou les projets de campagne. Bien qu’elle puisse être ajoutée à ces objets, toute tentative d’envoi d’un tel message se soldera par un événement BLOCKED en raison d’une erreur de langage de modélisation. Généralement, le message d’erreur indique qu’aucune valeur n’a été fournie pour la variable var, ce qui est normal puisqu’il n’existe aucun moyen d’ajouter une valeur à cette variable.

Cependant, il existe des moyens de faire fonctionner les variables var dans un modèle de marketing ou dans le cadre d’une campagne. Les deux approches les plus simples sont les suivantes :

• Ajouter une valeur par défaut à la variable var.
• Définir la variable à l’aide d’une fonction set.

Bien que ces approches fonctionnent techniquement, elles peuvent être contre-productives et moins utiles. En effet, elles vous obligent à définir la valeur de la variable dans le modèle lui-même avant l’envoi, sans permettre aucune variation de la valeur affichée en fonction du destinataire. Cela va à l’encontre de la raison d’être d’une variable et nuit à sa flexibilité.

L’utilisation correcte des variables var consiste à les inclure dans les modèles transactionnels ou directement dans le contenu des messages transactionnels. Les valeurs utilisées pour remplacer ces variables sont fournies par l’utilisateur par l’intermédiaire de l’appel API Send (en tant que partie du corps de la demande) ou pendant la session SMTP-relay (en tant qu’en-tête personnalisé), en fonction du canal transactionnel utilisé.

Pour déclarer les variables et fournir leurs valeurs respectives, des paires clé-valeur JSON sont utilisées. Par exemple, « name » :  » John » ou« testVariable123 » : « testValue« , etc.

Dans le contexte de Send API v3, l’objet qui contient les variables est appelé « Vars » Pour Send API v3.1, le principe reste le même, mais l’objet est nommé « Variables » Pour les messages générés par le relais SMTP, l’en-tête personnalisé qui doit contenir les variables encodées en JSON est « X-MJ-Vars »

Veuillez noter que pour que le langage de modélisation soit traité correctement et non comme du texte brut, le système Esendex s’appuie sur des propriétés spécifiques qui indiquent si les éléments du langage de modélisation doivent être traités comme tels. Ces propriétés sont de type booléen et vous trouverez ci-dessous le nom de la propriété appropriée pour chaque canal transactionnel :

• Send API v3 : « Mj-TemplateLanguage »
• API d’envoi v3.1 : « TemplateLanguage
• SMTP-relay : « X-MJ-TemplateLanguage »

Il est important de garder à l’esprit que la valeur par défaut de chacune de ces propriétés est « false » ou « 0 ». Si ce détail n’est pas pris en compte, même si les configurations sont correctes, les configurations de la langue du modèle peuvent ne pas fonctionner comme prévu. En effet, si les propriétés susmentionnées ne sont pas activées, le système interprète les éléments de la langue de présentation dans le message envoyé comme des chaînes de texte ordinaires, sans aucune signification supplémentaire.

Enfin, dans un scénario de niche où les utilisateurs créent des objets de projet de campagne via l’API et ont l’intention d’utiliser un langage de modélisation dans le contenu du projet de campagne, ils doivent s’assurer que l’objet« /campaigndraft/$ID/detailcontent » associé à leur projet inclut la propriété suivante dans l’objet « Headers » :

En incluant cette propriété, le système reconnaît l’utilisation d’un langage de présentation dans le contenu du projet de campagne.

Valeurs par défaut

Les variables var et data permettent l’utilisation de valeurs par défaut. Une valeur par défaut est une valeur de repli ou de sécurité que les utilisateurs fournissent à notre système lorsqu’ils configurent la variable dans le modèle ou le corps du message. Si certaines conditions sont remplies, la valeur par défaut sera affichée par notre système :

• variables de données : Si le contact qui reçoit le message n’a pas de valeur de propriété Contact définie pour cette variable/propriété de contact spécifique.
• variables var : Si aucune valeur n’est transmise via l’appel API ou la session SMTP.

Dans ces scénarios, la valeur par défaut sert de substitut pour garantir qu’il y a toujours une valeur affichée pour la variable, même lorsque les données nécessaires ne sont pas disponibles ou fournies.

Syntaxe

Compte tenu des considérations ci-dessus, examinons la syntaxe appropriée pour les variables autonomes (variables qui ne sont pas utilisées au sein d’une fonction).

Variables Var

• Pour ajouter une variable var, utilisez la syntaxe suivante : {{var:variableName}}
• Pour fournir une valeur par défaut avec la variable : {{var:nomdevariable:valeurpardéfaut}}
  Syntaxe alternative : {{var:nomdevariable : « valeurpardéfaut »}} (les deux options fonctionnent aussi bien l’une que l’autre)
• Pour imprimer un espace comme valeur par défaut, mettez-le entre guillemets : {{var:nomvariable : » »}}
• Pour ne rien afficher comme valeur par défaut, utilisez des guillemets vides : {{var:variableName : » »}}

Variables de données

• Pour ajouter une variable de données, utilisez la syntaxe suivante : [[data:contactPropertyName]]
• Pour fournir une valeur par défaut avec la variable :[[data:contactPropertyName:defaultValue]]
  Autre syntaxe possible : [[data:contactPropertyName]] : [[data:contactPropertyName : « defaultValue »]]

Note: Bien que les doubles accolades au lieu des doubles crochets fonctionnent également pour les variables de données, il est recommandé d’utiliser des crochets, sauf si des fonctions spécifiques exigent des doubles accolades.

Il est important de noter que le comportement du système diffère lorsqu’il rencontre une situation où il manque une valeur pour une variable data par rapport à une variable var. Si une variable de données n’a pas de valeur par défaut et que le contact n’a pas de valeur définie pour la propriété correspondante, un espace blanc sera imprimé dans le message. Toutefois, si une variable var n’a pas de valeur par défaut et qu’elle n’est pas déclarée dans l’appel API ou la session SMTP, le message sera bloqué.

Les valeurs par défaut ne sont pas obligatoires, mais elles peuvent être utiles pour éviter le blocage des messages. Par défaut, lorsque le système rencontre une variable var sans valeur fournie, il bloque le message. Pour influencer ce comportement, vous pouvez inclure une propriété booléenne spéciale dans votre appel API ou votre en-tête SMTP :

• Send API v3 : « Mj-TemplateErrorDeliver »
• Envoyer API v3.1 : « TemplateErrorDeliver »
• SMTP : « X-MJ-TemplateErrorDeliver »

La valeur par défaut de cette propriété est « false ». L’activation manuelle de cette propriété permet d’envoyer des messages même s’il y a des erreurs de langage de modélisation. L’activation de cette propriété empêche le blocage des messages.

Enfin, les utilisateurs peuvent choisir s’ils souhaitent être avertis par courrier électronique lorsque leurs messages sont bloqués en raison d’erreurs de langue de présentation. Cela peut être réalisé grâce à une autre propriété spéciale :

• Send API v3 : « Mj-TemplateErrorReporting » (exemple : « Mj-TemplateErrorReporting » : « reports@domain.tld »)
• Envoyer API v3.1 : « TemplateErrorReporting » (exemple : {« Email » : « reports@domain.tld », « Name » : « Recipient Name »})
• SMTP : « X-MJ-TemplateErrorReporting » (exemple d’en-tête personnalisé : X-MJ-TemplateErrorReporting : « reports@domain.tld »)

Variables prédéfinies

Dans notre système, certains noms de variables sont réservés à des variables statiques prédéfinies. Ces variables permettent aux utilisateurs de spécifier une variable qui correspond à une valeur spécifique basée sur le système. Les variables prédéfinies les plus couramment utilisées sont les suivantes

• L’ID du contact destinataire
• L’adresse électronique du contact du destinataire
• L’identifiant du modèle
• Liens partageables sur les médias sociaux pour la version en ligne de l’e-mail (Twitter, Facebook, LinkedIn, etc.) – ceci s’applique aux newsletters tout comme aux versions en ligne standard/PERMALINKS.

La syntaxe pour utiliser l’une de ces variables prédéfinies est la suivante : {{variableprédéfinieici}}.

Exemple : {{mj:template.ID}} affichera l’ID du modèle dans la version finale du message si un modèle a été utilisé pour envoyer le courrier électronique.

Veuillez noter qu’ il existe d’autres variables réservées, telles que le lien de désabonnement ou la version en ligne, qui sont introduites à l’aide de doubles crochets (par exemple, [[PERMALINK]]). Ces variables sont généralement ajoutées automatiquement par le système, mais les utilisateurs peuvent également les introduire manuellement par glisser-déposer, en HTML brut, dans les modèles MJML bruts ou dans les objets detailcontent des projets de campagne. Il est important de se rappeler que ces variables prédéfinies spéciales ne doivent pas être introduites avec des crochets. Le système les traitera comme des variables qui doivent être définies dans un appel API ou au cours d’une session SMTP (en tant que variables « var ») plutôt que comme des variables que le système peut aller chercher de lui-même.

Par conséquent, toute variable statique prédéfinie spécifiée dans la documentation de référence mentionnée ci-dessus (commençant par « mj : ») doit être introduite en utilisant« {{}}« , tandis que toute variable prédéfinie ne figurant pas dans cette documentation (ne commençant pas par « mj : ») doit être introduite en utilisant « [[]] ».

Objets multidimensionnels et tableaux multidimensionnels

Notre langage de modélisation permet l’utilisation d’objets multidimensionnels et de tableaux multidimensionnels. Ceux-ci sont utiles dans diverses situations, par exemple pour introduire des valeurs qui seraient utilisées dans une boucle « for ».

Un objet ou un tableau multidimensionnel implique des variables imbriquées les unes dans les autres. Ces objets ne sont utilisables que dans les modèles/messages transactionnels, car ils exigent que les valeurs soient fournies par l’utilisateur, ce qui doit être fait par le biais d’une structure JSON spécifique.

Voici un exemple de variable multidimensionnelle qui devrait être présentée comme un objet multidimensionnel dans les données JSON où les variables de ce message seront déclarées :

{{var:clothes.winter.coat}}

Chaque point (« . ») représente une « couche » d’imbrication – la valeur la plus à gauche indique le niveau le plus externe, tandis que plus nous nous déplaçons vers la droite, plus nous descendons dans la structure imbriquée. Voici la structure JSON correcte qui doit être utilisée pour que notre système localise correctement la valeur de la variable « clothes.winter.coat » (l’exemple inclut la propriété « Variables » de la v3.1, mais celle-ci varie en fonction du canal transactionnel utilisé, comme nous l’avons vu dans une section précédente):

La configuration ci-dessus entraînerait l’affichage du mot « blazer » à l’endroit où « {{var:clothes.winter.coat}} » a été placé dans le modèle/contenu de l’e-mail.

Les tableaux multidimensionnels sont quant à eux plus couramment utilisés, notamment dans les boucles for (nous y reviendrons dans une autre section). La logique qui sous-tend la structuration des données JSON serait similaire à celle utilisée dans l’exemple ci-dessus, avec quelques ajouts (à savoir, les tableaux JSON).

Voici un exemple simple : {{client.Nom}}

Si nous imaginons qu’il s’agit d’une variable utilisée dans une boucle for (ce qui signifie que nous voulons attribuer différentes valeurs à la même variable – dans ce cas « Nom »), nous pourrions utiliser un tableau avec des objets imbriqués pour y parvenir. Voici à quoi ressemblerait le JSON :

Comme vous pouvez le voir, nous avons une variable imbriquée appelée « Name » sous la couche appelée « customer », donc notre structure JSON doit refléter cela. Nous définissons d’abord « client » et nous spécifions qu’il s’agit d’un tableau en ouvrant les crochets. À l’intérieur des crochets, nous pouvons utiliser plusieurs paires d’accolades pour définir différentes valeurs pour la variable « Name ». Si nous n’utilisions pas un tableau multidimensionnel (qui, dans un scénario réel, serait également combiné à une boucle for), nous n’aurions pas pu utiliser la variable « Nom » plusieurs fois avec des valeurs différentes. Nous aurions dû utiliser quelque chose comme « Nom1 », « Nom2 », « Nom3 », etc. Ainsi, l’utilisation d’un tableau multidimensionnel nous épargne du travail, rend notre JSON plus facile à gérer, tout en nous permettant de réutiliser la même variable Name avec des valeurs différentes.

Nous examinerons un autre tableau multidimensionnel simple dans la section For-loop, ainsi qu’un tableau plus complexe (avec plusieurs niveaux d’imbrication).

Déclarations conditionnelles

Les instructions « si » sont utilisées pour introduire des exigences qui déterminent si un élément d’information spécifique doit être affiché. Elles peuvent également inclure des valeurs alternatives à afficher si l’exigence initiale n’est pas satisfaite, à l’aide d’instructions else. En outre, une exigence alternative peut être introduite à l’aide de l’instruction conditionnelle elseif. Une instruction if doit être fermée par l’opérateur endif.

En règle générale, les instructions conditionnelles if sont introduites à l’aide de blocs de langage de modèle dans un modèle Glisser-Déposer. Toutefois, elles peuvent également être ajoutées dans des éléments de texte. Ces instructions peuvent être utilisées à la fois dans les modèles marketing et transactionnels, bien que les modèles transactionnels offrent une plus grande flexibilité. Dans un modèle transactionnel, les conditionnelles peuvent être construites sur la base des valeurs des variables var, qui sont transmises via l’API d’envoi ou le SMTP, ainsi que des variables data, qui fonctionnent avec les valeurs des propriétés des contacts. Dans un modèle Marketing, seules les variables de données peuvent être utilisées car il n’y a aucun moyen de pousser les valeurs des variables var.

Voici un exemple d’instruction if-conditionnelle simple utilisée dans un modèle de marketing :

Voici un exemple d’utilisation du langage des modèles :

{% if data:firstname %}
IMPRIMER CECI DANS LE MESSAGE MARKETING
{% endif %}

Dans cet exemple, le langage du modèle commence par une clause d’ouverture qui contient la condition elle-même. Si la condition est remplie (c’est-à-dire que le destinataire a une valeur définie dans la propriété « firstname »), le système affiche le contenu du bloc (« PRINT THIS IN THE MARKETING MESSAGE »). La clause de fermeture marque la fin de la section If-conditional.

L’instruction If-conditional s’appuie sur une propriété Contact (« firstname »). Le système vérifie si le destinataire a une valeur définie dans la propriété « firstname ». Si la réponse est positive, le système inclura le contenu du bloc dans la version finale de l’e-mail. Si la réponse est négative, la chaîne spécifique ne sera pas affichée.

Voici un exemple de ce à quoi peut ressembler la version finale de l’e-mail pour un destinataire dont la propriété « firstname » est définie :

Voici un exemple de la version finale de l’e-mail pour un destinataire qui n’a pas de propriété « prénom » définie :

La condition If ci-dessus vérifie si la propriété est définie pour le destinataire. Cependant, vous pouvez introduire une valeur spécifique que la propriété doit avoir pour que le contenu conditionnel soit imprimé. Par exemple :

Dans cet exemple, le contenu conditionnel « IMPRIMEZ CECI DANS LE MESSAGE MARKETING » ne sera présent dans la version du message destinée au destinataire que si la propriété « prénom » du contact est définie sur la valeur « Gina ». Cette condition garantit que le contenu s’affiche exclusivement pour les destinataires dont la propriété « prénom » correspond à la valeur spécifiée de « Gina ».

Examinons de plus près quelques exemples impliquant des modèles transactionnels. Ces exemples illustrent l’utilisation des variables var et des éléments de langage Template, et ils peuvent être appliqués dans des blocs de texte ou des blocs de langage Template.

Exemple 1 : Utilisation d’une variable var dans un modèle transactionnel

Dans cet exemple, nous vérifions si la « variable » var est définie. La condition est soit vraie, soit fausse, agissant comme une propriété booléenne.

Voici ce à quoi vous pouvez vous attendre dans différents scénarios :

• Si la variable « variable » n’est pas définie dans l’appel API d’envoi (SAPI) ou dans la session SMTP, il en résultera une erreur de langage Template. L’ajout d’une valeur par défaut dans la condition if (var:variable:defaultValueHere) imprimera toujours « PRINT THIS STRING IN THE TRANSACTIONAL EMAIL » pour les destinataires pour lesquels la variable n’est pas définie.
• Si la variable est définie comme vraie dans l’appel SAPI ou la session SMTP, la condition sera remplie.
• Si la variable est définie comme« anyValueYouCanThinkOfOtherThanFalse » dans l’appel SAPI ou la session SMTP, la condition sera remplie.
• Si la variable est définie comme  » false  » dans l’appel SAPI ou la session SMTP, la condition ne sera PAS remplie. Notez la différence entre « variable » : « false » (scénario précédent) et « variable » : false (scénario actuel).

Exemple 2 : Présentation d’autres opérateurs logiques et de comparaison (else, elseif et ifelse AND)

Cet exemple illustre l’utilisation de différents opérateurs de comparaison et opérateurs logiques. Il comprend les instructions if, else et elseif combinées à l’opérateur logique AND.

Enfin, voici une capture d’écran à titre de référence visuelle :

Ces exemples illustrent comment les variables var et divers opérateurs peuvent être utilisés efficacement dans les modèles transactionnels pour personnaliser le contenu en fonction de conditions spécifiques.

Examinons maintenant les paires de données JSON et les résultats correspondants qu’elles produisent pour le destinataire final :

JSON 1 :

JSON 2 :

JSON 3 :

JSON4 :

Essentiellement, pour que la valeur « Je vais envisager de sortir » soit affichée, il faut que les conditions suivantes soient remplies simultanément : le « temps » ne doit pas être « mauvais », la valeur « bankAccountBalance » doit être différente de 0, et la variable « haveFreeTime » doit être vraie (ou définie). Si l’une de ces trois conditions n’est pas remplie, la valeur « Je ne sortirai pas » ou « Je resterai à la maison » sera affichée, selon la condition qui n’est pas remplie.

Veuillez noter l’utilisation de l’opérateur logique ET, qui nécessite l’utilisation de parenthèses () pour assurer un regroupement correct des conditions.

Boucles for-loop

Les boucles « for » vous permettent de parcourir plusieurs itérations d’une variable ou d’effectuer une boucle dans une liste de variables, ce qui offre une grande souplesse et un contenu dynamique. Il est important de noter que les boucles for ne doivent être utilisées que dans les modèles transactionnels et non dans les modèles marketing, car les valeurs ou les itérations ne peuvent pas être introduites dans un message marketing.

Examinons une représentation simple d’une boucle for :

Dans cet exemple, nous définissons une boucle for avec le nom de variable « Test » et spécifions l’espace de noms dans lequel le système doit la rechercher (var:Test). Nous supposons qu’il s’agit d’une variable simple avec une itération. L’appel API ou les en-têtes SMTP doivent inclure la structure JSON suivante :

Veuillez noter que la section précédente « tableaux multidimensionnels » contient une autre façon de présenter le même type de structure qui peut également être utilisée avec les boucles « for ».

La boucle for sera remplacée par les valeurs fournies dans la structure JSON. Voici un exemple de ce à quoi ressemblerait le message résultant.

Imaginons maintenant un scénario dans lequel vous faites partie de l’équipe des relations publiques d’une entreprise et devez envoyer un courrier électronique au service financier. Vous souhaitez communiquer les noms, pays de résidence et numéros de téléphone de trois clients qui ont gagné à un jeu organisé par votre entreprise et dont les coordonnées doivent être vérifiées par l’équipe financière.

Pour ce faire, vous pouvez utiliser une boucle for dans votre message pour faire défiler différentes itérations du même nom de variable (par exemple, Nom, Téléphone, etc.) et afficher des valeurs différentes à chaque fois.

Voici un exemple de configuration d’un modèle de langue :

Dans ce cas, nous utilisons le nom de variable « customer » pour parcourir les détails du client fournis dans l’appel API ou les en-têtes SMTP. La structure JSON doit suivre ce format :

En utilisant cette approche, vous simplifiez la structure JSON et réduisez le risque d’erreurs. L’e-mail résultant affichera les détails du client en fonction des itérations fournies.

Enfin, explorons un exemple plus complexe qui implique une structure de tableau multidimensionnel. Dans ce cas, nous supposerons un scénario lié aux vêtements d’hiver.

Voici la configuration de la boucle for dans le modèle :

Dans cet exemple, nous utilisons la variable « value » située dans l’espace de noms « items » de la structure JSON. Nous spécifions deux types d’articles (manteaux et chapeaux) avec leurs variables respectives imbriquées sous plusieurs couches de variables.

Voici à quoi ressemblerait la structure JSON de cet exemple :

Le message qui en résulte affiche les valeurs du manteau et du chapeau d’hiver en fonction des itérations fournies.

En utilisant des boucles for, vous pouvez itérer dynamiquement à travers les variables et générer un contenu personnalisé dans les modèles transactionnels. Il est important de veiller à la bonne structure JSON et de respecter la syntaxe du langage des modèles pour obtenir les résultats souhaités.

Tableau des principaux enseignements de l’instruction If-conditional et des boucles For-loops :

Blocs de texte – Blocs HTML – Blocs de langage de modèle

Lorsque l’on travaille avec des modèles de courrier électronique, il existe différentes approches pour incorporer des structures de langage de modèle. Elles peuvent être introduites par le biais de blocs de texte, de blocs HTML ou de blocs de langage de modèle dans les modèles transactionnels DnD. En outre, elles peuvent être directement intégrées dans le contenu de l’e-mail.

Il est généralement conseillé de séparer, dans la mesure du possible, le contenu HTML brut des structures de langage des modèles. Lorsqu’il est nécessaire de les combiner, par exemple pour créer un tableau avec des itérations variables à l’aide d’une boucle for, il est généralement plus sûr d’utiliser un bloc HTML DnD et d’y incorporer le langage de modèle plutôt que d’ajouter du HTML brut à un bloc de langage de modèle.

Les blocs de langage de gabarit sont particulièrement utiles lorsque l’on travaille avec des instructions de type « Si ». Chaque opérateur de la condition If peut être placé dans un bloc de langage de gabarit distinct, avec divers autres éléments DnD servant de contenu qui sera affiché en fonction d’une condition spécifique. Par exemple, vous pouvez afficher une image, une vidéo ou un bouton si certains critères sont remplis. Il est possible d’ouvrir une boucle « for » ou une condition « if » dans un bloc et de la fermer dans un autre, ce qui offre souplesse et organisation.

Pour maintenir la clarté et la séparation, il est recommandé de placer les structures de langage des modèles dans des blocs dédiés au langage des modèles plutôt que de les mélanger à d’autres contenus. Bien qu’il soit possible d’ajouter du texte brut dans un bloc de langage de gabarit, il est préférable d’utiliser des blocs distincts pour les contenus plus complexes. Lorsque l’on combine du HTML brut avec des structures de langage de gabarit, il est conseillé d’utiliser un bloc de HTML brut où le code est stocké à côté du langage de gabarit, plutôt que d’inclure du HTML brut dans un bloc de langage de gabarit.

Fonctions

Comme nous l’avons vu précédemment, les fonctions sont une partie essentielle du langage de modélisation d’Esendex, offrant une gamme d’opérations qui peuvent être effectuées par le système. Ces fonctions permettent des effets de formatage dans différents domaines, tels que :

• Opérations mathématiques : arrondir les valeurs numériques.
• Manipulation des chaînes de caractères : conversion des chaînes en majuscules ou en minuscules, ou mise en majuscules de la première lettre.
• Formatage des nombres : formatage des nombres en fonction de règles spécifiques.
• Encodage d’URL : conversion d’une chaîne en un format URL sûr.
• Échapper à la chaîne : s’assurer que les caractères spéciaux d’une chaîne sont correctement encodés.

En combinant ces fonctions avec des variables, des instructions conditionnelles et des opérateurs mentionnés dans la référence du langage de modèle d’Esendex, vous pouvez créer un contenu hautement personnalisable et dynamique.

Dans cette section, nous allons explorer deux fonctions spécifiques : la fonction Set et la fonction FormatNumberLocale.

Fonction Set

La fonction Set est une fonction puissante qui nous permet d’affecter une valeur directement à une variable dans le modèle ou le contenu du courrier électronique, sans qu’il soit nécessaire de déclarer la variable dans l’appel SAPI ou la session SMTP.

Prenons un exemple :

Dans l’exemple ci-dessus, nous utilisons la fonction Set pour attribuer une valeur à la variable « testVar » dans le modèle lui-même. À la ligne suivante, nous utilisons la même variable dans une phrase.

En utilisant la fonction Set, je peux pousser un message avec un objet Variables vide comme ceci :

Cette approche nous permet d’envoyer des messages sans définir explicitement la variable dans l’appel à l’API, et le message ne sera pas bloqué. Voici le résultat de l’envoi du message :

L’un des aspects intéressants de la fonction Set est qu’elle peut être utilisée plusieurs fois dans le même contenu pour mettre à jour la valeur de la même variable. Voyons un exemple qui corrige une déclaration :

Dans l’exemple ci-dessus, nous mettons à jour la valeur de la variable « testVar » dans le modèle. La deuxième affectation remplace la valeur initiale, ce qui donne le résultat suivant :

Il est important de noter que si vous transmettez une valeur pour la même variable par l’intermédiaire de l’appel API ou de la session SMTP, elle ne remplacera pas la valeur définie à l’aide de la fonction Set dans le modèle.

Fonction FormatNumberLocale

La fonction FormatNumberLocale permet de formater les nombres à virgule flottante (nombres avec fractions décimales) selon des règles spécifiques. Elle s’appuie sur trois propriétés :

• Format : Spécifie le format souhaité pour le nombre.
• Nombre : Fournit le nombre à formater.
• Locale : Sélectionne la locale pour déterminer le point décimal et le séparateur de milliers.

Prenons l’exemple du modèle de code suivant :

Dans cet exemple, nous utilisons la locale française (« fr_FR ») pour formater le nombre 3500 en utilisant le format « #,####.00 ». Le résultat sera le suivant :

Vous pouvez voir que le nombre comprend maintenant des séparateurs de milliers et des points décimaux selon le format français.

La fonction FormatNumberLocale prend également en charge d’autres variantes de format, telles que :

Ces exemples montrent comment de légères variations dans le format peuvent affecter le résultat. La locale « en_GB » est utilisée pour le formatage. Les résultats seront les suivants :

Lorsque vous utilisez des variables dynamiques avec la fonction FormatNumberLocale, veillez à respecter la syntaxe correcte :

Veillez à ce que la variable « var:VarName » soit fournie sans guillemets ni parenthèses. En outre, fournissez la valeur de la variable sous la forme d’un nombre entier dans l’appel API ou la session SMTP :

L’utilisation de guillemets autour de la valeur provoquera des erreurs dans le langage de programmation.

Ces fonctions, ainsi que les vastes capacités du langage de template d’Esendex, vous permettent de créer un contenu hautement personnalisé et dynamique dans vos courriels.

Notes supplémentaires

Il convient de mentionner que des variables peuvent être ajoutées en dehors des zones de texte, des blocs HTML ou des blocs de langage de modèle. Vous pouvez introduire des variables dans divers autres éléments, tels que les hyperliens, les boutons et les URL d’images dans les éléments Image DnD.

Lorsque vous utilisez une variable dans un hyperlien ou dans l’URL d’un bouton, vous pouvez utiliser une valeur de variable par défaut. Cependant, il est important de noter que vous ne pouvez pas utiliser une variable par défaut dans l’URL associée à un élément Image DnD. Le système vous permettra d’enregistrer la variable dans le champ URL avec une valeur par défaut, mais il la supprimera immédiatement.

Gardez à l’esprit que l’ajout d’une variable par défaut dans le lien d’un élément Bouton ou d’un hyperlien est possible et fonctionne correctement. Cependant, vous pouvez rencontrer une notification d’erreur dans l’éditeur, qui peut être ignorée. Veillez à ce que la valeur par défaut soit ajoutée sans guillemets et sans protocole HTTP/HTTPS au début. Par exemple : {{var:Link:www.esendex.com}}

Gestion des erreurs de gabarit

Découvrez cet article complet qui vous guidera dans le processus d’exploitation de la fonction de gestion des erreurs des modèles d’Esendex. Cette fonction puissante automatise la vérification de vos modèles, ce qui vous permet de gagner un temps précieux et d’éliminer les vérifications manuelles. Dites adieu à la tâche fastidieuse d’examiner individuellement chaque modèle, et accueillez une approche rationalisée de la gestion efficace des erreurs.

Un autre point important à prendre en considération est la déclaration des variables dans l’appel SAPI/la session SMTP. Elle doit correspondre exactement à la manière dont elles ont été ajoutées dans le contenu du message. La sensibilité à la casse joue un rôle crucial, il convient donc d’être vigilant en cas de divergence entre les majuscules et les minuscules. En outre, l’utilisation d’un point (.) dans les variables indique qu’il s’agit d’objets multidimensionnels ou de tableaux. Si un séparateur est nécessaire au lieu d’indiquer une structure multidimensionnelle, un trait de soulignement (_) est un meilleur choix que le point.