Contact Form Processing Products - for all your needs

FormMail • Form Encryption • Hosted Forms

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:

CSVHeading

specify this option and the CSV filter includes a heading line which lists the names of the fields.

CSVQuote

specifies the quotation character to surround field values. The default is double quote (").

CSVSep

specifies a field separator instead of the default (which is comma).

CSVIntSep

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.

CSVEscPolicy

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:

backslash

this is the default. A backslash character (\) will precede any CSVSep characters in field data. A backslash in field data will be preceded by another backslash.

double

CSVSep characters in field data are doubled. For example, " becomes "". This is compliant with RFC4180 and is the escape policy expected by Microsoft Applications such as Excel and Access.

strip

CSVSep characters in field data are removed (stripped).

conv

CSVSep characters in field data are converted to other characters. The only conversions currently supported are:

  • double quotes are converted to single quotes. This means that if your CSVSep is set to double quote, then any field data containing double quote will be changed to single quote.
  • single quotes are converted to double quotes. This means that if your CSVSep is set to single quote, then any field data containing single quote will be changed to double quote.

If your CSVSep is set to any other character, no conversion is performed and your CSV format may be invalid if the data submitted on the form contains your CSVSep character.

CSVRaw

normally, the CSV filter "cleans" the field data before using it. Cleaning involves:

  1. truncating values to the MAXSTRING length.
  2. replacing sequences of carriage returns, line feeds, and spaces with a single space. This means line breaks will be removed from your field data.
  3. removing all whitespace from the beginning and end of the field data.

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.

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.