COWForm 2.0

CGI

Yes! CF2 (or for those of you not into the whole brevity thing, COWForm version 2.0) is here! This upgrade is in fact a total re-write, and the script has matured immensely since the last version. Because this is a new version, I'd really like to know if you have any ideas to improve the script of this documentation and of course, any problems you may incur.

Description:

CF2 is an easy to use, Form to Email gateway. It uses simple templates to format all aspects of its output- you are in full control over everything it outputs. It can be setup to work as a multi-user script- so an ISP only has to install one copy for everyone to benefit from it. It can send out more than one email at once- so for instance, you can have it send one email to you, a different courtesy reply to the user, and another to your boss. It can write directly to files, allowing you to log every time the form is submitted, or to store order details securely on the server. CF2 does not have to send email on every invocation: so you can have multi-part forms which only send email (or write to a file) on the last stage. It can perform mathematical calculations on the data supplied. In short, CF2 is the most powerful, easiest to setup Form Processor around.

CF2 is a Perl script by Tuesday Bjork. It has been tested on Perl 5.004_04, running the Red Hat 4.2 Linux distribution. It should work on any system running Perl 5 and a standard web server like Apache.

Features:

• Fully customizable output formatted by simple text templates.
• Can send any number of different emails on every invocation.
• Can output (append) to any number of files per invocation.
• Can perform mathematical calculations on data supplied in the form- so you can total orders, work out shipping etc.
• Environment Settings (i.e. current time, user's hostname etc.) may be included in the templates.
• Can check that entered data matches a particular format- i.e. all digits, a syntactically correct email address, letters only, etc.
• Does not have to send email on every invocation- so you can have the form take a number of steps to fill out before finally being logged or emailed. (Here's how.)
• Security measures include you being able to specify what forms & sites are allowed to send to the script.
• One script can server a whole ISP, with individual templates being stored in each user's account.
• Simple, easy to understand error messages.
  

System Requirements:

A working server, where you can install & execute CGI scripts.
A working copy of and access to Perl 5 or higher (not perl 4!).
A sendmail compatible mailer (e.g. Sendmail).

Usage License:

This script is free to use, as long as you link to us, as detailed on the link page.
You may not redistribute this script without our express, written permission.
You may not use this script as a basis for your own script, without my express, written permission.
I (Tuesday Bjork) retain all copyright and ownership of the script.

Installation:

• Download AF2.
• Configure the script, the template(s), and your HTML.
• Upload the script, the template(s) (the script must be in anexecutable directory e.g. /cgi-bin, the templates can go anywhere the script can reach them, the HTML goes where your HTML normally goes).
• Remember to upload in ASCII mode!
• Set file permissions (CHMOD alienform.cgi 755, CHMOD all templates 644).
• Use it often!

Download:

Grab either the script and the examples in a Zipped Tarball; or download them individualy:

af.txt - the script itself. Remember to change the extension to .pl or .cgi.
html.txt - an example HTML form that would use the templates given below.
email.txt - an example email template to be sent to you.
email2.txt - an example of an automatic courtesy reply, sent to the person using the form.
error.txt - an example of an error template that would be outputted to the browser should something go wrong.
output.txt - an example success template that would be outputted to the browser if everything went right.
logfile.txt - an example of a log file template.

Configure the Script:

• When you open up the script, please make sure your word processor does not insert any work wraps! The script should be 300 lines long exactly.
• Set the first line of the script, the shebang, to the path to your Perl 5 binaries (Perl 4 doesn't cut it, check which version you're using!).
• Set $content_type to the MIME type you want sent to the browser. Unless you have good reason not to, use $content_type = "Content-Type: text/html\n\n";
• Set $base_path to the base path of your templates. The files specified in the HTML and log templates will be appended to this to make the real file name.
• Set $mail_cmd to the command to send mail on your system. The mailer must be able to accept the message headers and body via STDIN. E.g. $mail_cmd = '/usr/sbin/sendmail -t';
• Set @Referers to the list of Valid Referers- i.e. those sites & pages you want to be able to use the script. All others will be denied access. You can be very specific so only one page has access, or general so a whole site can use it. To allow any site at all to use the form, comment out this value entirely.

Configure the Templates:

Template file names are arbitrary. Try to use names you will remember, e.g. "email.txt", "error.txt", wherever you want the user to supply data, use a word inside square brackets, e.g. [yourname], [age].
You can have underscores in variables, as long as there is a switch in front of it.
You can specify one or more switches on the start of the variables, e.g. [re_email_address], [d_age]. Switches allowed:

r - this values is 'required'- it must be filled in.
e - this value must look like a valid email address.
d - this value may only contain digits (0-9).
w - this value may only contain "word" characters (A-Za-z0-9).
s - this values leading and trailing white space will be removed.

The field names in the HTML must match exactly with those in the templates. I.E. same switches etc.
For the email templates, make sure the To: and From: line will have a valid email address in it (by using the e switch). If you let the user put in any old information into the To: line, your email program will create an error.
Make sure for email templates there is a blank line between the headers and the content.
Logging templates must have the filename to write to as the first line. Everything after the first line will be appended (tacked onto the bottom of) the file specified.
Fields in the templates such at [%HTTP_REFERER], [%REMOTE_HOST] will be substituted with their counterpart environment values. The must begin with a %. You cannot require an environment setting- if it is not set it will be left blank.
In error templates, the error title is specified as [%OUT_TITLE], and the error message is specified by [%OUT_MSG].
To do arithmetic, place the calculation in brackets like [< ... >]. Variables will be filled out before being calculated. Examples:
[< [d_age] / 2 >] - will be given the value of the value of [d_age] divided by 2.
[< ([item1] + [item2] + [item3]) * [tax] >] - will add up the items and multiply them by the tax rate.
Remember to save the templates and the script in ASCII or Plain Text mode.
Configure the HTML

All the operations that you want to occur on this iteration are given in hidden form values. I.e. <input type="hidden" name="_send_email" value="email.txt">.
Operations are done in the order specified in the HTML. For this reason, it is recommended that you specify the browser output last.
Operations are denoted with a leading underscore. They are:
_send_email - this sends email using the template in this tag's value.
_out_file - this logs to a file using the template given in the value.
_browser_out - this displays the value's template in the browser.
_redirect - this redirects the browser to the URL given here.
_error_path - if an error occurs, this template is displayed by the browser.
_error_url - if an error occurs, the browser is redirected to this URL.
You can have more than one _send_email or _out_file, if you want more than one email sent or file appended to. In this case, you must specify a unique number or letter after each one- i.e. _send_email_1, _send_email_2, out_file_a, _out_file_b, _out_file_c. It really doesn't matter what you put after them, just as long as each operation is unique.
Make sure the name of each field corresponds exactly to what you want it to replace in the templates.

Troubleshooting:

• Error Message Explanation & Remedy to Try
  Server Error 500 Something very bad has gone wrong, probably in your installation method. Go through each step in the Configure the Script section. If you still have problems, see The Idiot's Guide to Solving Perl CGI Problems.
• Bad Referer This means the script does not authorize the referer (Form page) to submit to it. Add that host name or IP address (and optionally page information) to the @Referers array. E.G. if I just only wanted the form on http://www.yoursite.tj/form.html to be able to use the script, I'd put 'www.yoursite.tj/form.html' into the array.
• File Access Error The file could not be written or opened for the reason stated. Check than the file exists and the CGI process has permissions to read it.
• File Lock Error The file could not be locked for the reason given. Bad news, talk to your sysadmin.
• File Close Error The file specified could not be closed. No good can come from this, speak to your sysadmin. (If you are the sysadmin, take up golf instead!
• Mailer Open Error The mailer could not be opened. Check that you gave the right location etc.
• Mail Send Error The email could not be sent. Check that you are supplying it with correct headers etc.