GFORM Documentation

A lot of people have asked for guestbooks, mailers, interactive CGI scripts without knowing that one such binary already existed on Ra and could handle all of that.

GFORM is a very useful and easy-to-use CGI Binary that allows great flexability for both beginners and novices to the WWW. It allows you to design both the form and the response for the form within the same HTML document.

Intriguing so far? Sound like the tool you're looking for? Here's how it works:

Go ahead and design a form. Refer to Mosaic for X version 2.0 Fill-Out Form Support if you're not comfortable with forms quite yet. You'll catch up to speed in no time. Use this line for the beginning of your form:

<form method="post" action="/cgi-bin/gform">

You're half way there. Brain-dead? Grab a Coke and splash some water on your face. We're almost done. Remember in HTML how you can have comments? Like so:

<!-- This is a legal HTML comment -->

Well, GFORM scans your HTML document for these for how to handle the user's input. Since you don't want that information showing up on your document, the best way for both the software and for you, is to "hide" them using the comments. And since you may be the commenting type of person, it won't confuse your personal comments with those intended for the program, for it looks for comments like so:

<!--gform -->
And also <!gform > (but that's not good style)

GFORM has two main commands. Either a keyword command or a formatting command. A keyword command would tell GFORM how to handle the user's input (ie: send email, append to a file, show a response, etc). A formatting command would tell GFORM how to format the user's input into either a human-digestable format or maybe a SAS-digestable format.

Keyword Commands

  • Deliver

  • Mail
    This tells GFORM to send the user's input through email to the argument's address. Like so:

    <!--gform deliver=mail "Jason_Purdy@unc.edu"-->

  • File
    This tells GFORM to append the user's input to the file you specify. Be warned that you need to make this file WORLD writable (chmod a+rw [filename]) so that Ra's WWW server (the one running GFORM) can append the data to the file.

    <!--gform deliver=file "/html/home/purdy/data.db"-->

  • Reply

    This tells GFORM which HTML document to show as a response to the user after submitting the data.

    <!--gform reply="/~purdy/thanks.html"-->

    • Formatting Commands

  • Strings

    This is the basic, complete, dietary, supplemental, etc, building block to GFORM. Strings, for you non-programmers, are basically a type of computer variable that contains a collection of alphanumerical characters. For example:

    "The quick brown fox is cool." -- A String
    "al;skjdfskljjasj" -- A String
    "12341234" -- A String
    3.14157 -- NOT A String

    Getting the hang of it yet? Basically if it's composed within double quotes, it's a string. So the basic formatting command for GFORM is the string. It goes like this:

    <!--gform [INSERT YOUR STRING HERE]-->

    So basically the last half of your HTML document is a bunch of GFORM formatting commands.

  • The '\n'

    The '\n' represents a newline (n for newline) character. It's like hitting return and going to the next line. For example, if this were the string:

    "This is a test of the\nEmergency Broadcasting System.\nOnly a test.\n\n"

    This were what it'd look like:

    This is a test of the
    Emergency Broadcasting System.
    Only a test.

  • The '$'

    Okay, last bit, I promise. By now, you have to be asking yourself: "Yeah, but how do I get what the user inputted??" If you're not ... grab another Coke. The '$' represents a variable name. Variables are basically symbols representing ever-changing (chaotic) values. For example, if the user entered "Jason Purdy" (Yeah, a string! You're catching on!) as the name, then $name would represent "Jason Purdy" ... And if you wanted that information, then you would put that within a formatting command, like so:

    <!--gform "$name sent this to me.\n"-->

    Sometimes you will want the variable immediately following or preceeding another part of your string. In this case, you need to use parenthesis. Like so:

    <!--gform "They want $(amount)Mb of Disk Space\n"-->

    And lastly, if you want the dollar sign within your string, you need to escape it with the backslash, like so:

    <!--gform "That will cost exactly \$$amount dollars.\n"-->

    • There! That's it! Take a look at these examples, if you need some more insight. Feel free to email web-walkers@unc.edu (Join the list!), post to unc.www, or email me with any further questions.
    Credit should be given to Larry Raaymakers and Jonathan Magid, creators of GFORM. If you're interested in installing the source code on your own server, find the source code at ftp://swin.edu.au/pub/cwis.

    Directories Search Comments Help

    -------------------------------------------------------------

    To UNC-CH Home Page

    Last modified: 1997 Sep 97