Using FormMail's CSV Filter

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

This document describes the built-in CSV (Comma Separated Values) filter that has been available in FormMail since version 8.04. Please read the general How-To guide on filters first, then return to this How-To guide for specific information.

How is the CSV Filter Defined?

FormMail has a configuration setting called $FILTERS.

This setting allows you to define your own filters, which will be external to FormMail (i.e. additional software).

FormMail also uses this configuration setting to define its internal or built-in filters.

You can examine this configuration setting and see the definition of the CSV filter:

$FILTERS = array(...
    "csv"=>"csv",
    ...);

If you had a need to do so, you can rename the CSV filter to something else, like this:

$FILTERS = array(...
    "myname"=>"csv",
    ...);

The first string ("myname") is the external name of the filter (the name you use in your HTML) and the second string "csv" is the internal name. For external filters, the second string is the operating system command that FormMail must execute.

The "csv" filter is said to be "built-in to FormMail" because FormMail knows what logic to perform when it processes a filter whose internal name is "csv".

Using the CSV Filter

You use special FormMail fields in your HTML form to specify and control the use of filters.

There are 3 fields for this purpose:

• filter - specifies the filter to use
• filter_fields - specifies the fields you want to filter
• filter_options - controls how you want the filter to operate

The main use for the CSV filter is to format several (or all) of your form's submitted fields into a CSV file that gets attached to the email sent to you.

The following hidden fields will provide an attached CSV file (called "data.csv") with the name, email address, and phone number fields of your form.

<input type="hidden" name="filter" value="csv" />
<input type="hidden" name="filter_fields" value="realname,email,phone" />
<input type="hidden" name="filter_options" value="Attach=data.csv" />

Controlling Which Fields Get Filtered

As mentioned above, the "filter_fields" special field controls which fields will be filtered.

If you don't provide "filter_fields", but provide "csvcolumns" instead (see our document on Creating HTML Forms for information about this special field), then that field will specify which fields are to be filtered.

If you don't provide either "filter_fields" or "csvcolumns", FormMail will filter all the fields submitted by your form.

Options Available

Above, you've seen the use of the "Attach" option. This tells FormMail that you want the results of the filter attached as a file to the email it sends.

The following options control the way the CSV filter operates:

The following example uses all these options and specifies attachment of the output:

<input type="hidden" name="filter_options"
    value="Attach=data.csv,CSVHeading,CSVQuote=',CSVSep=|,
    CSVIntSep=:,CSVEscPolicy=double,CSVRaw" />

Importing CSV Files

There are important considerations when importing CSV files into applications.

From version 8.23 of FormMail, you can format CSV values on a per-field basis. You can read about these features. The formatting specifications you can use with csvcolumns applies identically to filter_fields.

For example:

<input type="hidden" name="filter_fields" value="email:c,realname:c,phone:cs,comments:r" />

Please note that you should specify the CSVRaw option if you want to use formatting specifications.