How can I use images in Mail Units?

From Wiki

1 Introduction
2 How to use dynamic images
3 How to use static images
4 Download the example

Introduction

The Mail Unit permits to send personalized emails to each destination address. The body of the mail can be dynamically computed replacing placeholders into the defined templates with the real content. The mail body can also contains images. We can distinguish two cases:

The mail body contains a placeholder in order to include an image that changes according to the instances.
The mail body contains a static image.

At run-time, the process to retrieve the resource of the image is:

the resource is searched as a public resource located under the application
the resource is searched as a BLOB, which can be located outside the application like a protected uploaded file or into the database
if no resource has been found, the received HTML mail shows the missing image icon instead of the real image.

In this article, will be explained how you can include dynamic and static images in the body of your e-mails.

[edit]

How to use dynamic images

Suppose you want to keep your customers up-to-date about your new products. Each time you add a product, you can send an e-mail with some details of the product such as the name, the description, the image.

Suppose your model appears like in the following image:

In order to correctly configure the Mail Unit you have to:

Add a placeholder for each information you want to add to the mail body. The name of each placeholder is used in the mail body to indicate where the placeholder must be replaced. The value of the placeholder is not specified because it must not have a default value.
1. Code: the code of the product
2. Name: the name of the product
3. Description: the description of the product
4. Price: the price of the product
5. Image: the uploaded image that represent the product
Add an SMTP Server that delivers messages. In the Mail Unit property view open the dropdown and click on the New.. option. Follow the wizard and configure the SMTP server.
Choose HTML as format of your mail body.
Use the button next the property Body Template File in order to create the template file. Write DynamicImages.mt as name of the file and click OK. The file is associated to the mail unit and its content will be used as body of the mail. The template for the mail can be as follows and it produces as result a mail like in the image:

<html>
  <body>
    <div>
      Dear Customer,
    </div><br/>
    <div>
      There is a new product for you: 
    </div><br/>
    <div>
      <b>Code</b>:  $$Code$$
    </div>
    <div>
      <b>Name</b>:  $$Name$$
    </div>
    <div>
      <b>Description</b>:  $$Description$$
    </div>
    <div>
      <b>Price</b>:  $$Price$$
    </div>
    <div>
      <b>Image</b>:  <img src="$$Image$$"/>
    </div>
  </body>
</html>

The placeholders are inserted in the body of the mail with the notation $$placeholderName$$.

The image, that is a BLOB attribute of the Product table, is added to the mail as <img src="$$Image$$"/> and the placeholder $$Image$$ will be replaced with the image path.

[edit]

How to use static images

Suppose you want to send an email to a user when he registers. The mail body must have your company logo as header. This means that the image is static and equal for each mail.

Suppose your model appears like in the following image:

In order to correctly configure the Mail Unit you have to:

Add a placeholder for each information you want to add to the mail body. The name of each placeholder is used in the mail body to indicate where the placeholder must be replaced. The value of the placeholder is not specified because it must not have a default value.
1. Username: the username submitted by the user
2. Password: the password generated when the user is created
Add an SMTP Server that delivers messages. In the Mail Unit property view open the dropdown and click on the New.. option. Follow the wizard and configure the SMTP server.
Choose HTML as format of your mail body.
Use the button next the property Body Template File in order to create the template file. Write StaticImages.mt as name of the file and click OK. The file is associated to the mail unit and its content will be used as body of the mail. The template for the mail can be as follows and it produces as result a mail like in the image:

<html>
   <body>
      <div>
         <img src="upload/webratio-logo.png"/>
      </div>
      <div>
         Dear Customer,
      </div>
      <div>
         Your subscription was accepted.
         Your access information are:
      </div>
      <div>
         <b>Username</b>: $$Username$$
      </div>
      <div>
         <b>Password</b>: $$Password$$
      </div>
      <div>
         Visit our 
         <a href="http://www.webratio.com">web site</a>
         to know the WebRatio world.
      </div>
   </body>
</html>

The image is added to the mail as <img src="{path-to-image}"/> where the {path-to-image} can be:

the relative path identifying a style image resource (e.g. Resources/webratio-logo.png)
the relative path identifying an uploaded public image (e.g. upload/ent1/1/webratio-logo.png) in the case of the upload directory is located under the application
the relative path identifying an uploaded protected image (e.g. ent1/1/webratio-logo.png) in the case of the upload directory is located outside the application

The placeholders are inserted in the body of the mail with the notation $$placeholderName$$.

[edit]