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.
From FormMail version 8.24, files uploaded from your forms can also be filtered.
Accessing Filters
There are three ways for FormMail to access FormMailEncoder or any filter:
- FormMail executes the filter using a standard PHP function. Your server's PHP
installation needs to support this. Most PHP installations do, and there's
no reason for a hosting provider to prevent this. FormMail uses PHP's
"popen" function to securely access FormMailEncoder on your server.
This is the fastest and preferred method to access FormMailEncoder. - FormMailEncoder is installed in your cgi-bin (it can operate as a CGI
program), and FormMail opens a URL to it - just like a browser.
FormMail uses PHP's standard features to open a socket to your
server for this method.
This is also secure, because the sensitive data never leaves your server, but it's a little slower to operate. - The third option is to access FormMailEncoder on another server. For this to be secure, you need trust the other server and your PHP needs to support opening of SSL sockets. We can advise you on this if the other two methods fail to operate for you.
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 ("encode" or "yourfilter" in the example) 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:
<input type="hidden" name="filter" value="yourfilter" />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:
<input type="hidden" name="filter" value="encode" />Only Filtering Some Fields
Normally, FormMail sends all the fields through the filter (except file fields - uploaded files are not filtered by default).
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:
<input type="hidden" name="filter_fields"
value="credit_card_number, credit_card_date" />Selectively filtering fields in this way works well with the PlainTemplate feature.
However, if you selectively filter fields and also use the HTMLTemplate feature, you 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 filtered 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:
<input type="hidden" name="filter_options" value="Attach=filename" />To attach FormMailEncoder results so you can open with a double-click:
<input type="hidden" name="filter_options"
value="Attach=form.fmencoded" />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:
<input type="hidden" name="filter" value="encode" />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:
<input type="hidden" name="filter_options"
value="Attach=data.fmencoded" />
<input type="hidden" name="filter" value="encode" />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:
<input type="hidden" name="mail_options"
value="PlainTemplate=yourtemplate.txt" />
<input type="hidden" name="filter" value="encode" />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.
<input type="hidden" name="mail_options"
value="PlainTemplate=yourtemplate.txt" />
<input type="hidden" name="filter_fields" value="credit_card_number,
credit_card_date, credit_card_verify_number" />
<input type="hidden" name="filter_options"
value="Attach=data.fmencoded" />
<input type="hidden" name="filter" value="encode" />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.
<input type="hidden" name="mail_options"
value="PlainTemplate=yourtemplate.txt,
HTMLTemplate=yourhtmltemplate.htm" />
<input type="hidden" name="filter_options"
value="Attach=data.fmencoded" />
<input type="hidden" name="filter" value="encode" />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.
Filter File Uploads
From version 8.24 of FormMail, you can tell FormMail to filter your file uploads.
To do this, you simply specify the file upload fields in a special field called filter_files (similar to filter_fields).
Upload a file: <input type="file" name="File1" />
Upload a file: <input type="file" name="File2" />
<input type="hidden" name="filter_files" value="File1,File2" />
