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.
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:
specify this option and the CSV filter includes a heading line which lists the names of the fields.
specifies the quotation character to surround field values. The default is double quote (").
specifies a field separator instead of the default (which is comma).
specifies an internal separator for fields that are arrays or lists of values. For example, a multiple selection select box can submit a list of values. These values will be listed as a single column in the CSV output, separated by the internal separator. The default internal separator is semicolon.
specifies the escape policy for field data. If a field value contains a CSVSep character (e.g. double quote), then those characters must be escaped to ensure the CSV format is valid.
The supported escape policies are:
normally, the CSV filter "cleans" the field data before using it. Cleaning involves:
If you specify the CSVRaw option, then no cleaning is performed on the field data.
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.
<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.