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
(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.
fs sa ~uniqname/survey-data umweb:servers rlidw
fs sa ~uniqname/survey-data system:anyuser none
- 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
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:
- Step 5
You can customize your survey form by copying the html source of
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
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"
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:
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
<input type="hidden" name="filename" value="grad-student-survey.data">
Then the file will be stored in:
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
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
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.
create the web template for your second
page use of the templates is described
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).
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:
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.