Creating HTML Forms for use with Tectite FormMail

Creating HTML Forms

Search our site:

Introduction

This page describes how to configure an HTML form to use Tectite FormMail.

If you know nothing about HTML forms, we recommend you use our Configuration Wizard to get a working sample HTML form. There are also a number of good resources on the web to teach you about the basics of HTML forms:

Alternatively, you can download a sample form with embedded instructions here.

Communicating With FormMail

Your HTML form communicates its requirements to formmail.php through a set of "hidden" fields (using <input type="hidden"...>).

The data to be processed by formmail (e.g. the actual email of form results to send to you) comes from a combination of hidden fields and other form fields (i.e. data entry fields from the user).

Configuring Your HTML Form

Here are the steps to use formmail.php with your HTML form:

Create your HTML form using standard HTML. Set the form tag's action attribute to the URL of your formmail.php.

Ensure your HTML form has the following fields defined. These are fields you expect the user to fill in:

email	the user's email address
realname	the real name of the user

Add some hidden fields to your form to tell FormMail what to do with the form results (see below). Typically, you'd specify recipients, subject, and required, as a minimum.
Once your form is working, you'd probably add good_url and bad_url.
Check that you've provided at least one of these fields:
- recipients
- logfile
- csvfile and csvcolumns
If you don't specify any of these, then formmail.php will fail because you've given it no work to do!

Hidden Fields

The following is a list of the hidden fields you place in your HTML form to instruct FormMail to perform various actions with form results.

This is not an exhaustive list: there are other hidden fields that FormMail recognizes for more advanced functions. See the HOW TO guides for more features.

recipients

a comma-separated list of email addresses that the form results will be sent to. These must be valid according to the TARGET_EMAIL configuration inside FormMail.
Example:

You would normally use the AT_MANGLE feature to hide the email addresses from spambots.
Example:

cc and bcc

a comma-separated list of email addresses that the form results will be sent to as CC ("carbon copy") and BCC ("blind carbon copy"), respectively. These must be valid according to the TARGET_EMAIL configuration inside FormMail.
Example:

You would normally use the AT_MANGLE feature to hide the email addresses from spambots.
Example:

required

a list of fields the user must provide, together with a friendly name. The field list is separated by commas, and you append the friendly name to the field name with a ':'.
Example:

Note that field names and friendly names must not contain any of these characters:

:|^!=,"

Advanced usage allows you to do the following:

field1:name1\|field2:name2	either field1 or field2 is required (both allowed, too)
field1:name1^field2:name2	either field1 or field2 is required (both not allowed)
field1:name1=field2:name2	field1's value must be the same as field2's value
field1:name1!=field2:name2	field1's value must be different from field2's value

In all the above ":name" is optional for any field.

The "required" feature is a simplified way of doing some of what the "conditions" feature can do (see below). Only use "required" or "conditions" on your HTML forms, not both. (You can use both, but the Advanced Error Handling feature works best if you only use one of them.)

conditions

a list of complex conditions, all of which must evaluate to true to allow the form submission to proceed. Conditions are a more powerful alternative to the "required" specification (see above).

We recommend that you use the "conditions" feature or the "required" feature on your HTML forms, but not both. "Required" is simpler to use, but less powerful.

The list of conditions is separated by a character you specify by the first character in the list. You specify the internal conditions component separator as the second character in the list, as follows:

specifies that the conditions are separated by the colon character, and that internally, each condition's components are separated by the @ character.

There are size limitations to HTML fields. Therefore, FormMail allows you to specify any number of conditions fields like this:

A condition has this general format (spaces optional):

@COMMAND@ test1 @test2 @... @MESSAGE@

COMMAND and MESSAGE are mandatory. MESSAGE is the message to display to the user if the condition fails. "@" is the internal separator that you specified as the second character of the conditions list. The tests are field comparisons, and have this general format:

field1 OP field2

OP is an operand. Tests are similar to the "required" specification, but the friendly field names are not supported (or needed, because you can provide a general message).

field1	field1 must have a value
field1&field2	both field1 and field2 must have a value
field1\|field2	either field1 or field2 must have a value (both allowed, too)
field1^field2	either field1 or field2 must have a value (both not allowed)
field1=field2	field1's value must be the same as field2's value
field1!=field2	field1's value must be different from field2's value
field1~pattern	field1's value must match the specified perl regular expression
field1!~pattern	field1's value must not match the specified perl regular expression
field1#=number	field1's value is interpreted as a number and must equal the given number
field1#!=number	field1's value is interpreted as a number and must be not equal to the given number
field1#<number	field1's value is interpreted as a number and must be less than the given number
field1#>number	field1's value is interpreted as a number and must be greater than the given number
field1#<=number	field1's value is interpreted as a number and must be less than or equal to the given number
field1#>=number	field1's value is interpreted as a number and must be greater than or equal to the given number
!	the test evaluates to "false".
empty	the test evaluates to "true".

The available COMMAND values are:

@TEST@test@message@	the test must be true. If not, the given message is shown.
@IF@test1@test2@test3@message@	if test1 is true then test2 must be true. If test1 is false then test3 must be true.

Following are some examples of conditions.

@TEST@realname@ Please provide your name so that we can address you properly.@	Test "realname" for a value and display the given message if it has no value. This has exactly the same functionality as a required specification except that you can provide an arbitrary message.
@TEST@email=email2@ Please enter your email twice.@	Test that the fields "email" and "email2" have the same value.
@TEST@age #>= 18@ You must be at least 18 to continue.@	Tests the age the user claims to be.
@IF@ salutation ~ /usefirst/ @ firstname@lastname@ You must provide your first name if you want us to use it to address you, or, your last name for Mr., Mrs., etc.@	Tests that firstname is required if salutation has the value "usefirst", and lastname is required otherwise. On failure, the given message is shown.
@IF@ payment ~ /ccard/ @ creditcard ~ /^[1-9][0-9]{12,15}$/@@ You must enter your credit card number to pay by credit card.@	Tests that if the payment value is "ccard" then the creditcard field must begin with 1 to 9 and be followed by between 12 and 15 digits.
<input type="hidden" name="conditions1" value=":@ @TEST@realname@ Please provide your name so that we can address you properly.@: @TEST@age #>= 18@ You must be at least 18 to continue.@: @IF@ payment ~ /ccard/ @ creditcard ~ /^[1-9][0-9]{12,15}$/@@ You must enter your credit card number to pay by credit card.@" />	This is a complete example that simply shows a number of the above conditions joined together in one conditions field. Note that colon separating each condition.

mail_options

a list of options to control FormMail when sending email. Options are:

AlwaysList	Tectite FormMail has a feature where it automatically formats a simple contact form to look like an ordinary email. This happens when the form only contains some special fields (such as "email", "realname") and one non-special field (typically a textarea field). When there are a number of non-special fields, FormMail formats the email as a list of lines like "field: value". The AlwaysList option forces the one non-special field case to be formatted this second way instead of the first way.
CharSet	Allows you to set the Content-Type email header field to specify a particular charset value.
DupHeader	Tells FormMail to duplicate some header lines in the body of the email. "To", "Cc", and "From" are the lines that are duplicated.
StartLine	If DupHeader is also specified, StartLine tells FormMail to include a "start" line like this "--START--". This feature can be used to help programs to automatically parse your emails.
Exclude	Provides a semicolon-separated list of fields to exclude from the form results email.
FromAddr	Provides an email address that will be the From address in the email sent. Some servers require a special email address to be specified before they will send email. You can use the AT_MANGLE feature to hide the email address from spambots.
KeepLines	Some fields, such as textareas, may contain embedded newlines. Normally, FormMail strips newlines from fields. If you specify this option, FormMail will keep the newlines.
NoEmpty	Normally, FormMail includes all fields sent from the user's browser even if they are empty. This option tells FormMail to exclude empty fields from the email it sends you.
NoPlain	If you specify HTMLTemplate, FormMail sends a MIME-formatted email. Normally, in this case, FormMail includes a plain-text copy of the form results as well as the MIME-formatted form results. If you specify the NoPlain option, FormMail does not include the plain-text copy.
SendMailFOption	This option is deprecated and has been replaced with the SENDMAIL_F_OPTION configuration setting.
HTMLTemplate	set to the name of the template to use for sending HTML email to the user
PlainTemplate	set to the name of the template to use for sending plain text email to the user
TemplateMissing	set to the string to use to fill in unsubmitted or empty fields in templates

Example:

derive_fields

a mechanism for deriving form fields by concatenating other form fields.
Example:

Operators are:

+	concatenate with a single space between, but skip the space if the next field is empty
.	concatenate with no space between
*	concatenate with a single space between

file_names

a mechanism for naming the files uploaded by the form. By default, the files will be named with user's original file name. This feature allows you to provide different names. The same facilities are available as for derive_fields.
Example:

good_url

the URL to redirect to on successful processing.

bad_url

the URL to redirect to on failed processing.

this_form

the URL of the form that's submitting the data; used with intelligent bad_url processing.

good_template

a template file that FormMail can display on * successful processing.

bad_template

a template file that FormMail can display on failed processing.

template_list_sep

a string to use when expanding lists of values in templates. The default is comma.

subject

a subject line for the email that's sent to your recipients.
Example:

env_report

a comma-separated list of environment variables you want included in the email.
Example:

filter

name of a filter to process the email before sending. You can encode or encrypt the email, for example.
Example:

filter_options

comma-separated list of options to control the filter.
Example:

filter_fields

comma-separated list of fields to filter. The behaviour of this specification can vary slightly depending on your other specifications. Refer to our How-To guide on Filtering for more information.

logfile

name of a file to append activity to. Note that you must configure LOGDIR for this to work.
Example:

csvfile

name of the CSV database to append results to. Note that you must configure CSVDIR for this to work. You must also specify the csvcolumns field.
Example:

csvcolumns

comma-separated list of field names you want to store in the CSV database. These are the field names in your form, and the order specifies the order for storage in the CSV database.
Example:

autorespond

comma-spearated list of specifications for the Auto Responder feature. Specifications are:

Subject	set to the subject line you want in the email sent to the user
FromAddr	set to the address you want as the From address in the email sent to the user. This would usually be your address. If you don't specify FromAddr, your server may use an inappropriate address for the sender of the email. You can use the AT_MANGLE feature to protect your email address from spambots.
HTMLTemplate	set to the name of the template to use for sending HTML email to the user
PlainTemplate	set to the name of the template to use for sending plain text email to the user
TemplateMissing	set to the string to use to fill in unsubmitted fields in template

You can specify either HTMLTemplate or PlainTemplate or both.
Example:

alert_to

email address to send errors/alerts to.
Example:

This feature is deprecated. The correct way to specify an email address for alerts is with the DEF_ALERT setting inside FormMail.