Return CGI Library
Return Form Handling

Please remember. Everything is case sensitive :-(

Mandatory Fields

If present, a field called MANDATORY lists the fields that must have data in them for the form to be accepted. This will be a benefit to everyone who's gotten a "YES, I want to buy this!" message without a return address :-(

ex. <input type=hidden name=MANDATORY value="FROM field2 field3" />

Presence of a TO value instructs the gadget to send an e-mail.

Supported fields in an E-mail message are:

• TO - An e-mail address. Specifies where the gadget should send the message.
• FROM - The visitor should put their e-mail address in this field.
• SUBJECT - The subject line you will see when you (or whomever is specified by the TO line) get the message.
• TEMPLATE - is template used for e-mail. (TEMPLATE is a file name relative to the top directory of the webserver.)

TO is the only required field for an e-mail message. The gadget makes an effort to put useful values in for the other fields. Note that it even sets a header line if you need to know where a form came from (the IP address and hostname are in a Received: header).

Reply screen

The default reply screen is a a very brief and in-elegant "Thank You" message. To change that, use one of the two methods described below.

The presence of a REPLY value tells the gadget to use a template for generating the reply screen. The value of REPLY specifies a file name relative to the webserver's top directory.

The presence of a REDIRECT value indicates a URL to send the browser to after handling the form data. This URL has to be an absolute URL. That is it must specify the path to the destination page from the top directory (e.g. /dir1/dir2/page.html instead of page2.html). The reason for this is that the browser thinks it is in the /cgi-bin directory. The gadget will stick the hostname and port on the URL if the URL you specify doesn't start with "http://". This can look ugly so you might want to do it yourself. The benefit of not doing it is that your HTML is more portable and you can use it on other virtual servers.

Saving form data to a file

SAVE indicates a file to save the results into. A value of LOGIN is required. The value of SAVE is a filename relative to the home-directory of LOGIN.

FORMAT indicates either a template, or a format to save the results in. Supported FORMATs are tab, comma, quote, and human. (Anything else is treated as a template.) For the pre-formated FORMATS you must specify a list of FIELDS to save.

For security reasons, the name of the file must end in ".dat" ... if it doesn't, the program will add ".dat" to the name of the file. [As a brief explanation, the template formatting could OTHERWISE allow some to append data to the password files that folks use to restrict access to some areas of their site... or a program file, etc... ]

Auto Responders

The presence of fieldnames whose names start with "ar-" indicates an autoresponder. The rest of the field name is taken as a path to a document to mail back. You can have several autoresponders in a single form. Each selected autoresponse will be sent in it's own e-mail message.

Required fields are: FROM (where the message should be sent), LOGIN (whose directory to look in for the documents to be mailed out), and of course the ar- fields themselves (which are usually done as checkboxes).

You can set the subject message on the auto-response by creating a hidden field with the name prefix "ars-" and the rest of the name being the same as the "ar-" field.

The auto-response will be mailed to the address in the FROM field, and will by default come from the webmaster of the server (usually webmaster@domain).... To change this specify a hidden variable named AR-FROM and put the desired return address as it's value.

NOTE: The autoresponder will generate status messages if you don't have a REPLY or REDIRECT value set. This can be useful when setting up your forms and files (after it works, you can put the pretty face on it later :-).

Formatting

You can specify format checks for a variable by creating a hidden field with the name prefix "format-". (e.g. "format-FROM" to specify a format for the "FROM" field.) There are currently four supported formats: EMAIL, CCNUM-, REGEXP-, and REGEXPI- which support email adresses, credit card numers, and PERL regular expressions (in both case sensitive and case insensitive forms). See the format page for details.

FLAGS

There is a FLAGS field for specifying some special/optional parameters. These will be COLON separated lists of options. The only option specified write now is ":OVERWRITE:" which causes the save-to-file option to overwrite the datafile instead of appending to it.

Notes:

One other note for folks using templates. All your HTML templates must specify links with respect to the top of the webserver... as the browser will think it is in the /cgi-bin/ directory (i.e. it is on the /cgi-bin/mail2 page).