HTML Forms: Using formdb
formdb is a special program which takes a user's input from a
Web page and generates a text file suitable for import into a database
or spreadsheet program.
How do I Use FormDb?
- You create an HTML form that contains certain special input
fields that tell formdb what to do.
- You tell your form to call formdb when the user submits the
information.
- formdb appends the contents of the submitted form onto a text
file. Important: You must use this
form to request that the data file be created for you.
- When you want to retrieve the data, you run a special command
which copies the data file to your MHC Home Directory. (The details
of how to use this command are sent to you when the data file
is created.)
- You then connect to your MHC Home Directory and analyze the
data file, usually by importing it into a spreadsheet or database
program.
HTML Code
| The Form
Creation Wizard is a good way to create the necessary
hidden fields, without having to know too much about HTML
code. It asks you a series of questions and generates
code that you can copy and paste into your web page. |
|
If you need information about creating FORMs with HTML, we can
recommend two references. For people who are starting out, you might
like a tutorial.
If you want a succinct summary of the different tags, try the HTML
2.0 specification.
formdb is invoked as the ACTION for your form in
the standard way: <form method=post action="/cgi/formdb">.
Note that formdb requires that you use the POST method.
All of the information passed to formdb is passed as input fields.
You have complete discretion as to the method of creating the information:
You may submit the information yourself as hidden elements, or you
can have the user enter information.
Required Fields
Certain fields are required for formdb to function properly. If
a form is submitted to formdb without one of these fields, it generates
an error message and displays it to the user. No information will
be appended to the data file.
| Field
Name |
What It
Does |
| field_order |
Use this
field to tell formdb what fields, and in what order, should
be appended to the data file. Only those fields that appear
in this list will be added to the data file.
The value
of field_order should be a space-separated list
of field names. You may use any valid field name, whether
it is a standard field or one of your own. For example, <input
type=hidden name="field_order" value="from_name from_address
city state">.
Three
special field names can also be used. To add the current date
and time to the data file record, use _date_time.
A date and timestamp in the format
Sun Jul 20 06:19:18 EDT 2008 will be added at the appropriate location.
To determine
the origin of the user submitting the form, you can use either
_IPAddress to insert the raw IP address of the
user, or _campus, which inserts an M
for MHC users, an F for Five College users, or
an O for all others. |
Additional Fields
You can add any additional fields that you like to contain the
information in your form. Be sure to assign each item its own name
(with the exception of radio buttons, which are grouped under the
same name). You can have formdb output the contents of any or all
of these extra fields by specifying them in the field_order
parameter. The following list consists of optional fields that you
can use to control formdb's behavior.
|
Field Name |
What It Does |
| db_field_sep |
This field
controls the separator which appears between each value in the
data file. These three types are currently defined:
- colon:
-
Values
in the format value1:value2:value3. If a
value contains a colon, the entire value is enclosed in
"double-quotes".
- comma:
-
Values
in the format value1,value2,value3. If a
value itself contains a comma, it is enclosed in "double-quotes".
If a value itself contains one or more double-quotes,
then the whole thing is double-quoted and the enclosed
double-quotes are themselves doubled. So, for instance,
the values:
Testing
He said, "Hello" to me
1, 2, 3
are
represented as the record: Testing,"He said,
""Hello"" to me","1, 2,
3"
This
is the format understood by most spreadsheet programs
as "Comma separated values" or CSV. If no db_field_sep
value is specified, this format is used by default.
- tab:
-
Values
in the format value1<tab>value2<tab>value3,
where <tab> is ASCII character #9.
If a value contains a tab character, the entire value
is enclosed in "double-quotes".
Example:
<input type=hidden name=db_field_sep
value=comma> |
| db_rec_sep |
This field
controls the value that is written after each record in the
data file. Currently, the values that are accepted are: mac,
pc, and unix. Each of these three
values outputs an end-of-line marker that is compatible with
the named operating system. If
no db_rec_sep value is specified, the default
value of unix is used. The spreadsheet program
Microsoft Excel can read files of this type on either a Mac
or a PC. |
| db_test |
Set the
value of this field to anything ("yes" is a good
choice) and formdb will display a sample of what data would
be written to the data file, instead of actually writing to
it. |
| field_required |
Use this
field to make some of your own fields required. If the user
doesn't fill them in, formdb will return an error message telling
him or her which fields are missing. The value of this field
should be a list of field names, each enclosed in {curly
braces}. For example, if I have two that I want
to make required, called "city"and "state",
I could enter <input type=hidden name
"field_required" value="{city}{state}">.
By default,
the error message that the user sees if a required value is
left blank contains the exact name of the field. Depending
on how the field was named, this may not provide a very good
description for the user. In this case, you can use the format
{fieldname=Long Name}. This way, the error message
will show the Long Name of the field, which will
hopefully give them a better idea which field to fill-in.
For example: <input type=hidden
name "field_required" value= "{city=The City were you live}
{state=Your State}"> |
| from_address
|
If this
value is used, formdb will check to be sure it looks like a
proper email address (though it's still quite possible to enter
a meaningless value). You will most likely want to add from_address
to the field_order parameter if you use this field. |
| keep_eols |
Set the
value of this field to anything ("yes" is a good
choice) and formdb will not convert the end-of-line characters
that are sent as part of text fields into spaces. This has the
advantage that the data will be exactly as the user typed it,
particularly for textboxes. It has the disadvantage, however,
that both Excel and Filemaker will confuse the EOL with the
end-of-record marker, and create a new field. Therefore, this
option cannot be used when importing data into either of these
programs. |
| no_log |
Normally,
formdb logs all data users submit, in a location that can only
be read by system administrators. Set the value of this field
to anything ("yes" is a good choice) and formdb
will log only very minimal information about what happens when
the user submits a form. Use
this option at your own risk. If you accidentally delete
the data, it will be permanently lost. |
| return_URI
|
formdb
posts a receipt to the sender that contains a "Return"
button. This button normally points to the original form. If
you would like the "Return" button to point to something
else, use this tag. The value is the URL of the place the button
should go. For example, <input type=hidden
name="return_URI" value="http://www.mtholyoke.edu">. |
| receipt_page
|
If this
field is set to the name of an HTML (or SHTML) file in the same
directory as the page containing the form, that page is displayed
instead of the default confirmation page. This allows you to
create a custom confirmation page. You will probably always
want to use this parameter. To
include the standard results within the custom confirmation
page, place the comment <!--%%PREVIEW%%-->
at the location where you want them to appear.
Note:
If your receipt page has any images or links to other pages
in it, they must be absolute URLs. This is because at the
time your page is being displayed the "working directory"
of the URL is that of /cgi/formdb. For instance,
if the receipt page was stored in /offices/reg/thankyou.html
and wanted to refer to an image in that same folder, it should
use a URL like /offices/reg/someimage.gif. If
this is left as just someimage.gif, the Web browser
will try to load /cgi/someimage.gif, which does
not exist. |
Example
Here's an example of a form that uses formdb to find out some
information about the reader:
<form method=post action="/cgi/formdb">
<input type=hidden name="db_test" value="1">
<input type=hidden name="field_order"
value="from_name from_address Race">
<input type=hidden name="field_required"
value="{from_name=Your name}{Race}">
Your name: <input name="from_name" size=45><p>
Your email address:
<input name="from_address" size=45><p>
Your race:
<select name="Race">
<option value="">(Choose One)</option>
<option value="weakling">Human</option>
<option value="warrior">Klingon</option>
<option value="fascist">Romulan</option>
<option value="mercenary">Farengi</option>
<option value="communist">Borg</option>
</select><p>
<input type=submit value="Submit Information">
</form>
formdb normally appends output to a data file. However, this example
uses the field db_test, which instead causes the output
to go to the screen and does not write the data.
To see what this form produces, fill-in some information and click
on the Submit Information button. |
