Using Filters

Search our site:

FormMail supports the concept of filtering form results before emailing them to you.

Filtering can do anything you desire. One use of a filter is to encrypt the form results. Another use is to create CSV (Comma Separated Values) output.

We've already configured FormMail to provide support for our encryption product FormMailEncoder.

FormMail from version 8.04 includes a built-in CSV filter. We have a HOW TO guide for using the CSV filter, but you should read the rest of this guide first.

This How-To guide describes configuring and using filters with FormMail. We'll mainly talk about a filter as an encrypting feature, but the discussion applies equally to any type of filter you choose to use.

What is a Filter?

A filter is a program (or script) that accepts the results of a form submission and returns those results in a different form.

To use a filter, you must first find or create one that can accept text as input and produce text as output.

Defining a Filter

The next step is to define the filter inside FormMail. In the configuration section, look for $FILTERS.

$FILTERS = array("encode"=>"$REAL_DOCUMENT_ROOT/cgi-bin/fmencoder -kpubkey.txt");

The default value defines a filter called encode with the command line shown to execute it.

To add another filter, simply add another array element, like this:

$FILTERS = array("encode"=>"$REAL_DOCUMENT_ROOT/cgi-bin/fmencoder -kpubkey.txt",
"yourfilter"=>"/path/to/ProgramName program-parameters");

The first string is the name for your filter. This is what you'll use in your HTML forms. The second string is the command to execute the filter.

Using a Filter

The name you give your filter is the name you use in your HTML forms. With the above example, you'd request your filter like this in your HTML form:

This simple hidden field tells FormMail to run the results of the form submission through the named filter before emailing them to you.

Provided you've installed FormMailEncoder on your server, along with the required public key, you can simply encrypt your form results with this hidden field:

Only Filtering Some Fields

Normally, FormMail sends all the fields through the filter.

You can tell FormMail to only send some fields through the filter and leave other fields un-filtered. This is especially useful for FormMailEncoder or other encryption filters.

For example, your form may collect a mixture of confidential information (such as credit card details) and non-confidential information. You probably only need to encrypt the credit card details.

To tell FormMail to encrypt (filter) only some fields, you provide the list of fields in the filter_fields hidden field:

Selectively filtering fields in this way works well with the PlainTemplate feature.

However, if you selectively filter fields with the HTMLTemplate feature, you also need to use the Attach feature in filter_options (see below).

Attaching the Filtered Results

After processing through a filter, FormMail sends you the results in the body of the email.

Using a filter_options value, you can tell FormMail to attach the filter results instead.

This is particularly useful if you provide a file name with a known extension, because you can simply double-click the attachment to view the filtered results in the appropriate application.

For example, if you attach your FormMailEncoder results in a file with the extension .fmencoded, Windows will automatically start FormMailDecoder and your data will be decrypted immediately. This saves on a copy-and-paste operation (requires version 1.5 or later of FormMailDecoder).

To attach the filtered results instead of putting them in the body of the email:

To attach FormMailEncoder results so you can open with a double-click:

Typical FormMailEncoder Usage

Below, we provide some typical ways you might work with the FormMailEncoder filter (encode) and other features of FormMail.

Encode the results in the body of the email

This is the original way to work with FormMailEncoder and FormMailDecoder. The email you receive has encrypted data, and you copy-and-paste it into FormMailDecoder to view the contents.

To do this, simply specify the encode filter in your HTML form:

Encode the results and attach to the email

The email you receive will be blank except for the attachment. You can double-click the attachment to decrypt and view the data.

To do this, simply specify the encode filter in your HTML form, and specify the Attach feature in filter_options:

Encode the results in the body of the email, and format with a plain text template

The body of the email will contain the encrypted form results. When you decrypt it, the results will be formatted according to your template. We provide a How-To guide for plain text templates.

To do this, specify the encode filter in your HTML form, and specify a plain text template:

Show some fields unencrypted in the email, and encrypt some fields in an attachment

The body of the email will contain some fields that you want un-encrypted, formatted by a template and some fields encrypted in an attachment to the email. You can simply double-click to decrypt the encrypted fields.

In the template, you only include the fields you want un-encrypted.

Show some fields unencrypted in the email using an HTML template, and encrypt some fields in an attachment using a plain text template

The body of the email will contain some fields that you want un-encrypted, formatted by an HTML template and some fields encrypted in an attachment to the email which are formatted using a plain text template. You can simply double-click to decrypt the encrypted fields.

Note: for this case, you must not specify the "filter_fields" hidden field. Because you're specifying both types of templates and a filter, FormMail automatically filters your PlainTemplate result and attaches it. If you do specify "filter_fields", FormMail will encode those fields and not encode your PlainTemplate.

You can read the How-To guides for HTML templates and for plain text templates.

In the HTML template, you only include the fields you want un-encrypted.

Note: as this is quite a complex scenario, we recommend you thoroughly test your form and ensure that what needs to be encrypted is encrypted. In particular, we recommend you look at the source of the email you receive to ensure that no confidential fields are shown un-encrypted.