gbook.txt

GBook - A web site guestbook

By Bill Kendrick
kendrick@zippy.sonoma.edu
http://zippy.sonoma.edu/kendrick/

September 22, 1996 - September 24, 1996
Upgrades:
  December 3, 1996


--- Q. WHAT IS GBOOK? ---

--- TECHIE A. ---

GBook is a "guestbook" for websites.  It runs as a CGI (Common Gateway
Interface) application on the server.  It's made up of a number of C sourcecode
files and a "makefile."

--- LAYMAN'S A. ---

GBook is a "guestbook."  Visitors of your website can come and see who has
signed the guestbook, and they can sign it themselves, leaving their name,
e-mail address, comments, their website address, etc.

GBook is actually a complete rewrite of my original "Bill Kendrick's
Guestbook."  After over a year of usefulness, I decided that the demands
others were putting on it required an upgrade.  (In other words, people who
downloaded my program and used it wanted it to do things it couldn't easily
do.  GBook fixes this.)

GBook is also pretty fool-proof when it comes to handling the data people
enter.  Some times people enter "don't have one" for website URLs.
GBook will catch things like this!


--- REQUIREMENTS ---

Not being as much of a Unix guru as people seem to think I am, I can't
easily answer this question.  I'll guess that it works on all flavors of
Unix (including Linux) and with all web browsers.  From the little experience
I've had with Windows NT, I feel that GBook should work fine there too.

As far as your webserver, you have to make sure you (as a user and web
author) have access to "CGI's".  (CGI's are the programs "behind" fill-out
forms on the web, among other things.)

You also have to have access to a compiler, like "gcc" (GNU C Compiler).

Oh, and you ALSO have to READ THESE INSTRUCTIONS WELL! :)


--- SETTING UP ---

= STEP 1 : DECOMPRESSING =

Since you're reading this, there's a 50/50 chance you've already decompressed
the source code.  If not, it's simple.  At your Unix shell prompt, type:

  gunzip gbook.tar.gz
  tar -xf gbook.tar
  rm gbook.tar

That decompresses the compressed file, then extracts the separate files out
of the "TAR" file, and then lastly (this is optional, of course), removes
the "TAR" archive, since you already have what was in it.

For help on any of these programs, type "man", followed by a space and then
the name of the program.  All three should be available.  If not ... ummm...

= STEP 2 : COMPILING =

To compile the program (as well as get almost all the files you need to
run the guestbook at its bare minimum), simply type, at your shell prompt:

  make

This will access the "makefile" file and follow the make-style instructions
within.  You should end up with the CGI itself, "gbook.cgi", and two other
files, "guests.html" (which will be your signatures page) and "temp.dat"
(a required in-between file).

NOTE: Your system is probably not set up like my system, so before compiling
(or, at least after errors start occurring), please make sure the "MAIL_CMD"
line inside "gbook.c" is correct.  The string which "MAIL_CMD" contains is
the path to the Unix "mail" program.  To find out where it is on your
particular system, simply type "which mail" and it will tell you.


= STEP 3 : SUPPORT FILES =

The first support file you'll need to get the program to run is some HTML
to display at the top of your signatures file.  It's called:

  top.html

Create an HTML file (remember, this is NOT a complete page, this is only
the top of the page!) and save it as "top.html" in your guestbook's
directory.

The next files you'll need (although these are optional - small default
pages will be displayed if these files can't be found) are as follows:

  noname.html                 What to show if they forgot to enter their name
  nocomment.html              What to show if they didn't give a comment
  notags.html                 What to show if they used HTML in their comments
  bademail.html               What to show if their e-mail address is messed up
  badurl.html                 What to show if their URL address is messed up
  fileerror.html              What to show if there was a file error (UH OH!)
  thanks.html                 What to show if their signature addition was
                              successful (YAY!)


= STEP 4 : THE FORM =

Unlike my previous guestbook program, this new guestbook program is a bit
more user definable (as per the requests of a number of my old guestbook
program users).

The following "variables" can be set within the HTML form (the page where
the visitors "sign" their information in).  How to use them in the form
will be explained in a moment.

  _MAILTO        Where to e-mail the signature. Leave blank to not e-mail.
  _POSTIT        Whether or not to even store the signature in an HTML page.
  _NEWONTOP      Store the entries with newest additions on top? (Newest first)
  _SHOWEMAIL     Whether or not to show signer's e-mail addresses on the page.
  _SHOWURL       Whether or not to show signer's URLs on the HTML page.
  _SHOWCOMMENT   Whether or not to show signer's comments on the HTML page.
  _SHOWFROM      Whether or not to show signer's "how they got here"s on
                 the HTML page.
  _KEEP          How many signatures to keep around. Set to 0 to keep all.
                 (ie, if you set it to 100, when you receive your 101st
                 signature, your first (oldest) one will be deleted;
                 when you receive your 102nd, your second (now oldest) one
                 will be deleted, and so on; thanks to Bill Thompson for
                 this idea.)

These "variables" will be stored as "hidden" fields in your form.  Like this:

  <input type="hidden" name="_MAILTO" value="someone@somewhere.org">

For the "yes/no" variables ("_POSTIT" thru "_SHOWFROM"), the "values" will be
(surprise) "yes" or "no" (or "on" or "off", if you like, although that makes
less sense.)


The "standard" set of input fields (boxes where the user types) are as
follows:

  _NAME       Signer's name. (REQUIRED)
  _EMAIL      Signer's e-mail address.
  _URL        Signer's URL (website address).
  _COMMENT    Signer's comments. (REQUIRED)
  _FROM       How the signer got to your website ("where they came from").

These fields are normal input fields.  An example:

  What is your name?  <input type="text" name="_NAME">  <br>
  What did you think of my page? <br>
  <select name="_COMMENT">
  <option selected> I LOVED IT
  <option> IT WAS OK
  <option> YUCK!
  </select>


Another thing some people (including me) wanted from my old guestbook
program which it didn't deliver was the ability to arbitrarily add some
more fields and have them show up on the guestbook and in the e-mail.

Well, now with GBook you can do it.  Any input field in the form whose
name does NOT start with an underscore ("_") will be shown.  For example:

  What's your age?  <input type="text" name="Age">  <br>

Would show up in the guestbook and the e-mail as:

  Age: 21


--- EXTENDED USES: ---

* Some things to remember about GBook is that you can have any of the following
  combinations done with people's signatures:

    1. e-mail it to you
    2. e-mail it to you and post it on a page
    3.                      post it on a page
    4.                                        neither (WHY!?)

* Also, the e-mail address in the "mailto" field can be multiple e-mail
  addresses.  Just combine them with commas (","):

    <input type="hidden" name="_MAILTO" value="john@abc.com,jane@def.org">

* When you receive e-mail from the GBook CGI, you SHOULD be able to [REPLY]
  directly to it with your e-mail program.  Well, ok, it's always worked on
  MY system, but rarely anywhere else.  You might have to do some
  Copy/Pasting.

* Some other uses of the guestbook could be a simple form of voting booth,
  a simple form-to-mail program (the user could even use a radio-button or
  pull-down menu to decide which e-mail address(es) to send to!), and more...

--- CREIDTS / HELP ---

This entire program was whipped up very quickly one Sunday evening by:

  Bill Kendrick
  New Breed Software
  kendrick@zippy.sonoma.edu
  http://zippy.sonoma.edu/kendrick/

LEGAL STUFF:  If you distribute this software, do not alter any of the files!
Please report any bugs or upgrade ideas to me - if you have a chunk of code
you want to see in this program, send it to me.  If it's good, I'll add it
to the standard distribution!  Also, do not sell this program, it's FreeWare.

--- THANKS! ---

Have fun!  Viven las Ataris!
