FillInForm -- A CGI program to verify form contents and send mail.

Overview and simple use

The FillInForm is a simple program (much like AnyForm) which processes the results of an HTML form. This program looks at the original web page where the form came from, and uses embedded comments and hidden form variables to control the action of the program and to decide if the form is correct or not. If there are problems with any of the fields, the form is re-presented with a user specified error message, and the user can correct the information. Once the data is correct, a user selectable acknowledgement page is presented, and a message is sent via email containing the form variables.

This program requires that the HTML file be directly accessible to the web server within the filesystem.

One of the reasons that I wrote this program is to allow Netscape to print the results of a filled in form, something that some versions of Netscape do very poorly with. As elaborations, this also allows error checking of the form before submission via email.

Note that this is a fairly simple program, and expects to find it's information in a fairly straightforward format. This means that you shouldn't try things like embedding HTML comments inside of HTML comments, omitting elements from the form variables, etc. Use the example files as a guide, and you should get reasonable results within the limitations of the program.

I have included a sample use of this program. The following pieces make up the program:

Additional information file

Each HTML file to be processed by this program must also have an associated file with a filetype of .fif. This file contains a number of preset variables which are used to guide the process. Ideally, this information would come from hidden form variables, but those variables are subject to manipulation from the outside. Putting this information in a separate file allieviates the abuse factor. This file typically looks something like: 

Mail-To:	regan@ao.com
Mail-Subject:	Trip plan
Mail-Reply-To:	regan@armoredpenguin.com
Mail-From:	regan@armoredpenguin.com

FIF-NextAction:		email
FIF-AfterEmail:		When done, hit
			continue to resume.

Lines starting with # are simply comments, and are ignored by the program. The entries starting with Mail- are used when addressing email.

Although most of the FIF- and Mail- variables cannot be specified from the input form, two mail headers are rather useful to be based upon user input: From and Reply-To. You can use these by creating a form item which might look like: 

    Your email address: <input type="text" size="20" name="Mail-From">
Note that there is no checking done on the addresses that the web user specifies, so the user of the email should be alert to bogus addresses.

When Email header lines are generated, if there is no Reply-To field specified, it is set to be the same as the From field.

Getting started

The general idea is that the HTML file is standard HTML and thus can be rendered with any appropriate browser. However, embedded into the HTML are comments of a specific form which allow for FillInForm to do its work.

This process starts with the form action looking like: 

    <form action="/cgi-bin/FillInForm/REFERENCE_TO_HTML" method=POST>
This starts the FillInForm, and tells the program where to find the web page. For security reasons, this only can refer to files which are in web space, and those filenames must end in .html.

In the simplest usage of FillInForm, the program presents the form with all of the form fields filled with the text that was entered. This allows the form to be printed by Netscape which is the core reason I wrote this program. Obviously, if the form action was unchanged, there would be no way to process the data. Thus one of the items in the file of additional information specifies the action to take: 

    FIF-NextAction:		email
    FIF-NextAction:		log
The form action gets a "?" followed by the FIF-NextAction tacked onto it to be used for the next submission. If you use the log form, then you also need to set the FIF-LogName variable to the name of the file or directory to log to. Note that this file or directory must be writable by the web server.

Another item to make this simple version useful is another comment which looks like: 

    <!--FIF-AfterGeneration
    	Hit the <i>Submit</i> button if this is correct -->
Any comments of this sort are emitted on the generated page where they appear in the HTML file.

The value of FIF-AfterEmail from the additional information file is presented to the user after email is sent off to the named user. This can contain a link to the next place to go. For example: 

FIF-AfterEmail:		When done, hit
			continue to resume.

In summary, the basic use of the FillInForm package is quite simple, and allows the user to see the form as filled in before submission to email.

Alternate second page

If you want your form information displayed by a different HTML file from the one which collected the input, you can specify an alternate file to use for generating output. Note that all of the error checking is still done based upon the original form.

The additional file variable FIF-ReviewWork is used to specify the file in web space on the server computer which is used for review. The value can also be None in which case a submit on the original page just gets sent via email. 

    FIF-ReviewWork:	/FillInForm/thankyou.html
If you use an alternate review page, it is your responsibility to ensure that all of the appropriate form variables get transmitted onto the final email page. To help with this (i.e. to make it possible), everyplace that a variable name occurs embedded in "$" characters, that symbol is replaced with the contents from the original form.

Alternate email acceptance page

The additional file variable FIF-WorkAccepted is used to specify a file to use for completed work. Variables are substituted as in the FIF-ReviewWork alternate page. 
    FIF-WorkAccepted:	/FillInForm/email.html

Alternate email notification template

The additional file variable FIF-EmailTemplate works very much like the FIF-WorkAccepted item above, and is used to format information which is sent via email.

There is a simple example showing this.

Error checking

The original HTML file can specify some simple pattern matching to verify data before it is sent off. If any error is found, the form is presented again with values filled in as originally specified, and error messages are inserted into the generated page.

The first check is simply to require that the field has something entered. This is specified by special comments in the file which look like: 

    <!-- FIF-Required field-name Error-message -->
This check ensures that the user has typed something into the specified field. If not, the Error-message is inserted into the generated web page.

The next check ensures that the number is numeric, and lies within the bounds specified. It looks like: 

    <!-- FIF-Range field-name min-value max-value Error-message -->
The range is inclusive.

The last check implements a simple Perl regular expression. The main simplification is that the expression must be enclosed in the slash ("/") character, and the slash character cannot appear in the regular expression. This is solely to make it easy to process. It looks like: 

    <!-- FIF-RE field-name /expr/ Error-message -->
Any value matching the expression is OK, all else is considered wrong.

If there are any errors found in the input form, then all of the text in directive of: 

    <!-- FIF-ContainsErrors Error text goes here -->
This allows you to put helpful text indicating to the user that they should find all of the errors, and correct the appropriate fields.

Summary

The FillInForm program allows for a fairly straightforward way to have process a form without writing a new CGI program for each form as long as the results of the form end up being email. It allows some flexibility in checking the fields, and different presentation of the material to the user and email recipient.

PEAK


Last modified 27 May 2006
Dave Regan
http://www.armoredpenguin.com/