cgi-mailer: user documentation

Requirements

All you need is your html form, a format file and (optionally) a response file.

Instructions

1. Your html form must have two hidden input fields, named 'destination' and 'subject'. The 'destination' field will have the email address where the email is to be sent, and the 'subject' field will contain the subject for the email message.

2. Other message headers can be set using inputs of the form header:<header-name> For example, to set the Reply-To: header, use the html <input name="header:Reply-To" value="j.smith@domain.com" type="hidden">.

3. The format file is essentially the body of the email message to be sent. Form fields that you want in the email message just need to have a '$' pre-pended to them. i.e. a form field of 'name' will become '$name' in the format file.

4. The ACTION attribute of the FORM tag should be set to http://your-local-host/cgi-bin/cgi-mailer.pl, and the METHOD should be POST.

5. The format file must be in the same directory as the HTML form, and with the same name as the form, but with an extension of '.data' instead of '.html'. e.g. If your form is 'myform.html', then your format file must be called 'myform.data'. If your form is called 'myform.htm', make sure you read the note below.

6. The response file must be in the same directory as the HTML form, and with the same name as the form, but with an extension of '.response' instead of '.html' (as with '.data' above). The response file will contain the html page you be returned to the user upon successful completion of the form. It can also contain the same fields as the format file (i.e. use $name to display fields that the user filled out).

7. If you wish to make the filling out of some fields in your form mandatory, you can add a "required" file. Create a file called 'myform.required', containing one or more lines of field-name<tab>Description. Each field name will be checked against the input to see if it isn't empty. If it is, an error will be shown using the Description to instruct the user to fill in that particular field.

8. If you don't wish to send an email message, and only want to format and show the response file, include an input field of the name nodata set to the value true.
   e.g. <input name="nodata" value="true" type="hidden">
   In this situation, you don't need a format (.data) file, just a response file.

9. If you want to use an index file for your form (i.e. where the URL of the page ends in '/'), you will need to include a hidden field which specifies the name of the index file:
   i.e. <input name="index-file" value="index.html" type="hidden">
   You can replace "index.html" with the appropriate filename.

10. You might also like to add a hidden field that contains the absolute URL of the form. This will assist users whose browsers or proxy servers don't send or remove the Referer header (which CGI-Mailer relies upon). This field must be called CgiMailerReferer.
    e.g. <input name="CgiMailerReferer" value="http://www.foo.com/forms/feedback.html" type="hidden">
    You can replace "http://www.foo.com/forms/feedback.html" with the appropriate URL.

11. You can reproduce CGI environment variables in the email message and response page by simply referring to them directly. e.g. $ENV{'REMOTE_HOST'}

12. [Note: users with inferior and/or broken operating systems that only allow 8.3 filenames must use .htm, .dat, .res & .req extensions for the respective files.]

Example:

Note: Be sure that the field names in the ".data" and ".response" files are exactly the same as those in the ".html" file.