This is gform.txt in view mode; [Download] [Up]
gform Version 1.1d notes. 10-Oct-95 HR
Also note that docco is available in HTML as gform.html and for the
latest check http://www.swin.edu.au/csit/gform.html
1.0 gform - generic web forms handler
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. Most often you want to collect submitted forms
in a file or send it thru the mail to yourself or someone else
who can colate these.
I find that web information providers are generally not programmers
and therefor can not easily write their own form programs.
gform addresses the problem of application style forms.
It enables the results of a form to be formatted and send
to a file or via the mail. ( You could also forward mail to
a "mail-to-print" gateway and get hardcopies ).
1.1 How it works
In HTML you use the tag FORM to specify a form and you use
'ACTION' to describe which scipt/program will handle the form
data. You specfy the ACTION as 'gform'
In the HTML tag set there is a tag for comment <!-- .. -->
What gform does is read comments that start with <!--gform ... -->
These special comments contain commands for gform.
Any number of these <!--gform ..--> comments maybe used anywhere
in the file.
(NOTE: The old TAG format of <!gform is still supported and will
probably work Ok, but it is not the correct syntax for
a HTML comment. Therefor the "<!--gform" form is encouraged.)
Gform works with various FORM specifiers such as Textarea,
radio buttons, checkboxes, multiple choice selections.
1.2 syntax of gform commands
There are 2 types of <!--gform ... --> commandlines.
Firstly, variables and text strings. Variables start with
a '$' sign followed by the variable name as specified on
the HTML INPUT tag in the HTML form file. The varables you use
should be those that you specified in the INPUT tags.
If the variable doesn't match, it will look for the variable
in the"environment" (See environement variables notes).
If it can't find it there it will return "null".
Beaware that "type=checkbox" returns "null" if it is
unticked. This is a side effect of how forms are handled.
You can also specify variables by enclosing them with
brackets and prefixing a dollar char: '$(variable)'
This is handy if you want text straight after the variable
name.
Variables maybe freely mixed with text. The following example
will send the text string and replace the "$name" variable
with what was given in the form submission.
<!--gform "Form submitted by: $name"-->
You will have to specify newlines and tabs by escaping them.
by preceding a special char with a '\'.
The following escaped chars are recognised:
\n - newline
\t - tab
\f - form feed
\r - return
\$ - Escape a dollar sign
\" - Escape a double quote
\\ - Escape a slash
So using the above example with a newline appended;
<!--gform "Form submitted by: $name\n And more text"-->
2.0 There are 2 special variables $(date) and $(time) that can be
used to return the current date and time.
2.1 Environment variables.
An extra bit was added (6-oct-95) that returns the values
of CGI environment variables.
For example;
<!--gform "Remote host is: $(REMOTE_HOST)\n"-->
will return the value of the remote host that submitted the
form.
These variables can also be seen in action with the "test-cgi"
shell script that comes with the CGI distribution.
The following variables exist:
SERVER_VERSION REDIRECT_REQUEST
SERVER_SOFTWARE REDIRECT_URL
SERVER_NAME REDIRECT_STATUS
SERVER_PORT GATEWAY_INTERFACE
REMOTE_HOST SERVER_PROTOCOL
REMOTE_ADDR REQUEST_METHOD
REMOTE_USER PATH_INFO
REMOTE_GROUP PATH_TRANSLATED
REMOTE_IDENT SCRIPT_NAME
DOCUMENT_ROOT QUERY_STRING
ANNOTATION_SERVER CONTENT_TYPE
AUTH_TYPE CONTENT_LENGHT
HTTP_ACCEPT
HTTP_USER_AGENT
HTTP_REFERER
(The usefullness of variables with gform is debatable.
However, it was easy to implement. The meaning of all these
is documented elsewhere, try http://www.yahoo.com )
2.1
The second commandline type that is recognised are lines with
keywords. These control where and how the form data is handled.
The following are recognised.
The next line will put the results in the file "/path/of/file"
<!--gform deliver=file "/path/of/file"-->
The next example will email the results to "address@swin.edu.au"
<!--GFORM deliver=mail "address@swin.edu.au"-->
and optionally specify a subject
<!--gform deliver=mail "address@swin.edu.au" subject="form Submission"-->
To print the results directly to a printer use,
<!--gform deliver=print "hp"-->
where "hp" is the name of a printer as found in your /etc/printcap
This following example displays the HTML file 'thanks.html' after
the form has been submitted. The pathname of "thanks.html" is
relative to your WEB directory (Absolute pathnames can also be
given).
<!--gform reply="thanks.html"-->
(commands and variables are case-insensative)
There is a compile time option that can enable tilde ( ~ )
character file expansion. If enabled, a "~user" in the http reference
will expand to a users home directory and a subdirectory
if so configured.
For example;
~harry/foo.html
will expand to the users home directory ( plus to whatever USERDIR is
defined to be . See INSTALL notes )
and
<!--gform reply="/~user/html/foo.html"-->
is also expanded to a users home directory.
1.4 Complete examples.
See the files
sample.html
sample2.html
sample3.html
These are the contents of the former NiCE NeXT User Group NeXTSTEP/OpenStep software archive, currently hosted by Netfuture.ch.