Skip to end of metadata
Go to start of metadata

A useful web page application is a form used to accept information from a user. The University's web server offers a standard CGI (Common Gateway Interface) called Form Mail which captures all data entered in an HTML form and mails those data to a designated recipient. Form Mail is for use only with official University web pages being served from the albany.edu domain. Before you can use the CGI, you must register the URL of the page containing the form with the University Webmaster.

There are just a few restrictions on form construction and contents. The CGI works for both the POST and GET form methods.

Error formatting macro: toc: java.lang.UnsupportedOperationException: The body of this ContentEntityObject ('Detailed Instructions for Using Form Mail') was 'BodyType:WIKI' but was expected to be 'BodyType:XHTML'

Form Configuration

The action of your form needs to point to this CGI, and the method must be POST or GET in capital letters.

Syntax

Include one of these statements in the HTML code at the line where your form is defined:

or

Form to Mail offers many ways to code your form to control the way the CGI performs. Below is a list of form fields you can use, how each is implemented, and what action the CGI will take due to their presence.

Mandatory Form Fields

There is only one form field that you must have in your form for Form to Mail to work correctly. This is the recipient field — Form Mail cannot mail the form data without knowing the recipient's address.

Field: recipient

This form field allows you to specify to whom you wish for your form results to be mailed. Most likely you will want to configure this option as a hidden form field with a value equal to that of your email address.

Syntax

Note that the field name here ("recipient") and elsewhere must be specified exactly as shown, namely all lower-case.

Optional Form Fields

Field: subject

This form field allows you to specify the subject that you wish to appear in the header of the email that is sent to you after this form has been filled out. If you don't specify this field, the CGI will insert a header line
Subject: HTML Form Submission

Syntax

If you wish to specify the subject text, use

To allow the user to choose the subject text, use

Field: email

This form field allows users to specify their return email addresses. If you want to be able to reply via email to your user, include this form field. The address the user provides will be used in the From: header line of the mail you receive.

Syntax:

Note:  if email is designated to be a required field (see the "required" form field below), the value a user specifies here is subjected to special checking to insure that it is a syntactically legal email address. Be aware, however, that a syntactically legal address is not necessarily a valid address and that this checking provides no guarantee that replies to this address will be deliverable.

Field: realname

The realname form field allows users to provide their real names. This field is useful for identification purposes. The name provided will also be put into the From: header line of the mail you receive.

Syntax:

Field: redirect

Upon successful processing of the user's data, Form Mail acknowledges by sending a page that summarizes the data received and saying that the data have been mailed to the recipient. If you wish instead to display a different Web page to the user, use the redirect field to specify the URL of this Web page.

Syntax:

Field: required

This very useful field allows you to require certain fields in your form to be filled in before the user can successfully submit the form. Simply place all field names that you want to be mandatory into this field. If the required fields are not filled in, the user will be notified of what they need to fill in, and a link back to the form just submitted will be provided.

Syntax:

As an example, if the email and phone fields must be filled in for the form to be acceptable, use a syntax like:

Extra fields

A note to the reader

The remaining fields are arcane and can be skipped on first reading. See, however, the remarks at the very end.

Field: env_report

"Environment variables" are parameters that describe the form's Web page itself along with the browser whence it originated. The env_report field causes certain of these parameter values to be recorded in the email to be sent to you. You can use this field if you wish to know what kind of browser the user was using, what domain it came from, etc. Here is a short list of environment variables that might be useful:

  • REMOTE_HOST — the domain name of the machine where the browser is running.
  • REMOTE_ADDR — the IP address of the machine where the browser is running.
  • REMOTE_USER — If the form is registered with the server as being one requiring user authentication, this is the user's authenticated username (userid). This is not usually set.
  • HTTP_USER_AGENT — The browser the client is using to transmit the form. The general format is: software/version library/version

There are others, but these are a few of the most useful.

Syntax:

If you wanted to know the remote host and browser sending the request, you would put the following into your form:

Field: sort

This field allows you to choose the order in which you wish your variables to appear in the email that Form Mail generates. You can have the fields sorted alphabetically or specify a particular order in which you want the fields to appear in your mail message. By leaving this field out, the order will default to the that in which the browsers sends the data to the CGI (which isn't always the same order in which they appeared in the form). When sorting by a set order of fields, you should include the phrase "order:" as the first part of your value for the sort field, and then follow that with the field names you want to be listed in the email message, separated by commas.

Syntax:

To sort alphabetically:

To sort by a set field order:

Field: print_config

print_config allows you to specify which of the config variables you would like to have included in the body of your email message. Normally no config fields are included in your email body. This is because the important form fields, like email, subject, etc., already appear in the header of the message. However some users have asked for this option so they can have these fields also included in the message body. The config fields that you wish to have included should be in the value attribute of your input tag separated by commas.

Syntax:

If you want to include the email and subject fields in the body of your message, you would use the following form tag:

Acknowledgment page related fields

All the remaining fields below have to do with the acknowledgment page that is sent to the user upon successful processing of the form data in the case where no redirect field (see above) has been specified. These fields allow some control over the appearance and content of this response page.

None of these fields should be used if the redirect field is specified.


Field: title

This form field allows you to specify the title and header that will appear on the response page.

Syntax:

If you wanted a title 'Feedback Form Results', use

Field: return_link_url

This field allows you to specify a URL that will appear as return_link_title on the reply page that acknowledges your data. It allows you, for instance, to provide the user with a way to get back to your main page.

Syntax:

Field: return_link_title

This is the title that will be used to link the user back to the page you specify with return_link_url. The two fields will appear on the resulting form page as:

<a href="return_link_url">return_link_title"></a>

Syntax:

Field: background

This field allows you to specify a background image that will appear on the acknowledgment page.

Syntax:

Field: bgcolor

This field allows you to specify a background color for the acknowledgment page.

Syntax:

For a background color of White:

Field: text_color

This field works similarly to the bgcolor field except that it controls the color of your text.

Syntax:

For a text color of Black:

Field: link_color

This field works similarly to the bgcolor field except that it controls the color of your links.

Syntax:

For a link color of Red:

Field: vlink_color

This field works similarly to the bgcolor field except that it controls the color of your visited links.

Syntax:

For a visited link color of Blue:

Field: alink_color

This field works similarly to the bgcolor field except that it controls the color of your active links.

Syntax:

For an active link color of Green:

Remaining fields

All other form fields that appear in your CGI will be included in the mail to the designated recipient and displayed in the acknowledgment page (if you do not have the redirect field set). There is no limit on how many other form fields you can use with this form beyond those limits imposed by browsers and your server.