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

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

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.

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:

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

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.)

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.

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 of a multi-page form sequence is just a regular HTML form. However, you need to add the following hidden fields:

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:

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.

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 >" />

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 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" />

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).

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.

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).

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.

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.