Advanced Error Handling

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:

<fmerror />

<fmerrorextra />

<fmfullerror />

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

<fmerroritemlist />

<fmerrorcode />

You can download a sample HTML error template from our
download forum.

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

Go to our download forum
and look for the post about fmbadhandler.php.
Download the attachment.

Step 2

Configure fmbadhandler.php by setting two values:

$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:

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.

Large Forms

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>

Email the webmaster (email to "webmaster at tectite dot com")
with questions or comments about this web site |
Email for information (email to "enquiries at tectite dot com")
about our products
By using our software or services you are agreeing to our standard
Terms and Conditions.