Coder dans sa Newsletter

par | Déc 13, 2021

La génération du code html d’une newsletter envoyée par Mindbaz utilise un moteur Perl de templating (PERL TEMPLATE TOOLKIT) qui vous permet d’utiliser de nombreuses fonctions et instructions à l’intérieur de votre message HTML.

Le Template Toolkit est une boîte à outils rapide et flexible qui est mise à votre disposition pour vous aider à rendre vos contenus HTML dynamiques.

Il est écrit en langage Perl mais vous n’avez pas besoin de connaître Perl pour pouvoir l’utiliser!

Si vous voulez allez plus loin dans l’utilisation du Template Toolkit, la documentation est disponible ici http://template-toolkit.org/docs/index.html

La documentation existe également sous forme de livre et est publié chez O’reilly

Perl Template Toolkit Book

1.Principales instructions

 

Une instruction du Template Toolkit dans Mindbaz doit toujours commencer par  [[  et finir par ]]. Si elle est sur plusieurs lignes, il faut mettre un ; à la fin de la ligne.

 

Par ex,


[[ i = 5 ]]
[[ j = 8 ]]
[[ k = i * j + 7 ]]

est équivalent à :


[[ i = 5;
j = 8;
k = i * j + 7 ]]

 

Remarque : Dans la documentation en ligne ou sur internet, vous pourrez trouver d’autres délimiteurs que [[]] car c’est un paramètre qui est configurable. Dans la documentation en ligne par ex, ils utilisent [% %].

 

Voici une présentation des principales instructions.

a. Afficher un champ de personnalisation de l’abonné

Vous pouvez afficher facilement la valeur des champs de vos abonnés avec le tag [[FIELD.XX]] (avec XX=id du champ).

ex: [[FIELD.14]] pour afficher le nom de l’abonné

La liste de vos champs avec leur id sont disponibles dans mindbaz dans la page “Gestion des champs” (dans le menu “Base de données”)

b. Afficher un champ de configuration

 

D’autres données « système » sont également utilisables dans votre HTML. Ce sont des informations spécifiques à votre base de données ou à votre envoi (id, nom…).

Ils s’écrivent comme ceci : [[CONF.N]] avec N le numéro dans la liste ci-dessous :

 

CONF.Nchamps configurés
CONF.1Identifiant de la base (défini lors du setup de base)
CONF.2Nom du site web (défini lors du setup de base)
CONF.3Url du site web (défini lors du setup de base)
CONF.5Id de la campagne
CONF.6Id du segment
CONF.7Id de l’envoi
CONF.8Date de la génération du message
CONF.9Id du job de génération
CONF.10Id du lien tracké (uniquement dans une url trackée)
CONF.11Id de la campagne dynamique
CONF.12Type du lien tracké (1:desabo, 2:miroir, 3:edito, 4:pub, 5:viral)
CONF.100Id de la configuration d’envoi
CONF.101Nom de la configuration d’envoi
CONF.104Email de l’expéditeur
CONF.105Alias de l’expéditeur
CONF.106Alias de l’adresse du destinataire
CONF.107Email de réponse
CONF.108Alias de l’adresse de réponse
CONF.111Entête HTML
CONF.112Entête TXT
CONF.113Pied de page HTML
CONF.114Pied de page TXT
CONF.115Désabonnement HTML
CONF.116Désabonnement TXT
SPYPIXposition manuellement le SPYPIXEL de tracking des ouvertures

 

Nous les utilisons par ex dans nos liens de désabonnement :

http://unsub.mindbaz.com/?e=[[FIELD.1]]&s=[[CONF.7]]&b=[[CONF.1]]

 

Vous pouvez également les utiliser dans vos liens par exemple si vous travaillez avec un partenaire qui a besoin de dédupliquer les clics de vos envois, vous pouvez ajouter un paramètre avec comme valeur: [[CONF.1]]-[[CONF.7]]-[[FIELD.0]]

 

Cela donnera une valeur unique par base>envoi>abonné

 

Les tags  [[CONF.111]] à [[CONF.116]] et le tag [[SPYPIX]] vous permettent de placer manuellement dans votre HTML les entêtes et pieds de page de votre campagne, ainsi que le pixel caché d’ouverture!

 

c. utiliser une variable

 

Grâce au Template Toolkit, vous pouvez déclarer et utiliser des variables dans votre HTML de newsletter.

 

Vous déclarez vos variables en choisissant un nom. Le type est déterminé dynamiquement en fonction de la valeur que vous assignez. Vous pouvez même stocker la valeur d’un champ de personnalisation dans une variable :


[[ variableText = 'mon texte';
variableNombre = 33;
variableDate = FIELD.2;
variableTableau =[ 'red', 'green', 'blue' ];
variableObject =  {
     id    => 'XYZ-2000',
     desc  => 'Bogon Generator',
     price => 666,
   };
]]

Ce bloc de code n’affiche rien dans votre HTML, il ne fait qu’initialiser des variables. Pour les afficher dans le HTML, il faut les appeler avec le nom de la variable dans un bloc [[]] tout simplement. 

Dans notre exemple cela donne:

[[variableText]]
[[variableNombre]]
[[variableDate]]
[[variableTableau.0 ]]
[[variableTableau.1 ]]
[[variableTableau.2 ]] 
[[variableObject.id]]
[[variableObject.desc]]
[[variableObject.price]]

<br /><br />

Affichera :

mon texte
33
2020/07/28 17:47:12
red
green
blue
XYZ-2000
Bogon Generator
666

 

A quoi ça sert?

Les variables sont très utiles pour structurer votre HTML afin de le rendre plus compréhensible et plus facile à maintenir.

 

  • Si vous avez des blocs qui se répètent dans votre HTML
  • Si vous avez des blocs conditionnels identiques à plusieurs endroits de votre HTML, vous définissez une seule fois la condition dans une variable au début et l’utilisez plusieurs fois dans le bloc IF (cf ex §1.d IF ELSE ELSIF).

 

Elles sont aussi utilisées pour stocker un objet récupéré par un tag CONTENT ou INCLUDE. Par ex, un produit d’un panier abandonné (cf. ex §1.e FOREACH).

d. Les blocs conditionnels :

Le IF permet d’exécuter un bloc de code si la condition est remplie.

[[IF age < 10]]
   Hello [[ name ]], does your mother know you're using her AOL account?
[[ELSIF age < 18]]
   Sorry, you're not old enough to enter 
   (and too dumb to lie about your age)
[[ELSE]]
   Welcome [[ name ]].
[[END]]
Il est très utilisé dans les newsletters pour adapter le contenu de l’objet ou du message en fonction du champ civilité:
Bonjour [[IF FIELD.13 == 'MR' ]]Monsieur[[ELSE]]Madame[[END]], ...
Voici un exemple avec une variable dans laquelle on stocke le résultat du calcul du nombre de jours passés depuis la dernière ouverture (FIELD.44) et qui affiche un html différent en fonction de cette variable:

[[ nbJoursOuv = date.calc.Delta_Days(date.format(FIELD.44,'%Y'), date.format(FIELD.44,'%m'), date.format(FIELD.44,'%d'),
date.format(date.now,'%Y'), date.format(date.now,'%m'), date.format(date.now,'%d') ) ]] 

  [[IF nbJoursOuv <14]] html abonné actif ici   [[ELSIF nbJoursOuv >60]] html abonné inactif ici
  [[ELSE]] html abonné normal ici
  [[END]]
L’instruction SWITCH/CASE est une autre forme de création de blocs conditionnels. Elle exécute tout d’abord une expression (celle du SWITCH) puis compare son résultat à plusieurs cas (les CASE). La comparaison est faite dans l’ordre et dès qu’un cas correspond, le switch s’arrête sans tester les autres cas. L’ordre des CASE est donc important.   Voici un exemple dans lequel on affiche le bon horoscope de l’abonné en fonction de son signe du zodiac:

[[SWITCH FIELD.20|zodiac_num]]
  [[CASE 1]]
BÉLIER - Horoscope du jour<br/>
Sous l'aile de Vénus, vos relations conjugales devraient vous combler. Vous établirez avec votre conjoint de solides liens de complicité. Beaucoup...
 [[CASE 2]]
TAUREAU - Horoscope du jour<br/>
Conseil de Neptune : en couple, rien ne vaut la franchise. "Parler franchement est le meilleur procédé" (Homère). Mais cela ne veut évidemment...
[[CASE 3]]
GÉMEAUX - Horoscope du jour<br/>
En couple, tout est possible : la solitude pour ceux qui placeront la barre trop haut ; une rupture pour ceux qui refuseront de faire des concessions....
(…)
[[CASE 10]]
CAPRICORNE - Horoscope du jour<br/>
Le cadeau de la journée, ce sera sans conteste l'influence de Vénus sur votre secteur d'amour. En formant une configuration favorable, cette...
[[CASE 11]]
VERSEAU - Horoscope du jour<br/>
La jalousie fera son apparition dans votre vie de couple et donnera lieu à des discussions que vous pourriez parfaitement éviter en y mettant...
[[CASE 12]]
POISSONS - Horoscope du jour<br/>
Avec la bénédiction de Vénus, tout baignera pour les célibataires. Les relations seront empreintes de ferveur sensuelle. En couple, si de graves...
[[END]]<br/>
 

e. Les boucles :

Une boucle FOREACH permet d’exécuter un bloc de code pour chaque élément d’une liste.

Voici un exemple qui affiche les jours de la semaine :



[[ 
    jourSemaine = [ 'Lundi', 'Mardi', 'Mercredi', 'Jeudi', 'Vendredi', 'Samedi', 'Dimanche']
    ]]
    Jours de la semaine
[[ FOREACH jour IN jourSemaine ]]
   * [[ jour ]] 
[[ END ]]
  

Affichera

Jour de la semaine:
Lundi
Mardi
Mercredi
Jeudi
Vendredi
Samedi
Dimanche

Autre exemple semblable mais à partir d’un tableau d’objets :

Code Perl Template Tooklit 2

Affichera :

Jour de la semaine:
Lundi : pluie
Mardi : pluie
Mercredi : orage
Jeudi : nuageux
Vendredi : soleil
Samedi : soleil
Dimanche : nuageux

Voici un exemple plus complexe de boucle foreach qui construit un tableau pour afficher le contenu d’un panier abandonné :

Code Perl Template Tooklit

Affichera:

Rendu Perl Template Tooklit
Ici, notre tableau est initialisé depuis un appel d’une url externe au moment de la génération de la newsletter. Nous appelons ce type d’url un “INCLUDE” car il permet d’inclure du HTML depuis votre url. Cela permet de facilement rendre dynamique le contenu de votre newsletter!   Dans cet exemple, l’url est https://preprod-ws.mindbaz.com/test/event.html Elle retourne ce code (en statique pour le test):

[[ event = {
  	id_event = 103
  	event_date = '2019-03-21 16:31:51'
  	event_user = 'george.abitbol@gmail.com'
  	event_action = 'purchase'
  	event_id_cart = '4840cb87cee1fc5118e5183f84a4ec9e'
  	cart_nb_products = 2
  	cart_date = '2019.05.22 15:01:02'  	
    cart_total_TTC = 43.7
  	custom = { 
  		"name" ='Abitbol'
  		first_name =  'George'
  		id_client = 12345
  		id_carte_fid = '1324QA45S434'
  		id_transac = 12456789
  		nom_mag = 'la_classe_americaine'  		
  		sub_total_ht = 30.49
  		sub_total_ttc = 36.49
  		shipping_ttc = 0
  		refund_ttc = 0
  		total_ttc = 43.7
 		
  		cart_lines =  [
  			{
  				id_product = 100
  				product_ean = '15165'
  				product_name = 'clavier'
  				product_desc = 'blablabla'
  				product_img_url = 'https://encrypted-tbn2.gstatic.com/shopping?q=tbn:ANd9GcSVYiLBhez8buAcEnh0tcL672W8FPidOupv20pUI7SODq7tZBc__xjAgig-bRCOkvCDCcNBxq1y5DY&usqp=CAc'
  				product_link_url = 'https://www.amazon.fr/ZzZz-Domination-M%C3%A9canique-Mecanique-r%C3%A9tro%C3%A9clairage/dp/B07MN97HV4/ref=asc_df_B07MN97HV4/?tag=googshopfr-21&linkCode=df0&hvadid=314669187343&hvpos=1o2&hvnetw=g&hvrand=327094231229743397&hvpone=&hvptwo=&hvqmt=&hvdev=c&hvdvcmdl=&hvlocint=&hvlocphy=9055774&hvtargid=pla-686080091901&psc=1&tag=&ref=&adgrpid=66664358310&hvpone=&hvptwo=&hvadid=314669187343&hvpos=1o2&hvnetw=g&hvrand=327094231229743397&hvqmt=&hvdev=c&hvdvcmdl=&hvlocint=&hvlocphy=9055774&hvtargid=pla-686080091901'
  				product_category = 'informatique'  				
  				product_price_ttc = 20.5
  				product_discount_ttc = 0
  				line_qty = 1
  				line_total_ttc = 20.5
			},
  			{
  				id_product = 200
  				product_ean = '15165'
  				product_name = 'souris'
  				product_desc = 'blablabla'
			  	product_img_url = 'https://encrypted-tbn1.gstatic.com/shopping?q=tbn:ANd9GcStriPS7LTFkB_qfjM7O3C4ggiZosldyIKOLa614cLjGcDWDgOSOzqr87eALWYc4sUploUrEdOnXcc&usqp=CAc'
  				product_link_url = 'https://www.amazon.fr/VicTsing-R%C3%A9cepteur-R%C3%A9glables-Ordinateur-Portable/dp/B00ZX6VST8/ref=sr_1_3?__mk_fr_FR=%C3%85M%C3%85%C5%BD%C3%95%C3%91&crid=2JW5RI5ID8XSC&keywords=souris+sans+fil&qid=1558601276&s=computers&sprefix=souri%2Ccomputers%2C136&sr=1-3'
  				product_category = 'informatique'	
  				product_price_ttc = 15.99
  				product_discount_ttc = 0
  				line_qty = 1
  				line_total_ttc = 15.99
			}  
  		]
  	} 
  } ]]

L’url d’include se charge de trouver les bonnes données à afficher et la newsletter se charge de son affichage. 

Une boucle while permet de répéter l’exécution d’un bloc tant que l’expression dans la condition est vraie

par ex pour afficher des nombres de 1 à 100 :


[[WHILE n<=100 ]]
	[[n]]
	[[n = n + 1]]
[[END]]

Remarque : En cas de boucle infinie, une exception sera levée lors de la génération de la newsletter et aucun email sera envoyé.

 

Voici un autre exemple de génération d’une image de palette de couleurs fabriquée à partir d’un tableau HTML :

Code Perl Template Tooklit 3

Affichera :

Rendu Perl Template Tooklit 2

f. les commentaires

Les commentaires en HTML alourdissent inutilement votre HTML. Ils consomment de la bande passante et de l’espace de stockage inutilement!

Vous pouvez utiliser les commentaires du Template Toolkit à la place:

  • ils sont toujours visibles dans votre éditeur de HTML de votre campagne
  • ils sont effacés lors de la génération du HTML final! Le FAI et vos abonnés ne pourront pas voir vos commentaires.

 

Vous pouvez donc utiliser autant de commentaires entre [[ ]] que vous voulez, la planète ne vous dira rien 😉

La syntaxe :


[[ # commentaire sur une seule ligne
a=1;  #autre commentaire
]]

[[# commentaire 
du bloc complet]]

2. Les fonctions utiles 

Quelques fonctions existent et permettent de modifier une valeur d’une variable, d’un champ de perso FIELD ou de configuration CONF.   Une fonction s’applique sur une valeur avec le caractère “|” :

[[ mavariable | fonction]]
[[ FIELD.XX | fonction]]
Voici les fonctions les plus utilisées dans les newsletters Mindbaz

a. fonctions dates

  • récupérer la date d’aujourd’hui

La date du jour peut etre obtenue avec l’instruction date.now

[[ date.format(date.now)]]
affichera 13/12/2021   Remarque : si vous souhaitez afficher la date au moment de l’envoi de la newsletter, préférez utiliser CONF.8 à la place de date.now. La différence se verra dans la page miroir car date.now correspondera à la date du jour de l’affichage de la page miroir!  
  • formater une date

Pour changer le format d’affichage d’une date, il faut utiliser la méthode : date.format(date, ‘format’) le format par défaut est ‘%d/%m/%Y’, c’est à dire JJ/MM/AAAA  [[ date.format(FIELD.3, '%d/%m/%Y %H:%M:%S')]] affichera 18/03/2021 09:44:16 (date de dernière inscription)
[[ date.format(date.now,'%A %d %B %Y') ]]
affichera lundi 02 août 2021 (date du jour)
[[ date.format(CONF.8,'%y-%m-%d') ]]
affichera 21-08-02 (date de l’envoi)
  • calculer l’âge

L’âge s’obtient en appliquant la fonction age sur une date. Par ex, sur la date de naissance de l’abonné :

[[ FIELD.20 | age]] 
  • différence entre 2 dates 

nbDays = date.calc.Delta_Days(year1,month1,day1,
                     year2,month2,day2);
Cette méthode renvoie la différence en jours entre les deux dates données. Le résultat est positif si les deux dates sont dans l’ordre chronologique, c’est-à-dire si la date #1 vient chronologiquement AVANT la date #2,  Cette méthode est souvent utilisée pour calculer le nombre de jours depuis la dernière ouverture d’un abonné. Les 3 premiers paramètres sont issus de FIELD.44 et les 3 derniers de la date du jour date.now. Cela donne :

[[ date.calc.Delta_Days(
date.format(FIELD.44,'%Y'), # year1
date.format(FIELD.44,'%m'), # month1
date.format(FIELD.44,'%d'), # day1
date.format(date.now,'%Y'), # year2
date.format(date.now,'%m'), # month2
date.format(date.now,'%d') ) # day2 ]]

b. fonctions texte

    •  Mettre en majuscule ou minuscule : upper / lower


[[ FIELD.14|upper]]
mettra le nom de famille en majuscule, par ex “DUPOND”

[[ "Hello WORLD"|lower]]
donnera “hello world”    
  • Mettre le premier caractère en majuscule : ucfirst 


[[ FIELD.14|ucfirst]]
donnera Dupond (si le nom de famille est dupond) Remarque : il est possible de combiner plusieurs fonctions. On peut mettre par exemple le nom en minuscule puis mettre la première lettre en majuscule avec :

[[ FIELD.14|lower|ucfirst ]]
donnera tout le temps “Dupond” même si le nom est stocké en majuscules  “DUPOND”.  
  • Modifier le contenu d’un texte: 

Remplace toutes les occurrences d’un mot par un autre dans une chaîne de caractères.   Par ex, très utile pour remplacer des retours à la ligne texte par un retour à la ligne HTML  <br> :

[["ligne1
  ligne2" | replace("\n","<br/>") ]]
[[FIELD.100 | replace("\n","<br/>") ]]
remove supprime toutes les occurrences d’un mot dans une chaîne de caractères.   truncate coupe une chaîne de caractères à la longueur voulue et ajoute ‘…’ à la fin. trim supprime les espaces en début/fin de chaîne uri encode au format URL tous les caractères de la chaîne de texte. url encode au format URL tous les caractères sauf ceux réservés aux urls (&, @, /, ;, :, =, +, ? and $)   La fonction html convertit les caractères <, >, & et « en &lt;, &gt;, &amp;, et &quot; Cette fonction remplace toutes les nouvelles lignes par des balises HTML <br>.