web design and hosting
features and pricing my account customer support about ICG Link, Inc. contact ICG Link, Inc.

Form.pl: The Basics
   
 
 
Our form script is a powerful, yet easy-to-use tool that will make your web site more interactive and useful for your visitors. The script allows you to create a web page with fields that are filled out by a visitor and then perform various tasks with that information. When the form is submitted, the information can be sent by email to a recipient or recipients in any format you choose, it can be saved to a file in any format you choose and the script can send the visitor to a plain results page or one that presents the data as submitted or presents altered information based on any calculations or automatic decisions you may want to apply to the information. When used in combination with the search and replace scripts, you can even use this script to enter content you manage from a back office administration area.

Select the article that describes the form script functions you need.
  • The Basics (this article): Send and format an email message, write to a file in a format of your choice, specify required fields, set up an error page, protect yourself from spammers.
  • Advanced Form Functions: Set and check cookies, perform calculations with built in math functions, manipulate text, use if - then logic, use a wide variety of preset values and more.
  • Upload Files: upload one or several files with a single submission, resize image files on the fly, create image thumbnails at the same time and more.
  • Send Encrypted Mail: Send encrypted email messages with GnuPG.
  • Perform Secure Transactions & ecommerce: Use the form script on our secure server and enjoy useful features dedicated to e-commerce.
MINIMUM NECESSARY:
  • <FORM METHOD="POST" ACTION="/cgi-bin/form.pl"> starts the form.
  • <TYPE="hidden" NAME="f_success" VALUE="/success.html">
    • This tells the form where to go after the form is submitted.
    • value=/filename - goes to the main web directory.
    • value=/foo/filename - goes to the foo directory.
    • Use a relative address for the location of the success page if you plan to carry information forward. If you use a full URL, field tags won't be replaced with information from the form. For example, if you use http://www.icglink.com/success.html for the success page, you will go to that page without being able to display any information from the form. Full URL is useful for a simple "Thank You" page.
    • See TEMPLATES below for more information on results pages.
  • This form is pretty useless unless you ask for information, so you will want to use textboxes, textareas, radio buttons or checkboxes to gather the information. A simple textbox asking for a name might look like this:
    <input type=text name="name" value="Enter Name">
  • <INPUT TYPE="submit" VALUE="Send Info"> submit button sends the form.
  • </FORM> ends the form.
REQUIRED FIELDS:

Use r_fieldname to require a field and use f_required to specify the page the visitor sees if they don't fill in a required field. For example, if the name field in the example above was required, you might use the code below.
    <input type=text name="r_name" value="Enter Name"> where the r_ makes the field reqiuired.
    <INPUT TYPE="hidden" NAME="f_required" VALUE="Full URL"> sets the required error page.
If the f_required page template includes the tag <! missingfields> somewhere on the page, that tag will be replaced by a <br> delimited list of missing fields. So you might want to say something like:

The following required fields were not filled out:
���<! missingfields>

DELIVERY OPTIONS:
  • <INPUT TYPE="hidden" NAME="f_recipient" VALUE="info@icglink.com"> is the e-mail address where the message will be sent. To send to multiple addresses, separate each address with a comma, as in info@icglink.com,someone@icglink.com,another@icglink.com. If you need to format mail for different recipients differently, see TEMPLATES below.
  • Note that <INPUT TYPE="hidden" NAME="f_cc" VALUE="info@icglink.com"> can be used to send a "copy" of your message to someone and <INPUT TYPE="hidden" NAME="f_bcc" VALUE="info@icglink.com"> can be used to send a blind copy of your message to someone.
  • <FORM METHOD="POST" ACTION="/cgi-bin/form.pl?info@icglink.com"> does the same thing for a single addressee.
  • <INPUT TYPE="hidden" NAME="f_sender" VALUE="anyone@icglink.com">
    or <INPUT TYPE="text" NAME="f_sender"> assigns the e-mail "From"
  • <INPUT TYPE="hidden" NAME="f_subject" VALUE="Message from Form">
    or <INPUT TYPE="text" NAME="f_subject"> assigns the e-mail Subject. The subject defaults to ** Form Entry ** if not assigned.
  • <INPUT TYPE="hidden" NAME="f_template" VALUE="locationoftemplate"> and
    <INPUT TYPE="hidden" NAME="f_htmltemplate" VALUE="locationoftemplate"> define how an email message will look.
    • If no template is specified, a default plain text email is sent in the form:
      fieldname: value
      fieldname: value
    • If f_template is specified, a plain text email is sent in the form you specify in the text file specified in VALUE=".
    • If f_htmltemplate is specified, an html email is sent in the form you specify in the text file specified in VALUE=".
    • If f_template and f_htmltemplate are specified, a multipart/alternative email is sent with both plain text and html attachments.
    • If the template file is named "template.mail" and is located just inside your "www" directory, you would replace locationoftemplate with /template.mail. For example, value="/filename" - goes to the main web directory andvalue="/data/filename" - goes to the data directory
    • Don't use full URL for template files or your variable information will not be passed.
    • The template is a simple text file with the layout you choose. In the template file, you can use <! field="fieldname"> to apply variable information from the form.
    • See TEMPLATES below for more information on mail templates.
  • Sending a fax rather than an email message is possible if you have signed up for our fax service. Once it's set up, just add the following variable to your form:
    <INPUT TYPE="hidden" NAME="f_fax" VALUE="/faxtemplate.name"> where faxtemplate.name is the location of the template used to format how the fax will look.
WRITING TO A FILE:
  • <INPUT TYPE="hidden" NAME="f_data" VALUE="filename.data"> assigns the file name where information is sent. The file must be in your /web/data directory.
    • value=filename.data - goes to the data directory
    • value=/filename.data has no effect
  • NOTE: FILE PERMISSIONS MUST BE rwxrwx--- (770) or you won't be able to write to the file.
  • <INPUT TYPE="hidden" NAME="f_delimiter" VALUE=","> if not included, defaults to a tab-delimited text file in the order fields appear on the form.
  • <INPUT TYPE="hidden" NAME="f_record" VALUE="!"> if not included, defaults to returns as record delimiters.
  • Data are saved in the order the fields appear on the form unless f_format is specified.
  • <INPUT TYPE="hidden" NAME="f_format" VALUE="locationoftemplate"> is the format template that defines the format of the data as it goes to the file. If the file is named "format.data" and is located just inside your "www" directory, you would replace locationoftemplate with /format.data.
    • value=/filename - goes to the main web directory
    • value=/foo/filename - goes to the foo directory
    • Don't use full URL for template files.
    • See TEMPLATES below for more information on format templates.
To enter un-typable characters, use the following backslash combinations instead.
  • backslash f - formfeed
  • backslash n - newline (return and linefeed)
  • backslash r - return
  • backslash t - tab
  • backslash backslash - backslash
SAVING ADDITIONAL FILES:

Simply Repeat the steps above adding a single digit starting with 1 after the name of each field. You may write to up to 10 files including the initial one - each with their own formatting, etc.
  • <INPUT TYPE="hidden" NAME="f_data1" VALUE="anotherfile.data"> assigns the second file name where information is to be sent. Once again, the file must be in your /web/data directory.
    • value=filename.data - goes to the data directory
    • value=/filename.data has no effect
  • NOTE: FILE PERMISSIONS MUST BE rwxrwx--- (770) or you won't be able to write to the file.
  • <INPUT TYPE="hidden" NAME="f_delimiter1" VALUE=","> This specifies the delimiter to be used on the second file. if not included, defaults to a tab-delimited text file in the order fields appear on the form.
  • <INPUT TYPE="hidden" NAME="f_record1" VALUE="!">Tells file 2 what to use to separate records. if not included, defaults to single returns as record delimiters.
  • Data are saved in the order the fields appear on the form unless f_format1 is specified for the second file.
  • <INPUT TYPE="hidden" NAME="f_format1" VALUE="locationoftemplate"> is the format template that defines the format of the data as it goes to the second file. If the file is named "format.data" and is located just inside your "www" directory, you would replace locationoftemplate with /format.data.
    • value=/filename - goes to the main web directory
    • value=/foo/filename - goes to the foo directory
    • Don't use full URL for template files.
    • See TEMPLATES below for more information on format templates.
TEMPLATES & PASSING VARIABLES (f_template, f_format, results pages):

A template is a text file (or in the case of results pages, an html file) that contains special substitution tags. The substitution tags in the template are automatically replaced with the matching information from the form. The tags can be inserted anywhere in the text and are in the form of
    <! FIELD="somefieldname"> where somefieldname is the NAME of a field from the form.
For example, you could include the following in a response email message using f_template.
    Thank you, <! FIELD="name">, for your order. We will call you at <! FIELD="phone"> with the status of your order.
If you submit a form with f_success set to the name of an html results page (using relative URL not full), the substitution tags in the template are automatically replaced with the matching information from the form in exactly the same way.

If you need to pass an environment variable, use <! env="name"> where name is the environment variable you want to display.

Sending Mail Using Multiple Templates: You may wish to send different email messages to different recipients when a form is submitted. For example, you might want your web site to send a support request to yourself and a thank you to the sender telling them they will receive help within some specified time period, or you might wish to send an encrypted message with secure form data to one person and an unencrypted message to someone else saying that secure data has been received. You can now use f_recipient, f_recipient1, f_recipient2 and so on with an unlimited amount possible, as long as the other attributes match. ie... f_template, f_template1 and f_sender, f_sender1, etc. (same with f_cc and f_bcc)

Quotation marks in a form: If you must pass a form value from one page to another where the liklihood exists that a form user will enter a quotation mark, you will have to make special provisions to prevent errors on the following template page. Include the tag <input type="hidden" name="f_quote" value="1"> and the script will pass the quotes correctly. Be sure this hidden tag is on a line by itself.

ERROR PAGE TEMPLATE:

Use f_error to set up an error page template. This page will return errors not caught by f_required, such as incorrectly formatted f_sender fields. The error page template must be in the data directory.
    <INPUT TYPE="hidden" NAME="f_error" VALUE="name.html"> sets the error page.
If the error page template includes the tag <! error> somewhere on the page, that tag will be replaced by a statement explaining the error.

HIDING FUNCTIONALITY FROM SPIDERS AND VIEW SOURCE
If you would like to hide the information in your hidden fields from people viewing your source or from spiders visiting your site looking for email addresses or other information, you can put all your hidden fields in a configuration file in your /www/data folder. To call this file, use the following tag:
<INPUT TYPE="hidden" name="f_conf" value="filename">
where filename is the full file name of the conf file (ie: myform.conf. The configuration file must be placed in your /www/data folder and should contain two columns separated by tabs or spaces. The first column contains the form variable without the _ prefix (ie: success, template, format, recipient, etc.) and the second column contains the value for that form variable. Any tags included in the .conf file will take precedence over the tags in your form, thus, the only tag really needed on the page is the one that calls the .conf file.

CAPTCHA & OTHER FORM SPAM PROTECTION:

The form script offers two methods for keeping spam robots from finding your form and filling it out automatically. Both use methods that attempt to determine if a genuine human is filling out the form.

First is the f_humancheck feature. Place the following code anywhere between the form tags that would be valid if you wanted it to be seen:

<table id="bigt">
        <tbody>
                <tr>
                        <td><input type="text" name="f_humancheck" /></td>
                </tr>
        </tbody>
</table>


<script type="text/javascript" language="javascript">
document.getElementById("bigt").style.display="none";
</script>
The above method uses CSS to establish a field that can be seen by robots, but not a human. If the field is filled out, the form fails.

Second is a captcha, which is one of those funky images that has characters on it that you must enter into a form before you can submit it successfully. It is used to insure that a human is entering the data and prevents robot spam. In order to use Captcha with form.pl you must:
  1. put <div id=captchaimage><img src="http://www.icglink.net/images/spacer.gif" id="newimg" width="150" height="50" /></div> wherever you want the captcha image to appear.
  2. create an input field called f_captcha where the user enters the string that appears in the image.
  3. paste the following code between the form tags:

<input type="hidden" name="f_captchasession" id="f_captchasession" value="test">
<!-- DO NOT ALTER THE CODE BELOW -->
<script language=JavaScript src="http://www.icglink.com/includes/jquery.js"></script>
<script language=JavaScript>
//<!--
$(document).ready(
function() {
myRand=parseInt(Math.random()*99999999); // cache buster
$.getScript('/cgi-bin/captcha.pl?rand='+myRand, function(sid) {
$('#f_captchasession').val(sid);
var i = document.getElementById('newimg').src = '/cgi-bin/captcha.pl?sid='+sid;
});});
//-->
</script>
<!-- DO NOT ALTER THE CODE ABOVE -->
SIMPLE FORM EXAMPLE:
(requires visitor to enter his name, sends mail and writes to a file.)

<form method="POST" action="/cgi-bin/form.pl">
<input type="hidden" name="f_subject" value="New Name Submitted">
<input type="hidden" name="f_data" value="project.data">
<input type="hidden" name="f_format" value="/project.format.data">
<input type="hidden" name="f_template" value="/project.template.data">
<input type="hidden" name="f_success" value="/thanks.html">
<input type="hidden" name="f_required" value="http://www.foo.com/required.html">
<input type="hidden" name="f_error" value="error.html">
<input type="hidden" name="f_recipient" value="info@yourdomain.com">
<input type="text" name="r_name">
<input type="submit" value="Go">
</form>
ICG Link, Inc. 7003 Chadwick Drive, Suite 111, Brentwood, TN 37027