Advanced Error Handling with FormMail

This How-To guide explains the error handling features FormMail provides for your forms.

Introduction

All versions of FormMail contain a default method of handling user errors and "system" errors. By "system" errors we mean errors in your form or failures of your server that are detected by FormMail.

FormMail distinguishes between these two classes of errors. Your web site visitor receives a different error message depending on the class of error.

FormMail provides the following levels of error handling (shown in increasing order of features):

Default	FormMail generates a standard page with little formatting. In the case of user errors, the page shows the specific error the user made. Limitations: The user must use the Back button in the browser to go back to the form (and sometimes the data they entered will be cleared from the form). The error page is just text - it doesn't look like the rest of your website.
bad_url	When an error is detected FormMail redirects the browser to a URL you specify. This gives you full control on the formatting of the page. Limitations: Unless you're prepared to write PHP or some other CGI script, the specific error message won't be displayed. Also, it's not trivial (or reliable) to allow the user to get back to the form with most of their data re-loaded for them. These limitations are removed if you use our Bad Handler (see below).
HTML Template	You create an HTML document that will be used as a template for your error page. You can format the error page to look exactly like the other pages on your website. This is a template because you can specify where errors are to be displayed by using special tags that FormMail will replace with error messages. FormMail displays your template to the user with the error messages displayed where you want them. Limitations: The only limitation with this approach is that the user cannot reliably get back to the form with their data re-loaded for them.
Our "Bad Handler"	We've provided another PHP script that you can use directly, or use as a basis for your own development. It's called fmbadhandler.php. fmbadhandler.php will provide a default error page with some formatting. When used in conjunction with an HTML template you provide, this option gives you the ultimate error handling If you set it up correctly, and provide the right information in your form, fmbadhandler.php automatically provides a link for the user to return to the form with all their data re-loaded. Limitations: none that we know of!

The sections below describe each of these options in detail.

Default Error Handling

In the default case, FormMail handles user errors by displaying a standard error page which shows the error that was detected.

Here's an example:

An error occurred while processing the form.

Some of the values you provided are not valid.
You've asked us to use your first name, but you
haven't told us what it is.

"System" errors are handled by sending an alert message to you, and displaying a page to the user that says you've been notified. (Note that the alert will only be sent if you've configured FormMail or your form to do so.)

An error occurred while processing the form.

Our staff have been alerted to the error.
We apologize for any inconvenience this error may have caused.

This is adequate for you while you develop your form and get it working. However, for a professional website, you'll want to use one of the more advanced error handling features.

Using bad_url

In your form, you can provide the following hidden field:

<input type="hidden" name="bad_url" value="http://someurl/" />

When FormMail detects an error it redirects the user's browser to the URL you've provided.

This can be an HTML page or a CGI or PHP script. By using a CGI or PHP script, you can get access to the actual error messages and display them to the user. An HTML page is static, so there's no opportunity to change the contents and display the error message; to display the error message(s) you need a script.

FormMail can add the error details to the URL you've provided. If your bad_url is a PHP script, then FormMail can also provide the error details in PHP session variables.

For non-PHP CGI scripts, you need to look at the documentation for the language you're using to find out how to access URL parameters. Below, you'll find the list of URL parameters FormMail adds to provide error information.

For PHP scripts, you can access the URL parameters with the $HTTP_GET_VARS or $_GET arrays.

The URL parameters that FormMail adds to your bad_url are:

error	the basic error message to display to the user. For example: "The form required some values that you did not seem to provide."
extra	information about the error. For example, this would show the list of required fields that the user didn't enter.
errcode	is the internal FormMail error code. You can look through formmail.php for these values if you want to use them. You generally wouldn't display this value to the user.
isusererror	is 1 if the error was a user error, or 0 if it was a "system" error.
alerted	is 1 if FormMail has sent an alert to you, or 0 if it hasn't.
erroritem1	each one contains one item that FormMail discovered in error. For example, each one would contain the name of a required field that the user failed to enter.

HTML Error Template

You can create an HTML document that FormMail can use as a template for error pages.

The process is simple:

Create an HTML document that's just like a page on your website.
Insert some special tags where you want the error(s) displayed.
Install the template in a special directory on your server.
Configure FormMail's $TEMPLATEDIR value to specify that special directory.
Add the bad_template hidden field to your form.

Steps 1 & 2

Create an HTML document and format it the way you want. Now, add one or more of the following tags to your document to present the error information to the user:

[fmerror /]	this is replaced with the basic error message. For example: "The form required some values that you did not seem to provide."
[fmerrorextra /]	this is replaced with extra information about the error. For example, this would show the list of required fields that the user didn't enter.
[fmfullerror /]	this is a shortcut for "[fmerror /]<br />[fmerrorextra /]".
[fmerroritem1 /]	this is replaced with the first error item. For example, the name of the first required field that the user didn't enter. Similarly, for [fmerroritem2 /], [fmerroritem3 /] and so on.
[fmerroritemlist /]	this is replaced with the list of error items each enclosed in <li></li> tags.
[fmerrorcode /]	this is replaced with the internal error code. You generally wouldn't show this to the user.

For FormMail version 8.24 and below and FMBadHandler version 1.21 and below, the tag format was slightly different, as follows:

<fmerroritem1 />, <fmerroritem2 />, ...

You can download a sample HTML error template.

Sometimes you'll want to use the same error template for system errors (e.g. server broken) and for user errors (e.g. missing fields). You can designate specific areas in your template that should only be included for user errors. Simply bracket these areas with [fmusererror] and [/fmusererror] tags. You can use these tags any number of times.

To bracket areas to include for system errors only, use [fmsyserror] and [/fmsyserror].

For FormMail version 8.24 and below and FMBadHandler version 1.21 and below, the tag format was: <fmusererror>...</fmusererror> and <fmsyserror>...</fmsyserror>

Step 3

For security of your server, FormMail will only process templates from a special directory. You can create a directory or folder on your server and call it "fmtemplates", for example.

Upload your new template to that directory.

Step 4

Ensure you have the latest FormMail version. Edit formmail.php and set $TEMPLATEDIR to the full path of the template directory you created in step 3.

Step 5

Add the following field to your form:

<input type="hidden" name="bad_template" value="fmerror.htm" />

replacing "fmerror.htm" with the name of the template you created.

Using an HTML template with our Bad Handler provides you with the ultimate in error handling.

Use our Bad Handler

Simply put, our Bad Handler is a PHP script you can use for your bad_url. Our Bad Handler is called fmbadhandler.php.

By default it provides a standard error page and a link back to the form (if the form tells it how). If the user clicks the link back to the form, fmbadhandler.php displays your form again but keeps all the data the user has already entered.

If you use fmbadhandler.php with an HTML template, you get the ultimate in error handling for your forms.

Using fmbadhandler.php is easy:

Download it from our download forum.
Configure it and upload it to your server.
Specify the URL to fmbadhandler.php in your form.
If you want to use your own HTML template (recommended) specify that on your form.
If you want the user to have a link back to the form in the error page, specify that in your form too.

Step 1

Download fmbadhandler.php.

Step 2

Configure fmbadhandler.php by setting two values:

$TARGET_URLS

$TARGET_URLS	if you want your error pages to have a link back to the form, you must specify the URL of your website(s) in this configuration setting. Here's an example of this setting, specifying two possible URLS for your forms: `$TARGET_URLS = array( "http://www.yoursite.com/", "https://secure.yoursite.com/");`
$TEMPLATEDIR	if you want to use an HTML template for your error handling, you must specify the directory on your server where you store your templates. See the section above about HTML templates for more information. This is the same value as you would set in FormMail. An alternative is to use $TEMPLATEURL; this is documented inside fmbadhandler.php.

if you want your error pages to have a link back to the form, you must specify the URL of your website(s) in this configuration setting.

Here's an example of this setting, specifying two possible URLS for your forms:

$TARGET_URLS = array(
    "http://www.yoursite.com/",
    "https://secure.yoursite.com/");

$TEMPLATEDIR

if you want to use an HTML template for your error handling, you must specify the directory on your server where you store your templates. See the section above about HTML templates for more information. This is the same value as you would set in FormMail.

An alternative is to use $TEMPLATEURL; this is documented inside fmbadhandler.php.

Step 3

Edit your form, and add the following hidden field:

<input type="hidden" name="bad_url"
    value="http://yoursite.com/fmbadhandler.php" />

Step 4

To use an HTML Error template, review the section above, and then edit your form, and add the following hidden field:

<input type="hidden" name="bad_template" value="yourtemplate.htm" />

Step 5

Edit your form, and add the following hidden field:

<input type="hidden" name="this_form" value="http://yoursite.com/yourform.htm" />

In other words, create a hidden field called "this_form" with the value being the URL to the form itself. You can refer to this field value as $return_link in your template.

Large Forms

If you're using Advanced Error Handling, it's probably because your form is quite large.

Please review the PUT_DATA_IN_URL FormMail configuration setting.

We recommend you set it to false to configure FormMail to communicate with FMBadHandler using a PHP session. This ensures there are no size limitations when passing your form fields between them.

Dynamic Web Sites

When the Bad Handler opens a URL you've specified (such as this_form or a template), it appends a parameter that tells the page what type of browser the user is using.

This is important for some web sites where the content is rendered depending on the user's browser type.

Our Bad Handler appends the following to the URLs it opens:

USER_AGENT=....

This means, for example, your pages can find out the user's browser by looking at that HTTP parameter. In PHP, you would do this:

if ($_GET["USER_AGENT"] == "somevalue")
....

HTML Form Reset Buttons

If your form includes a Reset button, your users will find that it doesn't work as you might expect once they return to the form.

This is because FMBadHandler inserts the user's original entries as the initial values of the fields. An HTML form Reset restores fields to these initial values.

If you really want your users to be able to clear all fields after returning to the form after an error, then change your Reset button to be a link to the original form.

For example, if your form is "http://www.mysite.com/contact.htm", you could do this:

<a href="http://www.mysite.com/contact.htm">Reset</a>

Finally....

One last thing to discuss....fmbadhandler.php returns the user to the form by reading the form then setting all the fields to the values the user previously entered.

It's quite flexible in doing this, but you'll need to format your field tags (INPUT, SELECT, OPTION, TEXTAREA, etc) in a way that's compatible with fmbadhandler.php. Read the section "Formatting your forms" in the comments at the top of fmbadhandler.php for full details.

And finally.....fmbadhandler.php puts the return link to your form just before the body end tag "</body>". If you want it in a different place, use the following tag:

[return_link /]

For FormMail version 8.24 and below and FMBadHandler version 1.22 and below, the tag format was: <return_link />

If you want to include just the URL of the return link (i.e. this_form), you can use $return_link, like this:

<a href="$return_link">Return to form</a>