Easyform and Easymail

[Jun 28, 2008 8:06] Email phishing scam targeting WebMail users has been reported. More Information

Table of Contents

Introduction

Easyform/Easymail is an easy-to-use package that you may install on your Web site. Visitors can enter information on a Web form, and when they submit it, Easyform/Easymail can do one of the following:

  • collect the data in a file compatible with Excel or other spreadsheets
  • send the data to you in an e-mail message

Easyform/Easymail does not require any programming on your part, and as the name implies, it is very easy to use. Its options are very limited, however, so if you have more complex needs (such as collecting data into a database, querying a database, or interacting with enterprise databases), then you may wish to consider another solution.

Installing Easyform/Easymail

Before installing Easyform/Easymail, you will need to have a Web site on a UVa UNIX server. To install Easyform/Easymail, you must perform two basic steps: log in to your UNIX account, and install Easyform/Easymail.

  1. Log into your UNIX account and go to the command prompt - e.g.:
    node4: /home/mst3k $
  2. Install Easyform/Easymail:
    • Enter the following command:
      /contrib/bin/efsetup
    • Output is similar to the following:
      E-mail will be sent to: mst3k@virginia.edu
      Installing /home/mst3k/public_html/email.dat
      Installing /home/mst3k/public_html/easyform.cgi
      Installing /home/mst3k/public_html/easymail.cgi
      Installing /home/mst3k/public_html/efresult.html
      Installing /home/mst3k/public_html/Readme file.
      All done.
      Documentation is at: http://www.itc.virginia.edu/desktop/web/efdoc.html

      You need to edit your HTML form. Change the action
      attribute of the <form action ...> tag to use the
      appropriate one of the following URLs.
      Write down the following lines for later reference:

      http://www.people.virginia.edu/~mst3k/easyform.cgi
      http://www.people.virginia.edu/~mst3k/easymail.cgi

      If those do not work, please try the following:

      http://www.people.virginia.edu/cgi-uva/cgiwrap/mst3k/test/easyform.cgi http://www.people.virginia.edu/cgi-uva/cgiwrap/mst3k/test/easymail.cgi
    • Before logging out of your UNIX account, write down the last four web addresses that appear on your screen for later reference. You may now log out of your UNIX account.

Building a Form to Collect Data

Create and upload a Web page with an appropriate HTML form.

We recommend that you use a graphical page editor like Macromedia Dreamweaver. If you are editing html, the code for your <form> tag should look similar to the following (where mst3k would be replaced with your computing id), assuming you have chosen to use Easyform as opposed to Easymail):

<form action="http://www.people.virginia.edu/~mst3k/easyform.cgi" method="post">

Installing with an Alternate Email Address

If your account is on minerva, or for some reason you want the form data mailed to someone besides the owner of the account where the Web page resides, then you will need to use the -e command line switch, similar to the following:

/contrib/bin/efsetup -e <full-email-address>

where <full-email-address> is the complete e-mail address of the recipient. Here is an example:

/contrib/bin/efsetup -e mst3k@virginia.edu

You may combine this alternate email feature with the following alternate directory feature.

Installing in an Alternate Directory

The Easyform/Easymail package can be installed in any directory, although for personal use, you install the Easyform/Easymail package in your public_html directory, or in a subdirectory of public_html. Contact your system administrator (or email web-consult@virginia.edu) for detailed information.

Below is an example of how one might install Easyform/Easymail in an existing directory other than the default public_html directory. At the UNIX command prompt, enter the following:

/contrib/bin/efsetup -d <directory-name>

where <directory-name> is the full path to the installation directory. You must use the full path of the directory—for example, using the directory “survey” as the installation directory:

/contrib/bin/efsetup -d /home/mst3k/public_html/survey/

To combine the alternate e-mail address with the alternate directory option:

/contrib/bin/efsetup -d /home/mst3k/public_html/survey/ -e mst3k@virginia.edu

Installing in a Departmental Account (with no public_html directory)

Many departmental web sites do not have a public_html directory. If this is your situation, you will need to type the following command at the UNIX prompt:

/contrib/bin/efsetup -s -d <directory-name> -e <email-address>

where <directory-name> is the name of the installation directory, and <email-address> is where you want Easymail to send the data. Here is an example:

/contrib/bin/efsetup -s -d /www/doc/desktop/web/ -e mst3k@virginia.edu

The -s option will install special versions of Easyform/Easymail. Do not do this installation when logged in as root or a system administrator; just log in as yourself.

Many departmental websites have groups of people who manage the files. If someone other than the group owner installs easyform or easymail the following problem may occur:

  • Setup: easyform/mail was installed by a group member with a command similar to

    /contrib/bin/efsetup -s <dir_name> -e <email_address>

    where dir_name is group-writable

  • Symptom: easyform/easymail fails to create formkeys.dat & output.txt
  • Solution: Change permissions on the writer file (see below) with the command:

    chmod g+s writer

In addition, because efsetup was written for an earlier configuration on most servers, it may be necessary to edit easymail_s.cgi and/or easyform_s.cgi to modify the location of the efresult.html file that presents feedback to anyone submitting a form. To do this,

  1. Open easymail_s.cgi in a unix text editor.
  2. Find the two lines in the file that begin with “Location:”
  3. Edit these lines to point to the correct location of the efresult.html file.
  4. Save your changes and exit the file.

Description of Files

These files are installed by efsetup:

  • easyform.cgi - a perl script to take HTML form data and put it in a file
  • easymail.cgi - a perl script to take HTML form data and email it
  • Readme - a text file with most of the info on this page
  • email.dat - a text file containing the email address. If you don't use the -e command line switch then this email address is the owner of the account (usually you).
  • efresult.html - an html file which displays the sentence “Data submitted successfully.” You may change this html file to suit the look and feel of your Web site.

If you used the -s installation switch the files are:

  • easyform_s.cgi - a perl script to take HTML form data and put it in a file
  • easymail_s.cgi - a perl script to take HTML form data and email it
  • writer - an executable program that writes the two data files (formkeys.dat, output.txt)
  • Readme - a text file with most of the info on this page
  • email.dat - a text file containing the email address. If you don't use the -e command line switch then this email address is the owner of the account (usually you).
  • efresult.html - an html file which displays “Data submitted successfully.” You may change this html file to suit the look and feel of your Web site.

The two files below are created when you submit a form to easyform.cgi or to easyform_s.cgi. (Note: easymail.cgi and easymail_s.cgi do not create the file output.txt):

  • output.txt - the data from your HTML form
  • formkeys.dat - the field names (column names) from your HTML form

The perl scripts automatically handle data from forms. They use the POST method, and you specify an ACTION attribute that tells where the easyform.cgi (or easymail.cgi) file is located. This <FORM> tag would be found in the source code for your web page form:

An example form tag to use for creating a file of form data is:

<FORM ACTION="http://www.people.virginia.edu/~mst3k/easyform.cgi" METHOD="POST">

An example form tag to use to send form data in e-mail is:

<FORM ACTION="http://www.people.virginia.edu/~mst3k/easymail.cgi" METHOD="POST">

Technical Notes

  • You can quickly check your data. Login to your UNIX account and get to the command prompt. Change to your website directory (usually public_html) using the cd command, and more the file output.txt:

    cd public_html
    more output.txt

    This is a quick check since usually the records in the data file are quite long, and the best way to view them is in a spreadsheet. More on that below.

  • The first time you submit your form, we strongly recommend that you put some bit of text in every field, check every checkbox, and check at least one button of every radio button group.
  • easyform.cgi concatenates data into the file named output.txt. This means that each time the form is submitted, a new record is added at the end of the file.
  • easymail.cgi sends the form data by email to the owner of the account. If your user id were mst3k and your web page form is in your public_html directory (where your Web site resides), when the form (using easymail.cgi) is submitted, the data is emailed to mst3k@virginia.edu.
  • Both easymail.cgi and easyform.cgi store the field names in the file formkeys.dat.
  • If you transfer output.txt to your microcomputer and put it into a spreadsheet, the names of the columns are the field names found in the file formkeys.dat.
  • If you delete a field from your form, that column will remain in the data file. Old data in that column will be preserved. New form data will ignore that column, and so the column will contain empty strings for records entered after you deleted the field.
  • If you add a new field, it is added to the end of the data record.
  • Because of the above two features, you don't need to modify any files when you modify your form.
  • If you want to modify the form, and rearrange the data file, then you should copy the two files (output.txt and formkeys.dat) to different file names so they will not be overwritten. Then submit your form, and two new files (still named output.txt and formkeys.dat) will be created with the new form field order. Your old data is in the output.txt.save and formkeys.dat.save files.
  • Test your form carefully by submitting test data several times. The last step of the testing phase is to download the data file (output.txt) to your computer and verify that the data is being correctly collected. Generally, you put the data into a spreadsheet for convenient viewing and analysis. After the test phase, you'll probably delete the file output.txt. Do not delete formkeys.dat.
  • When importing data into a spreadsheet, the data is delimited, and the delimiter is a comma. You may have to click some checkboxes or radio buttons to inform the spreadsheet program of these settings.
  • If you have two or more forms that need to put their data into different files, put each form in its own separate directory and install Easyform/Easymail in each of the directories.
  • You can have several copies of Easyform/Easymail installed on your Web site, each handling a separate form. If you need a second copy of Easyform/Easymail, you must install it into a new directory. Do not copy easymail.cgi or easyform.cgi into different directories, since some the of the data file paths are hard-coded when the package is installed.
  • A single copy of easyform.cgi could handle input from more than one form, as long as you wanted the data from the forms in a single data file. There are situations where this might be appropriate. In these cases you might also want to use some hidden fields in your form to distinguish the data's source.
  • Paragraph characters in your form data are changed to spaces (but not with easymail). Normally a carriage return is a paragraph break, but this can signal an end of record. This ambiguity leads to difficulties with the data, so any carriage return (or other control character) is changed to a space.

© 2008 by the Rector and Visitors of the University of Virginia.

The information contained on the University of Virginia’s Department of Information Technology and Communication (ITC) website is provided as a public service with the understanding that ITC makes no representations or warranties, either expressed or implied, concerning the accuracy, completeness, reliability or suitability of the information, including warrantees of title, non-infringement of copyright or patent rights of others. These pages are expected to represent the University of Virginia community and the State of Virginia in a professional manner in accordance with the University of Virginia’s Computing Policies.