WMU Gform User's Guide

Gform is a program on homepages.wmich.edu that allows the creation of simple Web forms by using commands that are embedded inside the form's HTML file.  It then uses variable substitution to deliver the results. The results can be collected in a file, sent via email, or even sent directly to a printer.

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

HTML specification says that comments in an HTML file should be enclosed by '<!--' and '-->'.   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 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/gform">
Enter your name:<INPUT type="text" name="yourname"><br>
<INPUT type="submit" value="submit">
</form>
</body>
<!--gform "The person's name is: $(yourname)\n"-->

<!--gform deliver=mail "nobody at wmich.edu"--> 
</html>

When somebody submits this form and gives their name as "Joe Bronco", 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.

Syntax of gform commands

The are three 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 sent to the user after they submit the form.

The syntax can be summarized as: <!--gform <"text|$(var)">|<[reply="URL"]|[deliver=[mail"address|$(var)" [subject= "subject"]]|[file"path|$(var)"|<reset>-->

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:

<!--gform "The quick brown fox"-->
<!--gform "jumped over the lazy dogs"-->

This will be returned as: "The quick brown foxjumped over the lazy dogs"

But by inserting newline characters,

<!--gform "The quick brown fox\n"-->
<!--gform "jumped over the lazy dogs\n"-->

we get

"The quick brown fox
jumped over the lazy dogs"

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;

<!--gform "The persons name is: $(myvar)\n"-->

$(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) return the current date and time.

Mandatory Fields

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

<!--gform NONULL="variablename"-->

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:

<!--gform NONULL="variablename" NULLERROR="~username/directory/errorfile.html"-->

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 email, or in a text file. Any combination of delivery methods can be used.

To get the results sent to you via email use:

<!--gform deliver=mail "address@somesite.edu"-->

                                                or

<!--gform deliver=mail "$(address)"-->

The "<!--gform " lines with the text and variables you have specified, will be sent to either "address@somesite.edu" or the email address specified by the variable address via email.  The variables, of course will be translated to the values entered by the form submitter.

You can optionally also include a subject:

<!--gform deliver=mail "address@somesite.edu" subject="Form x submission"-->

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

To get the results appended to a file you use (for files you want browsable by anyone):

<!--gform deliver=file "~username/directory/filename.html"--> 

To get the results appended to a file you use (for files you do not want to be browsable):

<!--gform deliver=file "~username/private/directory/filename.html"-->

These files would not be browsable by anyone, including you, as owner of the file. To access these files via FTP, the directory specification would be:

homepages.wmich.edu/user/gformdata/private/directory/filename.html

The delivery file must exist in the form owner's area on the Web server before releasing your form.

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

<!--gform reset-->

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/directory/mythanks.html">

This command should be the last gform command in your form. At the very least, it should be after all <!gform reset--> commands.

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:

<!--GFORM SEPARATOR=" : " -->

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:

<!--GFORM SEPARATOR="," -->

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 currently recognized CGI environment variables:

  •  ANNOTATION_SERVER
  • AUTH_TYPE
  • CONTENT_LENGTH
  • 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 of a gform form

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 right away.

<HTML>
<HEAD>
<TITLE>gform sampler</TITLE>
</HEAD>
<BODY>
<H2>gform form sampler</H2>
<P>
Here are some different form specifies that will work with gform<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 email address:<INPUT NAME="email" 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>

<!-- I like to show the results as the reply file -->
<!--gform "<PRE>\n\n===================================\n"-->
<!--gform "Form submitted by: $(name)\n"-->
<!--gform "The date is $(date) and the time is $(time)\n"-->
<!-- A comment: Note use of environment variables just below -->
<!--gform "He/She is using: $(HTTP_USER_AGENT)\n"-->
<!--gform "and their host is: $(REMOTE_HOST)\n"-->
<!--gform "Email address given as: $(email)\n"-->
<!--gform "selected drink is: $(drink)\n"-->
<!--gform "A $(size) pizza with: $(pizza)\n"-->
<!--gform "salt: $(salt) pepper: $(pepper)\n"-->
<!--gform "Here is a dollar sign \$ and a double quote \"\n"-->
<!--gform "The coordinates on the submit image were: $(img.x),$(img.y)\n"-->
<!--gform "Comments:\n"-->
<!--gform "$(comments)\n"-->
<!--gform "</PRE>\n"-->
<!-- Don't feel like printing it. The next line is treated as an ordinary comment -->
<!--gform deliver=file "~j0bronco/forms/results.txt"-->
<!--gform deliver=mail "nobody@host.site.domain" subject="Form X submission"-->
<!--gform reset-->
<!--gform "This person would like $(drink) to drink\n"-->
<!--gform "They would also like a $(size) pizza with: $(pizza)\n"-->
<!--gform deliver=mail "$(email)"-->
<!-- Note that the reply file is relative to Document Root -->
<!--gform reply="~j0bronco/forms/mythanks.html"-->
</FORM>
</BODY>
</HTML>