***************************************************************** * VisitorBook 1.1.1 README - UNIX Version, 1/3/00 * * Copyright 1997-2000 Mike Wakerly, Command-O Software * * E-Mail: * * Web: * * * * Redistribution in whole or part of the VisitorBook script is * * strictly prohibited without the written permission of the * * author and Command-O Software. * ***************************************************************** ***************************************************************** * Table of Contents * ***************************************************************** * This document is best viewed in a 9-point, mono-spaced, font * * such as Monaco. * * * * 1.1 - Introduction * * 1.2 - Feature List * * 1.3 - Known Problems / Incompatibilities * * 1.4 - Files Included * * * * 2.1 - Installation: The Basics * * 2.2 - Configuring the Variables * * 2.3 - Modifying the 'form.html' File * * 2.4 - Setting the Permissions * * * * 3.1 - Testing It Out * * 3.2 - A Note on ".CGI", ".SHTML", etc... * 3.2 - Getting Help, etc... * * 3.3 - Change History * ***************************************************************** ---------------------------------------------------- --> Section 1.1: Introduction ---------------------------------------------------- VisitorBook 1.1.1 is not another bulky, ugly guestbook script. It's a database driven CGI designed to be quick and easy for you to set up, and of course, for visitors to use. One important feature is its ability to limit the number of posts allowed -- an important consideration for high traffic sites. VisitorBook was, of course, written completely from scratch. It's not a hacked up version of another CGI or a modified form processor. It's also 100% free. VisitorBook 1.1.1 doesn't have a huge amount of features, since it was designed to be simple. But it will work great for your company's home page, your home page, or where ever else you want to use it. ---------------------------------------------------- --> Section 1.2: Feature List ---------------------------------------------------- The key features of VisitorBook 1.1.1 are as follows: => Fully customizable header & footer files => Maximum post limitation (optional) => Date and time stamp => Slick table-based output => Sorting options: top to bottom or vice versa => Database driven - easy to remove entries => Mail to user/admin after post => Customizable output => Intelligent detection of web site address (will not recognize non-URLs) => Optional display of user's IP address Note: If you've looked at the list above, and don't see a feature you're looking for, send me an e-mail and I'll see what I can do. This is one of the first releases of VisitorBook, so expect to see more features in the future! ***************************************************************** * NOTE! Please be sure to mail feature suggestions and / or bug * * reports to me. * ***************************************************************** * FEATURE NOTE * After modifying the guestbook database file, it was seemed necessary to wait * for a new entry (or post a new one) for the HTML file to be updated. However, * a previously undocumented feature has existed in all versions of VisitorBook. * * To update the database file, simply type in the URL as follows (with the * proper domain name): * http://www.domain.xyz/cgi-bin/visitorbook.pl?refresh ---------------------------------------------------- --> Section 1.3: Known Problems / Incompatibilities ---------------------------------------------------- VisitorBook has been tested on a few Linux/Unix systems, and has run without a problem. However, I have not tested it on any NT servers or the like. If you have problems running it on any other system, I can't help. The only systems I use are Linux based and Macintosh servers. If you'd like to port VisitorBook to another platform, please do so! If you need any help from me, I'll do my best, though, as I say, I'm unfamiliar with most other servers. Being that this is the first version, there are most likely some bugs/glitches in Visitor Book. If you find any, mail me at the e-mail address listed at the top of this file... you will be credited in the next release! ---------------------------------------------------- --> Section 1.4: Files Included ---------------------------------------------------- If you are using VisitorBook for the first time, you should have downloaded the following files: README.txt - This file! visitorbook.pl - The main script. Does all the work for you! gb-top.html - File in which you should put the header for the guestbook. gb-bottom.html - File in which you should put the footer for the guestbook. book.db - An empty file that you can use as the databse file. book.html - An empty file that you can use as the book HTML file. If you're missing any of these, go to the VisitorBook download page at FreeScripts . ***************************************************************** ---------------------------------------------------- --> Section 2.1: Installation: The Basics ---------------------------------------------------- The first thing you need to do in order to get VisitorBook running is to make sure you have the correct path to PERL at the top of the script. This first line is sometimes called 'the bang line'. How do you know if you have the path right? There's a few ways... - Ask your ISP/Service Provider what the correct path to Perl is - In Telnet, type 'which perl' or 'whereis perl' - On your ISP, snoop around in someone else's CGI and see what they've got Some common paths to Perl (listed in order of popularity) are: #!/usr/bin/perl #!/usr/local/bin/perl #!/bin/perl #!/usr/sbin/perl ---------------------------------------------------- --> Section 2.2: Configuring the Variables ---------------------------------------------------- The next step you should do is to customize the variables in the script. These are all conveniently located in one section. This section (and 'the bang line') are the only parts of the script you should really need to edit. 1. $cgilib = "/path/to/cgi-lib.pl"; For convenience, VisitorBook utilizes Steve Brenner's CGI-LIB library. You don't need to understand what this is to get it to work... but it is basically common pieces of code stored in one file for easy distribution. This is a UNIX path -- NOT a URL. If you do not know what this is or where cgi-lib is after you upload it, ask your service provider. If you don't know how to find the path to this file or what it is, someone familiar with your site will be the only person who can help. Since every site is different, we can't really help you here if you get stuck... 2. $mailprog = "/bin/sendmail"; This is the UNIX path to the mail program on the server. The CGI lets you e-mail yourself or the user after postings. The mail program does all the dirty work. 3. $thanks = "http://www.site.xyz/thanks.html"; After the user signs the book, the CGI takes them to this URL. Easy! 4. $top = "/path/to/gb-top.html"; The book file is automatically created by the CGI every time it is signed. This file must include the top part of the HTML to be used on the guestbook. So, this file might look like: The VisitorBook!

Here is The Guestbook

Basically, the guestbook entries are sandwiched in between this file and the bottom file, so it is up to you to have all the and tags and such... 5. $bottom = "/path/to/gb-bottom.html"; Do you really need to ask? Okay, this is the bottom file, the partner of the top file. See above. 6. $main_book = "/path/to/book.html"; The CGI will generate the guestbook file with three components: the top file, the guestbook entries, and the bottom file. The is the UNIX path to the nonexistent file that the CGI will automatically create. 7. $main_db = "/path/to/book.db"; This is the path to the database file that will be used by the script. You must create this file yourself (it should be empty). 8. $max_posts = "100"; The script will limit the number of posts that will be displayed on the guestbook file. After this number is reached, the oldest post is removed when a new one is posted. Set this to -1 to have no limit, or to 0 (zero) to turn posting off. 9. $head_bg = "#6699FF"; VisitorBook prints the output of the guestbook as one big table. You can specify the color you would like as the background of the 'header' of each entry -- this is where it says From, Date, and the user's web site. Setting a color here better distinguishes it from the comments and other entries. By default, it is is a light blue color. 10. $comments_bg = "#EEEEEE";; Here, you can specify a background color for the comments section of each guestbook entry. By default, it is is a light gray color. 11. $newest = "top"; Set this variable to "top" if you want new entries to appear at the top of the VisitorBook. Otherwise, set this value to "bottom". 12. $mailuser = 0; Would you like to e-mail the user after he or she posts to the VisitorBook? Set this to 1 (* no quotes *) to do this. Otherwise, set this to 0. 13. $thankstxt = "mailthanks.txt"; Path to the text file that contains the thank-you message that will be sent to the user. The contents of this file are merely put in to an e-mail message. 14. $mailadmin = 0; Set this to 1 if you want to e-mail you (or whoever is specified in the next variable) every time a new entry is posted. 15. $adminaddr = "feedback\@FreeScripts.com"; This is the address that messages are sent to if the $mailadmin variable is set to 1. 16. $blockhtml = 1; Set this to 1 if you want to disallow HTML tags in the VisitorBook. Note that this does not hide the HTML tags. It merely prevents them from being activited. So, if someone wrote HI!! in the comments field, the VisitorBook would show the comments exactly like that (without making the text bold). 17. $showip = 1; Setting this variable to 1 will print the user's IP address after his or her name in the VisitorBook. Setting this to 0 (zero) will not display any IP address in the visitorbook. Note that this information is always recorded in the database file. ---------------------------------------------------- --> Section 2.3: Modify the 'form.html' File ---------------------------------------------------- Be sure to modify the form.html file. The
tag needs to point to the visitorbook.pl file on your server in order for you to post. ---------------------------------------------------- --> Section 2.4: Getting it Online ---------------------------------------------------- By this point, all you should have had to edit to get VisitorBook running has been edited. The next step -- if you haven't done so already -- is uploading the files to your web directory. Fetch 3.0 for the Macintosh and WSFTP for Windows are two among many great programs with which you can upload the files. The following is the suggested layout for where you should put the files. /user/mike/htdocs/vbook (http://domain.xyz/vbook) -> book.html (just an empty file - the script will fill it up) -> form.html (you can name this anything...) /user/mike/htdocs/vbook/vb-files (http://domain.xyz/vbook/vb-files) -> gb-top.html -> gb-bottom.html -> book.db (just an empty file - the script will fill it up) /user/mike/cgi-bin (http://domain.xyz/cgi-bin) -> visitorbook.pl After you upload the files, be sure the paths match the ones you set in the variables. With a setup similar to this, you would sign the form at... http://domain.xyz/vbook/form.html ...you would view the VisitorBook at... http://domain.xyz/vbook/book.html ...and you would refresh the book at... http://domain.xyz/cgi-bin/visitorbook.pl?refresh ---------------------------------------------------- --> Section 2.5: Setting Permissions ---------------------------------------------------- Now that the files have been uploaded to your site, you need to tell the server to allow the files to do certain things. Some of the files need to be assigned special permissions. * For Telnet Accounts To set the permissions for the files using a telnet/shell account, type the following. chmod 777 /path/to/book.html chmod 777 /path/to/book.db chmod 755 /path/to/visitorbook.pl * Using an FTP Client There are two ways to do this, depending on your computer platform. On a Macintosh, we use Fetch 3.0. Find the book.html file, and click once on it. Go to the "Directory" menu, and select "Set Permissions..." Select all of the boxes, and click OK. Repeat this process for the book.db file. Then, do the same for the visitorbook.pl file, selecting all the checkboxes EXCEPT the bottom two in the second column. On a Windows machine, we are told the best way to do it is using WS FTP. Go to the directory that contains the book.html file. Right click with your mouse, and select "Site" from the window that pops up. Then, type "chmod 777 book.html". Repeat this process for the book.db file. Do the same for the visitorbook.pl file, except type "chmod 777 visitorbook.pl" ***************************************************************** ---------------------------------------------------- --> Section 3.1: Testing It Out ---------------------------------------------------- Now that you should have done everything, the script should be working. Try posting a message. If it doesn't work... ---------------------------------------------------- --> Section 3.2: A Note on ".CGI", ".SHTML", etc... ---------------------------------------------------- Sometimes, FreeScripts names HTML files with an ending of .shtml. This is basically a file that can use server side includes, but is otherwise a normal HTML file. Note that, in VisitorBook, .shtml or .html makes no difference. Some scripts, like BannerWheel, require server-side includes, and thus require .shtml endings. VisitorBook does not. Whatever you name the book html file, just be to set the $main_book variable accordingly. Also, sometimes we name our scripts with an ending of .cgi instead of the normal .pl. The reason for this is that it lets us run the CGI outside of the cgi-bin directory. Your host may be a bit different, so you may not be able to run CGIs outside of the cgi-bin directory. You shouldn't have a problem if you name the script visitorbook.pl and plop it in the cgi-bin directory. ---------------------------------------------------- --> Section 3.3: Getting Help, etc... ---------------------------------------------------- If your first attempt at setting up VisitorBook doesn't work, don't despair. There are many areas where only a simple mistake can make the script choke. Re-Read all the instructions, and make sure you understand what you are doing. If you aren't, ask your site administrator (or ISP tech support). They will be the fastest and most reliable source for information on what is going wrong -- plus, you're probably paying them for it already. If your are getting server errors or the script won't run, ASK YOUR TECH SUPPORT before you ask us! Most problems that people send us are ones that we cannot answer without knowledge of your server. Your Tech Support would best be able to do this. If you've tried re-reading the documentation and asking your ISP, ask us. We can't guarantee the fastest support, but if there is something that you ask us that we know the answer to, we will probably help you out. You should probably visit before you e-mail us. We have resources available that might just solve your problem. ---------------------------------------------------- --> Section 3.4: Change History ---------------------------------------------------- => Version 1.1.1 - 01/03/00 <= Bugs Fixed * Fixed Y2K glitch with date printing as 100 instead of 00. => Version 1.1.0 - 06/27/98 <= Bugs Fixed * Added file-locking. This prevents books from being erased. [Thanks to Alp for the suggestion.] * Added more URL detecting compatibility. Glitches Fixed * Some useless code removed from the script. * Fixed documentation ambiguities. * Added more comments to code. New Features * Optional HTML blocking with the $blockhtml variable. * Optional mail to admin on new posting with $mailadmin variable. * Optional thank-you message to poster after post. * Optional display of user's IP Address. => Version 1.0.1 - 01/31/98 <= Bugs Fixed * Users are now redirected to the proper page (whoops!) * Fixed problem where the form would only return a blank page. Glitches Fixed * VisitorBook table now displayed in better format * Some changes to the README that aren't very important. New Features * You can specify whether to add entries to the top or bottom. * Required fields can be made optional. => Version 1.0.0 - 01/19/98 <= First public release ---------------------------------------------------- --> End of VisitorBook README ---------------------------------------------------- ***************************************************************** * Disclaimer * * * * This script is free for commercial and non-commercial use. * * You are permitted to modify the script, so long as all * * copyright notices remain intact. * * * * Redistribution of this script, in whole or part, is not * * permitted without the written permission of the author and * * FreeScripts. E-Mail license@FreeScripts.com for more info. * * * * Neither FreeScripts nor the author shall be held responsible * * for sequential and/or consequential damage resulting from the * * use of this product. Use at your own risk. No warranty. * *****************************************************************