CONFIGURING & USING CGIEmail
What is CGIEmail?
CGIEmail is another form processing script, totally different than FormMail. It is a program written
in the C language that takes the contents of fill-in boxes on a form and emails them to a specified
location. In addition to the form specification in the .html file, a mail specification in a .txt
file is required to format the resulting email message.
How do I use it?
We provide the cgiemail in the cgi-bin directory of your server. You need to have an action in your
order.htm file to call it. It should look like this:
<form method=post action="http://www.yourdomain.com/cgi-bin/cgiemail/order.txt">
Note: If you wish to use CGIEMAIL on a secure server please see the
special instructions.
Look for a file in your www directory called order.htm.
This is our example form we
put on your site that shows how a form should be configured to work with
CGIEmail. Look at it in a browser, and download it to your hard drive using FTP
so you can see how it works. If you've never dealt with HTML forms before, don't
worry, they're easy to create and understand.
The form prompts the user for data which is sent to the server as simple key-value pairs. Each
<INPUT> tag specifies a record. The key is given by the name attribute,
and the value is given by the value attribute. The type attribute tells the
browser what kind of data to expect. Now, try looking at the example.
Please note that the hidden items are used to transmit critical info to CGIEmail. They
provide the location of the success file, the name of the person the results should be sent to, and
the subject of the form. When making your own forms, you may want to change the
email address in the required-to field, and likely the subject in the subject field.
The first item tells CGIEmail what to show the user after successfully completing the form. You can,
but don't need to customize this.
After that come the items that are actually presented to the user. You'll want to use
type=text input items with cgiemail: it's a simple tool. The size=60 tells the
browser how big to make the box. The name=something is required in each input tag,
otherwise the browser wouldn't know how to send the data to the server. The value=""
attribute is correct in most cases, unless you want a default value in the form.
Note that if a field begins with required-, cgiemail
will require that the user enter a value for this field. This is particularly
useful if you want to require a user to submit their email address.
When the user presses the Submit button, the data goes to our machine where cgiemail starts doing
something with it. What is does is controlled by the order.txt file discussed
below.
By the way, you can name your HTML form anything you want to.
Now that we have all this data, what do we do with it? Mail it, of course! But for flexibility,
cgiemail requires that you create a mail file to show it what to send. (If
you didn't want flexibility you'd use a mailto link.) The program will read this
file, perform substitutions, and pass it to the mail system. In our example, the mail file is named
order.txt, but you can name it anything you want.
Make sure that you upload your mail file in ASCII mode. Failure to upload in ASCII mode will
generate the message: "Server Error: The server encountered an internal error or
misconfiguration and was unable to complete your request." There is already an
example order.txt document in the forms directory in your www directory (
http://yourdomain.com/forms/order.txt).
Note that the first several lines are mail headers. You probably shouldn't change that part, or the
corresponding parts in your form. In particular, there must be a To: header or
the mail won't go anywhere!
What cgiemail does is simply replace every string that looks like [key] with
the value the user typed into the field with name=key. That's all. You can lay out
your form as is best for your users, but lay out your mail file as is best for you to read.
You can even insert gobs of text to help format the output. Only the
[key] parts will be replaced by CGIEmail.
CGIEmail does not report environmental variables like
FormMail will, but other than that, it is an excellent program, allowing you more flexibility
in the way you want your data returned by the form.
For a more detailed explanation of cgiemail's capabilities and syntax, visit the
cgiemail user guide
published at MIT.
Calling CGIEmail Through the Secure Server
If you want to call your cgiemail form through the secure server, use the following ACTION tag:
<FORM METHOD=POST ACTION="https://machine.safe-order.net/cgi-username/cgiemail/forms/order.txt">
where machine is the name of the server on which your domain resides, and username
is your domain name without the top-level domain extension (e.g., for hostingmanual.net, the username
is hostingmanual.)
If you're specifying a success page, the appropriate tag would be:
<INPUT TYPE=HIDDEN VALUE="https://machine.safe-order.net/username/pagename.html name="success">
CGI & Perl Applications
Source: http://www.hostingmanual.net/cgi/cgiemail.shtml
|
