Division of Information Technology
Web Publishing @ SFSU
CGIEMAIL

Using CGIEMAIL

A copy of the CGIEMAIL User's Guide is available for detail information.

An advanced guide shows several of the new features.

The CGIEMAIL program allows account holders to set up feedback forms with the input from users being directed to the e-mail recipient of your choice, and formatted in any way you choose.

Basic Steps

Sample Use

Design the Form

The first part of using the program is to design your form. Look at our online Forms instructions or NCSA's information on Forms. The following example from the Forms page has one of each of the entry field types.

The actual form looks like this.

Year:

Are you a student, staff or faculty?
Student
Staff
Faculty

Please select the term?
spring
summer
fall
winter

What is your major?

What is your E-mail (optional)?

Comments:

Reserved Words

 Required Fields

If you want to make a field required, add "required-" to its name. To make the email field required you would change name="email" to name="required-email".

Success and Failure Fields

You can send the recipient to a second page or URL after they submit the form. If you wanted to send the user to another page after they have successfully completed the submitted the form, you would use this field in your form:

<input type="hidden" name="success" value="http://server.sfsu.edu/~accountname/completed.htm">

If the user had submitted an incomplete form you would use:

<input type="hidden" name="failure" value="http://server.sfsu.edu/~accountname/formfailed.htm">

Addendum Field

You can send the recipient a message in response. This is done by using fields with the input type of "hidden". To send a text response that said "Thank You" you would use this field:

<input type="hidden" name="addendum" value="Thank You">

Create the Template

The CGIEMAIL program requires a second file that formats the response. If you call your form file 'feedback.htm' you might call your second file 'feedback.txt'

The following sample templates matche the code above.

Custom Formatted Text

From: [email]
To: your-email-address@sfsu.edu
Subject: Sample Form

Year: [year]
Group: [group]
Term: [term]
Major: [major]
My comments:
[comments]

The name of the field to be substituted is placed in square brackets []. The SFSU mail system requires the first and second lines of the template to start with 'From:' and 'To:' respectively. The subject can be any text, this is what will appear in the subject field of the mail application. You can include form values in the headers, for example, if the email address was one of the form fields (as in the example), you could have the first line of your template include it. You would use From: [email] to fill in a person's email address if they have entered it on the form.

This combination of the form and template above would provide the following output:

From:
To: your-email-address@sfsu.edu
Subject: Sample Questionnaire

Year: 1999
Group: Student
Term: spring
Major: Accounting
My comments:
users comments

Delimited Text

If you want to accept the form responses in a delimited format, you would create a template that looks something like this:

From: [email]
To: your-email-address@sfsu.edu
Subject: Sample Questionnaire

[student],[term],[major],[comments],[month],[day],[year]

The advantage to delimiting your responses is that it allows you to manipulate the data easily in a spreadsheet or database program. In this example commas are used however if the user enters commas in the text area of the form it may result in errors when importing the data into a database or spreadsheet. You can use other special characters as delimiters.

Determine the Form 'Action'

The form action determines what will be done when the filled form is 'submitted'. In the case of CGIEMAIL, the action is made up of two parts:
  • the first part points to the location of CGIEMAIL
  • the second part tells CGIEMAIL where to find the template

Example:

<form METHOD="POST" ACTION="/cgi-bin/cgiemail/~accountname/feedback.txt">

This tells the CGIEMAIL program to process the form with the template file.

Test the form with CGIECHO

Before you actually start using your form you can test it with a program called CGIECHO, CGIECHO works like CGIEMAIL except the it will display the results or error in a web page.
To test your form:
  1. In your html file (feedback.html) replace cgiemail with cgiecho

    <form METHOD="POST" ACTION="/cgi-bin/cgiecho/~accountname/feedback.txt">

  2. Open your page in a web browser
  3. Enter information in the fields and press the submit button.

Example:

From: [email] (optional)
To: your-email-address
Subject: Sample Form

Student: [student]
Term: [term]
Major: [major]
My comments:
[comments]

If everything worked, a page will be displayed showing the information submitted. If instead you see an error with a number near 500, your ACTION is probably set wrong. Go back to the previous step. If some of your inputs don't seem to be showing up in the processed form, make sure that the inputs have the exact same names in the HTML form as in the template.

Processed form looks like this:

From:
To: your-email-address
Subject: Sample Form
Date 01/01/1999
Group: student
Term: summer
Major: Accounting
My comments:

If the information returned was by CGIECHO was correct make the form live by replacing cgiecho with cgiemail in your html file (feedback.htm).

<form METHOD="POST" ACTION="/cgi-bin/cgiemail/~accountname/feedback.txt">

Some mailto Form Parsers for Macintosh Mail to Converter
Mail to Tamer

SFSU Home   Search   Need Help?  

1600 Holloway Avenue, San Francisco, CA 94132 (415) 338-1111
Last modified February 11, 2008 by the Web Team