DM 171: Week Eleven - Form Processing

Email Form Processing

An email form on your site is a great way to encourage your visitors to communicate: there is no need for them to open a dedicated email application (Outlook, Mail, Thunderbird,…) to send you a message. It also lowers your exposure to email harvesting spambots that look for mailto: in the email links within your code.

In General

If you already have web hosting for a domain, there is a good chance that a form/email handling script is already installed. It is good to know both for yourself and as an economical option for your clients since you do not have to install the CGI script; you only have to configure the HTML form page correctly. A very popular option is FormMail by Matt Wright; I have seen it installed by default at a number of hosting services. There are also third party vendors that host email processing scripts remotely for you; you may need this option if your/your client’s web host does not allow CGI installation or does not have any solutions pre-installed.

You may also choose to install your own script. For this example, we will be using Big Nose Bird’s bnbform.cgi script to do the email work for us.

Click on a tab to reveal its content…

  • Big Nose Bird’s Form Script
  • Configure bnbform.cgi
  • Create HTML Form
  • Misc Details

Obtain bnbform.cgi

The bnbform.cgi is a very flexible form processing script and is also free!

  1. Go to the Big Nose Bird web site and download the bnbform.cgi script and documentation package:
    http://bignosebird.com/carchive/bnbform.shtml
    the links are located a bit down the page.
    * The .tar archive uses Unix line endings, the .zip archive uses Windows line endings. Some servers may object to Windows line endings so you may be better off sticking with the .tar archive. Thanks to Melody for the warning…!

  2. After downloading the archived, un compress it with the utility of your choice.

  3. You should be presented with a folder named “bnbform” that has several files in it:
    • bnbform.cgi - the Perl form handling script
    • bnbform.html - a sample HTML file showing form element examples used to configure bnbform.cgi
    • mymessage.baut - your message if you turn on the auto respond function (Sigh, sadly, at least one spammer has a robot that fills out contact forms to generate auto messages so they can harvest email addresses that way. Turn this function on with care…)
    • oops.html - a sample HTML file with an example of an error message; certain user errors will send them to this page
    • README.TXT - guess…
    • SSLNOTES.txt - notes about using bnbform.cgi with secure pages
    • thanks.html - an example HTML file used for a “thank you” page after successful use of the form

  4. Next, configure bnbform.cgi, go to the next tab…

Configure and Upload bnbform.cgi

Make sure to use a text editor that will give proper Unix line endings to configure bnbform.cgi. The README.TXT has more detailed instructions; these will get you through installation on the webhawks.org server. You will need to make three changes to the bnbform.cgi.

  1. Line #62: Un comment the line and change the domains to reflect webhawks.org; this protects from others using the form from another domain. Change from:
    #@okaydomains=("http://mydomain.com", "http://www.mydomain.com");
    to:
    @okaydomains=("http://webhawks.org", "http://www.webhawks.org");

  2. Line #67: Comment this line; we will use sendmail instead of SMTP mail. Change:
    $SMTP_SERVER="localhost";
    to:
    #$SMTP_SERVER="localhost";

  3. Line #72: Un comment the line and change the path to sendmail. Change:
    #$SEND_MAIL="/usr/lib/sendmail -t";
    to:
    $SEND_MAIL="/usr/sbin/sendmail -t";
    Note the change in directories from /lib to /sbin.
    Note! This path to sendmail may differ from server to server; you may need to use a utility script like envirolyzer.cgi to find the proper path to sendmail for your particular installation.

  4. While you have the bnbform.cgi open, read the commented section that starts with:
    ############## SPECIAL FORM VARIABLES ############################
    All the variables (more or less) can be used in your HTML form page to configure the bnbform.cgi except the last two.

  5. Save bnbform.cgi for upload to the webhawks server.

  6. Using an FTP client, create a folder within the public_html folder of your webhawks.org web space called cgi-bin, it is important that the name is exact so the server will allow scripts installed within it to execute. Within your cgi-bin, create another folder named bnbform. You don't really need this extra directory; however, you will end up with a number of files associated with bnbform.cgi so this helps to keep your cgi-bin a bit tidier.

  7. Upload bnbform.cgi into the bnbform directory that you have just created inside your cgi-bin; make sure that it uploads as text.

  8. Change bnbform.cgi’s permissions on the server to “755” to let the server know it is OK to run the script.

On to the next tab…

Create HTML Contact Page

Now use Dreamweaver to create your contact page. Open the sample file “bnbform.html” that came with bnbform.cgi to see examples of form fields and how they are used to configure bnbform.cgi.

  1. Ask Dreamweaver to create a new HTML file; name it to your wishes and give it the .shtml suffix if you are using server side includes.

  2. Add your heading and a paragraph explaining how to use your form.

  3. From Dreamweaver’s menus, Insert > Form > Form or click on the Form button on the Forms toolbar.

  4. Configure your form tag, you may work from the code or the properties inspector.
    form tag properties inspector screen shot
    These settings produce this code:
    <form id="contact" name="contact" method="post" action="/~dm171student/cgi-bin/bnbform/bnbform.cgi">
    </form>

    The path value of your action attribute will reflect the path to your webhawks server space and its cgi-bin:
    action="/~your-webhawks-user-name/cgi-bin/bnbform/bnbform.cgi"
    Notice that the Form name field of the properties inspector creates both id and name attributes with the same values. The better to style your form…

  5. Between the form tags or within the thin red border of the form in Design view, insert (via menu or toolbar) a text field to collect your user’s name, give it a name and configure it to taste. When you insert a form element, you will be presented with an Accessibility Attributes dialog box; refer to the help menu for instructions on filling these options out. Yours may look similar to my example:
    <input type="text" name="name" accesskey="n" tabindex="0" id="name" />

  6. Insert another text field, name it “submit_by” in the properties inspector. This is one of the Special Form Variables commented in the bnbform.cgi script; its value is the email address of the person completing form. It is a mandatory field for bnbform.cgi to work since the script needs the user's email address to send your auto respond message back if you have specified this option. Your code may look like my example:
    <input type="text" name="submit_by" accesskey="e" tabindex="0" id="submit_by" />

  7. Insert a textarea for your user’s message, name it to your choice.

  8. Insert submit and reset buttons, label them to choice.

  9. Insert hidden input fields to configure bnbform.cgi to your specifications. These examples come from a hypothetical contact form, also refer to the example file that came with bnbform.cgi. And you wondered what those hidden inputs were for…
    1. Mandatory hidden field: data_order
      <input name="data_order" type="hidden" id="data_order" value="name,submit_by,optimism_level,message" />
      The values in this example are the names of the various fields in my example form that the user fills out separated by commas, your form field names will vary. No data will be recorded without this hidden input. Remember to add any new field names to this hidden input when you add more input elements to your form.

    2. Mandatory hidden field: required
      <input name="required" type="hidden" id="required" value="name,submit_by,optimism_level,message" />
      Use the hidden field named required to specify which form fields need to be filled out for successful form submission. If the user neglect to fill out a required field, bnbform.cgi send them to your error page. submit_by is the only one that really needs to be required but you may want to require more…

    3. Mandatory hidden field: submit_to
      <input name="submit_to" type="hidden" id="submit_to" value="teaching@wallyzone.com" />
      Of course, the value for this field will be your email address! You may list more than one email address, use a comma as a separator.

    4. Optional hidden field: cc_to
      Just like the submit_to field only for carbon copy messages.

    5. Hidden field: form_id
      <input name="form_id" type="hidden" id="form_id" value="Wally's Example Contact Form" />
      The value for form_id will appear as the subject line for the email message. You may make this a hidden field with your own value, a text field to allow the user to invent their own subject, a selection menu or radio button set to give them a set number of choices, or whatever your imagination can come up with.

    6. Hidden field: ok_url
      <input name="ok_url" type="hidden" id="ok_url" value="/~dm171wally/contact/thanks.shtml" />
      This is the URL that bnbform.cgi sends your user to when the form submission is successful. Of course, the value will reflect the path to your thank you file!

    7. Hidden field: not_ok_url
      <input name="not_ok_url" type="hidden" id="not_ok_url" value="/~dm171wally/contact/oops.shtml" />
      This is the URL that bnbform.cgi sends your user to when the form submission is missing a required field. Of course, the value will reflect the path to your error message file!

    8. Hidden field: automessage
      <input name="automessage" type="hidden" id="automessage" value="wally_respond" />
      With this hidden input, bnbform.cgi will send an automatic responding message to the submit_by address using text in a file within the same directory as bnbform.cgi, the file’s name needs to be the value of this hidden field with “.baut” as the file suffix.

    9. Hidden field: countfile
      <input name="countfile" type="hidden" id="countfile" value="contact_count" />
      This hidden input tells bnbform.cgi to create a text file named your_value.bcnt in the same directory as bnbform.cgi with a count of number of times the form has been used. In my example, the count file will be named contact_count.bcnt.

    10. Hidden field: emailfile
      <input name="emailfile" type="hidden" id="emailfile" value="contact_emails" />
      This hidden input tells bnbform.cgi to create a text file named your_value.bemf in the same directory as bnbform.cgi with a list of all email addresses used in the submit_by field. In my example, the count file will be named contact_emails.bemf.

    11. Hidden field: outputfile
      <input name="outputfile" type="hidden" id="outputfile" value="contact_output" />
      This hidden field tells bnbform.cgi to create a text file named your_value.bout in the bnbform folder with the total output of the form. My examples file name will be contact_output.bout.

  10. Style your form to taste and you are done.

On to the next tab…

Miscellaneous Details

There are still a few loose ends to clean up before the entire task is done.

  1. Create your “oops” and “thank you” pages if you have specified them with hidden inputs. Upload them to the location you specified with the hidden inputs.

  2. Create your auto reply message if you have specified this option with your hidden input. The file name is the value you used in the input tag with a “.baut” suffix. The message is plain text with no formatting tags. Use your text editor to make it just to be on the safe side…

Test Everything

After all files are uploaded properly, test everything.

If bnbform.cgi does not seem to be working:

  • Was bnbform.cgi edited with a text editor that preserved Unix line endings?
  • Was bnbform.cgi uploaded as text?
  • Was bnbform.cgi given the proper permissions on the server (755)?
  • Was bnbform.cgi configured using the directions? If you are installing it on a server other than webhawks.org, your path to sendmail may vary.

Send yourself a test email.

  • Does the test email arrive? It may take a moment or two…
  • Does the script write to the output file? Another good reason to turn on this option.
  • If bnbform.cgi writes to its output file but does not deliver an email, be suspicious of the hidden input specifying the submit_to variable and perhaps your path to sendmail.
  • Does bnbform.cgi send you to your “thank you” page as you specified?

Test the error functions.

  • Try using a malformed email address such as one without the “@” symbol.
  • Try submitting the form without filling in the required fields.

If all is working well, congratulations! After you are done troubleshooting, link your contact page to the home page of your homework site.