FILEFORM SCRIPT
The Fileform script takes data from an HTML form and appends it to a file on the web server or sends it by e-mail to a designated address or addresses. The script must be placed in your personal www/cgi-bin directory to operate. The data comes from the fields in the form which are defined with HTML tags like input and textarea. Refer to an HTML guide for details about forms and see the example below.
FILE OUTPUT
When using file output Fileform appends the data to a specified file, creating it if necessary, in your personal www/cgi-bin directory. The file will contain tab-delimited fields in the following format:
date time [tab] client [tab] referer [tab] field1 [tab] field2 ...
The "date" is in the form yyyy.mm.dd (year, month, and day) and the "time" is in the form hh:mm:ss (note that the date and time are separated by a blank, not a tab). The "client" is the client's network address. The "referer" is the referring URL -- the URL of the web page containing the form that called the script.
The values from the HTML form's fields follow. (See the fields field description below for more information.) The field names are not included in the output file.
The maximum length of the value for any individual field is 1,000 bytes. Certain characters are not allowed in the field values and are translated to underscores. These include nulls, tabs, and linefeeds, but not carriage returns.
E-MAIL OUTPUT
When using e-mail output Fileform sends the data to a specified address or addresses. The body of the message will contain the data from the fields, one per line, in the following form:
fieldname: value
Where "fieldname" is the name of the field (it always appears in all lowercase). Before the data fields from the form three special lines are included. These are labeled timestamp, client, and referurl and include the information as described above for file output.
The maximum length of the value for any individual field is 1,000 bytes, but for e-mail results you may need to restrict the length so that the field name and data together are less than 80 bytes -- some mail systems truncate longer lines or may damage them in some way. Certain characters are not allowed in the field values and are translated to underscores. These include nulls and tabs. Linefeeds and carriage returns are translated to blanks.
CONTROLLING FILEFORM'S OPERATION
There are several special field names that are used by fileform to obtain information about how it should process the data. The values of these fields are not included in the output file or e-mail. The case is ignored for these special field names: file, File, and FILE, for example, are equivalent. Generally these special fields will be type=hidden in the form.
Do not repeat field names in a single form -- the result in that case is not defined, but will probably cause the script to fail with an index error.
- name="echo"
- The echo field contains a list of field names, separated by blanks or commas, to be included in the page presented to the user after submitting the form. The field names must match the field names used in the HTML form exactly, including case. The default is to echo no input fields. If the only item in the list is "all" then all of the fields in the fields field will be echoed, in the order given there.
- name="fields" value="name1,name2,etc."
- The fields field contains a list of field names, separated by blanks or commas, to be included in the output. The fields are included in the output data in the order listed and fields missing from the form data are supplied as a blank or empty field. The field names in the list must match the field names used in the HTML form exactly, including case. If the fields field isn't provided the default is a list of form fields for which data was provided from the form and in alphabetical order by field name. This means that fields with no data are not included in the output.
- name="file" value="filename"
- Specify this field to get output written to a file. The value of the field is the first part of the name of the data file on the server -- the string ".data" is added to the end of the supplied name. The file must reside in the same directory as the script and certain characters, including slashes, backslashes, and colons, are not allowed in the field value. However, the file can refer to an alias in the directory with the script that points to a file in any directory. Your web user must have authorization to write to the target file either as the owner or through a group. Note that any file that you are authorized to write to can be written to by Fileform with an appropriate alias!
- name="mail" value="address"
- Use the mail field to get the form data via e-mail. Specify a list of e-mail addresses separated by blanks or commas. It is generally not a good idea to allow users to supply the value for the mail field -- it is not possible for the script to adequately check the supplied addresses for validity. The addresses must be in the uky.edu domain and each address must be less than 40 characters long.
- name="next"
- The next field is reserved for future use.
- name="notify" value="address"
- Use notify to provide a list of e-mail addresses to be notified when a form is submitted. The e-mail addresses in the list can be separated by commas or blanks, must be in the uky.edu domain, and each must be less than 40 characters long.
The HTML file containing the form that calls the script must reside on a server in the uky.edu domain, but there are no restrictions on the clients. If the call is rejected the only information returned will be a script failure code from the web server.
USING FILEFORM
A copy of Fileform is available in the parts directory on the web server and can be copied from there to your www/cgi-bin directory. The path to the script is:
/www/htdocs/parts/fileform.py
It cannot be executed at that location! You must copy it to your www/cgi-bin directory to use it.
To copy the script you would login to the web server (using an SSH client) and use a series of commands something like this:
cd ~/www change to your www directory
mkdir cgi-bin create a cgi-bin directory if you haven't before
then copy the file
cp -p /www/htdocs/parts/fileform.py cgi-bin/fileform.py
The -p option on the cp (copy) command preserves the flags for the copy of the fileform.py file. It is essential that the execute flag be set. This can also be accomplished after copying by using the chmod command. It is also possible to copy the file using an FTP client. In that case use the permission setting function of your FTP client to set the execute flag once the file is copied to your www subdirectory.
A SIMPLE EXAMPLE
<form action="/cgi-bin/cgiwrap/~user/fileform.py" method=post> <input type=hidden name="file" value="sample"> <input type=hidden name="fields" value="lname,fname,comment"> Enter data here: <br> <pre> <label for="f">First name:</label> <input type=text name="fname" value="?" id="f"> <label for="l">Last name:</label> <input type=text name="lname" value="?" id="l"> <label for="c">Comment:</label> <input type=text name="comment" value="?" id="c"> </pre> <input type=submit value="Submit"> </form>
Note that "user" in the form tag above must be replaced by the web user where the script resides. Also note that cgiwrap is used to run the Fileform script.