Using The Common Gateway Interface: webform.pl

Name:	webform.pl
Version:	1.9
Last Modified:	April 6, 2005
Author:	Alex Brelsfoard
Updated By:	Alex Brelsfoard

You must use POST method in the form declaration tag.

If there is a chance that the form might be called by a server other than the server the webform.pl script is on then reference the entire URL in the action of the form tag.

If you write data to a file, please protect that file with a simple .htaccess file.

Due to a browser glitch that causes forms to return no value for unselected radio buttons and checkboxes, forms that use checkboxes or radio buttons must have all fields declared with "form-header-list".

Required fields:

at least one (1) of these fields MUST be used

"email-recipients": This is a list of all the email addresses you would like this form to be sent to, separated by commas (,). Example: "john@wpi.edu,Mary@wpi.edu".
"form-record-file": This is an optional field that should be the full directory path to a file that you would like to hold the form data as it comes in. By default this hidden field is NOT included, and therefore nothing is written out to file. By including this field you tell the script to write out the form data to this file. At first, this file should be completely blank ('touch' 'd by a WDO worker & with at least 664 permissions). The script will create the header. Blank fields will be replaced by the term specified in "form-blank-field". NOTE: Be careful to always have your radio and checkbox fields have a default option checked or the field will not be read at all.

There are other co-dependencies. These are listed with their respective descriptions.

Optional fields:

Controlling Form Fields

"required-fields": This should be a comma-separated list of all the fields that you would like to be required. (Ex: "form-fname,form-lname,form-email")
"form-dependency#": This field is used to manage co-dependencies. For example if you would like to make it so that the "other" field is required when the "source" field is filled, you would write the following: <input type="hidden" name="form-dependency1" value="source,other">. If you would like to be more specific you can say: if the source field is filled with the value "other", then the field "other" is required. <input type="hidden" name="form-dependency1" value="source=other,other"> If you have another co-dependency you would like to insert, its name would be "form-dependency2" and counting...
"form-header-list": This field is used for everything that does the automatic field listing: default success page, default email, and output file. This field allows you to list, in order, the fields you want to be printed out (system variables allowed). This should be a hidden field separated by commas; <input type="hidden" name="form-header-list" value="form-name,event,guest,form-referrer,form-datetime">.

Success Pages

Use one or the other

"success-redirect": This should be a full URL to the page you would like the viewer to be sent to upon completion of the web form. (Ex: "http://www.wpi.edu/redirect-page.html")
"success-page": This should be a full directory path to the template file you would like to have used as the success page upon completion of the web form. NOTE: the field "redirect-page" cannot exist for the success page to function properly. If a header ('html-header') or footer ('html-footer') is specified, it will be automatically added to this page.
(Ex: "/www/docs/Academics/Depts/Dir/success.tmpl")

Failure Pages

Use one or the other

"failure-redirect": This should be the full URL of a fully designed failure page. This hidden field is used INSTEAD of using failure-page.
"failure-page": This should be the full directory path to the custom failure page that you would like to use. This file can be a template file, accepting any variables received from the form, the 6 system variables, and the reason for the failure. It is not necessary to list this field if you would not like to use it. If a header ('html-header') or footer ('html-footer') is specified, it will be automatically added to this page.

E-mail Templates

"email-template": This should be a full directory path to the template file you would like used to create the email sent by this script. (Ex: "/www/docs/Academics/Depts/Dir/email.tmpl"). Using this field will require to use of the "form-email" field.
"email-template-user": This should be a full directory path to the template file you would like used to create an email to be sent to the user (most frequently used as a thank you or confirmation email). If this field is not listed on the form page, the default is to NOT send any template email to the user. Using this field will require to use of the "form-email" field.

Collecting Personal Information

"form-email": This should be the complete email address for whomever you would like this email to look like it was sent from. If you would like this email to be the email address of the user filling out the form (so as to make it easier to reply) then make sure to name the email address field (to take down their email address) "form-email". NOTE: only include one email address here.
"form-name": This should be the full name of the person you want to have the form being sent out as. Again, if you want it to look like the email was sent directly from the person filling out the form, then make sure to name the field to hold the user's name "email-from-name". If you would like to have the name broken up in two parts, first name and last name, the use the next two fields INSTEAD (form-fname and form-lname).
"form-fname": Use this field INSTEAD of using form-name. This will allow you to break up the first and last name. This field will contain the user's first name. This field is meant to be used with form-lname.
"form-lname": Use this field INSTEAD of using form-name. This will allow you to break up the first and last name. This field will contain the user's last name. This field is meant to be used with form-fname.

E-mail Options

"email-cc": This is a list of all the email addresses you would like this form to be sent to as carbon copy, separated by commas (,). Example: "john@wpi.edu,Mary@wpi.edu".
"email-bcc": This is a list of all the email addresses you would like this form to be sent to as blind carbon copy, separated by commas (,). Example: "john@wpi.edu,Mary@wpi.edu".
"email-subject": This is the subject of the email to be sent from this web form. This field may contain variables such as the ones used in the template files. Ex: <input type="hidden" name="email-subject" value="Conference Registration, [[form-name]], Dept: [[Dept]]">
"email-cc-user": This is a toggle to say whether or not you would like the user to be cc'd on the email to be generated. "YES" means DO CC the email-from address. "NO" means DO NOT cc the email-from address.

Listing Form Fields in Output

"form-dolist": This hidden field is used to tell the script that you would like one or more fields to show up in the list when listing all the fields and their values (including the system variables). This will overwrite the default setting in the webform_variables.pl file. The default is to not list this field.
"form-donotlist": This hidden field is used to tell the script that you would like one or more fields NOT to show up in the list when listing all the fields and their values (including the system variables). This will overwrite the default setting in the webform_variables.pl file. The default is to not list this field.

Return Page Header and Footer

"html-header": This should be a full directory path to the header file you would like to use for all success and failure pages. If you would not like to use a header file then simply do not list this field. It IS acceptable for this file to contain SSI statements (except nested IF statements).
"html-footer": This should be a full directory path to the footer file you would like to use for all success and failure pages. If you would not like to use a footer file then simply do not list this field. It IS acceptable for this file to contain SSI statements (except nested IF statements).

Other Field Names

All other fields listed on the form will be automatically taken in and used. These field names can be used in your template files.

Using template files:

Template files are simply regular text or web page files with variables in them to be interpolated by webform.pl. Typically they have the extension ".tmpl".

You will create the web page (for success page or failure page) or text file (for email template) pages like normal (but give them the ".tmpl" extension). Then where ever you would like to insert the value entered on the web form (i.e. the user's first name) you will put [[form-fname]] (in the case that you had named the field for the first name on the web form "form-fname").

The permissions for these files should be at least 644.

Other/System variables:

to be used in template files, or listed

"list-fields": This will list all of the fields and variables accepted as listable. By default recipients, form-name, form-fname, form-lname, form-remotehost, and all non-system fields are listed. This can be changed by using the variables form-dolist and form-donotlist.
"form-blank-field": This will Allow you to change the value that is used to replace fields that were left blank. So, if you make a template requesting information from the form, but the user leaves it blank, the script will replace the variable with the term specified here. If this field is not used the default ("[no value entered]") will be used. NOTE: this will also affect when blank values are attempted to be added to the output file (form-record-file). NOTE: Be careful to always have your radio and checkbox fields have a default option checked or the field will not be read at all (these will not be caught as blank fields).
"form-date": This contains the date of the form submission in Month Date, Year format.
"form-datetime": This will be the same as form-date just with the time, in HH:MM format listed directly after the date.
"form-time": This contains the time of the form submission in HH:MM format.
"form-remotehost": This will return the IP address or domain name of the machine the user is on.
"form-referrer": This will return the Web Address of the page that called the EmailForm.pl script.
"form-browser": This will return the type of browser the user is using.
"failure-reason": This will return the error that was received from processing the form. This variable will only work with the failure page, and of course, will only appear when an error has occurred.

NOTES: No spaces or special characters are allowed in the naming of the fields on the form. Acceptable characters are all letters A-Z upper and lower-case, numbers, dashes (-), and underscores (_).

Examples:

Example 1

The following code would create a form that uses templates for the email, the success page and the failure page. It will write out the form data to a file, require two fields, and contain one co-dependency. It will also customize the e-mail's subject, and list all of the fields from the form at the bottom of the email and success pages:

<form method="post" action="/cgi-bin/webform.pl"> <input type="hidden" name="failure-page" value="/www/docs/Alex/failure.tmpl"> <input type="hidden" name="email-recipients" value="alexb@wpi.edu"> <input type="hidden" name="email-subject" value="Event Reservation Request"> <input type="hidden" name="email-template" value="/www/docs/Alex/emailExample.tmpl"> <input type="hidden" name="template-list-fields" value="YES"> <input type="hidden" name="success-page" value="/www/docs/Alex/success.tmpl"> <input type="hidden" name="required-fields" value="form-email,Dept"> <input type="hidden" name="form-dependency1" value="form-fname,form-lname"> <input type="hidden" name="form-record-file" value="/www/docs/Alex/record.txt"> First Name :<input type="text" size="30" name="form-fname"> Last Name: <input type="text" size="30" name="form-lname"> E-mail :<input type="text" size="30" name="form-email"> Phone :<input type="text" size="15" name="Phone"> Department :<input type="text" size="30" name="Dept"> Mailing Address: <textarea name="Address" rows="3" cols="50" wrap="on"></textarea> <input type="submit"> </form>

Example 2

The next example will be a form using the redirect option for the failure page, default email option. It will not be writing out the form data to a file. It will have no required fields but two dependencies. It will still keep the customized email subject. It will cc two addresses and also have two e-mail addresses in the recipients list. It will also overwrite the setting to not have the variable form-datetime display when listing all the fields and values:

<form method="post" action="/cgi-bin/webform.pl"> <input type="hidden" name="email-recipients" value="alexb@wpi.edu, trek@wpi.edu"> <input type="hidden" name="email-cc" value="alexb@wpi.edu, alex@breltech.com"> <input type="hidden" name="email-subject" value="Event Reservation Request"> <input type="hidden" name="failure-redirect" value="http://www.wpi.edu/youfailed.html"> <input type="hidden" name="form-dependency1" value="Dept,Address"> <input type="hidden" name="form-dependency2" value="form-fname,form-lname"> <input type="hidden" name="form-dolist" value="form-datetime"> First Name :<input type="text" size="30" name="form-fname"> Last Name: <input type="text" size="30" name="form-lname"> E-mail :<input type="text" size="30" name="form-email"> Phone :<input type="text" size="15" name="Phone"> Department :<input type="text" size="30" name="Dept"> Mailing Address: <textarea name="Address" rows="3" cols="50" wrap="on"></textarea> <input type="submit"> </form>

Maintained by webmaster@wpi.edu
Last modified: Jul 25, 2005, 15:33 EDT