Creating online forms
SuperForm handles data submitted via your WWW forms. SuperForm was created exclusively for AAPT Web customers and works only if your Web server is at connect.com.au. SuperForm is located in your cgi-bin directory as superForm.cgi

 SuperForm offers several features. You can: 

  • use an unlimited number of fields; 
  • specify any field as mandatory ensuring users complete all necessary information before submitting the form; 
  • set fields to accepts only values of a particular type (matching a particular regular expression); 
  • specify that the information from your form be appended to a file in your AAPT Web area; 
  • nominate a nickname for your form results to be emailed to (nicknames allow you to restrict the set of addresses (Max of 5) that form results are emailed to); 
  • encrypt the information from your form using PGP public key encryption; 
  • customise the message format; and 
  • nominate which URL is displayed when the form is submitted. 
To call the superForm.cgi in your form, you must include the following FORM tag. 
   <form method=post action="/cgi-bin/superForm.cgi">
To email a specific person, add a "nickname" to the mail.list file in the cgi-bin directory in the following format 
   nickname: me@my.email.address

For example, to have two people receive results delivered to the nickname survey, the following line should appear in the mail.list file: 
survey:msmith@connect.com.au,jjones@connect.com.au

(note: if there are more than 5 email recipients the form will fail)

To: Then in the form put the following line to email "nickname"  
    <input type="hidden" name="to-nickname" value="nickname">
Any fields that are in the form will be emailed to the person defined in the nickname field.
From: Then in the form put the following line to define the sender  
   <input type="hidden" name="from-email" value="webmaster@foo.com.au">

To make a field mandatory, you need two lines of code 

  • One input line saying the field is mandatory
  • One input line with the field line.
   <input type="hidden" name="from-name-MANDATORY" value="true">
   <input type="text" name="from-name" size="40">
To call a page when the form is successfully submitted  
   <input type="hidden" name="next-url" value="/path/to/success/file.html">
Some other automatic fields are
  • from-name: The real name of the person filling in the form. If present, it is used in the From Name line of the email message. 
  • from-email: The email address of the person filling in the form. If present, it is used in the From Email line of the email. 
  • subject: The subject of the message. If present, it is used in the Subject line of the email. 

Notes:

  • For mail to be sent you MUST specify BOTH a from and to address, and both must be valid. If you are sourcing one of these addresses from your web page (Eg: your visitor must enter their address) you need to validate this information. 80% of failed forms are due to visitors entering an invalid address. It is suggested that as a best practice you do not rely on the visitor information, by hard-coding in email recipients, and requesting the email address in a different field.
  • We do not support large recipient lists on mail from the web hosting cluster. This is to avoid visitors using our servers as spam relays. If you require a mailing list, please speak to your account manager.


superForm.cgi - Troubleshooting Guide

The most common problem's with superForm.cgi are:
  • Incorrect permissions (should be 755)
  • Incorrect html
  • Incorrect configuration of nicknames (mail.list and $useNicknames value)
  • Uneccesary changes to superForm.cgi
  • Changes have been made offline and ftp'd back to the web site using binary transfer.

To call the superForm.cgi in your form to mail a "specific person" without using nickname's, you need the following FORM tags. 

<form method=post action="/cgi-bin/superForm.cgi">
<input type="hidden" name="from-email" value="username@companydomain">
<input type="hidden" name="to-email" value="username@somedomain">

To email multiple person/s, add a "nickname" (max of 5) to the mail.list file in the cgi-bin directory in the following format.... 

selected_nickname: this@email.address, that@email.address, andtheother@email.address

For superForm.cgi to use nicknames you need to set 

$useNicknames = 1;
(if you dont want to use nicknames set the value to = 0)

The html should look like this.... 

<form method=post action="/cgi-bin/superForm.cgi">
<input type="hidden" name="to-nickname" value="a_nickname_in_mail.list">
<input type="hidden" name="from-email" value="username@companys_domain_name">

The format that nicknames in mail.list should appear is as follows.... 

nickname:emailaddress
(e.g., sales:@billjones@companyname.com.au)

If you want multiple email addresses (Max of 5) to append to a nickname the format is as follows 

nickname:emailaddress,emailaddress,etc
(e.g., sales:bill@companyname.com.au,barry@companyname.com.au,fred@companyname.com.au)

To make a field mandatory, you need two lines of code

  • One input line saying the field is mandatory
  • One input line with the field line.
<input type="hidden" name="from-name-mandatory" value="true">
<input type="text" name="from-name" size="40">

To call a page when the form is successfully submitted 

<input type="hidden" name="next-url" value="/path/to/success/file.html">

Any fields that are in the form will be emailed to the person defined in the nickname field.



Alterations to superForm.cgi

Generally superForm.cgi needs very little alteration, but this is a list of the most common area's where webmasters tend to alter superForm.cgi and cause it to break.  It is always recommended that you make an unchanged copy of superForm.cgi as a backup.

The red coloured area's denote how it should be configured (companyname.com.au refers to your domain name).
  

require "cgi-lib.pl";
# ------------------------------------------------------------
# Configurable variables
# True if must use nicknames
$useNicknames = 1; (or 0 if not using nicknames)
# The name of the default nickname file under the referrers server root
$nicknameFile = "cgi-bin/mail.list"; (or a filename of your own choosing)
# The name of the administrator
$adminName = "www.companyname.com.au webmaster";
# The email address of the administrator
$adminAddress = 'webmaster@companyname.com.au';
# The location and flags of the sendmail program on your system
$sendmailProg = "/usr/lib/sendmail";
# The location of the pgp executable on your system
$pgpProg = "/usr/local/bin/pgp";
# The default name of the pgp public keyring for pgp encryption.
# Relative to $serverRoot
$pgpKeyringDir = ".pgp";
# Define true if you have BSD flock in your perl
$haveFlock = 1;
 
# End of Configurable variables
# ------------------------------------------------------------
ReadParse(*input);  # grab cgi parameters
# Debugging support
#print &PrintHeader;
#print &PrintVariables(%input);
#print `env`;
 
###########################################################################
# Find their server root dir and make sure they are 'one of ours'
# First the domain name of the referer
if ($ENV{'HTTP_REFERER'} =~ /http:\/\/([^\/]*)\/.*/) ( /http[s]?:\/\/([^\/]*)\/.*/ if HTTPS is enabled)
{
    $serverRoot = "/www.companyname.com.au/";
    chomp $serverRoot;
 error("Can't determine server root directory. Perhaps your Web
server is not at <a href=http://www.companyname.com.au>DOMAINNAME</a>")
  if $serverRoot eq '';


More information is available on SuperForm in the documentation within SuperForm itself which you can find by entering the command "cat superForm.cgi" at the prompt in your cgi-bin directory.



Copyright © AAPT Limited