• You can download it from this page and install it on your site's CGI directory.
• If you don't want to install it or have no CGI support on your account, that's no problem. The script is installed on sandershosting.com and you can use that script directly from your website.

Some of the features of Sanders Hosting's Form CGI are:

• Redirect user to an URL once s/he submits information
• You can specify the format/layout of the email with the data
• You can limit the CGI's usage to just your domain
• You can make fields "necessary"
• Redirect user to an URL if a field is missing, or print custom HTML code
• You can generate a random number to assign IDs to each email
• You can specify who will get the email
• The email can be made to look as if it came from soneone else
• Sends data from multiple checkboxes on one line

Now, one thing you will need is a minor knowledge of HTML Form code first. I'm going to speak a bit here about the HTML involved in forms. If you already know form code, you can skip the following section.

At the end, we'll do an example form so that you can understand everything better.

The HTML behind the form

HTML for forms is easy, but can be quite complex if you wish to do "amazing" forms. We'll keep this short tutorial to a basic level (no Javascript, no CSS, DynamicHTML, etc). At the end, I'll give you a link to more information on HTML for forms.

The first form related tag on every form is the <FORM> tag. Here's an example:

<FORM METHOD="POST" ACTION="http://asdf456.com/cgi-bin/submission/submitscript.cgi">

This tells the browser that form code will follow, that this form will use the "post" method to submit the data (you don't need to know about that to use our form CGI), and that the form should submit data to the URL specified on the ACTION parameter. The URL you see above is the actual URL to the Form CGI on Sanders Hosting.

Now, how to design the form? How do you do all those fields, pull down menus, checkboxes, radio buttons, etc? Well, here's the code:

• <INPUT TYPE="hidden" NAME="emailfrom" VALUE="[email protected]">
  This tag is of the type "hidden". It passes information to the CGI, which is not visible on the page.
  
  Note: all form tags have a "NAME" parameter. You must give each one a name.
  
  
• <INPUT TYPE="text" NAME="firstname" SIZE=25>
  This code generates:
  
  
  
  
  
  It's "name" is firstname, and it has a size of 25. The bigger the size value, the longer the field is. If you add a value parameter like this:
  
  <INPUT TYPE="text" NAME="firstname" SIZE=25 VALUE="Peter">
  
  Then the field will appear like this:
  
  
  
  
  
  It will contain the value on the field by default.
  
  
• <INPUT TYPE="checkbox" NAME="rich" VALUE="yes">
  This code generates:
  
  
  
  
  
  The "value" parameter in this case will make the form send the CGI a "yes" for this field when the checkbox is marked. If no value is specified, the CGI will just get a "off" or "on" for the checkbox. If you use more than one checkbox, all with the same "name", the value of all checkboxes will be sent to you.
  
  
• <INPUT TYPE="radio" NAME="salary" VALUE="20000">
  This code generates:
  
  
  The "value" parameter in this case will make the form send the CGI a "20,000" for this field when the checkbox is marked. If no value is specified, the CGI will just get a "off" or "on" for the checkbox.
  
  Code for radio buttons are usually used in conjunction with other radio buttons. Check the following code:
  
  $20,000 <INPUT TYPE="radio" NAME="salary" VALUE="20000">
  $30,000 <INPUT TYPE="radio" NAME="salary" VALUE="30000" CHECKED>
  $40,000 <INPUT TYPE="radio" NAME="salary" VALUE="40000">
  
  This code will generate:
  
  
  $20,000
  $30,000
  $40,000
  
  
  All this radio buttons have the same "name". Because of this, only one of them gets selected. The "CHECKED" parameter makes the browser "check" that radio button by default.
  
  
• <SELECT NAME="gender">
  <OPTION>Man
  <OPTION>>Woman
  </SELECT>
  
  This code generates:
  
  
  Man Woman
  
  
  The text next to <OPTION> will be sent to the CGI. If you use it this way:
  
  <OPTION VALUE="M">Man
  
  Then the "M" is what will be sent to the CGI.
  
  
• <TEXTAREA COLS="30" ROWS="2" NAME="opinion" WRAP="virtual"> </TEXTAREA>
  This code generates:
  
  
  
  
  
  The COLS and ROWS parameters are to specify width and height. The WRAP parameter specifies how text behaves in the field. The value "virtual" will make text wrap to the next line once you reach the edge of the field.
  
  
• <INPUT TYPE="submit" VALUE="Submit the data!">
  This code generates:
  
  
  
  
  
  Of course, without a submit button...
  
  
• <INPUT TYPE="reset" VALUE="Submit the data!">
  This code generates:
  
  
  
  
  
  And of course, this one resets the form.
  
  And that's it. That's the code to most of the form tags you will be using. There are a lot more parameters for each of them, and you can check them on any HTML reference book or website. I suggest you download "The HTML Reference Library 4.0" at http://www.htmlib.com/. It is a great reference file and it's free.
  
  

Formatting the form to use our Form CGI

For you to be able to use our Form CGI, there are a few special instructions you must send to the CGI as "hidden" tags. Here's a list of some of them:

• <INPUT TYPE="hidden" NAME="emailreceiver" VALUE="[email protected]">
  This tag tells the script where to send the email with the submitted data (your address for example). In this example, it will send the data to [email protected].
  
  
• <INPUT TYPE="hidden" NAME="emailfrom" VALUE="[email protected]">
  If you want an email address to appear in the "FROM" field when you get the email with the data, enter it here as VALUE. In this example, the email will appear to come from "[email protected]".
  
  
• <INPUT TYPE="hidden" NAME="subject" VALUE="Data submission">
  This is the subject that will appear on the email you receive with the data.
  
  
• <INPUT TYPE="hidden" NAME="redirect" VALUE="http://me.com/thanks.html">
  This tag and value will tell the script to redirect the user to that URL when s/he submits the data.
  
  
• <INPUT TYPE="hidden" NAME="randomdigits" VALUE="4">
  This will be explained later on...
  
  

Note: There are more, which will be mentioned in the advanced section farther below.

It is important that you do *not* change the names of these tags, and that you use them all (the "randomdigits" one is not necessary).

Now, the most important part: how to format the email.

Formatting the email

There's one more special "hidden" INPUT field. It's name is "template". Let's follow an example first. Here's a form:

• Once the user submits the data, we want the email with this data to say:
  
  The user's name is "anyname" and his/her age is "age number".
  
  Of course, "anyname" and "age number" will be replaced with the data filled in the forms.
• The subject must say ID of this submission is "randomnumber". "randomnumber" will be replaced by a 4 digit random number generated by the script.
• The email will be sent to "[email protected]".
• The email will look as if it came from "[email protected]".
• We also want to forward the user to http://mydomain.com/thanks.html.
  
  

Now, check the HTML code for the form above with all these requirements by clicking here.

Did you see how the INPUT field named "template" was used? Whatever you put there will appear on the email. Also, it doesn't have to be one line of text. It can be several. Just type up lines of text one below the other. You can leave empty lines and spaces too.

The codes enveloped in double [] are the names of the fields of the form. So, data submitted on the "name" field above will be inserted in all places where there's a [[name]] code. Data submitted on the "age" field above will be inserted anywhere where there's a [[age]] code.

Also, you can embed these codes in the subject field. As you can see in the code, there's a [[random]] code there. Since you later specify that "randomdigits" equals 4, then [[random]] will be replaced by a 4 digit random number. The maximum is 10 digits I believe...

This technique of submitting a template and using codes embedded in [[]] is also used to display a template for when people forget to fill missing fields. We will discuss this in the advanced section below.

Note: names of the fields must be lowercase.

Advanced

Let's play a bit more. As we said earlier, there are more of those hidden INPUT fields with special instructions. Here's a list of a few more:

• <INPUT TYPE="hidden" NAME="necessaryfields" VALUE="firstname,age">
  This makes filling the fields with the names "firstname" and "age" mandatory. What to do if they are not filled? We'll discuss that below...
  
  
• <INPUT TYPE="hidden" NAME="redirectonerror" VALUE="http://me.com/error.html">
  Here's one thing you can do if a user does not fill a necessary field: redirect them to another page. It could be a "error" page saying "You did not filled a necessary field".
  
  
• <INPUT TYPE="hidden" NAME="necessaryfieldnames" VALUE="firstname,First Name;age,Age">
  This gives a "English" name to the fields. More on this below...
  
  

There's two more INPUT fields: one is named "template_missing_fields", which acts very much like the "template" one used above to specify the format of the email, and then there's one called "html_code_to_list_missing_fields". Rather than explaining these advanced functions, it would be better if you would see the source code to an "advanced" form. You can do so by clicking here.

And we have reached the conclusion of this tutorial. The CGI is pretty complete and has all the features you could need. The script is simple and easy to understand if you know a bit of Perl, so you can go ahead and modify it. It's so simple in fact, that writing this tutorial actually took longer than coding the CGI.

If you wish to install the CGI on your own directory, then you can get the source code by clicking here.

Paste it to a pure text file (use something like TextPad; download it at TextPad.com), name it with a .cgi or .pl extension (example: submit.cgi) and upload it in ASCII mode to your /cgi-bin/. Set permission 755 to the file. Make sure the directory where it's in is not set to permission 777.

If you have any questions, contact the tech support department. If you need us to setup the CGI in your account and design the forms you want, there will be a fee of $30/hour.