Mail HTML avec images encapsulées

Les mails HTML sont un vaste sujet. Cette note technique traite essentiellement des mails HTML créés automatiquement. Si vous cherchez un éditeur HTML pour que vos clients puissent créer leurs documents HTML, regardez du côté de « 4D Email 3.0 », un nouveau client email créé avec 4D 2004 et utilisant le plugin HTML de www.marketblast.com.

Les mails HTML peuvent utiliser des images externes ou se référer à un fichier d'image en pièce jointe. La plupart des emails publicitaires (SPAM ou liste de diffusion) utilisent des liens vers des images hébergées sur un site web standard. Le gros avantage est que cela génère peu de trafic en volume. Il est possible de savoir si un utilisateur a lu l'email quand l'image est demandée au serveur. En conséquence, de plus en plus de clients email ne téléchargent plus les images, respectant la sécurité des utilisateurs.

Une bonne manière d'envoyer une image est de l'encapsuler dans le document. L'avantage est que tous les clients email affichent l'image, ce qui rend le « reporting » plus lisible.

La base exemple envoie automatiquement un rapport commercial : les chiffres de ventes, un graphique en camembert affichant les ventes par code postal, les chiffres par code produit et un graphe par code produit. Les graphiques sont créés avec 4D Chart ; l'image est ensuite convertie en GIF.

L'exemple montre plusieurs manières de sortir les statistiques au format HTML. La première manière est facile à utiliser, elle est basée sur l'éditeur d'état rapide (NQR). En utilisant cet outil, le développeur 4D ou un client peut créer un rapport de statistiques sans avoir de connaissances en HTML. La seconde manière est plus complexe : elle utilise un modèle HTML (template) fourni par le développeur 4D ou modifié par le développeur html, ainsi que la nouvelle commande de 4D 2004, TRAITER BALISES HTML, pour créer le reporting final.

Pour terminer, les quatre parties (deux tableaux statistiques et deux images) sont associées selon un modèle avec TRAITER BALISES HTML. Le résultat est envoyé en utilisant les Internet Commands de 4D.

Le rapport final ressemblera à ceci :

Lancez la base exemple. Le dialogue d'accueil s'affiche. L'écran suivant vous permet de tester la base :

Vous devez paramétrer l'application : entrez les informations habituelles requises pour un client email, le nom (ou l'adresse IP) du serveur de mail. Si votre serveur de mail requiert une authentification SMTP, vous devrez entrer votre nom de compte et son mot de passe.

Pour tester, nous vous suggérons d'utiliser votre compte email en tant qu'expéditeur et destinataire.

Les deux boutons « Utiliser l'éditeur d'état » et « Utiliser le modèle HTML » créent automatiquement un rapport et l'envoient. Les deux rapports contiennent les mêmes données, mais utilisent des styles et des couleurs différents.

Le chapitre suivant explique comment personnaliser le rapport et l'utiliser dans votre propre application. Premièrement, nous modifions le rapport dans la base exemple « Facturation ». Ensuite, nous expliquons comment ajouter le code dans votre propre application. Et finalement, nous montrons comment vous pouvez autoriser un client à modifier le rapport.

Personnaliser le rapport de statistiques


Fermez la fenêtre de démo en cliquant sur le bouton « Fermer ».

1 - Allez dans le mode Utilisation et sélectionnez la table [Factures].

2 - Ouvrez l'éditeur d'état rapide.

3 - Créez un nouvel état. Vous pouvez le créer manuellement, en utilisant les fonctionnalités de l'éditeur d'États Rapides, ou demander à l'assistant (le bouton à droite) de vous aider.

4 - Vérifiez l'état avec la prévisualisation dans le menu Fichier.

5 - basculez dans le mode Assistant, même si vous avez terminé de créer votre état.

6 - Cliquez sur « Étape suivante » en bas à gauche jusqu'à atteindre le point « 6 - Destination ».

7 - Sélectionnez « Fichier HTML ».

8 - Cliquez sur « Étape suivante ». Dans le point « 7 - Présentation », vous pouvez ajouter quelques couleurs.

9 - Cliquez sur « Étape suivante » et allez au point « 8 - Finalisation ».

10 - Cliquez sur le bouton « Générer le code 4D ». C'est une nouvelle fonctionnalité de 4D 2004. Ce bouton n'est disponible qu'en interprété et en mode Utilisation.

Dans les options de code, sélectionnez toutes les boîtes à cocher. Cliquez sur « Générer le code ».

Cette fonctionnalité crée le code 4D qui construit l'état que vous venez de créer, mais par programmation !

11 - Ensuite, cliquez sur le bouton « Copier dans le presse-papiers », fermez le dialogue et quittez l'éditeur d'état rapide.

12 - Allez dans le mode Structure et créez une nouvelle méthode appelée « Mail_Report_test1 ».

Utilisez le menu Copier/Coller pour insérer automatiquement dans votre méthode le code créé par l'éditeur d'états rapides.

Le code est pratiquement terminé. Nous avons besoin d'y faire quelques modifications.

La ligne 9 contient le code :

QR FIXER DESTINATION($ID; qr fichier HTML;"")

Changez pour :

QR FIXER DESTINATION($ID; qr fichier HTML;$2) ` remplacer le dernier paramètre "" par $2

13 - Puis, dans le menu Édition, sélectionnez Remplacer.
Entrez les caractères suivants dans « Chercher » :
=\"
et dans « Remplacer » :
=3D\"

Cliquez maintenant sur le bouton « Remplacer ».

L'éditeur d'états rapides crée un modèle HTML qui sera utilisé avec un navigateur web. Pour utiliser le modèle HTML avec un mail HTML nous devons procéder aux modifications Chercher/Remplacer. Vous trouverez de plus amples informations sur cette modification dans le dernier chapitre « Les mails au format MIME multipart ».

Maintenant, testons notre rapport. Ouvrez la méthode appelée Mail_CreationRapport. À la ligne 16, remplacez la méthode Mail_Rappor1 par votre méthode créée sous le nom Mail_Report_test1.



Et c'est fini. Retournez au mode Menus Créés et démarrez la démo en sélectionnant le mail HTML dans le menu Fichier. Si vous ne l'avez pas encore fait, configurez vos paramètres de courrier électronique et cliquez sur le bouton « Utiliser l'éditeur d'état ».

Vous recevrez un email avec le nouveau rapport.

Pour envoyer des rapports en HTML depuis votre application, vous avez simplement besoin d'installer une seule méthode !

• Retournez dans le mode Structure et ouvrez la méthode HTMLEnvoyer_Mail. Sélectionnez Exporter la méthode… du menu Méthode pour la sauvegarder sur votre bureau.

• Quittez 4D.

• Si votre application n'utilise pas les 4D Internet Commands, installez le plugin. Démarrez votre application et allez dans le mode Structure.

• Créez une nouvelle méthode et appelez-la HTMLEnvoyer_Mail.

• Sélectionnez Importer la méthode… du menu Méthode et choisissez la méthode exportée.

• Fermez la nouvelle méthode.

• Ouvrez le dossier exemple « Facturation » puis le dossier « HTML_Mail_Template » (en utilisant l'explorateur ou le finder). Localisez le fichier « 1report.txt » et placez une copie du fichier à côté de votre structure. Renommez-le « htmlmail_template.txt ».
Ce fichier contient le code HTML pour construire un email HTML contenant un ou deux rapports avec zéro, une ou deux images. Nous expliquerons plus tard comment personnaliser ces modèles.


Suivez les étapes du chapitre précédent et créez une méthode appelée Mail_Report_test1 avec le code pour créer le tableau statistique HTML à partir d'une table de votre application, comme pour la table [Factures].

Ensuite, créez une méthode test pour lancer la procédure. En environnement de test, nous coderons en dur.

En environnement de production, vous ajouteriez une interface utilisateur ou vous automatiseriez la procédure dans un process qui tournerait sur le serveur chaque soir.

HTMLMail_Titre := "Ceci est le titre de notre email"
HTMLMail_Text1 := "Nous créons ce mail pour montrer comment fonctionne cette note technique"

$qreport := QR Creer zone hors ecran
   `remplacer avec votre nom de table et champ
CHERCHER ([Factures];[Factures]Date_facture>(Date du jour-30)) 
$chemin := "HTMLMail_Report1.html"
Mail_Report_test1 ($qreport ; chemin)
QR EXECUTER COMMANDE($qreport ;qr commande nouveau)
QR SUPPRIMER ZONE HORS ECRAN($qreport )

$err := HTMLEnvoyer_Mail("nom@domaine.com" ; "nom@domaine.com"; HTMLMail_Titre ;
                              "mail.domaine.com" ; "utilisateur" ; "mot de passe")

En premier lieu, nous codons en dur le contenu du titre et du texte. Ensuite, nous construisons une sélection pas trop importante (si vous avez peu d'enregistrements, vous pouvez tout simplement faire un TOUT SELECTIONNER). Et enfin, nous envoyons le mail en entrant directement le nom du destinataire, de l'expéditeur et le mot de passe. Si le code fonctionne comme vous le voulez, il vous reste à remplacer le code en dur par des variables ; vos utilisateurs pourront ainsi modifier les valeurs.

Faites un essai. Vous recevrez un email contenant le rapport que vous avez créé, formaté en HTML. Eh oui, c'est vraiment simple !

Les rapports statistiques sont plus facilement lisibles s'ils sont accompagnés de graphiques. Notre prochaine étape est donc la création d'images à insérer dans le mail.

Les graphiques financiers peuvent être créés dynamiquement avec 4D Chart. Il y a plusieurs manières de procéder, beaucoup de notes techniques ont déjà été publiées sur le sujet. Le code exemple contient également deux exemples pour créer dynamiquement un graphique.

Nous commençons par une image statique dans le mail HTML. Nous poursuivrons ensuite en remplaçant cette image par un graphique créé dynamiquement. Si vous avez déjà un graphique que vous souhaitez utiliser, servez-vous simplement de la commande CT Zone vers image.

Sinon, parcourez votre bibliothèque d'images dans la Toolbox. La bibliothèque d'images contient généralement quelques boutons images. Notez le numéro de l'image (vous pouvez aussi insérer une nouvelle image).

Insérez ce code avant la dernière ligne (HTMLEnvoyer_Mail) :

C_IMAGE($monImage)

LIRE IMAGE DANS BIBLIOTHEQUE(851;$monImage)

IMAGE VERS GIF($monImage;HTMLMail_Pict1Base64)
` convertit l'image 4D au format gif, dans un blob

ENCODER(HTMLMail_Pict1Base64)
` encode le contenu du blob en Base64

Nous lisons l'image statique (nous remplacerons plus tard cette ligne avec le code qui crée l'image dynamiquement). Nous la convertissons en GIF (les graphiques financiers utilisent habituellement 256 couleurs ou moins, GIF est donc le format adéquat), et nous l'encodons au format base 64.

La dernière étape requiert l'utilisation de modèle (template) qui supporte une image.

Ouvrez le dossier exemple « Facturation » (en utilisant l'explorateur ou le finder) et le dossier « HTML_Mail_Template ». Trouvez le fichier « 1reports_1picture.txt » et placez une copie à côté de votre structure. Renommez le fichier « htmlmail_template.txt » (il remplace le fichier précédent).

Exécutez la méthode. Vous recevrez un rapport contenant l'image que vous avez choisie.

L'étape suivante consiste à inclure plusieurs tableaux statistiques dans un seul mail ou d'inclure plus d'une image. Pour avoir deux tableaux de stats avec deux images, vous pouvez simplement utiliser le modèle « 2reports_2pictures.txt », ou personnaliser le modèle selon votre envie. Nous vous montrerons comment personnaliser le rapport, en se basant sur le modèle que nous utilisons présentement. Ouvrez le fichier « htmlmail_template.txt », qui est dans le dossier de la structure, avec un éditeur de texte.

Ne vous inquiétez pas. Cela semble compliqué, mais vous pouvez ignorer la plupart du contenu. Si les détails vous intéressent, le dernier chapitre intitulé « À l'intérieur des mails au format MIME multipart » explique le contenu.

Vers le milieu du document, vous verrez :

<!--4DInclude HTMLMail_Report1.html-->
      <P><BR></P>
      <IMG align=3Dbaseline border=3D0 hspace=3D0=20
      src=3D« cid:001@<!--4DVar HTMLMail_MailID--> »>

La première ligne inclut le rapport créé par l'éditeur d'état rapide de 4D. La seconde ligne est une ligne vide. La dernière ligne inclut l'image.

Si vous souhaitez ajouter un autre rapport, copiez la première ligne et insérez-la après l'image. Renommez le document inclus en « HTMLMail_Report2.html ».

Créez un autre rapport avec 4D. Enregistrez la méthode qui le crée et dupliquez le fragment de code qui lance l'éditeur d'états rapides. Pour $chemin, utilisez le même nom ci-dessus, « HTMLMail_Report2.html ». Et c'est tout.

Si vous connaissez le HTML, vous pouvez aussi modifier le document HTML, comme ajouter plus de texte ou changer le format.

Pour utiliser une autre image, copiez la ligne <IMG…> et insérez-la où vous voulez voir cette nouvelle image affichée. Cette ligne contient le lien cid : suivi par le nombre 001. Remplacez-le par 002 (et ainsi de suite). Ne changez pas les nombres qui sont avant le tag HTML 4D parce que ces nombres sont nécessaires pour construire un identifiant (ID) unique.

Nous voulons finalement insérer une autre image. Descendez à la fin du document. Vous verrez cette section :

      ------=_NextPart_001_<!--4DVar HTMLMail_MailID-->
      Content-Type: image/gif;
      name=« Pict1.gif »
      Content-Transfer-Encoding: base64
      Content-ID: <001@<!--4DVar HTMLMail_MailID-->>
      Content-Description: Pict1.gif
      Content-Disposition: inline;
      filename=« Pict1.gif »
      Content-Location: Pict1.gif
      <!--4DHTMLVar HTMLMail_Pict1Base64-->

Dupliquez la section entière. Dans le Content-ID, remplacez le nombre 001 par 002 (et de même pour les images suivantes).

Remplacez le nom de l'image « Pict1.gif » par « Pict2.gif » (vous pouvez aussi choisir un autre nom de fichier image, mais les noms doivent être uniques). Puis remplacez le nom de la variable 4D HTMLMail_Pict1Base64 par HTMLMail_Pict2Base64.

Dans votre méthode 4D, créez une autre variable avec HTMLMail_Pict2Base64, et c'est terminé.

Une autre manière de faire est de laisser l'utilisateur final créer ou modifier le rapport. Vous pouvez faire cela soit en ouvrant l'éditeur d'états rapides ou en incluant l'éditeur d'états dans un formulaire. Le rapport créé est sauvegardé dans un document externe ou dans un blob.

Dans les exemples précédents, vous ouvrez une zone externe et utilisez QR BLOB VERS ETAT pour utiliser cet état rapide créé.

Ouvrez la méthode Mail_Report_test1 de la base exemple et copiez les lignes entre QR FIXER DESTINATION et QR FIXER MODELE HTML dans votre code.

Puis exécutez le code en utilisant la commande QR EXECUTER. Cette combinaison permet à l'utilisateur de dessiner librement son rapport. Vous pouvez vérifier par programmation que la destination et le modèle HTML du rapport sont corrects.

Tout le reste fonctionne comme dans l'exemple précédent.

Plutôt que d'utiliser l'éditeur d'état rapide de 4D pour créer le rapport HTML, vous avez la possibilité d'avoir un contrôle total et de créer le rapport manuellement. Pour ce faire, vous devez avoir des connaissances élémentaires en HTML et les tags HTML de 4D doivent vous être familiers. Pour de plus amples informations, consultez la documentation du langage de 4D 2004, le chapitre Serveur Web, sous-chapitre Balises HTML 4D.

Vous trouverez un code exemple dans la base test Facturation, dans la méthode Mail_RapportManuel1. Au lieu d'utiliser le code créé par l'éditeur d'états rapides, nous créons ce code manuellement. Vous pouvez utiliser la méthode exemple comme guide.

Le code crée 4 tableaux qui contiennent les données (lignes détail, en-tête, sous-total et total) qui seront utilisées dans le rapport. Le code utilise également la commande TRAITER BALISES HTML pour créer le rapport HTML utilisant ces tableaux. Si vous savez comment utiliser les balises HTML, c'est facile de créer des rapports HTML complexes.

L'information suivante explique comment fonctionne un mail HTML incluant des images. Vous n'avez pas besoin de lire ce chapitre pour utiliser le code ! Si vous utilisiez déjà le HTML et les balises HTML de 4D, ce chapitre peut vous apporter quelques informations supplémentaires.

La meilleure façon de comprendre ce concept est d'envoyer des mails en utilisant d'abord l'exemple en premier lieu. Ensuite, vous trouverez dans le dossier d'exemples, un document nommé « htmltest.txt », qui est destiné au débogage et à la compréhension du concept. Il contient le code source du message envoyé. Ouvrez le document avec un éditeur de texte.

Vous remarquerez qu'il se structure en plusieurs parties, toutes divisées par un en-tête qui ressemble à :
« ------=_NextPart…. ».

L'en-tête SMTP du message n'est pas inclus dans ce document. Cet en-tête est :
Content-Type: multipart/related; boundary=« ------=_NextPart…. »

L'en-tête décrit au client email que le message contient plusieurs parties et quel est le séparateur de ces parties. La première partie du mail (sans en-tête additionnel) ne contient que le texte, qui sera affiché dans le client email qui ne supporte pas les mails HTML. Si vous recevez le message, cette partie vous est retournée par la commande des Internet Commands MSG_GetBody.

Pour réduire la complexité de cet exemple, nous avons simplement utilisé la chaîne « Ceci est un message multipart au format MIME » pour la partie texte.

Il vaudra mieux insérer ici dans cette section une copie du rapport au format texte.

Il est maintenant temps de regarder de plus près le séparateur NextPart. Il débute avec un identifiant (ID) numérique « _001- » puis un identifiant unique, composé de la date et heure courante (utilisant les ticks).

L'identifiant unique est calculé pour chaque mail, la suite du contenu est basée sur un modèle statique.

La première section se réfère à une sous-section commençant par _002_, et qui contient la section HTML du mail. L'en-tête de la section informe le client email quelle table de caractères et quel encodage utiliser. Pour le moment, passez toute la section HTML. Nous y reviendrons plus tard. Nous allons regarder les sections suivantes.

Les deux sections suivantes se ressemblent beaucoup, et sont peu lisibles (elles paraissent cryptées). Comme vous vous en doutez, ces deux sections contiennent les images. L'image doit être encodée en base 64.

L'en-tête informe le client email que le contenu est une image au format GIF, encodée en base 64, et dont le nom est « Pict1.gif ». L'en-tête contient également la balise « content-ID », qui est requise dans la section HTML pour se référer à l'image encapsulée.

Revenez maintenant à la section HTML. Vous remarquerez qu'elle ressemble à une page HTML classique, à deux différences près.

Des balises paraissent étranges, comme :

      <div align=3D« right »>

Du fait que le texte est formaté en « quoted-printable », il est nécessaire de remplacer tous les « = » par « =3D ». 3D en code hexadécimal est le caractère « = ». La seconde différence est l'image :

      <IMG align=3Dbaseline border=3D0 hspace=3D0=20 src=3D« cid:001@22.08.2005_63125777 »>

Encore une fois, il faut utiliser la combinaison « =3D ». La source de l'image n'est pas une URL, mais une référence interne ; c'est le content-ID que nous avons vu dans la section des images.

Le format d'un mail en HTML est assez simple. Vous pouvez insérer à peu près tous les codes HTML dans la section HTML, en veillant à remplacer « = » par « =3D ». Si vous voulez vous référer à des images, vous pouvez soit utiliser une URL externe ou un lien vers l'image encapsulée. Dans ce cas, l'image doit être placée à la fin du mail, chacune dans sa propre section, avec son propre Content-ID. Le Content-ID est un compteur (001, 002 et 003) suivi par un ID unique (nous utilisons encore la date courante_nombre de ticks).

Télécharger la base exemple.