Save-form-results
Introduction
The HTML specification lets the author of a World Wide Web (WWW) page create "forms" which allow users to submit information to the system. Each form is a screen with one or more data entry fields and buttons. The user types information into the appropriate boxes and then presses a "submission" button which then sends the form information to the WWW server.
The author of the form specifies the name of a program to be run on the WWW server to process the form. This program (usually called a "cgi-bin" program or script) can be made to do just about anything with the data: email it to a human, store it in a file, use it to query a database and display the results, etc.
HTML has no facility for "generic" forms. Each new form requires a new custom program to be written to process the particular data produced by that form. Obviously, replicating very similar forms can become quite time-consuming and expensive.
To help avoid some of this expense, SWCP has produced a program which can be used to save the results of a form submission to a file. The owner of the form can later retrieve the information by downloading the saved file. Optionally the program will email the owner when a new submission is received. The program will work with any form and can be used by any user. The only limitation is that the program only takes one action: it saves the form data to a file. If you need a form to do anything different, then you will have to write your own (or hire somebody to write it for you).
How To Use It
This tutorial does not cover the issues involved in form creation in general. It is assumed that you will know what to do with the information that follows. If not, you should read up on how forms work. Two good resources are:
http://www.utoronto.ca/webdocs/HTMLdocs/NewHTML/intro.html has a good section on forms. The data at this site is part of a book which has been published, called "The HTML Sourcebook". From its description, it sounds like a good reference.
The book "Managing Internet Information Resources," published by O'Reilly, has a couple of chapters on HTML, including forms. It's a big book with LOTs of other good information in it about other Internet resources (gopher, mailing lists, etc.)
The name of the program is sfr and it is stored in the /cgi-bin directory on SWCP's WWW server. To use it, use this URL for the ACTION in your form:
/cgi-bin/sfr
Note that you do not necessarily have to have your own cgi-bin directory to use sfr because it resides in SWCP's cgi-bin directory, which is available to all users. However, the program will require write access to a directory you specify in order to save the information. If you use the SWCP-supplied copy in /cgi-bin, then the form will be run by the server as user "nobody" (an unpriviledged user), so you will have to provide a directory which has world write and execute priviledges (733).
An alternative is to have your own cgi-bin directory which we can arrange to run programs under your user id. That way the program can write to any directory which you have access to and you needn't provide world write access to any of your directories.
Your form must include three hidden fields which communicate information to sfr. They are:
save-dir or save-file
Name of the directory or file to save output files in. If save-dir is used then a file called sfr#####.txt will be created, where ##### is a "random" number. The directory must exist before you attempt to use sfr. Example value: /users/cheeks/submissions
If save-file is used, the output for every form submission is appended to the named file. Example value: /users/cheeks/submissions/form12.txt
save-format
This tells the form processor what format to save the form data in. Possible values are delimited or tagged. If you choose delimited, the form items will be output all on one line, separated by a delimiter character (e.g. commas or dashes, see delimiter below). If you choose tagged format, the form data items are listed one per line, each preceded by the name of the field. Example value: tagged
return-link-url
After a form is submitted, the user is "sent" to a new page. This page should usually say something like "Thanks for your submission." return-link-url specifies the URL that the user will be sent to.
Example value: http://www.swcp.com/~cheeks
There are several optional hidden fields which you may include in your form to tell the form processor to treat certain other fields in a special way:
delimiter
If you specify a save-format of delimited, then the delimiter field is required. It specifies what character to use to separate the data fields in the output. Common delimiters are the comma (,), colon (:), or pipe character (|). Note that the delimiter you specify should not be likely to occur in any of your data fields.
Example value: |
field-order
This is a comma-separated list of field names and specifies the order that the fields should be listed in the output. This is crucial for delimited output since you need to know which fields are in which order to import the data into a spreadsheet or database. It can also be used for tagged output as well.
Example value: timestamp,name,email,phone,addr1,addr2
required-fields
This is a comma-separated list of field names and specifies that the listed fields must not be empty. If the user neglects to provide some data for any of the fields specified in required-fields, they are informed of the error and asked to re-submit the form. If you use this setting, it is recommended that you tell the user which fields are required and mark them with an asterisk or something similar.
Example value: name,email,phone
notify
If the notify field is present, it should contain an email address. The program will send a short message to the indicated address to tell you when a form submission has been processed. The message will include the name of the file the submission was saved in.
Example value: cheeks@swcp.com
notify-subject
When combined with the notify field, notify-subject specifies the message subject to use for the notification message.
Example value: Form No. 12 Received Submission
timestamp
If this field is present and set to true then the program will generate a timestamp field which contains the date and time that the form submission was processed in this format: mm/dd/yy hh:mm:ss This can be useful for automatic database insertions. Note that if you include the timestamp field in your output, then you should not use the "/" or ":" characters as delimiters.
Example value: true
If use the save-dir tag, then after the form is submitted, a file will be saved in the directory you indicated. The file name wil be:
* sfr#####.txt
The ##### is replaced by a 5-digit sequence number. The sequence number is essentially random and simply guarantees that the filename is unique so that concurrent submissions don't overwrite each other's files.
Example
In this example, the user wileycoyote created a directory named orders/ in his home directory, where he can retrieve orders. To view the HTML source for the form, click on the link above, then choose 'View Source' in your web browser. In this example, the user wileycoyote retrieves files from the orders/ directory that contain delimited entries like this:
roadrunner|runner@desert.org||on|||||on|on
This entry indicates that anvil, springs and trebuchet were in the 'on' position when the form was submitted.
If you have any questions about (or problems with) using sfr, send mail to webmaster@swcp.com.
