Mail-form-results
SWCP Simple Mail-in Form Processor
A Tutorial
Introduction The HTML specification lets the author of a World Wide Web (WWW) page create "forms" which allow users to submit information to the system. Each form is a screen with one or more data entry fields and buttons. The user types information into the appropriate boxes and then presses a "submission" button which then sends the form information to the WWW server.
The author of the form specifies the name of a program to be run on the WWW server to process the form. This program (usually called a "cgi-bin" program or script) can be made to do just about anything with the data: email it to a human, store it in a file, use it to query a database and display the results, etc.
HTML has no facility for "generic" forms. Each new form requires a new custom program to be written to process the particular data produced by that form. Obviously, replicating very similar forms can become quite time-consuming and expensive.
To help avoid some of this expense, SWCP has produced a program which can be used in a generic way to e-mail the results of a form submission to a user. The program will work with any form and can be used by any user. The only limitation is that the program only takes one action: it e-mails the form data to a user. If you need a form to do anything different, then you will have to write your own (or hire somebody to write it for you).
How To Use It
This tutorial does *not* cover the issues involved in form creation in general. It is assumed that you will know what to do with the information that follows. If not, you should read up on how forms work. Two good resources are:
http://www.utoronto.ca/webdocs/HTMLdocs/NewHTML/intro.html has a good section on forms. The data at this site is part of a book which has just been published, called "The HTML Sourcebook". From its description, it sounds like a good reference.
The book "Managing Internet Information Resources," published by O'Reilly, has a couple of chapters on HTML, including forms. It's a big book with LOTs of other good information in it about other Internet resources (gopher, mailing lists, etc.)
The name of the program is mail-form-results and it is stored in the /cgi-bin directory on SWCP's WWW server. To use it, use this URL for the ACTION in your form:
/cgi-bin/mail-form-results
Note that you do not necessarily have to have your own cgi-bin directory to use mail-form-results because it resides in SWCP's cgi-bin directory, which is available to all users.
Caveat:If you have your own domain, you'll need to fully specify the path to the system wide CGI bin as follows in the ACTION for your form:
http://pages.swcp.com/cgi-bin/mail-form-results
Your form must include three hidden fields which communicate information to mail-form-results. They are:
form-owner
Email address to which the results of the form should be mailed. Example value: cheeks@swcp.com
return-link-url
After a form is submitted, the user is shown a page which says something along the lines of, "Thanks, click <here> to go back to <some page>". return-link-url specifies the URL that will be offered. Example value: http://www.swcp.com/~cheeks
return-link-name
This is the name of the link that return-link-url points to. Example value: Cheeks' Home Page
There are several optional hidden fields which you may include in your form to tell the form processor to treat certain other fields in a special way:
email-field
The name of the field in your form which will contain the email address of the person submitting the form. Example value: email
subject-field
The name of the field in your form which will contain a subject for the email message which is sent to you.
Example value: subject
return-link-immediate
This field is optional. If this field exists and has a value of true, then instead of displaying a page with a link to the return-link-url, the user will be sent to the return-link-url directly.
Example value: true
omit-empty-fields
If set to true, then form fields which a user leaves blank will not be included in the email message sent to the form owner. This is useful if you have a very large form but the typical user only fills out small parts of it.
Example value: true
append-file
If set, the named file will be appended to the email message which is sent to the form owner. You must specify the full pathname for the file.
Example value: /users/cheeks/.signature
required-fields
If set, the list of fields named will be required. If the user neglects to provide data for one or more of those fields, they will receive an an error message and be asked to supply the required data. The field names should be separated by commas, and they must appear exactly as the fields are defined elsewhere in the form. (For example if you say that the field "Address" is required but the field in the form is really called "address", then the user will never be able to fill in the appropriate data and will always get an error message.
Example value: name,addr1,addr2,phone
wrap-long-lines
If set to an integer, then a field that is longer than this value will be folded to this line length. This is for use with fields where one expects a long response. It will make them easier to read in the mail message.
PGP encryption
There are several variables needed to provide PGP encryption. See this tutorial for information on what's needed to successfully set up PGP encryption. The variables involved with this process are pgp-encrypt, pgp-path, pgp-platform, pgp-do-mime. And gpg specific variable, gpg-keyring. Note: we now use gpg exclusively for the encrypting program.
If you include the email-field hidden field in your form, then the field it points to will be examined to check whether it contains something that looks like an email address (i.e. something like user@someplace.com). If it does not, then the user will be told that they must enter a valid email address and they will have the chance to back up and re-enter it. If the field does have an email address, then the mail message which is sent to you will list that address in the "From:" line of the mail header. Note that the user can enter anything in the email address field, so they may enter something which looks like a valid email address but isn't (e.g. bob@some-fake-place.net).
If you include the subject-field hidden field in your form, then the field it points to will be used in the Subject: header of the email message which is sent to you. The typical use for this field would be to reference another hidden field (e.g. subject) which contains the subject text which will be used for all submissions of that particular form. For example, the subject field could be defined as Form submission from spinach survey or New product feedback. Another option would be to make the subject field a regular form input field which is filled in by the user.
Note that both the email-field and subject-field hidden fields are optional. If you do not include email-field, the mail message which is sent to you will appear to be from the user nobody. If you leave out subject-field then the subject of the message will be Form Submission.
After the form is submitted, you will receive an email message which contains a list of each field name and the data entered by the user for that field.
Note that the form-owner, return-link-url, and return-link-name hidden fields must appear in lower case. If they appear in upper or mixed case, mail-form-results will not recognize them and you will get an error message when you try to submit the form.
Captcha
There is a newer version of this script mfrwc (Mail form results with CAPTCHA) to cut down on the spam you get sent from the web. This version of the script uses a few additional fields and include files and 'requires Javascript enabled by you website users.
Examples
Here is a sample form which demonstrates the use of mail-form-results. Feel free to copy and modify this form for use on your own pages. If you do this, PLEASE remember to change the three hidden fields to be appropriate for your form.
Here is a copy of the email message I received after entering data into the above form and submitting it. The order that the fields appear in the email message will always be the same as the order in which they are declared in the form definition.
If you have any questions about (or problems with) using mail-form-results, send mail to webmaster@swcp.com.
