PBL GuestBook v 1.32 Read Me ================================ Written by Lev <email@example.com> Written & Released: December 15th 2004 (last revised Jun 05 2006) ----------> GO TO WWW.PIXELATEDBYLEV.COM :) Fully functional guestbook loaded with tons of features and packed for premium optimization and performance! * Web-based administration control panel * Prevent double-posting or post-hammering! * Allow or disallow HTML * Enable a notification email to receive a notice when you get a new post * Allow visitors to rate your site * Emoticon support * Show or log the visitors IP * 5 customizable questions * Choose the number of posts per page to be displayed * Template support; totally control the theme and appearance of the guestbook! * Control the width, font face, sizes, colors and nearly every element of the guestbook! INSTALLATION GUIDE 1) Requirements 2) Customizing the script 3) Uploading / Permissions 4) Installation 5) Admin / User Guide a. Appearance & Main Settings b. Customized Questions c. Image URLs d. Show / Disable IP e. Allow / Disable HTML f. Rate Site Function g. Prevent Post Hammering / Double-Posting h. Enable Email Notification i. Enable Emoticons j. Require Approve Before Public Addition k. Image Code Function / Prevent Spam! l. Creating A Backup m. Restoring A Backup n. Private Posts o. Revert (Re-Install) 6) History / Help / Troubleshooting 1)===========REQUIREMENTS========== php 4 or > acess, a mySQL database, access to the email server on your host (only if using the email notification function) 2)===========CUSTOMIZING THE SCRIPT========== *REQUIRED* There are four mySQL parameters you MUST configure properly! These appear on lines 7-10. On line 7 is the variable $GLOBALS[sqlhost]; inside the quotes you should enter the name of your mySQL hostname. Generally "localhost" is the correct value for this variable and it probably does not even need to be changed. On line 8 the variable $GLOBALS[sqluser] represents the mySQL username you have with your hosting company. You must change "username" to whatever your username is. If you are unsure, simply ask your hosting company. On line 9 is the variable $GLOBALS[sqlpass]; simply change the value "password" to the value of your password for the mySQL database. You also will need to change the variable $GLOBALS[sqldbnm] on line 10 to the name of the database you are provided with. Again, if you are unsure on any of your mySQL information just contact your system administrator. They get paid to help you! Odds are, if you pay for hosting you get at least one mySQL database. If you have more than one, just choose the one you want the database tables to be created in. This program creates two tables (pblguestbook_config & pblguestbook_posts); you do not need to create these. *OPTIONAL* On line 2 the variable $language must be set to a valid language for this program and the language pack must be present or the script will fail to function. Fortunately this script comes with at least the English language pack. If you wish to run this script in English you do not need to do anything. The value "en" represents English. Whatever language abbreviation you use, must be used with an accompanying language pack. In other words, if you change the language of the script to Swedish (sv), then you must have the language pack pblguestbook_language_se.php installed on the server in the same directory as the english pack and pblguestbook.php scipt. For language packs and valid abbreviation codes go to www.pixelatedbylev.com/downloads.php! *OPTIONAL* Line 3 represents the template file to be used with every page of the script. I tend to provide most of my programs with template support, because I remember when I had to use programs other people were making I always wished I had more control over how the scripts are displayed with my site. Using templates allows you to take total control over the design and appearance of the program. Basically templates work like this. The template file is opened and the data is grabbed. Then this program looks for $data and $title to appear in the template file. Whenever the script finds $data in the template it places the guestbook data in place of it and wherever it finds $title in the template it places the title given by the script. So in other words, you can create a totally unique and personalized design, save it and call it whatever you want (mytemplate.htm for example). Then change the value of $template to "mytemplate.htm" (obviously replace that with whatever you named the template you want the script to use). Assuming your template file is valid and contains the string of text $data and $title then the guestbook will function fine. You do not need to use your own template and may use the default template which comes with the program, but to change the background color (or image) and essential design of the book you should make your own. *OPTIONAL* If for some reason you should rename the maing script (pblguestbook.php) then you need to change the variable on line 4; $thisprogram. Simply write the correct filename of the script itself. 3)==========UPLOADING / PERMISSIONS========== This package should contain at least the following: agreement.txt font_readme.txt readme.txt pblguestbook.php pblguestbook_language_en.php imgcode.php imgcodebg.gif but_del.gif but_email.gif but_home.gif but_ip.gif frown.gif grin.gif smile.gif tongue.gif wink.gif actionj.ttf If for some reason or another you do not have one or more of these files then visit www.pixelatedbylev.com/downloads.php! Upload or move all of these files to your server in the same directory. For the sake of this example I will use www.pixelatedbylev.com/ (home dir) as my directory. Once I have moved all the files in this directory I need to make sure the permissions are set properly. You need to make sure that the folder that these scripts reside in is writable because the script creates a backup file which is stored in the same directory. For a server to create files on the fly, it is necessary that directory has writing permission. Generally on Windows servers you do not need to change anything. UNIX/LINUX servers usually require CHMOD 777. Usually php scripts do not need to be granted with permission, but if your server refuses to process them then CHMOD both .php files to 755. To CHMOD a file or directory you usually can right click on a file or directory and "CHMOD" is usually listed on most FTP clients as an option. Check with your system administrator for proper CHMOD permissions if you are having trouble getting the script to work. The .gif images do not necessarily need to be stored in the same directory as the other files, but for a default installation it is recommended, since the script automatically installs itself setting the image variables to be in the same directory as the script itself. Each of these images may be replaced with an image of your own if you desire. It is wise to create images approximately the same size to keep the functionality of the book consistent. You also can set the path/URL of each image separately in the admin control panel. As of version 1.1 you also are required to upload the imgcode.php library into the same directory as the pblguestbook.php script. The font file actionj.ttf should also be placed in the same directory (for a default installation). You are more than welcome to store the font in another directory; simply change the path/location to it in the admin panel. ***NOTICE ABOUT THE FONT FILE THAT CAME INCLUDED*** The "actionj.ttf" font is included because the image code function of 1.1 requires a font file to be used when displaying the text of the image. Instead of forcing you to bug your system administrator in finding out the path to the server's font folder, you simply can place the font (ending with .ttf) of your choice in place of the packaged TTF font. You can change the font in the admin panel as you desire. Consult the "font_readme.txt" for credit and information on the creator of this font! 4)==========INSTALLATION========== Installing the script couldn't be any easier. You do not need to go through a long process to actually get the guestbook setup and installed. Simply enter the URL of the pblguestbook.php script in your web browser. For example: www.pixelatedbylev.com/pblguestbook.php Assuming you entered the correct URL of your script and assuming it is given the proper permissions it will automatically redirect you to the installation routine. As soon as the screen loads up your guestbook is setup! You do not need to create any tables in the database or enter any values into any tables. The script's installation creates the tables needed and creates the default configuration data as well. Your default password will be set to "pbl". As soon as you login you should change this! That's all there is to installing the script; you're now ready to begin customizing the configuration to your taste! 5)==========ADMIN / USER GUIDE========== To view your guestbook use the following URL format: http://www.pixelatedbylev.com/pblguestbook.php?action=view To sign your guestbook use the following URL format: http://www.pixelatedbylev.com/pblguestbook.php?action=sign To access the admin control panel: http://www.pixelatedbylev.com/pblguestbook.php?action=admin To access a page containing your choice of pages and to view the average rating of your site: http://www.pixelatedbylev.com/pblguestbook.php a. Appearance & Main Settings Obviously you will want to give your guestbook some sort of name. You can call it "My Guestbook" or whatever you want. Simply change the field "title of book" to your guestbook title. It might also be important to set the timezone server offset. This might sound confusing here, but listen up and it will make things much nicer for you. The time stamps that are recorded in the database are based on the server clock. Often times you do not live in the same timezone as the server so the times might not be displayed accurately to your local time. To correct this you can enter a number between -24 and 24. Just play with the hour difference until you get the date to display in your proper timezone. Be sure to write "-24" for negative numbers; but don't write a + for positive numbers. This value simply corrects the timezone to make it local to your time. It might take a minute to find out what value is correct for your setting, though! You should also make sure to change your password. Your password must be entered correctly twice to be changed. Passwords are case sensitive! You can also control your guestbooks FONT SIZE by using the similar named field. This is on a scale of 1-7 (HTML sizes). 1 is the smallest font size. 7 is the largest. 3 is average. I choose 2 as the default size for the guestbook merely because I think it suits the script the most. Some font sizes may be increased or decreased based on the importance of the text. The number you choose will be the standard size, but certain blocks of text may appear larger or smaller based on their significance. The font face (style) may also be changed. Keep in mind setting a font a user doesn't have won't work! If you would like to set alternatives use the standard HTML method (Verdana,Anarchy). In this case if the Anarchy font isn't found on the user's computer Verdana is used instead. You can also set the font color. You can also choose the color of any links in the guestbook data. This color does not affect any links you might have on your template; it only affects those links created by this guestbook. !!!!!IMPORTANT NOTICE ABOUT COLORS!!!!! There are several different elements of the guestbook in which you can choose the colors for. When choosing the color for any of these fields you may write common color names (red,orange,blue) or hexadecimil values (#FF0000). RGB values are not valid. !!!!!IMPORTANT NOTICE ABOUT COLORS!!!!! Don't like the thin line that is the table's border? You are free to set it's thickness in pixels to your liking. The width of the guestbook data can be set in the field called "width". This value can be a pixel value (ie: 650) or a percentage (ie: 50%) You may also choose how many posts per page you would like to be displayed when viewing the guestbook. If you set this to 10 and your book has 15 posts in it, a link will appear to bring you to the next page of posts. b. Customized Questions This book provides you with the opportunity to create up to five of your own custom questions you would like to ask visitors when signing your guestbook. You could ask "how old are you?" or "What is your favorite movie?" or whatever you want. These custom questions are not required but are there if you would like to use them and make your book more personal. You may change them at anytime; the answers for people who answered questions you no longer ask will still display the old asked question so there isn't any confusion. c. Image URLs If you are storing the gifs that came with this program in a directory other than the main script then you need to change the URL to these images using the appropriate fields. You can create and use your own graphics and then change the URL to them if desired. d. Show / Disable IP If you would like the IP address of every visitor who signs your book to be displayed with their post then change this option to 1. 0 is off; 1 is on. You may change this whenever you want as the visitor's IP is always being logged, whether it id displayed or not. e. Allow / Disable HTML Sometimes HTML can be harmful to your site. It is also not so rare that it may make your book look weird or annoying. To allow users to post HTML in your book turn this option on. 1 is on and therefor visitors can post HTML; 0 is off therefor blocking HTML. f. Rate Site Function If you would like to allow visitors to rate your site on a scale of 1-10, then you should turn this option on. It creates a selection list allowing the visitor to rate your site and displays what they rated the site with their post. To see an average rating of your site simply go to the URL of your book pblguestbook.php g. Prevent Post Hammering / Double-Posting Sometimes there is a certain annoying someone who doesn't like you and thinks it would be funny to ruin your guestbook by posting 100 messages of useless bullshit. Sometimes a visitor will accidently click the post button twice and the message could get posted twice when it was not intended. To prevent people from hammering your guestbook with posts and from double posting them you should enable this option. What it does: checks the IP address of the visitor. If it is the same IP as the IP which posted the last message in the guestbook then the post will be blocked as long as you are it has not been at least X seconds since the last post. In that statement X represents the value you choose for the "seconds to prevent hammering". The default is 60 seconds. This means that the same IP may not post a new message for 60 seconds after posting a message. If you set this value to 300 for example, this would prevent visitors from posting a new message for five minutes since they last posted a message. If you only want to prevent double-posting, then it's smarter to use a smaller value such as 10. This way it will only restrict the user from posting a new message for 10 seconds. h. Enable Email Notification If you would like to receive an email telling you everytime you get a new message in your guestbook, then enable this option. 1 is set to on; 0 is off. It is also necessary, of course, to set your email address in the provided field. i. Enable Emoticons If you want to give your guestbook a more "snazzy" feel you might want to use emoticons. These are 5 small smiley graphics which will appear when the visitor writes the correct emoticon syntax. :( = frown.gif :D = grin.gif :) = smile.gif :P = tongue.gif ;) = wink.gif To enable this function set it to 1. 0 is disabled. j. Require Approve Before Public Addition This option is disabled by default, yet can be very handy for your site if you desire to use it. Set this option to 1 to enable it, thus requiring all newly added posts to be approved by you first before they are publically listed in your guestbook. Once enabled a new link appears in the admin panel next to the "view" and "sign" links. Use this new "approve" link to view any pending posts and approve or delete them. k. Image Code Function / Prevent Spam! If you would like to eliminate the possibility of robots processing your sign guestbook form then you will want to keep the image code function enabled! This function requires that your server has compiled PHP with the GD library. Odds are your server has, but if you are wondering why it isn't working for your site, you might want to contact your system administrator and ask them to enable the GD library. It's a popular graphics library that allows PHP to create images on the fly. The image code functions requires it to work! Everything you need to get the image function to work came with the package and should enable itself by default to the standard settings. The If you would like to use another font than the font that came in the package, simply upload it to your server, and change the path to it in your admin panel under the field for the "image code font face". When entering the font size of the image code keep in mind that this size should be in PIXELS; it should NOT be an HTML size like 1-7. Well, you can enter a size between 1 and 7 but it will show up quite small and probably unreadable. A good size is generally between 20-40. The font color of the image code and background color of the image code may also be set using a hex value. Hex color values are such as "000000", "#FF0000", "00C08B" and so on. If you would like your image code to use a another image file as the background of the code itself, enter the path to the image to be used as a background in the appopritate field. DO NOT ENTER A PATH IF YOU DO NOT WANT TO USE A BACKGROUND BECAUSE THE IMAGE WILL NOT DISPLAY! If the path to the background image exists and is not correct the image will not display properly. The path as it is set to by default should work no problem, assuming you did upload the imgcodebg.gif graphic as instructed! ;) l. Creating A Backup This (along with the restore function) are probably the most handy tools you may encounter at some point or another. These links appear in the table below the control panel table. There are two types of backups you may perform (as well as restorations). To create a backup click the link for the type of backup you would like to perform (config or posts). A "config" backup saves your configuration table in the database (this contains all your colors, settings and options). A "posts" backup saves your post table in the database (all the posts for your guestbook). When you create a backup the script is creating a text file in the same directory (this is why the directory must have write permission). The pblguestbook_backup_config.txt is created when you backup your config data. The pblguestbook_backup_posts.txt is created when you backup your posts data. These files contain mySQL commands which tell mySQL what to add in the database. m. Restoring A Backup Restoring a backup is done using the links next to the backup links. When you restore a backup (config or posts) all current data is erased and the backup is restored instead. Restoring a backup requires, of course, that you created a backup prior to restoring one. When you restore a backup, the backup file is opened and processed line by line. When restoring a config backup make sure pblguestbook_backup_config.txt exists! You may replace it with a different version of the backup if you saved multiple versions elsewhere. The likewise goes for restoring posts backups. NOTE: WHEN YOU RESTORE A CONFIG BACKUP THE PASSWORD IS SET TO THE PASSWORD ON THE BACKUP!!! n. Private Posts If the visitor chose for their post to be private you can ONLY view it when you are logged into your guestbook. Simply login as the admin first, then view the book. o. Revert (Re-Install) The revert function was just thrown in for anyone who, for some reason or another, wants a fresh start and just wants to reset the entire guestbook. This means set erase the current config data, erase every post, and re-install the guestbook to it's default state. Additionally, you may want to note that when re-installing the password is reset to "pbl"! 6)==========HISTORY / HELP / TROUBLESHOOTING========== PBL Guestbook HISTORY: Dec 19 2004 - added password page to change password, passwords now encryped (md5), language pack corrections & updates Dec 15 2004 - released Dec 24 2004 - some coding issues resolved with the installation and $action changed to _GET['action'] to insure cross-compatibility Dec 25 2004 - completely resolved issue with book not installing on certain servers; cleaned up save_config routine to make sure no warning output is sent before the redirection is called. Book should now install for everyone! Feb 22 2005 - resolves issue with assuring custom templates work; modified code to allow for php builds that lack file_get_contents function Feb 26 2005 - added image code function to prevent robot spammers; added select list to jump to page of book; corrected several bugs, updated & added items to language pack; added view / sign links in admin area Mar 11 2005 - includes updated language pack with all needed text items Jan 06 2006 - cleaned up syntax (replaced most occurances of $var[element] with $var['element']; new font packaged for compliance with the image code & GD library; font_readme.txt attached for credit on the author of the font Jan 25 2006 - added function to allow site owner to require approval of posts before they are publically listed Jan 27 2006 - made the powered by footer quite a bit smaller and got rid of obsolete CSS code giving a null color value Jun 05 2006 - updated imgcode.php to allow for non-freetype font support; should now work for *almost* all GD servers If you have any problems with the installation or use of this script you are more than welcome to contact firstname.lastname@example.org Likewise if you have ideas for improvement, suggestions, comments, complaints or concerns you are more than welcome to provide me with them. Thanks for visiting www.pixelatedbylev.com!