Gform User's Guide

Gform User's Guide

A generic Web form handler utility.

Introduction
How it works and a simple example

User guide

Supported INPUT fields.
Syntax of gform commands
Special characters
Variables
Mandatory Fields
Delivery Methods
Reply URL
Separating multiple values
CGI environment variables

Introduction.

The problem with forms is that they all need their own program or script to handle the fields in the form and perform some sort of action. This can make the creation of simple questionaire type forms difficult for web information providers. Usually you want to collect submitted forms of this type in a file or send it via e-mail to yourself or to someone else or even send it directly to the printer.

Gform is a program that enables you to easily create these type of forms by using commands that are embedded inside the form HTML file. It then uses simple variable substitution to deliver the results.

If you have some experience with HTML and forms, you may want to look at the examples that come with 'gform' or the complete example at the end of this document. This should give you a good idea of how it works and how it is used.

How it works.

The HTML specification says that comments in an HTML file should be enclosed by ''. Gform takes advantage of that and will interpret the tag '<!--GFORM ' as the start of a command. These tags are considered to be comments by the HTML browsers. These gform 'comment' tags can appear anywhere within the form HTML file.

Take a simple form example:

<html>
<title>A Simple Form</title>
<body>
<form method=POST action="/cgi-bin/handler">
Enter your name:<INPUT type="text" name="yourname"><br>
<INPUT type="submit" value="submit">
</form>
</body>
</html>

To handle this form, you need a script or program to interpret the input value(s) for you. In this case this is specified as '/cgi-bin/handler'. If you add input fields to this form you typically will also need to modify /cgi-bin/handler'. Having one script or program for each form is obviously very cumbersome to maintain. More often than not, the person who writes the form is not a programmer and may find it difficult to write form handlers.

Here is the same example with 'gform' as the 'handler'

<html>
<title>A Simple Form</title>
<body>
<form method=POST action="/cgi-bin/gform">
Enter your name:<INPUT type="text" name="yourname"><br>
<INPUT type="submit" value="submit">
</form>
</body>


</html>

(The gform commands will be explained later)

When somebody submits this form and gives their name as "Joe Bronco", then the following line is sent to: "nobody@wmich.edu"

The person's name is: Joe Bronco

Supported INPUT fields.

All the INPUT type tags defined in HTML v2.0 can be used.

TEXTAREA A variable is assigned with all the entered text including linefeeds.
SELECT A single value is returned from a list of options.
SELECT MULTIPLE A comma separated list of the selections is returned.
CHECKBOXES The value of the checkbox is returned if selected. Otherwise "null" is returned.
RADIO BUTTONS The value of the selected radio button is returned. Otherwise "null" is returned.

See the complete example for usage of these.

Syntax of gform commands.

There are 3 types of gform commands. The first handles text and variables, the second defines a delivery method. and the third is an optional reply URL that is send to the user after they submit the form.

The syntax can be summarized as:

Where;

bold text is a keyword that must be entered.
Text between "<>" brackets indicates required data.
Vertical bar "|" reads as an 'exclusive or'
Square brackets "[]" encloses optional data.
"text" is a series of alphanumeric characters and $(var) is a variable. Any number of variables and text can be freely mixed, except in the deliver = mail|file. In that case either a variable or a string of text can be used.

Special Characters

Within gform text strings there would be no way to handle certain characters because they either have special meaning to gform or they simply can't be entered from the keyboard. To handle these characters we precede certain letters with a backslash character.

Here is the list of escaped characters with special meaning within gform text.

\n - newline
\t - tab
\f - form feed
\r - return
\$ - Escape a dollar sign
\" - Escape a double quote
\\ - Escape a slash

The most useful one is the Newline character. For example take the next 2 lines;




This will be returned as: "The quick brown fox jumped over the lazy dog"

But by inserting newline characters,




we get

"The quick brown fox
jumped over the lazy dog"

The complete example shows various use of escaped characters.

Variables

Variables are identified by a '$" sign and may be enclosed with parenthesis so that you don't have to have a space between it and text immediately following it. A variable should match with the name given in the input specification, or it can be a CGI environment variable. Variables are case insensitive except for CGI environment variables.

For example a typical line in a form may be:

Enter your name:<INPUT TYPE="text" name="myvar">

The variable name is given by 'name' and is called 'myvar'.
The corresponding gform line could look something like;

$(myvar) is then replaced by what the form user entered and the result is delivered according to the given delivery method(s).

There are 2 special variables that are always defined. $(date) and $(time) that return the current date and time.

Mandatory Fields

For those forms where you really want people to fill out certain portions.

This tag declares variablename as a variable that must contain data for the form to be processed. If this variable is left blank then an error message page is returned and the form is not processed. The error message page is declared as follows:

The NULLERROR keyword declares that errorfile.html be returned if variablename is blank. A different error page can be returned for different variables and there is a simple default message returned if NULLERROR is not defined.

Mandatory fields do not work with Checkboxes or Radio Buttons or Select boxes. It can be applied to the variables involved but will have no effect.

Delivery methods.

There are 2 ways you can get the information from a submitted form. These are e-mail, or in a text file. Any combination of delivery methods can be used.

To get the results sent to you via e-mail you use


or


The "<!--gform " lines with the text and variables you have specified, will be sent to either "address@some.site.edu" or the e-mail address specified by the variable address via e-mail. The variables, of course will be translated to the values entered by the form submitter.
You can optionally also include a subject

The double quotes in the <!--gform lines are required.

To get the results appended to a file you use


or


For example the "/path/of/file/" maybe "~username/forms/results.txt". Be aware that the web server owner must have write access to the file. The web server runs as user "hmpg-srv". In other words make sure that the file protections for the file "results.txt" allows everyone to write to that file. You can do this by issuing the command "chmod o+w results.txt". You should create an empty file before releasing your form. In all cases the delivery file must exist in the form owner's area on the web server.

Sometimes you may want to deliver different information from a form to different places. To facilitate this, WMU has added a command to gform which clears the buffered output and allows you to start over. The command is

By using this command between two deliver commands, you can build up a result for delivery to one place, deliver it, reset the output, build a new result, and deliver that, etc.

Reply URL

After the user has submitted the form, the form creator has the option of specifying a URL to send back. This is done by using the 'reply' command. By default a simple "Thank You" will be sent.
For example;

<!--gform reply="~username/forms/mythanks.html">

Separating multiple values

If your form contains multiple checkboxes with the same name, or select multiple fields, the values are returned as a single variable with the values separated by a string which may be user defined. To specify the separator, use a command like:

This example specifies that multiple values are to be separated by a colon with a space on both sides of it. The separator may be changed before each formatting line. If the separator command is never used, the default separator is " + " (that is, a plus with a space on each side). Special characters, such as \n (new line) can be included in the separator string.

Note: If you are dependent on the separator behavior of older versions of GFORM (which used a single comma as the separator), include the command:

CGI environment variables.

If a variable specification in a <!--gform line doesn't match any in the INPUT specification, then it will interpret it as an environment variable. If it is not an environment variable, it returns the word "null" Here are most of the CGI environment variables currently recognized:

ANNOTATION_SERVER
AUTH_TYPE
CONTENT_LENGHT
CONTENT_TYPE
DOCUMENT_ROOT
GATEWAY_INTERFACE
HTTP_ACCEPT
HTTP_REFERER
HTTP_USER_AGENT
PATH_INFO
PATH_TRANSLATED
QUERY_STRING
REDIRECT_URL
REDIRECT_REQUEST
REDIRECT_STATUS
REMOTE_ADDR
REMOTE_GROUP
REMOTE_HOST
REMOTE_IDENT
REMOTE_USER
REQUEST_METHOD
SCRIPT_NAME
SERVER_VERSION
SERVER_SOFTWARE
SERVER_NAME
SERVER_PORT
SERVER_PROTOCOL

Complete example.

For demonstration purposes the file that the results are collected in is also the reply file. So when this form is submitted, you can see the results straight away.

<HTML>
<HEAD>
<TITLE>gfrom sampler</TITLE>
</HEAD>
<BODY>
<H2>gform form sampler</H2>
<P>
Here are some different form specifies that will work with gform
version 1.1 (6-oct-95) <BR>
You may have to edit the FORM method... line according to your
local setup.
<FORM method=POST action="/cgi-bin/gform">
<HR>
<P>
Some regular text input fields
<P>
What is your name: <INPUT NAME="name" VALUE="" ><BR>
Your e-mail address:<INPUT NAME="e-mail" VALUE="" ><BR>
<HR>
<P>
Single choice select option:
<P>
What do you want to drink ? <SELECT NAME="drink" >
<OPTION>nothing
<OPTION>coffee
<OPTION>tea
<OPTION>juice</SELECT><HR>
<P>
Using multiple choice select options:
<P>
What do you want on your pizza ? <BR>
<SELECT MULTIPLE NAME="pizza">
<OPTION VALUE="ham">ham
<OPTION VALUE="cheese">cheese
<OPTION VALUE="tomato">tomato
<OPTION VALUE="capsicum">capsicum
<OPTION VALUE="chili peppers">chili peppers
<OPTION VALUE="mushrooms">mushrooms
<OPTION VALUE="olives">olives </SELECT>
<BR>
<INPUT TYPE="RADIO" NAME="size" VALUE="Small"> Small (6")<BR>
<INPUT TYPE="RADIO" NAME="size" VALUE="Medium">Medium (8")<BR>
<INPUT TYPE="RADIO" NAME="size" VALUE="Large">Large (10")<BR>
<BR>

Here are some checkboxes
<P>
<INPUT TYPE="CHECKBOX" NAME="salt" VALUE="yes"> salt<BR>
<INPUT TYPE="CHECKBOX" NAME="pepper" VALUE="yes"> pepper<BR>
<BR>
<HR>
<P>
Here are some radio buttons:<BR>
Please select your subscription length: <BR>
<HR>
<P>
A textarea
<P>
Please let us know what you think of our service by entering your
comments in the space provided<BR>
<TEXTAREA NAME="comments" ROWS=5 COLS=40>
</TEXTAREA>
<P>
<INPUT type="submit" value="send"> <INPUT TYPE="RESET"> <HR>

























</FORM>
</BODY>
</HTML>