The cgiemail program makes it easy for
our customers to setup an e-mail form and have it working in just a few minutes.
Simple forms (up to 9 fields) do not require the customer to do any further
adjustments to the code, but those who wish to customize their cgiemail form to
include more fields, or format the e-mail that will be sent to them when the
form is submitted, will need to understand how the e-mail form works with the cgiemail
template.
Using the Control Panel
Installer
When the Email
Form option in the tools section of the Control Panel is selected,
input boxes appear for the user to name the fields that will be used in the
form. If the checkbox for Required is checked, that field must
be filled out by the visitor of the site for a successful submission.
Below those fields on the form is the success URL entry field. The success URL
is the page that the visitor will be taken to after the form has been submitted.
The value must be a complete URL, including the http://, for a successful
submission. If the URL is not complete, an error will be generated. If no URL is
entered in this field, a page will appear with the information the visitor
submitted.
At the bottom of the page are two input boxes to name the form page and the
template page. The defaults for these are 'form.html' and 'mailtemp.txt'. These
can be renamed if multiple forms will be in use on the site.
The form.html page is the one that will appear on the website.
Viewing the source code for that page reveals the values submitted on the form
creation page in the control panel. Each value can be found in the INPUT tag as
a NAME attribute. This means, essentially, that a variable has been created, and
the person submitting the form will assign a value to that variable by filling
out the form.
For instance, if the first field had an INPUT NAME of "contact", and
the customer has entered "Mike", the cgiemail program will read it as
"contact=Mike" when it processes the form. All fields will be
processed the same way. If the "contact" field is required, then the
INPUT NAME would be "required-contact" and cgiemail would read the
input as "required-contact=Mike".
The cgiemail program also requires a template in order to create the e-mail.
This is the mailtemp.txt file mentioned earlier. This consists of the basic
e-mail header information such as TO, FROM, and SUBJECT. Webmasters will usually
change the default values of these fields so the e-mail message goes to a
specific address, and the subject is made relevant to the form's intent.
Below the header information, a blank line must be in place. If the blank line
is missing, and error will be generated and the form will not submit correctly.
Below the blank line are the same
INPUT NAMES used in the form.html page, only they are contained
in [brackets]. These bracketed names must match exactly the INPUT NAMES in the
form page, or the form will not submit correctly. This is the most common error
with the cgiemail application. Many webmasters will edit the form page and add
more values, but never add the bracketed values in the mailtemp.txt file.
Going back to our example: if the first form field is
"required-contact" and the HTML tag reads "<INPUT
NAME="required-contact">, then the mailtemp.txt file must have
[required-contact] somewhere below the blank line separating the headers. These
fields are case sensitive. [Required-Contact] would fail in the above example.
Text can also be added to the mailtemp.txt file if the webmaster needs
clarification of fields. For instance if several fields of numbers were present
on the form.html page, it would help the cgiemail recipient to have the original
meaning of those numbers present in the e-mail message. So, if a form had
<INPUT NAME="age"> and <INPUT NAME="spouse
age">, the webmaster may want to setup the mailtemp.txt file with
"age [age] spouse age [spouse age] " to differentiate the
two. Spaces can be used in the form and mailtemp
values.
Sample Form and Template Files
Here is the default cgiemail
form as installed from the Control Panel:
<HTML><HEAD><TITLE>Generated
E-mail Form</TITLE></HEAD>
<BODY>
<H2>Generated E-mail Form</H2>
<P>Please fill out the following information and press the SUBMIT
button<BR><P>
<FORM METHOD="POST" ACTION="/cgi-bin/cgiemail/mailtemp.txt">
<INPUT NAME="success" TYPE="hidden" VALUE="http://domainname.com/index.html">
<TABLE BORDER=0 CELLPADDING=0 CELLSPACING=5>
<TR>
<TD><B>contact</B></TD>
<TD><INPUT NAME="required-contact" TYPE="text"
SIZE="35"><BR></TD>
</TR><TR>
<TD><B>company</B></TD>
<TD><INPUT NAME="company" TYPE="text"
SIZE="35"><BR></TD>
</TR><TR>
<TD><B>address1</B></TD>
<TD><INPUT NAME="required-address1" TYPE="text"
SIZE="35"><BR></TD>
</TR><TR>
<TD><B>address2</B></TD>
<TD><INPUT NAME="address2" TYPE="text"
SIZE="35"><BR></TD>
</TR><TR>
<TD><B>city</B></TD>
<TD><INPUT NAME="required-city" TYPE="text"
SIZE="35"><BR></TD>
</TR><TR>
<TD><B>state</B></TD>
<TD><INPUT NAME="required-state" TYPE="text"
SIZE="35"><BR></TD>
</TR><TR>
<TD><B>zip</B></TD>
<TD><INPUT NAME="required-zip" TYPE="text"
SIZE="35"><BR></TD>
</TR><TR>
<TD><B>country</B></TD>
<TD><INPUT NAME="country" TYPE="text"
SIZE="35"><BR></TD>
</TR><TR>
<TD><B>comments</B></TD>
<TD><INPUT NAME="comments" TYPE="text"
SIZE="35"><BR></TD>
</TR>
</TABLE>
<BR><BR>
<INPUT TYPE="submit" VALUE="Submit"><INPUT
TYPE="reset" VALUE="Clear"></FORM>
</BODY>
</HTML>
Here's the mailtemp file for the
above form:
To: webmaster@domainname.com
From:webmaster@domainname.com
Subject: Information Request
[required-contact]
[company]
[required-address1]
[address2]
[required-city]
[required-state]
[required-zip]
[country]
[comments]
Modifying Existing Forms
To Work With cgiemail
First, a template file must be
created (it can have any name, but we'll use mailtemp.txt for this example). The
webmaster will have to go through the form and create a template file based on
the INPUT NAMEs found on the form. The template file should have the desired TO
FROM and SUBJECT headers, then a blank line, then the INPUT NAME values in
backets, with any additional descriptive text necessary to understand the
results. This file should be uploaded to the website in ASCII mode. The rest of
the example assumes the template file will be uploaded to the root directory.
After the template file is in place, the only modification that needs to be made
to the form is in the <FORM ACTION> attribute. The path to the cgiemail
program must be set, along with the template to be used to process the input
values. The cgiemail script resides in the server's cgi-bin directory and does
NOT have to be installed within a customer's account. To reference cgiemail, use
the following format:
<form
method="post" action="/cgi-bin/cgiemail/mailtemp.txt">
This code calls the cgiemail script in
the server's cgi-bin directory when the web page visitor clicks the Submit
button. Cgiemail then calls the template which formats the submitted form
content into an e-mail message, and sends the message to the TO address in the
header of the template.
If you want a specific web
page to load when the e-mail message is successfully sent, such as a thank you
note, add the follow code to your HTML form:
<input type="hidden"
name="success" value="http://your_domain.com/thanks.html">
Subsitute the URL of the file you wish to
load after form data is submitted. The field name in this case MUST be
"success", but does not need to be added to the template. The URL must
be complete, including the http://, for successful submission.
*** Important ***
If you are implementing a secure form in
conjunction with cgiemail, you will need to reference the script in the form
ACTION as well as the "success" URL securely. Please note that the
"secure" environment refers to information transmitted from web
browser to web server. The resulting e-mail message that gets sent from the our
computers is not encrypted and therefore not secure.
*** Tip ***
When you receive the
submitted form content via e-mail, you will see that the return address is one
that is associated with the server domain name. In most instances, the webmaster
may want to reply directly to the person that completed the form.
To do this, add a field to the HTML form, then add the field name to the
corresponding template in the following manner:
To:username@youractualdomain.com
From: [email]
Subject: Information Request
The cgiemail script will insert
the address entered in the field named e-mail. When the emailed form is received
it will be tagged with this return address.