Comment-Guestbook Documentation

Thank you for trying out my little script. This project was born when I was looking for something in between a guestbook and a shoutbox, and couldn't find one quite like I wanted. The original version was hard-coded to my site, and administration was done through phpMyAdmin. One day, someone asked if they could borrow my script, and many hours later I came up with this version. This can be used on any site that has PHP and a MySQL database of any recent versions.

Easy to install - modify a few configuration variables, upload to your server, and run the supplied installer script
Displays country flag of the poster, flag display can be easily turned on or off
MouseOver a comment to display the time/date/ip of the posting
Bad word filter, user modifiable
Flexible implementation - can run in an iframe, or as it's own page, or in a new window. Easily modifiable CSS
Easy to implement multiple instances of the script, allowing 'topic-specific' comment areas for different pages on your site
All functionality is contained in only 2 script files
Administration Panel - easily modify or delete posts. If you have multiple guestbooks, all of them will use the single administration script

Download the zipped package name 'commentsv12-dist.zip' and extract its contents (you might have done that already). You should have folder named 'commentsv12' containing:

readme.txt - a readme telling you to read the readme contained in the main file
comments.php - the main script file
commadmin.php - an administration module that allows simple editing and deleting of posts
comminstall.php - An installer that creates the table needed to run your script

In the docs folder - No need to upload this to your server:

docs.html - The documentation that you are reading right now.
a few gif images used by this documentation

Before uploading the files to your server you need to modify some values in the main script, 'comments.php'. They are contained in a section labelled **SET THE VARIABLES BELOW** . The following instructions are repeated within the script file itself. It is clearly marked in the script when you should stop editing. You will need to use a text editor like Notepad, or similar. Don't use a word processor, as it will introduce formatting codes into the script that will make it not function. Here's the information you need to supply:

The first 4 items are database connection details:

$dbserver - the name of your database server. 'localhost' is a common value for many webhosts, but some use named servers, so put that value here. Ask your webhost if you don't know.
$dbuser - the user name for your database. Ask your webhost if you don't know.
$dbpassword - the password for your database. Ask your webhost if you don't know.
$dbname - the database available to you, must exist already. Check with your web host if you don't know what this is.

The next 2 items are specific to your running of this comment script. It's kind of important to understand the relationship between these 2 items, which becomes clearer if you read this entire document:

$admin_name - this is your administrator PASSWORD for this script ONLY - It is not related to your database or webserver passwords and SHOULD be set to something completely unrelated to any other passwords you use - keep this PRIVATE. You will post comments to your guestbook using this name, and also use this to access the administration window (see Administration below).

That said, as an example, if your name is Bob, you might set your $admin_name to 'Bob_xyz' (or whatever), then....

$display_name - Set this to 'Bob' in this example. When you, as admin, post a comment, use the admin_name you created above, 'Bob_xyz', it will display in the comments as 'Bob', and have a distinguishing highlight. Other posters will be unable to use the name 'Bob' to post.

This next item sets the table name that will be created when you run the installer script. Comments posted to your guestbook will be saved in this database table:

$tablename - default is 'comments', change to whatever you like if you need to. It might make your life simpler if the tablename was the same as the script name, especially if you plan to implement multiple copies, ie, script name 'comments2.php', tablename 'comments2'. If you have a table named 'comments' in your database used by by some other script, you must change this name. The installer will not overwrite an existing table of the same name, but it will warn you that one exists.

That is the end of required edits. The last item is optional. To change the display of flags on or off:

$flags - set to 1 to turn on, 0 (zero) to turn off

No further edits are needed for your script to run. If you want to modify the CSS styles or the bad word filter, you can move on further down the script, taking care to not disrupt any of the other coding.

You can save the script with the default name 'comments.php', or rename it to anything you like (must end with .php). The installer will ask you for the new name. DO NOT rename or modify the administration script, 'commadmin.php', or the installer, 'comminstall.php'.

Upload these files to your webserver:

comments.php (or your renamed copy of it)
commadmin.php
comminstall.php

They need to be in the same directory, but can be in a sub-directory. Then you use your web browser to open the installer script, eg:

http://www.yourwebsite.com/comments/comminstall.php

Enter the name of the script if you have renamed it, and press 'Create Table'. If you have entered all the information correctly, a table will be created and you will go to a success screen where you can visit and test your new guestbook directly. If there is a problem, there will be some suggestions as to how to correct them.

It's probably a good idea to remove the installer script from your server. If you need to install additional guestbooks at a later date, you can upload it again. While on the topic of multiple guestbooks, if it requires further explanation, here's an overview:

Configure you first script with all the required variables. The only things that will change for additional scripts will be the script name and $tablename in the variables section. So, for example, if want 3 comment areas:

start with comments1.php with $tablename set to comments1
save comments1.php as comments2.php, change $tablename to comments2
save comments2.php as comments3.php, change $tablename to comments3
upload the three 3 comment scripts, the installer, and one unmodified commadmin.php to your server. Open the installer, eg. http://www.yoursite.net/comments/comminstall.php
first run of the installer, change the script name to comments1.php, click Create Table, press the back button to get back to the first installer screen (if successful, otherwise, you have a problem with your configuration values)
second run of the installer, change script name to comments2.php, Create Table, go back again
third run of the installer, change name to comments3.php, Create Table, done - you now have 3 database tables , each responsible for its respective comment script.
you only need one administration script, commadmin.php, but it must be in the same directory as the 3 comment scripts

The simplest method of showing the guestbook on your site is with an iframe. On the page you wish to show it, insert this HTML code:

This would display your guestbook as you see it illustrated in this document. You can freely modify these values, google for more information on iframe. You could also have it open in it's own window:

<a href="comments.php" target="_blank">Open My Guest Book!</a>

In fact this method is useful if just for your own purposes in seeing how the script works at different widths - you will find that it currently doesn't work too well in narrower displays with out some hacking of the input areas. If you want it to run on it's own page, you probably want to modify the 'body' section of the CSS to control the margins and width. See CSS customization section below.

Some of these areas might seem to be self explanatory, but here's a few notes:

Name Input - This is where a poster would enter their name (duh). Not so obvious is that if you, the site owner, post a comment, you will enter your $admin_name defined in the configuration setup. Your name will display as your $display_name. In the example above, the site owners $admin_name is 'admin' , her $display_name is 'Administrator'. No other poster can enter 'Administrator' as a name - they will be prompted to use another name in the Status Bar.
Comment Input - Enter a comment here. Entry is limited to 250 characters. Any characters can be entered, they will stripped of HTML or otherwise illegal SQL or PHP commands before insertion in the database - in other words, weblinks, formatting, or code will not be active and will display 'as is'. A limited form of tagging is in the works for the next version.
Text Counter - As a comment is entered, this will dynamically count down to the maximum 250 character limit.
Submit - Sends the comment. As noted next in Status Bar, checks are made for blank or invalid entries.
Status Bar - Displays useful messages for both your visitors and you:

This status will be displayed when a visitor first enters your site, or attempts to send with a blank name or comment, or simply presses the send button, or attempts to use the 'admin' comment when they are not the administrator (no comment will be entered):

Enter your name and a comment. Thanks!

This status will be displayed if a visitor attempts to enter a comment with a name matching $display_name (your name) :

The name you used is reserved by the site owner. Please use another name.

This status is displayed when you enter your $admin_name (your administrator password) and the word 'admin' in the comment box (without quote marks) and you press SEND. This is your gateway to the administration panel:

Click Here To Open The Admin Window

This status will be displayed after you or a visitor post a valid comment:

Your comment has been added, (poster name). Thank You!

Comments - All posted comments are displayed here, most recent first. Bad words are filtered and replaced, in this example with 'xxxxxx', you can change that in the script if you wish. Your $display_name is shown in red, with no flag, visitors in blue. Flag display can be turned off in the initial configuration described above.
Scrollbars - Note that no scrollbars appear in your initial installation, and won't until there are enough entries to fill the window. They are customizable in the CSS section, but CSS scrollbars only have effect in Internet Explorer. They will display as standard scrollbars in other browsers.

Your gateway to the administration panel is to enter your administration password as a name, enter the word 'admin' in the comment box (without quotes), and press SEND. The Status Bar will display a link:

Click Here To Open The Admin Window

Security Note - the script has been engineered so that you (or any user) cannot directly open the commadmin.php script; it must be opened from the status bar link. (during a browser session, if you have previously accessed the admin panel through the status bar link, you may find that you can in fact access commadmin.php directly, but it probably won't function correctly. If you quit your browser then try again to access commadmin.php directly, you should see a 'You are not authorized...' message)

Clicking this link will open the Administration Window as a popup:

Click the X symbol to delete a comment. A javascript alert box will ask for confirmation. If you press OK, the comment will be forever deleted and the list will refresh.
If you have deleted or edited any comments, clicking 'Close Window and Refresh List' will close the admin panel and refresh the guestbook listing in your browser. (most browsers will warn you that you are resending POST data, just OK the message)
Click the • symbol to edit a comment. This screen will appear:

Edit the comment as desired, click 'Save Changes' to save the changes and return to the previous screen, or, to abort your changes, press your browsers 'back' button or close the window.

The image below points to the relevant CSS sections you might like to modify in the script, and represents the way your script will look on initial installation. After fairly extensive testing on several browser/platform combinations the 'stock' CSS setup displays quite consistently (it looks quite awful on some older browsers, but my care factor is zero for outdated browsers). There are plenty of good resources on the web for help on CSS if it's new to you:

CSS Notes:

I deliberately chose to use an internal style sheet, to minimize file management. If you are experienced with CSS and are using multiple guestbooks, I don't have to explain how to remove the style sheet and link it externally.
If you want to run the guestbook in it's own page, you might want to look at the 'body' section for setting width and margins
The horizontal line between the comments is simply the margin between comment tables (each comment is in it's own table). Thus, the line will be the color of the body background. To control it's thickness, change the top or bottom margins in the 'table' CSS.
The input area is pretty fragile. Forms don't like to be inline with no margins it seems. To rearrange the order of the fields, you will have to find the form element in the script and fool around, as inline styles were the only way I could find to achieve this effect. Modify carefully. This is the area most likely to go screwy across browsers (ie might look fine in IE but whacked in Opera)
The scrollbar CSS is valid only in Internet Explorer, other browsers use there own scrollbars
The colors of the poster names in the comments are inline in the php functions that display the comments, you'll have to dig to find those and be careful to not disrupt the surrounding code.
A wordwrap function is in the script limiting a single word to 40 characters before breaking. This prevents the comment tables from mucking up in CSS layouts where veryveryvery long words stretch a table beyond it's intended bounds.

Here's an example of a simple 5 minute hack, just playing with colors, fonts, and turning flags off:

I'm just a regular guy with a job and other obligations, so I don't have a lot of time to help you with this if you have problems and you haven't already done some homework. Please don't ask me questions like 'how do I set up a database', or 'how do I upload the files', or you used a word processor for editing php files, or you didn't read the readme. Otherwise, feel free to write bryhal@rogers.com.