Iowa State University

Iowa State University
Public Homepage Web Server


 

Generalized Feedback Utility

 
 
The Public Homepage Server is a World-Wide Web server offered by the ITS as a service to the students, faculty, and staff of Iowa State University. This document describes the generalized feedback utility available to all users of this system.

Please read the entire contents of this document before trying to use this utility.

Introduction

Shortly after the Public Homepage Server was introduced, it became evident that the people and groups providing information needed a mechanism to obtain feedback (comments) from those viewing their information.

ITS provides a utility that generates a generalized feedback form based upon a configuration file stored in a WWW-accessible directory with other WWW documents. In this configuration, one tool is available that generates a form, processes the input, and uses electronic mail to relay that information.

To use the feedback utility, you should follow these steps:

  1. Read this document carefully.
  2. Create a feedback configuration file named feedback.conf (this file must be anywhere under the WWW directory to be accessible by the feedback utility).
  3. Place a reference to the feedback utility (pointing to your configuration file) on your homepage.

Uniform Resource Locators and Configuration File Location

The feedback utility is a CGI (Common Gateway Interface) program that runs on the WWW server (www.public.iastate.edu). This program reads a configuration file and (among other things) generates a feedback form. However, it must know where to find the configuration file to read.

This configuration file is referenced by appending a location to the end of the URL for the feedback utility. The feedback configuration file can be located in any WWW-accessible directory (anything under the ~/WWW directory for users, and anything under /home/lockername/WWW for lockers).

The Uniform Resource Locator to the generalized feedback utility is:

http://www.public.iastate.edu/cgi-bin/feedback

For example, to reference the configuration file feedback.conf (stored in /home/joeuser/WWW/feedback.conf) the following URL would be used:

http://www.public.iastate.edu/cgi-bin/feedback/~joeuser/feedback.conf

Example HTML for referencing the feedback form would be:

Please leave your <A HREF="http://www.public.iastate.edu/cgi-bin/feedback/~joeuser/feedback.conf"> comments or suggestions</A>.<P>

Note that since URLs may be referenced relative to the current server, this can be simplified further to:

Please leave your <A HREF="/cgi-bin/feedback/~joeuser/feedback.conf"> comments or suggestions</A>.<P>

Configuration File Description and Format

The configuration file for the feedback utility is a plain-text file that can be edited with any text editor. The configuration file contains three types of information: comment lines, settings, and field specifications. The format is described below.

Comment Lines

Blank lines in the configuration file are ignored. Lines starting with a pound sign (#) are treated as comment lines and are also ignored.

For example, the following lines are all treated as comments:

# Lines beginning with the pound sign (#) are comments.

# Blank lines (like the one above) are comments too.

Settings

Settings are used to alter the behavior of the feedback utility or to provide information other than field specifications (described in the next section).

Settings and field specifications are used (one per line) in the following manner:

name=value
where name is the setting or field name, and value is the optional value for that setting or field specification.

The following settings are available:

mailto=Electronic mail address
Required. The electronic mail address of the person (or list) that the feedback should be sent to (e.g., mailto=cc-feedback@iastate.edu).
title=Document Title
Optional. The title of the document (used as the <TITLE> in the <HEAD> section of the document). Note that the title does not appear in the body of the document. For graphical WWW browsers, it is normally shown in the title bar of the window that the browser is running in (e.g., title=AIT Feedback).
subject=Subject Text
Optional. Short string of text that gets appended to the Subject: line of the electronic mail message when the form is processed. This is provided to make it easier for one person to handle the output of multiple forms. The MH pick command could be used to select mail messages based on this string. If not explicitly set, subject defaults to the title setting above.
Note that the mailto setting is required. The form cannot be processed without an electronic mail address to mail the results to.

The following example shows the mailto and title settings in a configuration file:

# --- Settings ---
# use e-mail to send the results to the following address
mailto=cc-feedback@iastate.edu
# set the document title
title=AIT Feedback

Field Specifications

When the feedback form is generated, a set of field specifications is read from the feedback configuration file. This information is used to determine which fields are displayed on the form.

For most uses, the following field specifications should suffice:

name
The name of the person filling out the form.
email
The electronic mail address of the person filling out the form. (Do not confuse this with the mailto setting described in the previous section.)
comments
The comments (the feedback discussed throughout this document) of the person filling out the form. Probably a paragraph or two of text. The comments field is required.
Note the following:

  • The field specifications have the form name=value similar to the settings described in the previous section.
  • Valid values are req for required, and opt for optional.
  • The value may be omitted. In this case, the default value of req is used. In other words, just listing the field names (one per line) defaults to those fields being required.
  • Fields are displayed on the form in the order they appear in the configuration file.
  • The comments field is required.
The following example specifies that fields for name, electronic mail address, and comments should be displayed.

# --- Fields ---
name
email=opt
comments

The following additional fields are also defined.

  • phone
  • homephone
  • dayphone
  • fax
  • gender
  • age
  • college
  • department
  • major
  • class1
  • class2
  • street1
  • street2
  • street3
  • street4
  • city
  • state
  • country
  • zipcode
For a complete list of acceptable fields, use your WWW browser to reference the URL http://www.public.iastate.edu/cgi-bin/feedback

Examples

A minimal configuration file would only contain the mailto setting and the comments field.

# --- Settings ---
mailto=cc-feedback@iastate.edu
# --- Fields ---
comments

Require name and comments, e-mail address optional.

# --- Settings ---
mailto=cc-feedback@iastate.edu
title=AIT Feedback
# --- Fields ---
name
email=opt
comments

Note that because the default value for fields is req for required, the following configuration file is functionally equivalent to the one shown above.

# --- Settings ---
mailto=cc-feedback@iastate.edu
title=AIT Feedback
# --- Fields ---
name=req
email=opt
comments=req

Default Configuration and __HEADER__

By default, a generic message (or heading) is displayed at the top of the automatically generated form.

Alternatively, a customized header may be specified. If the special line __HEADER__ is included, all subsequent lines are interpreted as HTML code for the portion of the document just before the form. Note: __HEADER__ is two underscore characters, then HEADER followed by two more underscore characters.

The HTML in the __HEADER__ is inserted at the beginning of the <BODY> section of the document. Note that the __HEADER__ specification must come after all comments, settings, and field specifications in the configuration file.

For example,

# --- Settings ---
mailto=cc-feedback@iastate.edu
title=AIT Feedback
# --- Fields ---
name=req
email=opt
comments=req
# Everything below the next line is HTML that will be displayed
__HEADER__
<H1>My Feedback Form!</H1>
Leave your comments here. Thanks.<P>

No Field Verification or Validation

When the form is processed, no attempt is made to verify or validate any of the information provided.

Menu-based Utility for Creating Feedback Configuration Files

A menu-based utility has been created which allows for the simple creation of feedback form configuration files.

To use this utility, issue the following commands at the Vincent (isua) prompt,

vincent% add www
vincent% setup_feedback