Contact Form Processing Products - for all your needs

FormMail • Form Encryption • Hosted Forms

Multi-page Forms

This How-To guide explains how to use multi-page forms with FormMail..

Introduction

Starting from version 7.00, FormMail supports HTML forms consisting of multiple consecutive pages.

Also, if you include our optional FormMail Computation Module, you can perform calculations between the pages.

Some reasons to use multi-page forms are:

  • you have a lot of information to collect from the user and you want to structure it into smaller pages
  • you need to control what information to collect based on the answers the user provided for previous form values (fields)
  • you need to perform calculations from the submissions of a form before displaying another form

Doesn't JavaScript Handle This?

JavaScript can handle some requirements of multi-page forms. However, there are several problems with JavaScript:

  1. You cannot rely on JavaScript being available or switched on in the user's browser. Therefore, you need to detect this and disallow these users from accessing your form.
  2. Use of JavaScript to handle all the features that multi-page forms can provide requires the skills of a professional programmer. With JavaScript, your HTML form must become a complete program.
  3. You cannot protect your forms from manipulation. For example, suppose you had a "total" calculation in JavaScript. An attacker could bypass that calculation or adjust it to their benefit before submitting the form fields to your server.

Can't I Use PHP To Do All This?

Yes. Using PHP you can do all that FormMail's multi-page forms can do and more. However, you need to be a very knowledgeable programmer to write safe, secure, and reliable PHP code.

As with JavaScript, your HTML forms must become a complete program if you use PHP.

The multi-page features in FormMail are designed to bridge the gap for you between simple HTML and complex programming.

The purpose is to allow non-programmers to construct professional multi-page forms with little or no programming skills.

Working Example

If you'd like to see an example of a multi-page form, try our working example.

Our Computation Module is also useful with multi-page forms, and we have a working example that performs calculations between pages.

Feel free to use your browser to view the HTML source code so you can see how each page operates.

Before Getting Started

Before trying to create a multi-page form, get a single page form working first. Make sure you understand at least these features of FormMail:

recipients specifying the email recipients of form results
good_url
good_template
redirecting the user to a "thank you" or completion page
bad_url
bad_template
redirecting the user to an error page. You're probably also going to want to use our FMBadHandler for advanced error handling.

You can start with a single form by using the sample here.

Overview

The first page of a multi-page form sequence is an HTML form that submits to FormMail. This is a regular HTML document with the appropriate action set to formmail.php.

All other pages of a multi-page form sequence are FormMail templates. These are regular HTML documents with forms that submit to formmail.php, but you can also substitute previous field values (i.e. values submitted from previous pages) by using the $field syntax.

For example, if on the first page the form provides a field called "name", you can show the value that the user enters in this field by using $name on subsequent forms.

The last page of the form sequence should provide the recipients field and the good_url or good_template you want to use.

(You can provide recipients on each page, but then FormMail will send interim results for each page submitted. This is probably not what you want.)

FormMail Configuration

In the configuration section of FormMail, you must set either $MULTIFORMDIR or $MULTIFORMURL.

You should set aside a particular directory/folder on your server to hold the templates for your multi-page forms. However, if you prefer, you can use the same location as the rest of your pages.

The second, third, ... pages of a multi-page form must be located in directory/folder you've specified in $MULTIFORMDIR or $MULTIFORMURL.

For returning to the first page in the sequence, FormMail requires you to provide the $TARGET_URLS configuration. This setting is a security feature and it specifies the valid URL prefixes that can be used when returning to the form. The typical setting would be:

$TARGET_URLS = array(
    "http://www.yourhost.com/",
    "http://yourhost.com/");

If you've already worked with FMBadHandler, you'll be familiar with this setting in FormMail.

Note the specification of your host name with and without the "www.". We've seen some servers identify themselves without the "www." even though the website is always accessed with "www.". By specifying both URLs, you may avoid receiving a "Return URL is invalid" alert message from FormMail.

Sample Multi-Page Form

You can download a sample 3-page form from here.

The sample consists of 1 HTML document and 2 HTML templates:

  • multitest.htm
  • multitest2.htm
  • multitest3.htm

The first file is the HTML document and you can place it in your server's document root. The other two files are templates and must be installed in $MULTIFORMDIR or $MULTIFORMURL.

You can find configuration instructions inside each of the 3 files.

The First Page

The first page of a multi-page form sequence is just a regular HTML form. However, you need to add the following hidden fields:

this_form set to the full URL of the page
multi_start set to "1" (value="1").
next_form set to the name of the next form in the sequence. This file must be in the location specified by $MULTIFORMDIR or $MULTIFORMURL.

Second to Second-Last Form Pages

All form pages other than the first must be FormMail templates. A FormMail template is simply a regular HTML document but with some special tags and/or strings that FormMail will substitute.

For example, suppose your first form page requests the user's name:

<input type="text" name="name" />

On the second or other pages, you can display the value the user submits like this:

<p>
Your name: $name
</p>

The second and subsequent pages of a form sequence must provide the following hidden fields:

this_form set to the special value provided by FormMail, like this:
<input type="hidden" name="this_form" value="$this_form_url" />
As mentioned above, you need to set $TARGET_URLS in FormMail to allow this feature to work.
next_form set to the name of the next form in the sequence. This file must be in the location specified by $MULTIFORMDIR or $MULTIFORMURL. The last page in the sequence obviously shouldn't specify next_form - see below for instructions for the last page.

The second and subsequent pages of a form sequence must not specify the multi_start hidden field. That is only for the first form in the sequence.

The Next Button

You need a way for the user to submit each form page and go to the next form page in the sequence.

It's simply a submit button, like this:

<input type="submit" name="submit" value="Next >" />

A Back Button

The second and subsequent pages can provide a back button too, to allow the user to go backwards in the sequence. Here's how:

<input type="submit" name="multi_go_back" value="< Back" />

The Last Form Page

The last page is just like the second and subsequent pages, but with some important differences:

  • it must not provide the next_form field
  • it must provide the final hidden fields required for the form submission. For example, it would likely provide recipients and good_url or good_template.
  • The submit button should probably be called something other than "Next". This is usual:
    <input type="submit" name="submit" value="Submit" />

Error Handling

Each page should provide its own bad_url or bad_template fields. If you use our FMBadHandler it will automatically allow the user to go back to the individual page in error to make corrections (provided you've specified this_form as described above).

Expanding Fields in Templates

As described above, every page except the first in a multi-page sequence is a FormMail template. This means you can show previously submitted field values.

For example:

<p>
Your name: $name
</p>

Note, however, for technical reasons, FormMail does not expand special fields. Special fields include "email" and "realname".

In most cases, this isn't a major problem. However, if you find you need to expand special fields, such as "realname", use these steps:

  1. Choose a new name for the field. For example, instead of "realname", use "Name".
  2. When you want expand it in a subsequent page, use: $Name
  3. On the page that you want the actual special field value set (this is usually the last page), create the special field like this:
    <input type="hidden" name="realname" value="$Name" />

You can get the complete list of Special fields by looking in FormMail for the value called $SPECIAL_FIELDS.

Remembering Previous Values

FormMail remembers the values entered by a user on a page and automatically re-enters them when the user goes backward in the multi-page form sequence.

Because of potential data corruption in the submitted form, FormMail does not usually re-enter values when the user goes forward after going backwards.

As an example, if page 2 in a multi-page form contains Name and Address fields, and the user goes back to page 1, then forward again to page 2, FormMail will not restore the Name and Address details the user previously entered, and the user must re-enter them him/herself.

On first glance, this might not seem sensible. However, if page 2 contained a money calculation based on a value entered on page 1, then there would be the danger that the money value was not recalculated if the user went back to page 1 then forward to page 2. This danger is the reason FormMail does not usually restore fields when the user goes forward.

Beginning with version 7.02, FormMail provides this "Forward Remembrance" as an optional feature. To enable it, each of your HTML pages must provide a list of the fields you want re-entered in a hidden field called multi_keep. Like this:

<input type="hidden" name="multi_keep"  value="name,address1,address2,town,postcode" />

multi_keep specifies which fields are safe to restore for the user when the user goes forward after going backwards.

Each page must only list the fields to "forward remember" that are present on that page. It must not mention fields on other pages (if it does, the field value will be forgotten).

Working with File Uploads

To use file uploads with multi-page forms, you must set SCRATCH_PAD in FormMail's configuration section. This is required so that FormMail can save uploaded files in your private temporary folder when moving between the pages of your multi-page form.

Advanced Features with File Uploads

Multi-page forms in conjunction with file uploading can be used for very advanced and complex forms processing. Especially when combined with our FormMail Computation Module and Advanced Templates.

For more information about this please refer to the How-To guide on uploading files.

 
Close