survey

home / how-to / cgi-scripts / survey

About survey

Survey is a form-to-database script written in Perl by David Winkel & Kevin McGowan. It works without any arguments to generate a form, or with POST input as a backend to that form.

How to use Survey

• Step 1
  Survey "writes" into a user's home directory so the UNIX and AFS file system permissions need to be handled accordingly. In the ITD Institutional File System (IFS) environment this is accomplished by creating a directory called survey-data in your IFS Home Directory and setting the ACLs to umweb:servers rlidw. The following commands will provide the necessary directory and permission scheme:

  mkdir -p ~uniqname/survey-data
  fs sa ~uniqname/survey-data umweb:servers rlidw
  fs sa ~uniqname/survey-data system:anyuser none

  (Substitute your own uniqname, or the name of the group IFS home directory for uniqname in the commands above). You will need an IFS Home Directory to use Survey.
• Step 2
  Now, you need to set up a survey database. By default, this database file should be named "survey.data" (though you can use a different name if you include the "filename" directive in your form, described below). Decide what fields you want to collect, and enter them in a file as a list of field names separated with tabs. Creating this file with pico can be difficult if you have a large number of fields, because all of the fields *MUST* be on the same line. If you wish to use pico, please use it as "pico -w survey.data", so that it doesn't add returns for you. We recommend that you use vi, emacs, or some other editor to create the "survey.data" file. This file should then be saved in the survey-data directory created in step one.
• Step 3
  You can now use http://cgi.www.umich.edu/cgi-bin/survey/uniqname as your survey submission form. Please note that you should replace uniqname with your uniqname in the URL above. For most purposes, the form that is automatically generated is not specific enough for people. It does, however, make a good starting point for generating a form that can be used to collect the data.
• Step 4
  After submitting comments using the survey form, by default, your database will be located at:

  ~uniqname/survey-data/survey.data

• Step 5
  You can customize your survey form by copying the html source of http://cgi.www.umich.edu/cgi-bin/survey/uniqname and creating a new page in your /Public/html directory.

Be warned that anything may be submitted in any fields! Users of Survey are not guaranteed of the respondant's identification. No verification is performed.

For help, contact webmaster@umich.edu.

How to customize your Survey

Survey will store only fields named on the first line of the survey database into the survey database. This means that the field names in your form, and the field names in your database MUST match exactly.

There are five special options that Survey will treat specially. These options need to be designated by using a hidden form field for each. An example would look like this:

<input type="hidden" name="successURL" value="http://www.umich.edu">

Those five options are as follows:

• successURL - The full URL to which a successful survey submission is directed. If this is left blank survey returns a stock success message. Note: it is important that this be a full URL, for example: http://some.servername.edu/path_to_file.html
• filename - an alternative filename, for maintaining multiple survey databases in the same home directory. For example, if filename is set to "grad-student-survey.data" with the tag:

  <input type="hidden" name="filename" value="grad-student-survey.data">

  Then the file will be stored in:

  ~/survey-data/grad-student-survey.data

  Note that slashes (/) are not allowed in this filename.
• rawDATA - If this field is set then Survey will store posted data unchanged in your survey database. Otherwise, Survey will strip all tabs, carriage returns, and newline characters from posted entries (so that data can be easily imported into spreadsheet and database programs, for example).

The following two fields should be included in your Survey form only if you are using the multi-page form feature of Survey.

• nextFORM - If this field is set then Survey will attempt to parse the named template and display another page instead of saving entries to your datafile. An example line might look like this:

  <input type="hidden" name="nextFORM" value="page-two.html">

  Survey will look in your survey-data directory (the one created in step 1 above) for a file called "page-two.html" which it will then parse and return to the browser. Please refer to the section of this document on multi-page forms for more information on parsing, template files, and the nextFORM variable.
• saveENTRY - Only useful in conjunction with the nextFORM variable, if set to "yes" Survey will save the currently entered information before advancing to the next page in the multi-page form. This is not normally a good idea, but can be quite useful for creating success pages. This field is also explained in more detail in the section on multi-page forms. Use this field with great care.

The form can be changed to include any of these fields, or more fields than this.

Using Survey to Create Multi-Page Forms

Multi-page forms allow the web author to spread a large survey across several, smaller web pages while still storing all survey responses in a single, tab-delimited text file. In fact, the goal of a multiple page survey is the same as a single page survey: collect the answers to a group of questions and store those answers in a data file. The only difference is that, in the case of a mulitple page survey, the questions are spread across more than one web form.

You begin by following all of the steps to create a standard, single-page form. Once you have your survey working (be sure to test it thoroughly -- you want to make sure you have the basics done correctly before you make things more complex) you need to do the following:

1. set the nextFORM field (described above) in your survey to the name of your second page this will make survey look for a second page instead of saving your data right away.
2. create the web template for your second page use of the templates is described below.
   
   Once you've created the secondary pages, you'll need to move them to your survey-data directory for survey to read them. (Survey can't find files stored in your ~/Public/html/ directory).
3. make certain each piece of data is being carried across all of your pages and ultimately landing in your survey data file. This is just more testing, but it is very important. Notice that multi-page forms pass data from one page to the next and that only the final page actually saves anything in your data file. Imagine a line of people with buckets trying to move water from a pump to a fire: if one of the people doesn't have a bucket (or if one of the people has a damaged bucket) no water will make it to the fire.

Working with Survey's template files

Survey uses template files based on the Server Side Include (SSI) Standard. More information on SSIs is available from: http://www.umich.edu/faq.html

Survey uses SSI tags to allow you to carry data from one form to another in your survey. If, for example, you have a field on the first page of your form called "last_name" all subsequent pages must include the tag:

<!--#echo var="last_name" -->

to make certain that this information will be passed along and ultimately saved in your data file. In fact, for every field in your survey you should have a corresponding echo tag on every subsequent form.

Example: A Three Page Survey

View the example Multi-Page Survey To get a better idea of how this all fits together.