CGI 101 : A Guestbook of your own by Robin Bassett
Absolutely Victorian Greetings originally posted at http://www.perlarchive.com/tlc/0002/01.shtml

Are you tired of using those free services that provide Guestbooks, Autoresponders and other scripts to website builders who do not have their own cgi scripts? Once upon a time Grandma used those, too - and then Grandma discovered her cgi-bin directory.

Installing your first Perl script can be a frightening proposition, especially if you think like I do and figure that you can't possibly program your way out of a paper bag with a map. Grandma can tell you, though, that it is much easier than it looks - and you don't need to know how to program a single line! So, let's install a Guestbook and customize it to match your site.

Step One: Get your Tools Together

• A text editor. You will need a good plain text editor, preferably one that does "find and replace." If you don't have one, you can try my favorite, Arachnophilia, which includes many of the same tools that you will find in those expensive WYSIWYG editors and has a great price: FREE. Arachnophilia is "careware" whose author asks that you do a good deed for someone else as your payment to him. You can download it at http://www.arachnoid.com/arachnophilia/.

• An FTP program. You will also need an FTP program such as Cute FTP and a decompression utility to unzip the archived files. (Grandma will explain what FTP is later!) You will find trial versions of many FTP programs at http://download.com. Download a trial version of WinZip32 while you are there. Note: Your unzip program MUST be able to unzip TAR archives.

Install your new programs to your computer and create a new, empty directory somewhere convenient named "guestbook."

Get the script

The Perl Archive contains links to nearly 100 different Guestbook scripts. We're going to use the Selena Sol's WebGuestbook, an internet classic that is extremely well documented in plain English and is quite easy to install and customize. Download the free script at http://www.extropia.com/scripts/guestbook.html.

Install the script

Find the location of your downloaded Guestbook script. You can use the "Find ...Files and Folders" function in your Start menu to locate the script. It is named Guestbook4_0.tar. Double click on the program listing in your Find screen to begin the unzip process. Unzip the files to the empty guestbook directory that you created. After the unzip operation is completed, you should find the following files in your Guestbook directory:

• cgi-lib.sol
• cgi-lib.pl
• mail-lib.pl
• guestbook.cgi
• guestbook.setup.cgi
• guestbook_admin.cgi
• index.html

You will also find two new folders: HTML and DOCS. The DOCS directory contains instructions for installing the Guestbook. The HTML directory contains the html file that will be your actual Guestbook and an index file to keep snoopers out of your directory online.

The main file that we will work with is guestbook.setup.cgi - open that up in your text editor. Make sure that you have turned OFF Word Wrap in your options settings so that you do not accidentally introduce stray spaces or characters that will keep your script from functioning correctly.

Guestbook.setup.cgi is going to need to be changed on almost every line, so you will want to have an original copy handy to refer to. An easy way to do that is to simply Save As the file to a different directory so that you can have both copies open while you work on them - Grandma keeps a directory called Done for just such things. Another way would be to Save As the file with a different name - perhaps my.guestbook.setup.cgi. Whichever method you use, open up both a reference copy and a working copy of the script.

If your text editor has a Find and Replace feature, use it to change each entry in guestbook.setup.cgi as outlined in README.INSTALLATION. Otherwise, proceed very carefully by hand, paying special attention to the various punctuation symbols - one misplaced ; will cause your script not to function.

A word of warning: pay very close attention to the difference between a PATH and a URL. A URL starts with "http://", a path simply tells the script where things are located on the server in relation to the script. Many folks can get away with the PATH "/cgi-bin/myscript.cgi", but you might need to ask your system administrator what the correct path is. Each server is different.

Edit each of the remaining files according to the instructions given in README.INSTALLATION to reflect the required information correctly for your particular server and website. As you finish each file, save it to "Done" directory. Right click on the files that you did not have to edit and copy them to Done - having files to be uploaded in two different directories might cause you to upload an unedited script over the correct one. (You can just leave the HTML directory as is for now.) Now, fire up your web browser and connect to your website using your FTP program.

Take a look around your main website directory from the back end when you first connect. Assuming that you have a cgi-bin, you should see several directories or folders inside your home directory. Each server names things a bit differently, but you should have a directory called "cgi-bin" and another where your html files are placed. On my server that directory is called "htdocs" - but it might be something else on yours. Ask your systems administrator if you aren't sure.

Upload each of the files from your Done folder to your cgi-bin. If you are fairly new to web building you may have been using the "autodetect" feature on your FTP program each time that you upload files. Cgi-scripts are one instance when you definitely want to override the autodetect and specify that the script files MUST go up ASCII (plain text).

Double check to be very sure that you have each of the seven files listed above in your cgi-bin. Right click on each file that you uploaded to the cgi-bin (except index.html) and choose Change File Attributes. If you are using Cute FTP, you will see this screen:

Other FTP programs have similar interfaces.

In the box labeled Manual, type the numbers given in the instructions as the correct permissions for each file and click the OK button. The program will return a message to you confirming that the permissions were changed correctly. When you have changed the permissions correctly on all the files that you uploaded to the cgi-bin, move to your main directory (the one where your HTML pages go) and make a new directory called "guestbook" - be very careful to name this exactly as you did in your guestbook.setup.cgi. You will receive an error message when you try to access your Guestbook if the names do not match exactly - scripts are case sensitive.

Open the guestbook.html file in the HTML folder and change the links to refer to the particular location of your cgi-script - "/cgi-bin/guestbook.cgi" will work for many people, but you might need to use the full URL. When you are done, upload guestbook.html and index.html into the Guestbook directory that you made inside htdocs. If you still have your FTP program set to manual rather than autodetect, send these files ASCII too - all text files go ASCII. Image files go BINARY.

Use your favorite web browser to access your new Guestbook. It should look like the one here: http://www.robinsplace.com/guestbook/guestbook3.html

Pretty bland, right? So, let's customize it to look like the one here: http://www.robinsplace.com/guestbook/guestbook.html

Customizing your Guestbook

Begin by opening a new HTML file in your favorite WYSIWYG editor. Start by setting the page background that you would like to use, along with your font and link colors.

Grandma particularly despises text that crowds the borders of her screen. She finds pages that align to the left of the screen with no margin at all, like the default Guestbook page, does very distracting - not to mention ugly. We can get around that by inserting a table 1 column wide and 1 row long that is about 75% of the width of the page. This will leave a nice margin around your text no matter what resolution your viewer is using.

There are several philosophies of what to do about table width in web design. Some folks are of the opinion that it is necessary to give everybody exactly the same view of a page. To do that you must hard code exact pixel dimensions for everything into your HTML, using the lowest common denominator: the very low resolution that WebTV displays at. You have probably seen pages like this - they are the ones that have a huge, empty right hand margin, with the display running down only half the width of your screen.

Some folks simply design for a certain screen resolution, often 800 x 600, and if you don't happen to use that resolution, too bad for you. You'll find these labeled "best when viewed at."

Grandma's philosophy is a bit different - I design at 800 x 600, but I try to make it acceptable at any resolution. For that reason I use percentages rather than hard coded pixels. The basic "balance" of the page will be approximately the same at any resolution, and text elements will simply wrap to fit.

Whichever philosophy you follow, select the table and center it on the page. If you are coding by hand you can just enter the tags <div align="center"> right before <table> and </div> right after </table>. Change the Cell Properties to align="left", valign="top" and border="0". Your completed HTML should look like this:

<div align="center">
<table width="75%" border="0" cellpadding="0" cellspacing="0">
<tr>
>td align="left" valign="top" border="0">
Some stuff goes here
</td>
</tr>
</table>
</div>

Use the top three inches or so of the page to compose your Guestbook Heading, adding any images or links that you want to use. If you want to display an ad banner at the top of the page, you will need to hard code this into the page rather than use an SSI call. If you don't know what that means, you can just paste in your regular LinkExchange or other banner service script as usual where you want the banner to appear. You can even embed a midi file if you like - but be sure to use <embed> so that all browsers can read it. A little control panel is a nice addition too. If you need to, you can insert another table (called nesting tables) inside the first in this area to assist in the layout of your header.

When this page looks just as you want it to, save the file and open it in your plain text editor. Make sure that all the links for graphics that you have used refer to their future location on your server, rather than on your hard drive. If you are putting your graphics inside your Guestbook directory, simply take out all reference to any directories that appears in those image tags, leaving only the tag names, surrounded by quotation marks like this: <img src="myimage.jpg">

Remember, that your Guestbook page is a real html file that will be indexed by search engines. Insert a page title and full meta tags into the header section of your html file. You can copy and paste this from another page - just be sure that you do not end up with double <head> or </head> tags in the top of your document. Take out any spare tags below the </table></div> tags, except the </body> and </html> tags.

Open up guestbook.html in the HTML directory and look for the line that says <!--begin--> - paste that into your HTML page directly underneath the end of the entries that you made to the top of the page but inside the </td> tag. This is where your Guestbook entries will appear. If you want to leave a bit of space between your header and the first entry, include the line <p> </p> before the <!--begin-->. Paste the line that says <!--end of guestbook entries--> directly above your </td> tag. Your finished file should look like this:

<html>
<title>My Guestbook</title>
Meta tags go here
</html>
<body>
<div align="center">
<table width="75%" border="0" cellpadding="0" cellspacing="0">
<tr>
<td align="left" valign="top" border="0">
Some stuff goes here that will be your header design
<!--begin-->

<!--end of guestbook entries-->
</td>
</tr>
</table>
</div>
</body>
</html>

If your WYSIWYG decided to insert a "Height" property tag inside your <td>, be sure to remove it - if you don't, once you have more entries than the specified height allows your Guestbook will no longer display properly.

You will also find a link to your Add page in the guestbook.html code. It reads in the original script <A HREF = "../guestbook.cgi">Add</A>. Place that code into your header wherever you want the link to appear. Be sure to modify that link to correctly reference your particular script on your server. You can probably get away with <A HREF="../cgi-bin/guestbook.cgi">. If you have problems calling the script, try using the entire URL: <a href="http://mydomain.com/cgi-bin/guestbook.cgi">

If you want to use an image such as a button rather than a text link, simply put the <img src> inside the <a href> tags where it says "Add." If you do not want a border around your image be sure to add border="0" to your image tag. Your finished link should look like this:

<A HREF = "../cgi-bin/guestbook.cgi"><img src= "myimage.jpg" border="0"></a>

Save the file in Done and use your FTP program to upload this file to your server in place of the plain guestbook.html

Modifying the Add Page

Save As the guestbook.html file as add.html and keep it open in your text editor. Take out the lines that say <!--begin--> and <!--end of guestbook entries-->. Your code should now look like this:

<html>
<title>My Guestbook</title>
Meta tags go here
</html>
<body>
<div align="center">
<table width="75%" border="0" cellpadding="0" cellspacing="0">
<tr>
<td align="left" valign="top" border="0">
Some stuff goes here that will be your header design
</td>
</tr>
</table>
</div>
</body>
</html>

Open up guestbook.setup.cgi in your text editor so that you have the code for both files open simultaneously. Locate the line in guestbook.setup.cgi that says "print <<"end_of_add_form_header"; " DO NOT DISTURB THAT LINE!

Scroll down until you see end_of_add_form_header again. Now copy everything between those two statements and paste it inside your table in the same place that <!--begin--> used to be, then delete this section from guestbook.setup.cgi - again, be very careful to leave the two lines that say end_of_form_header exactly as they are!

The section that you want to remove says:

<HTML>
<HEAD>
<TITLE>Guestbook (Add Form)</TITLE>
</HEAD>
<BODY>
<CENTER>
<H2>Add to my Guestbook</H2>
</CENTER>
Please fill in the blanks below to add to my guestbook.  The only
blanks that you have to fill in are the comments and name section.
Thanks!
<P><HR>

If you would like to change any of the wording, do so. Just be careful not to disturb any of the HTML tags. Take out the <HTML>
<HEAD>
<TITLE>Guestbook (Add Form)</TITLE>
</HEAD>
<BODY>
section of the code that you pasted into add.html and the </body> and </html> tags at the bottom of your file, then save the file. Your file should now look like this:

<html>
<title>My Guestbook</title>
Meta tags go here
</html>
<body>
<div align="center">
<table width="75%" border="0" cellpadding="0" cellspacing="0">
<tr>
<td align="left" valign="top" border="0">***  
Some stuff goes here that will be your header design
<CENTER>
<H2>Add to my Guestbook</H2>
</CENTER>
Please fill in the blanks below to add to my guestbook.  The only
blanks that you have to fill in are the comments and name section.
Thanks!
<P><HR>
</td>
</tr>
</table>
</div>

Select the entire file using Select All and copy the file.

Maximize your open guestbook.setup.cgi file. Select the same area that you copied into add.html and delete it, being very careful to leave those end_of_add_form lines just exactly as they are. Paste your add.html file into guestbook.setup.cgi between the two lines that say end_of_add_form.

You can go on to customize your Thanks page and Missing Required Field note in the same way. Those sections of the script are just below the end_of_add_form. When you are done, save guestbook.setup.cgi somewhere where you will not overwrite the original.

Upload this new file to your server with your FTP program in ASCII format (choose overwrite when it asks), check your permissions on the file to be sure that they are still set correctly and you are done - congratulations!

Oh, what's FTP? It means File Transfer Protocol - in other words, it is a program to move files around the Internet, copying them from one machine to another. The biggest thing to remember about FTP is that text goes ASCII, images go binary and never use autodetect with cgi scripts.  

Robin Bassett, otherwise known as Grandma, publishes Absolutely Victorian Greetings and A Letter from Grandma at http://robinsplace.com. One of the largest free egreetings sites online, the newly redesigned Absolutely Victorian Greetings is powered entirely by scripts found through the Perl Archive and customized by Grandma. Robin specializes in graphic restoration, web design, and teaching internet & design skills to newcomers.