NAME

guestnik - configurable guest book program


SYNOPSIS

<FORM METHOD=[POST|GET] ACTION="http://SERVER_NAME/cgi-bin/guestnik" ENCTYPE="x-applictation-www-urlencoded">


DESCRIPTION

The guestnik program accepts postings from various HTML forms. It can reside as several links to the same script, and read a different configuration file for each link. It is designed to be secure, using no user-supplied text to produce email addresses, never calling the UNIX/NT shell directly, and running with Perl taint checking. It can be run by either Perl 4.036 or Perl 5.

It requires only one HTML form variable to work properly, form_type, which is normally set as a hidden field in the HTML form. The form_type is used as the basis for all configuration file settings, including the address which the form output will be mailed to. If it is not set an error message will be displayed.

There are two optional variables which are used in the mail header. The variable mail_subject is used as the Subject: line for the mailed message, and the variable title is used in the message header as the title of the form. Omission of either of these is non-fatal, but means that there will be no Subject line or Title display.

This is a valid guestnik form:

<FORM METHOD=POST ACTION="/cgi-bin/guestnik"> <INPUT TYPE=HIDDEN NAME="form_type" VALUE="sample"> <INPUT TYPE=HIDDEN NAME="mail_subject" VALUE="Output of Sample Form"> <INPUT TYPE=HIDDEN NAME="title" VALUE="Sample Form"> Enter your name:<INPUT NAME="name"> </FORM>

It will take the results of the variable and send mail to the location defined by the destination setting in the configuration file. If the destination was defined to be user@company.com, and the user input the name "Mike Heins" in the form, the following mail (or something like it) would be sent.

Return-Path: http Date: Wed, 3 Jan 1996 11:33:06 -0500 Reply-to: mikeh@iac.net To: user@company.com Subject: Output of Sample Form ------------------------------------------------------------- Mailed form input processed by Guestnik V1.03 Date: 01/03/96 Time: 11:33 AM ------------------------------------------------------------- Remote Host: localhost Remote IP No: 127.0.0.1 Other info we received that you asked for: The browser email address: blank The script called: /cgi-bin/guestnik _____________________________________________________________ Form Title: Sample Form _____________________________________________________________ name: Mike Heins

The standard header information that is sent with every form output includes the date and time of submission, the version of the program used to process it, the remote host/ip address of the submitter, and any information asked for with a GetInfo configuration file entry. In this example, the GetInfo entries include HTTP_FROM (the browser's idea of the submitters email address) and the SCRIPT_NAME called. Unfortunately, Netscape does not usually send the header needed for HTTP_FROM, so the browser email address is often blank.

Options

None, other than those in the configuration file.

Configuration File Format

The configuration file is scanned at program startup. There are three variable types -- simple (scalar) variables, arrays, and hashes. The standard types are:

                    BlankError   hash
                    DateStyle    scalar
                    DeleteBlank  scalar
                    Destination  hash
                    FormatError  hash
                    GetInfo      hash
                    IgnoreOutput hash
                    Required     array
                    Standards    hash
                    Thanks       hash
                    ValidForm    hash
                    WhatInfo     hash
                    DEBUG        scalar

The configuration file entries are like this:

Hash: Name key value Array: Name value1 [value 2 ...] Scalar: Name value

An entry must be on the first space of the line -- no indenting is allowed. If a line begins with a space (or tab), it is assumed to be a continuation of the previous line. Lines that are blank are skipped. Lines beginning with a # are comments, which are ignored. The keys and names are not case-sensitive.

The sample guestnik.cfg file gives an example of the format as it is used in practice.

BlankError fieldname value
The message that you wish to send to the user if the field is a required field, and is blank. An example would be:

blankerror name Your name was blank - please go back and put it in the form.

DateStyle [Europe|US]

Controls the order in which the day and month are printed in the date. The default is US-style MM/DD/YY; if you need European style DD/MM/YY put europe in the field.

DeleteBlank yes

If this parameter is defined, blank fields from the form will not be included in the emailed output.

Destination form<email address>
The place where the form is mailed to. The form is the 'form_type' specified in the HTML form. Can contain any number of addresses. An example:

destination orderform sales@company.com,accounting@company.com destination registry marketing@company.com,webmaster

FormatError fieldname value
The message that you wish to send to the user if the field is a required field, had a Standards entry, and did not pass the Standards check. An example would be:

formaterror phone Your phone number didn't have enough numbers in it.

GetInfo HTTP_VARIABLE yes
Fill this in if you wish to get information that may be captured by the web server. Examples of the common ones are in the sample configuration file. Here is one that gets the browser used in the transaction:

GetInfo HTTP_USER_AGENT yes

IgnoreOutput field yes
Set a field so that it will not be listed in the output section of the mailed form. If the value is used in one of the header fields (such as mail_subject), it will still be used for that purpose. It is not case sensitive. Example:

IgnoreOutput form_author yes

The value of the HTML fill-out form variable named form_author will not be printed in the mail message.

Required field1 field2 [fieldn ...]
This is an array of field names which are required to be filled out before the user is allowed to submit the form. If there is a corresponding Standards entry, the field will also be checked to conform to it. If the checks fail, the BlankError and FormatError entries will be checked to see if they exist, and that message (or messages, in the case of multiple failures) will be returned to the user along with a polite request to go back and correct the problem. A default message is displayed if there are not BlankError or FormatError messages. Example:

required name phone email company

This would require that the HTML form entries with the names of name, phone, email, and company are not blank. They may be checked for format if a Standards entry is present.

Standards field standard-spec
This is a format checking entry which takes the form of a Perl regular expression. A couple of standard entries (phone numbers and email addresses) are supplied in the sample configuration file -- contact the author if you need a special one and are not comfortable with regular expressions. Here is the example phone number check:

standards phone (\+?\d+[-/. ]\s*\d+|\d{7,})

Here is a standard that checks to see if a single-letter answer is put in:

standards question1 ^\s*[ABCDabcd]\s*$

A small script, checkstd, is supplied with the guestnik distribution. It will test the Standards entries in your configuration file for syntax, as well as test it against entries that you want to try against the standard.

ValidForm formname yes
This entry is checked to see if the hidden variable named form_type matches. If the form_type is not in the configuration file, the user will not be allowed to submit the entry. This is a check to make sure that the right form is being submitted, and is used to check the email destination address. IMPORTANT: This must be filled in properly, and the form_type must match. To do this, just make sure that you have this entry in your guestnik.cfg:

ValidForm orderform yes

And this as a line in your HTML form:

<INPUT TYPE="hidden" NAME="form_type" VALUE="orderform">

Thanks formtype valid_html
This allows you to have a different thank-you message for each form supported. The valid_html entry can be any valid HTML for display, and can span multiple lines as long as each line begins with a space. Example:

thanks orderform <H1>Thanks for the Order!<H1> <IMG SRC="/images/handshak.gif" ALT="Shake Hands Icon"> <P> Thanks for placing an order with Internet Robotics. We will be sending a confirmation by return email or FAX as soon as possible.<BR> <A HREF="/index.html">Go to Home Page</A>

IMPORTANT: Note that the lines below the first begin with a space.

WhatInfo HTTP_VARIABLE description
Fill this in if you wish to have a description of the information that may have been captured as a result of the GotInfo directive. It will be put in the mailed form output. Example that matches the GetInfo entry above:

whatinfo HTTP_USER_AGENT The browser used by the customer

.

Author

Mike Heins, Internet Robotics, mikeh@iac.net