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:
- 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.
- 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.
- 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:
|
|---|---|
| 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:
- Choose a new name for the field. For example, instead of "realname", use "Name".
- When you want expand it in a subsequent page, use: $Name
- 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.
