Templates for Plain Emails

From version 3.00, FormMail provides a feature where you can format the plain text email it sends you.

If you've got FormMail working, then you will have seen the email it sends you. Typically, the email contains the field names and their values, listed down the page. The email is formatted in plain text.

This How-To guide explains how you can change the wording, order, and format of the plain text emails FormMail sends to you.

If you want it to send you HTML email, there's a specific How-To guide that explains how to do that.

Overview

In overview, here are the steps you need to perform:

1. Create a directory on your server to hold templates.
2. Configure FormMail for a template directory (or URL prefix).
3. Create a plain text template.
4. Configure your form to tell FormMail to use the template.

Step 1 - Create a Directory

Your template files can be placed anywhere on your server, however we strongly recommend creating a separate directory (folder) to hold template files.

It's much more secure. FormMail won't load templates outside the directory you specify - this means that a hacker cannot use FormMail to access files on your server that are to be kept secret.

By creating a directory that only holds template files, you can be sure that a hacker cannot use FormMail to compromise your server.

We recommend that you create a directory called "fmtemplates" at the top of your web server document root.

Step 2 - Configure FormMail

Edit formmail.php and look for $TEMPLATEDIR in the configuration section. In version 3.00 this is near line 1350. The line you're looking for looks like this:

$TEMPLATEDIR = "";                  // directory for template files; ...

It's a good idea to review the documentation above this line.

Now, alter $TEMPLATEDIR to specify the full path to your template directory:

$TEMPLATEDIR = "/path/to/fmtemplates";      // directory for template files; ...

Step 3 - Create a Template

Use your favourite text editor and write the text you want FormMail to send to you.

To tell FormMail to include a field value, simply put the name of the field where you want and prefix it with '$'. Here's an example:

This is the latest form submission:

Email: $email
Name:  $realname

Now upload this file to the directory you created in Step 1. Let's assume you've called this file "plain.txt".

Step 4 - Configure your Form

Finally, edit your HTML form and add a hidden field to tell FormMail to use the template:

<input type="hidden" name="mail_options"
    value="PlainTemplate=plain.txt,AlwaysList" />

If you already have a mail_options field in your form, simply append "PlainTemplate=plain.txt,AlwaysList" to the value and precede it with a comma.

Upload your modified form and test!

The AlwaysList option is required in case your form only has one non-special field (i.e. one field other than email and realname). Some versions of FormMail would ignore your plain template specification in this case, unless you specify AlwaysList.

Missing Fields

By default, FormMail will send you an alert and fail the form submission if your template specifies a field that the user hasn't entered. (This default was changed in version 8.13 of FormMail. From that version onwards, no alert is sent, the form does not fail and missing fields are replaced with no value.)

You can tell FormMail to insert a specific value when a field is missing. Simply add the "TemplateMissing" option to mail_options:

<input type="hidden" name="mail_options"
    value="PlainTemplate=plain.txt,AlwaysList,TemplateMissing=n/a" />

The above tells FormMail to write "n/a" in place of missing fields. You can use any value (except comma and double-quote). To replace missing fields with no value (which you don't need to do from version 8.13):

<input type="hidden" name="mail_options"
    value="PlainTemplate=plain.txt,AlwaysList,TemplateMissing=" />

Comma Separated Values

Some users have requested that FormMail send a CSV format email to them. This is easy with the PlainTemplate feature. Just create a template that lists the form values with commas:

$email,$realname,$yourfield1,$yourfield2,....

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.