New HTML Message Builder class

New HTML Message Builder class

Many people ask how to create HTML messages in Indy.  Due to the nature of MIME nesting, and how Indy 10 implements pseudo-nesting support via the TIdMessagePart.ParentPart property, this is not always easy to do correctly.  In my earlier article about HTML Messages, I explained in detail how to correctly set up the pieces of the TIdMessage component for creating mixed text/html/attachment emails in different scenerios.  To make this task even easier, I have used that information to create a new set of helper classes to handle the ugly details for you!  Now, all you have to do is set a few properties and the contents of a TIdMessage will be filled in appropriately.

Introducing the IdMessageBuilder unit

A new unit named IdMessageBuilder.pas has been added to the IndyProtocols package.  This unit declares a base class TIdCustomMessageBuilder and 2 descendants - TIdMessageBuilderHtml and TIdMessageBuilderRtf (I will not cover TIdMessageBuilderRtf in this article).  These classes are light-weight helpers.  They are designed with the most common usage scenerios in mind.  For more specialized layouts, you have to continue setting up the TIdMessage.MesageParts collection manually.

The TIdCustomMessageBuilder class declares 3 public properties - Attachments, PlainText, and Subject - and two public methods - FillMessage and NewMessage.  The Attachments property is a TStrings to contain local file names that are to be attached to the message, and do not relate to any other sections of the message.  The email receiver can save these attachments to files as desired.  The PlainText property is a TStrings to contain the plain textual data.  The Subject property is the message's Subject text.  The FillMessage() method fills in the content data for an existing TIdMessage object instance, whereas the NewMessage() method instantiates a new TIdMessage object instance and fills it via FillMessage().

The TIdMessageBuilderHtml class adds 2 more public properties - Html and HtmlFiles.  The Html property is a TStrings to contain the HTML textual data.  The HtmlFiles property is a TStrings to contain local file names that are to be attached to the message.  These files are to be referenced by the HTML, such as embedded images and other multimedia files.

Although TIdCustomMessageBuilder and its descendants do the bulk of the work for you in setting up TIdMessage's body, you are responsible for setting up TIdMessage's various header values OTHER THAN the Subject and ContentType properties.  These 2 properties are managed for you, based on the generated body content.  By leaving the rest of the headers alone, you can include custom headers, specify recipients, etc as desired before saving/transmitting the message.

Using TIdMessageBuilderHtml

Rather than jump into the details about how the TIdMessageBuilderHtml class works internally, I'm going to just show code snippets of it in action.  I will demonstrate the same message scenerios that are listed in my earlier article.  Remember to add the IdMessageBuilder unit to your uses clause:

Plain-text and no HTML and no attachments

    with TIdMessageBuilderHtml.Create do
    try
      Subject := 'example';
      PlainText.Text := 'plain text goes here';
      FillMessage(IdMessage1);
    finally
      Free;
    end;

HTML and no plain text and no attachments

    with TIdMessageBuilderHtml.Create do
    try
      Subject := 'example';
      Html.Text := 'HTML goes here';
      FillMessage(IdMessage1);
    finally
      Free;
    end;

Plain-text and HTML and no attachments

    with TIdMessageBuilderHtml.Create do
    try
      Subject := 'example';
      PlainText.Text := 'plain text goes here';
      Html.Text := 'HTML goes here';
      FillMessage(IdMessage1);
    finally
      Free;
    end;

HTML and non-related attachments and no plain-text

    with TIdMessageBuilderHtml.Create do
    try
      Subject := 'example';
      Html.Text := 'HTML goes here';
      Attachments.Add('c:\folder\archive.zip');
      FillMessage(IdMessage1);
    finally
      Free;
    end;

HTML and related attachments and no plain-text

    with TIdMessageBuilderHtml.Create do
    try
      Subject := 'example';
      Html.Text := 'HTML goes here';
      HtmlFiles.Add('c:\folder\image1.jpg');
      HtmlFiles.Add('c:\folder\image2.jpg');
      FillMessage(IdMessage1);
    finally
      Free;
    end;

Note: at the time of this writing, the HtmlFiles property does not yet support user-defined ContentID values for each related attachment.  The actual filename is used as the ContentID, so make sure your HTML refers to that value accordingly, for example: <img src="cid:image1.jpg">.

Plain-text and HTML and attachments

HTML-related attachments only

    with TIdMessageBuilderHtml.Create do
    try
      Subject := 'example';
      PlainText.Text := 'plain text goes here';
      Html.Text := 'HTML goes here';
      HtmlFiles.Add('c:\folder\image1.jpg');
      HtmlFiles.Add('c:\folder\image2.jpg');
      FillMessage(IdMessage1);
    finally
      Free;
    end;

Non-related attachments only

    with TIdMessageBuilderHtml.Create do
    try
      Subject := 'example';
      PlainText.Text := 'plain text goes here';
      Html.Text := 'HTML goes here';
      Attachments.Add('c:\folder\archive.zip');
      FillMessage(IdMessage1);
    finally
      Free;
    end;

Related and non-related attachments

    with TIdMessageBuilderHtml.Create do
    try
      Subject := 'example';
      PlainText.Text := 'plain text goes here';
      Html.Text := 'HTML goes here';
      HtmlFiles.Add('c:\folder\image1.jpg');
      HtmlFiles.Add('c:\folder\image2.jpg');
      Attachments.Add('c:\folder\archive.zip');
      FillMessage(IdMessage1);
    finally
      Free;
    end;