How to use the script

Due to popular demand: how to use the guestbook script.

Note: this explanation you have the PERL script language installed and that you are on a unix-like system.

Ok: there are two steps you need to complete in order to use the script on your machine.

Customize the script to run on your machine
Write a form to run the script and file the comments

Customizing the script

The script has an initialization section. But first, make sure Perl is installed and running by typing which perl at a Unix prompt.

   % which perl
   /usr/local/bin/perl

This path must be hard coded into the first line of the script so it also matches the output of the which perl command:

   #! /usr/local/bin/perl
   # 
   # Mogens Sept 94 
   etc etc...

That is important. The next step is to make sure that the file is executable, so type

   % chmod a+rx comment.perl
   % rehash
   % ./comments.perl
   Location: /default-comments.html
   Content-type: text/html

   The comments are <A HREF="/default-comments.html">here</A>
   <P>

   %

Ok - you now need to place the comments.perl into the cgi-bin directory, or (if you are using the NCSA server) make sure the .perl suffix is associated with the application/x-httpd-cgi - check the end of the server's conf/srm.conf file.

As a final check we can access it through the web server by using the proper http://your.machine-name.domain/cgi-bin/comments.perl.

The program should respond with a link to a non-existent file called default-comments.html.

Setting the variables

Ok - having achieved the state where we can execute the program, we now need to customize it for our needs. We need to change three variables in the program initialization section.

First locate the # Define fairly constants section. Change these three lines:

   $COMMENT= "/usr/local/etc/httpd/htdocs/default-comments.html";
   $URL="/default-comments.html";
   $SENDMAIL="/usr/lib/sendmail -t";

$COMMENT: The first variable is the path to the default comments form (see next section on how to create one).
$URL: The second variable is the URL path instead of the file path to this same default form. This path is only used if there is no path specified in the PATH_INFO (see below).
$SENDMAIL: This contains the command used to send a mail message to the owner of the form each time a new comment is added to the list. You must determine the path to sendmail on your system and put it in this variable. You can try typing which sendmail or asking your admin.

Writing a comments form

At the top of the script there is a comment listing the form fields you can use - handy reference information. The form fields are:

realname - text Full name of submitter - defaults to 'Anonymous'
username - text e-mail address of submitter.
comments - TextArea comments to be added
mailto - hidden e-mail address to CC new comments to - none.

The other piece of information is to note that the path info (excess path when referring to the script) is used to point to the file that is used for storing comments. Since that made no sense, let's illustrate with an example.

Ok - we have the partial URL path /cgi-bin/comments which refers to the comment script.
We can extend this path and have the server pass the extra information to the script. We also have the comments file located at URL /foo/chatter.html. We add the partial URL of the file to the script URL to get: /cgi-bin/comments/foo/chatter.html.

What happens is that the /cgi-bin/comments script is run, and the excess /foo/chatter.html is passed to the script as extra information. This is important, because it allows us to have many different comment files without having more than one script.

   /cgi-bin/comments         runs the script without any path info.
   /cgi-bin/comments/foo     runs the script with /foo as path info.
   /cgi-bin/comments/a/b/c/  runs the script with /a/b/c/ as path info.

The Form

The form must define the fields required by the script. A typical form can look like this:

  <FORM ACTION="/cgi-bin/comments/foo/chatter.html" METHOD="POST">
  Name   : <INPUT NAME="realname">
  E-mail : <INPUT NAME="username" MAXLENGTH=40>
  Chat   : <TEXTAREA NAME="comments" ROWS=6 COLS=40>Chat here</TEXTAREA>
  <INPUT NAME="mailto" TYPE="hidden" VALUE="mogens@cs.stanford.edu">
  </FORM>

Now for the clever bit.

The Clever Bit

Remember that the form passes the path /foo/chatter.html to the script. The script then appends the comment to the file /foo/chatter.html.

Now, if the /foo/chatter.html file contains the form (and is world writeable so the server can access it), then the comments are placed after the FORM. Simplicity itself.

In order to make a file writeable by anyone (world writeable) use

    % chmod a+rw foo.html
    % ls -l foo.html
    -rw-rw-rw-   1 mogens   users        159 Aug 26 19:21 foo.html
    %

So to summarise:

Make sure that the comment script runs without errors.
Make sure your form document has the right INPUT fields named and is writeable by all.
Check that the FORM ACTION URL includes the path to the script and the form document.

Christian Mogensen@cs.stanford.edu