WMU GFORM User's Guide
Gform is a program that allows you to easily create simple questionnaire-type Web forms by using commands that are embedded inside the form HTML file. It then uses variable substitution to deliver the results. The results can be collected in a file, sent via e-mail, 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 and a simple example
- Supported INPUT fields.
- Syntax of gform commands
- Special characters
- Variables
- Mandatory Fields
- Delivery Methods
- Reply URL
- Separating multiple values
- CGI environment variables
- Using gform in password protected pages
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/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>
<!--gform "The person's name is: $(yourname)\n"-->
<!--gform deliver=mail "nobody@wmich.edu"-->
</html>(The gform commands will be explained later) 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 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 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 - newlineThe most useful one is the Newline character. For example take the next 2 lines;
\t - tab
\f - form feed
\r - return
\$ - Escape a dollar sign
\" - Escape a double quote
\\ - Escape a slash
<!--gform "The quick brown fox"-->This will be returned as: "The quick brown foxjumped over the lazy dogs"
<!--gform "jumped over the lazy dogs"-->
But by inserting newline characters,
<!--gform "The quick brown fox\n"-->we get
<!--gform "jumped over the lazy dogs\n"-->
"The quick brown foxThe complete example shows various use of escaped characters.
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;
$(myvar) is then replaced by what the form user entered and the result is delivered according to the given delivery method(s).<!--gform "The persons name is: $(myvar)\n"-->
There are 2 special variables that are always defined. $(date) and
$(time) that return the current date and time.
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/filename.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 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
<!--gform deliver=mail "address@somesite.edu"-->The "<!--gform " lines with the text and variables you have specified, will be sent to either "address@somesite.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.
or
<!--gform deliver=mail "$(address)"-->
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:
www.wmich.edu/user/gformdata/private/directory/filename.html
or
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.
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
Using gform in password protected pages
If you are using gform with an online form where any of the following pages/files for that form are in a password protected directory:
- the online form page
- a page used in a gform reply= command
- a page used in a gform nonull= "variable name" nullerror=command
then you must allow the Web server account, www-cgi, access via your x.htsecure file. See more in Password Protecting Pages on www.wmich.edu.
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 get to see the results straight 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
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 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>
<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>
revised December 17, 2003
Phone (269) 387-5430 | Contact OIT | Last Updated: February 29, 2008
Report Copyright Infringements