Using the HTMLTemplate Feature in FormMail

This page describes how to setup FormMail and your form so that the results are sent to you in an HTML email.

Before attempting this, first ensure you've got FormMail working with your form and sending you plain emails.

Overview

Here are the steps in overview:

Create an HTML document that will be used by FormMail as a template for your email. This can be a modified copy of your form, for example.
Create a directory on your server to hold your HTML template(s).
Upload your HTML template from step 1 to the directory you created in step 2.
Configure FormMail: set $TEMPLATEDIR to the pathname of the directory you created in step 2.
Add a hidden field to your form called "mail_options". In this field specify the option "HTMLTemplate" and set it to the name of the HTML template you created in step 1.

Step 1 - Create an HTML template

FormMail sends you HTML email by taking the fields from a form submission and putting their values into HTML document you've created. This document is a template because you use a special syntax to tell FormMail where you want each field.

It's very simple to do this: you create an HTML document, using your favourite HTML editor, that looks the way you want.

Then, wherever you want a field, you place the field name and prefix it with a dollar sign ($). The field names are the names you've used in your form.

Here's a very simple and short HTML template:

<html>
<body>

<p>Here is the latest form submission from your website:</p>
<br />User's name: $realname
<br />Email address: $email
<br />Their comments:
$comments

</body>
</html>

This template is similar, but puts the form results in a table:

<html>
<body>

<p>Here is the latest form submission from your website:</p>
<table border="1">
<tr>
    <td>User's name:</td>
    <td><b>$realname</b></td>
</tr>
<tr>
    <td>Email address:</td>
    <td><b>$email</b></td>
</tr>
<tr>
    <td>Their comments:</td>
    <td><b>$comments</b></td>
</tr>
</table>

</body>
</html>

Step 2 - Create a directory

This is an important security requirement. By creating a special directory on your server to hold all your templates, you can ensure that an attacker cannot download files that you don't want anyone to see.

Without this step, it might be possible for an attacker to read your password file or some other secure location on your server.

Create a directory called "fmtemplates" at the top of your web server document root.

Step 3 - Upload your template

Now upload the template you created in step 1 to the directory you created on your server in step 2.

You can use any file name for the template, but let's assume you've called the template "mytemplate.htm".

Step 4 - Configure FormMail

You've done this before, so you shouldn't have any trouble. Simply find the line containing $TEMPLATEDIR in the configuration section.

In version 8.24, $TEMPLATEDIR is defined around line 335.

Set it to the full path of the directory you created in step 2. For example:

$TEMPLATEDIR = "/home/your-name/www/fmtemplates";

Step 5 - Tell your form to use it

Now edit your HTML form. You've already set it up to use FormMail, so the only thing to do is to put a hidden field in to tell FormMail you want it to send the form results via the HTML template.

To do this, just add a hidden field called "mail_options", like this:

<input type="hidden" name="mail_options"
    value="HTMLTemplate=mytemplate.htm" />

That's it.

If you've managed to follow the steps correctly, your form submissions will now be sent to you in HTML format.

Prior to version 8.13 of FormMail, the user must fill in all the fields specified by your template. Therefore, you need to make these required fields, or use the TemplateMissing mail_option. From version 8.13, missing fields are simply replaced by a blank, and you can use TemplateMissing to provide a different value.

If you're using FormMail before version 8.13, this is the additional code you need:

<input type="hidden" name="required"
    value="realname,email,comments" />

and/or:

<input type="hidden" name="mail_options"
    value="HTMLTemplate=mytemplate.htm,TemplateMissing=N/A" />

Substitution Options

When you substitute fields in templates, there are several options available to control how the substitution is performed.

Please read the How-To guide on template substitutions.

Other features

Once you've got your HTML form working with an HTML template, there may some tweaking you want to do.

Here are are some ideas:

I only want the HTML, no plain text.

By default, FormMail sends a multi-part MIME message which has the form results in two formats. The first format is plain text (just like FormMail sent before), and the second format is your HTML template.

Most mail readers know how to treat the email correctly and just show you the HTML version.

If you're having problems with the plain text showing, or you simply want to reduce the size of the emails you receive, you can switch off the plain text version. In "mail_options", simply specify "NoPlain".

Like this:

<input type="hidden" name="mail_options"
    value="HTMLTemplate=mytemplate.htm,NoPlain" />

My TEXTAREA fields have all the lines joined together.

This is the default action for FormMail. To get FormMail to keep lines separate, in "mail_options", simply specify "KeepLines".