Guestbook Documentation v1.30  Table of Contents Introduction Terms of Use Installation Administration Main Menu Display/Edit/Delete Posts Admin Log Out Guestbook Configuration Database Manager Color/Graphic Selection Change Password Reset IP Address Log Check for Version Updates Register Program (free) Feedback Form Alternate Language Configuration Database Structure Importing Databases Known Issues About the Developer Introduction Does the Internet need yet another guestbook program? Maybe not, but after years of using "remote hosted" guestbooks and CGI/PERL scripts, I felt it was time to "roll my own" and create a guestbook with all the features I wanted. The result is HyperBook, a full-featured guestbook designed with the administrator in mind... and for peace of mind. Since not all hosting accounts which support PHP also include access to a database such as MySQL, HyperBook relies on it's own internal "Multi-file Flat Text Database." Many guestbook programs store all records (your visitor's posts) in a single flat text file, which is fine as long as you don't have many visitors. However, as the number of records grows, so does the size of the single database file, which in time could become several megabytes in size. If this file must be loaded or searched each time a page of posts is displayed, it could put a heavy load on your host's resources (known in this case as "disk banging"). HyperBook breaks this database file into many smaller files, thus reducing the need to access a single large file. By default, each file contains 25 records, or about 10-15kb of data (this setting may be changed, if necessary). Therefore, to display a page containing 10 posts, only one or two small files will need to be accessed. Not only will this make your system administrator happy, but it will improve the speed of even guestbooks with thousands of entries. However, there are some limitations to PHP and some operations (eg. deleting posts and name searches) may need to access a large number of records, which could cause a problem (see Known Issues for more details). Along with the improved efficiency of a multi-file database, I also wanted a guestbook that would be easy to maintain. In particular, I was tired of removing "double posts" (or in some cases, triple or quadruple posts). A double post is usually caused by an impatient guest pressing the submit button multiple times, resulting in the same message being posted multiple times. HyperBook compares the name and comments of each post with the post that precedes it... if they match then the second post is rejected. Sometimes a malicious visitor will intentionally try to post multiple messages, changing each one slightly to get around the double post protection. To discourage this form of attack, a log of the last 25 IP addresses is kept, and each IP address can be given a quota for how many posts they can make. The quota may be set by the Admin, two or three posts is usually sufficient. Also, the poster's IP address and Remote Host (if available) is stored in each record and can be seen by the Admin. And just for good measure, an optional "Banned Words" list may be used to screen out expletives. Another feature I wanted was e-mail notification of each new post so I wouldn't have to continuously visit the guestbook. Many guestbooks now have this feature, but I also wanted to include a link in the e-mail to take me directly to a page where the post could be edited or deleted. And just for fun, I added a "Guestbook Administrator's Comment" field to the editor so I could reply to some of the more "interesting" posts. I feel this makes the guestbook more entertaining for visitors who decide to peruse its pages. Being a professional website designer, I knew I'd be installing this guestbook on a number of sites, so set-up had to be quick and easy. PHP can usually detect important information such as the current directory path and URL, along with creating some of the initial files needed to get a guestbook up and running. The only problem area was using PHP running in "safe mode" to create new directories with the proper owner/permissions... so creating the two directories used by HyperBook must still be performed manually (which only takes about 30 seconds). After that it's just a matter of uploading a few files and running the Admin program, which detects a first time run and displays a short form to be filled out. In all, a new HyperBook can easily be set-up in under two minutes if you know what you're doing. The final goal was to make HyperBook as customizable as possible, without the end user knowing a thing about writing PHP code. The first step was allowing up to three additional questions to be added to the Sign Book form, and to allow these questions to be changed at any time. Next I wanted the Admin to be able to select colors that matched the rest of the website. In total, 10 colors may be selected along with a banner graphic and background image. There is also an option to use a custom "Sign the Guestbook" graphic, and if two graphics are used, the second will be displayed as a mouseover button... it adds a nice touch. There were a few guestbook "features" I didn't want, such as allowing visitors to use HTML in their posts. There was a time when I thought this was a fun thing to do, but after over 7,000 posts to my personal guestbook, I've changed my mind and made HyperBook strip HTML out of all posts. It's not that I mind a little formatting or an image link to a small graphic, but often it takes away from the guestbook more than it contributes. Links to graphics are often broken, which can make the pages seem slow to load. Some folks have posted rather large graphics and WAVs, which seriously slows the pages down. Yet others have been sloppy with their HTML tags, resulting in unclosed font and link definitions, or unclosed tables (anyone who uses Netscape knows that an improperly formatted table results in a blank page). If all that wasn't enough, there were people posting small Javascripts to redirect visitors to their own homepage... whether the visitor wanted to leave my site or not. To even consider allowing HTML tags, I would have to selectively remove Javascript, validate what code was allowed for proper format and periodically test for broken links. And then there is the security issue, allowing code in posts opens a small door for hackers. Remember, PHP is a program which interacts with the data being submitted, it's wise to treat "raw data" with caution and "cook" it to remove any unwanted code which could be mistakenly executed. See why I left the HTML out? So now that I've created the guestbook I've always wanted, should I keep it all to myself or share it with the Internet community? Well... I have used my share of other people's software, and since guestbooks are a dime a dozen I probably couldn't sell this one... so sure, you may run it on your website if it supports PHP. And I'd like to hear your comments and suggestions, if there is enough interest I'll continue to develop HyperBook... it was designed to be expanded (additional message display templates might be nice). But keep in mind that HyperBook is a hobby, not a commercial product. As such I can't offer much in the way of personal, free tech support, my clients' websites have to come first if I'm going to pay the Visa bill each month. I do feel it's my responsibility to check into bug reports and security glitches, so please use HyperBook's built-in Feedback form to submit reports and the Version Check to see if there has been a new release. On the other hand, please don't ask me something like how to use your FTP program to make a new directory and set the permissions, that's the responsibility of the FTP program's developers and I'm sure they explain it in that program's help files. There also may be issues that involve your host server's configuration... I'd like to hear about them but I can't promise I'll be able to fix them. HyperBook was developed and tested on a commercial community server running PHP Version 4.0.4pl1, Apache/1.3.17 and Linux.. it runs great here but, like they say, your mileage may vary. Now that you know a little about HyperBook, I hope you'll give it a try and enjoy using it as much as I've enjoyed developing it. Please read the rest of this doc file, it contains tips and explanations of some of HyperBook's inner workings. The most important documentation is contained within the pages of HyperBook's Admin section, but this doc should be read at least once (BTW, I hate writing dox, but it's a necessary part of being a lone programmer). [ Table of Contents ] Terms of Use Downloading and using HyperBook is subject to the terms of the License Agreement. If you agree to these terms then you may use HyperBook for free... gratis, no charge. Since few people ever actually read the License Agreement, I'll summarize the key points here: You are permitted to download and install HyperBook on as many servers as you wish and keep back-up copies. You are not permitted to redistribute or make HyperBook available for download. You are not permitted to sell, rent or lease HyperBook to anyone. You are not permitted to remove the program credits or copyright notice. Modifications to the program will be considered derivative works and still subject to all terms of the License Agreement. The software is provided on an "as is" basis, there is no warranty of fitness for a particular purpose. I'm not liable for your site content or the posts left in your guestbook. I'm not liable for any damages arising from the installation or any use of HyperBook. Even though you may use the program for free, I retain the copyright to it. Essentially, I'm allowing anyone to use the program for free, but I won't allow anyone to profit from my work without permission. If you want to sell guestbook software then write your own, but don't even think about charging for my program. Even if you make changes to the program and improve it, you still are not permitted to distribute a program that contains any of my code. I'd like to note that prior to developing HyperBook I was using a fairly good free CGI guestbook and could have edited the code to include the extra features I wanted. However, the developer of that script had similar terms of use, and rather than violate them, I decide to write my own program from scratch. I ask for the same consideration. With regard to modifying the HyperBook PHP code for your own use, you are welcome to do so. In fact, I encourage you to do so (the source code is commented, though not extensively). If you would like to share your modifications, then send them to me and if they are used in a future release I'll give you full credit for your work. Or keep them all to yourself... it's your choice. Just don't take away my credits and copyright if you've built upon my work. There are some good reasons why I don't want you to offer HyperBook for download from your website. First of all, the copy you offer may be out-of-date. If a future version of HyperBook contains bug or security fixes, then that is the only version that should be available. By downloading the program from my site, the user is assured of always getting the most current version. It also gives a reasonable assurance that they are getting code that hasn't been tampered with. I hope HyperBook will gain a reputation for being secure and reliable, but if a modified version with potential bugs or security flaws were to be distributed, that reputation could become tarnished. So if you would like to make HyperBook available on your site, please link directly to the download file on my site... that will be the only "official" copy of the software. [ Table of Contents ] Installation HyperBook was designed to be easy to install. It has been tested on UNIX systems running PHP Version 4.0.4pl1 and Apache. Hyperbook has also been successfully installed under Win98, Win2K and NT operating systems using Apache. Microsoft IIS has not been tested as of this writing. HyperBook is not designed to work with PHP prior to version 4.0.1. Note: HyperBook requires "register_globals" to be turned on in the php.ini file. The user should know how to upload files to their hosting account via FTP or Telnet, create new directories and set file permissions (if installing on a UNIX system). The first step is to download the hyperbook.zip file and unzip it into a directory on your computer. For security reasons you should always obtain HyperBook files and updates from diamond-back.com, this will ensure that the PHP code has not been altered in a potentially harmful manner (either intentionally or accidently by a hacker/programmer). You should have the following files: admin.php - Program that allows you to administrate your guestbook. background1.jpg - background4.jpg - Backgrounds used by the CAPTCHA feature to obscure text. background.jpg - Sample background, may be replaced with one of your own. bannedwords.txt - Short list of words you may wish to screen from your guestbook posts. colorchart.html - Small chart of 216 "browser safe" colors to assist with color selection. database_functions.php - Core database functions used by admin.php and index.php. display_template.php - Template used to display guestbook entries. documentation.html - HyperBook Administrator's instructions, the file you are reading. guestbook.jpg - Sample guestbook banner, may be replaced by one of your own. index.php - Program used by your guests to view and sign the guestbook. input_template.php - Template used to submit and edit guestbook entries. language.conf - List of words and phrases displayed to guestbook visitors. logo.jpg - The HyperBook logo. phpinfo.php - Optional program used to display the PHP configuration on your host, does not need to be uploaded. readme.txt - Brief HyperBook overview and set-up instructions. signdown.jpg - Sample "Sign the Guestbook" button in the mouseover state. signup.jpg - Sample "Sign the Guestbook" button in the normal mouse off state. verification_image.php - Script used to generate CAPTCHA images. Now that you have all the files listed above, you'll need to upload them to your hosting service (unless you are running a web server on your computer). Before you start uploading, you should be certain that your host supports PHP programs. If you're uncertain, upload the "phpinfo.php" file to your web directory and then display it in your browser. Hopefully you'll be greeted with a screen full of PHP configuration information, if instead you only see "<? phpinfo() ?>" then you may need to contact your system administrator and find out if PHP is available for your account. Alternately, you may also contact me about finding a host that supports PHP. Once you know PHP runs on your account, it's time to fire-up your favorite FTP or Telnet program and upload the HyperBook files. Upgrade Notice: If you have previously installed a version of HyperBook Guestbook lower than 1.10, only the following files need to be replaced: admin.php background1.jpg through background4.jpg database_functions.php display_template.php documentation.html index.php input_template.php language.conf (new file, needs to be chmod'ed to 777) verification_image.php Your data files will remain compatible with the current version so no posts will be lost. However, this might be a good time to back-up your data directory. Step 1 Create a new directory in your web file space (ie. where you keep your website files... this directory must be accessible from the web). You may give it any name you wish, I recommend calling it "guestbook" since it will be part of the URL used to visit your guestbook. Step 2 Set the permissions on the new directory to allow everyone to read, write and execute the files contained in it... ie. CHMOD to 777 (rwxrwxrwx). Step 3 Open the new directory and create a subdirectory called "data" and CHMOD it to 777. The name of this directory is not optional, it must be called "data" (all lower case), be inside the directory you created for your guestbook and have full permissions set. Step 4 Next upload the HyperBook files to the first directory you created (eg. "guestbook" - not the "data" directory). Files with a ".jpg" or ".gif" extension should be uploaded as binary files, all others should be uploaded as text. It's not necessary to upload the "readme.txt" file. Depending on your server's configuration, you may need to CHMOD the PHP files to be executable and the "language.conf" to be readable (CHMOD 777 will work). Step 5 Now that you have your files online, it's time to access the Admin program with your browser and complete the set-up procedure. Enter the URL to the admin.php program (eg. http://www.yourdomain.com/guestbook/admin.php) and you'll be presented with a short form to fill out with the necessary information to get your guestbook up and running. Each field has a short description of the information required, some fields even have the info filled-in if PHP was able to determine where your files are located. Make certain the information is correct and that all fields have been filled-in, then click the "Set-up Guestbook" button. You'll be able to update all information on this page if you change you mind later (eg. if you want to give your Guestbook a different name). Congratulations, if all went well you should see the Administrator's Main Menu and your guestbook is ready for visitors. If you see an "Enter Password" screen it probably means your browser isn't accepting cookies (which is where your password is stored so you don't have to keep entering it while navigating the admin program). If you see the Set-up screen again, then PHP was probably unable to write files to the data directory, make certain this directory is in your "guestbook" directory and the permissions have been properly set (see Step 3). You may now begin to customize the look and function of your guestbook. To link to your guestbook, use the URL to your guestbook directory (eg. http://www.yourdomain.com/guestbook/ ). If your host server doesn't recognize "index.php" as the default file, you may need to add it to the link URL (eg. http://www.yourdomain.com/guestbook/index.php ). Using this URL will display the most recent posts to your guestbook, along with a link to sign the guestbook. If you would like to have a link directly to the Sign the Guestbook form, use this URL: http://www.yourdomain.com/guestbook/index.php?action=sign The next section will walk you through each of the administration menus... try out the various functions and give your guestbook a complete test run. [ Table of Contents ] Administration Main Menu The Guestbook Administration section is where you control all aspects of your guestbook, from the questions that will be asked to the colors and graphics. It is also where you may edit, delete or add comments to guestbook entries, or import/export database files. Each function in the Admin section is fully documented so you will not have to repeatedly refer back to this file. Because most of the documentation is in the program itself, this section will only provide an overview of where the functions can be found and tips for getting the most use out of them. In addition to the links to each admin section, the Main Menu has three search boxes. The Record search will pull up the post with the corresponding record number (the first post is record number one, etc.). Note that record numbers may change if a post is deleted, with each higher numbered post being reduced by one for each deleted post. The Name search will search posts based on the name field. The search is not case sensitive and partial matches will be returned. For example, a search for "mary" will return a record with the name "Ms. MaryJane." If only one match is found, it will be displayed in the Record Editor, if more than one match is found they will be displayed in the guestbook format with links to Edit or Delete. Only the first 25 matches will be displayed, starting with the most recent post. The UID search will look for a record with the same Unique Identifier number. Each post is assigned a UID which, unlike record numbers, will never change. It is mostly used for displaying posts linked from a notification e-mail, but you may also search by this field if you know the UID of a post. [ Table of Contents ] Administration: Display/Edit/Delete Posts This section will display guestbook entries the same way they appear to your guests, except that under each post there will be links to Edit and Delete the post. Also, if an IP address was recorded for an entry, that address and the Remote Host (if found) will be displayed. This information can be useful if you receive harassing posts in your guestbook, especially the Remote Host address which often contains the name of the visitor's ISP. When all else fails, you can try sending an e-mail to "abuse" at the visitor's ISP... be sure to include the IP address(es) associated with the harassing post(s), the exact time of each post (indicate your time zone) and the nature of the harassment (such as a copy of the post). Many responsible ISPs will use this information to find out who was using their service at the time of the incidents and either warn them or terminate their account. Clicking on the Edit link will load the corresponding post into the Editor, where you may change or remove any of the information entered. You also have the option of adding a "Guestbook Administrator's Comment" which will appear in italics under the visitor's comments... a convenient way to answer questions or return a compliment (or perhaps an non-compliment, if you get my drift). Sometimes a post just has to go, and that's why there is a Delete link under each entry. Chances are it will be much easier for the Admin to click the delete button than it was for the visitor to enter the unwanted post. Before the post is sent to the bit bucket, a confirmation (Confirm/Cancel) screen will be displayed... just in case you clicked Delete by mistake. You may also follow the link to "Sign the Guestbook" from this page. When the Admin adds a post to the guestbook, all of the same rules apply regarding field lengths, stripping of HTML tags and banned words (if activated), but no IP Check is performed and a notification e-mail will not be sent. [ Table of Contents ] Administration: Admin Log Out When you log into the Admin section, your password is stored in a "cookie" file on your computer. To prevent other people who may have access to your computer from being able to use the Admin section, click on the "Admin Log Out" link which will set the password in the cookie to "null" and block further access until the correct password has been reentered at the Log-In screen. [ Table of Contents ] Administration: Guestbook Configuration This is the heart of HyperBook, where you can change the information displayed by the guestbook and how it functions. The Guestbook Name is the title of the guestbook which will be displayed unless a Guestbook Banner is specified in the "Color/Graphics Selection." The Guestbook Name will also be included in the subject of any notification e-mails if this feature ihas been activated. The Website Title is displayed in links back to the homepage. It may be entered as a short message such as "Click here to return to the homepage." The Homepage URL is used in links back to the homepage. It must be proceeded by "http://" though this will be automatically added if omitted. If no URL is specified, a link back to the homepage will not be displayed in the guestbook. The Webmaster E-mail Address is the e-mail address which will be displayed for private messages if this option is checked (see below). The Admin Program URL is used to create links in e-mail notifications and should have been correctly determined when you set-up your guestbook. If your homepage URL changes, be sure to update this setting. If the Send E-mail Notification box has been checked, notifications of new additions to the guestbook will be sent to each of the e-mail addresses entered in the E-mail Notification List. The addresses should be separated by a comma. The list can contain up to 3,000 characters, enough for hundreds of e-mail addresses. This is intended for websites administered by a group of people so everyone will be notified when a new post has been submitted. Along with the complete text of the post, a link will be given to go directly to the Editor for that post (to make changes, delete or add a comment). If you are not already logged in via a cookie, you will first be prompted to enter the admin password before dropping into the Editor. Anyone on the notification list who does not know the password will not be able to use this link. Note that notifications also display the poster's IP Address and Remote Host, which is not normally displayed to the public. Depending on where your website is hosted, the time stamp returned by the server may be different than your local time. Using the Time Zone Offset you may adjust the time displayed on guestbook posts by adding or subtracting a number of hours. For example, if you make a post at 3pm local time and it is displayed as 1pm, then enter a "2" for the offset and all subsequent posts will have the displayed time increased by two hours. Likewise, if the displayed time were 5pm, enter a "-2" to decrease the displayed time by two hours. The IP Check is used to keep a log of the IP addresses of the last 25 posts. You may use it to determine how many times someone at a particular IP address may enter posts (at least within a span of 25 posts). If this feature is set to "1" then only one post will be allowed from a particular IP address within the 25 post span. To allow for additional posts, increase this number (eg. a "3" will allow up to three posts within the last 25 logged). Entering a "0" will disable IP Logging, which will allow any number of posts to be submitted by the same IP address. It is advisable to set this number low to discourage guestbook "flooding," where one person enters many posts, usually to harass the guestbook owner. IP Logging will not completely stop someone from making multiple posts, it's possible to obtain leases on new IP addresses and then continue posting (for example, an ISP dial-up customer could disconnect and then dial-in again, most likely being assigned a different IP address). However, it should slow down an abusive guest, making it more difficult to flood a guestbook... and it should be easier for the Admin to delete the posts than it was for the guest to obtain new IP addresses (consider that to be a small victory). Note that some ISPs use cache servers which will report the IP of the server rather than the user. For this reason it is recommended that the IP Check be set to "5" or higher so that different users of the same cache server are not inadvertently blocked. Posts Per Page allows you to determine how many entries are displayed on each page. Usually ten posts is about right, though you could try as few as five or as many as 25 and decide what works best for you. Banned Words will allow you to screen words from all fields of a guestbook post. You may edit the "bannedwords.txt" file in your guestbook directory to add or remove words from the list. If found, the characters in banned words will be replaced with asterisks (*) anywhere that they appear in a post. The match is case insensitive, so banned words only need to be added once. For example, if "micro" were a banned word, then "Microsoft" (even in all caps) would be changed to "*****soft". If you wanted to ban the entire word "microsoft," then enter it on the list prior to "micro," otherwise it would be changed to "*****soft" before the check for "microsoft." By default, Banned Words is not activated, you must check the box to turn it on. CAPTCHA (Completely Automated Public Turing Test to Tell Computers and Humans Apart) is used to prevent spammers from using scripts (spambots) to post messages in the guestbook. When selected, guests will be asked to enter a five digit code which appears on a graphic before their post will be accepted. This feature requires the GD library module and the use of sessions. No URLs will prevent spammers from leaving URLs in their posts in two ways. First, the homepage/URL fields will no longer be displayed. If a URL is submitted anyway (as when an automated script submits data directly to the guestbook), the entire post will be rejected. Second, a search will be performed for "http://" in the comments and if found, again the post will be rejected. You may wish to make a note of this in the Welcome Message section so your guests will know beforehand not to attempt to include URLs in their comments. Hide E-mail Addresses when checked will prevent guests' e-mail addresses from being displayed to the public. The administrator will still see e-mail addresses when viewing posts from the Admin script. This feature is designed to allow guests to leave an address the admin may use to contact them without spammers being able to "harvest" the addresses. Password Cookie Expiration allows you to set the time before the cookie containing the Admin password saved on your computer will expire (ie. be removed). It may be set to as little as one hour or as long as one year. Note that cookies are associated with a website based on the URL, any change to the URL will render a cookie non-functional. It is strongly recommended that you not rely on cookies too much, they sometimes fail and you will need to enter your password manually at the log-in screen (at which time the cookie expiration will be reset). It's also not unheard of for a cookie to be "stolen" by some other website, which would reveal your password. You may nullify a Password Cookie at any time by clicking on the Admin Log Out link. Up to three Additional Questions may be added to your guestbook for a personal touch. Both the questions and the answers may be up to 100 characters in length. Your questions are stored along with the guest's answers in each guestbook entry, so you may change the questions as often as you wish (even daily) without interfering with the questions displayed with past answers. For example, you may ask your first hundred visitors what their favorite band is, and the next hundred what their favorite movie is... the appropriate question/answer will be displayed in all 200 entries. To temporarily remove the display of a question/answer, uncheck the Displayed box next to each additional question (and don't forget to check the box when adding questions). If a guest chooses not answer a question, that question will not be displayed in the resulting post. Found Options will be displayed in a dropdown list on the Sign Guestbook form. This was done to encourage visitors to indicate how they found your website, a topic of interest to most webmasters. You should add as many additional options to this list as you can think of and it may be updated at any time. Visitors are also given a blank field to enter a note about how they found you site, if they enter anything in this field it will be displayed in place of an option from the dropdown list. Note that if you edit a post, a choice from the dropdown list will take precedence over the "blank field" entry. Display UIN (ICQ Number) Field will display a field for ICQ users to enter their personal contact number. ICQ is a popular "instant messaging" program, many people use their ICQ number (aka UIN) in place of an e-mail address, so you have an option to display this field. If an ICQ number is entered, it will be displayed as a link to the "ICQ Personal Communication Center" page for that user. If you check the Display Webmaster's E-mail Address option box, then the Webmaster e-mail address will be displayed in a note on the Sign Guestbook page instructing visitors to send "private messages" to that address. Some guestbooks allow private messages that can only be read by the Admin to be posted, but that seems to defeat the purpose of a guestbook, which is to state opinions publicly. E-mail seems to be the more appropriate venue for private messages, and the absence of private messages in your guestbook will make it more interesting for your visitors to read. Some people really do read other people's guestbooks, especially if the website they are associated with is interesting and they all looking for other people with similar interests (or have absolutely no life of their own *g*). The Welcome Message is displayed on the Sign Guestbook page. It can be used to explain why you have a guestbook or suggest what kind of comments you are interested in receiving. This message can set the tone of your guestbook. The Thank You Message you enter will be displayed to visitors after they sign your guestbook. It's nice to receive compliments about your site, and a personal thank you message is a nice way to show your appreciation to your guests. The Header Tag HTML allows you to have a short section of code inserted at the top of each page. Some free hosting services (such as Spaceports) require you to display their ad banners on your pages, entering the banner code in this box will allow you to meet that requirement. You may enter any code you wish in this box, but use caution to insure you have closed any font, link or table tags. Your code will be inserted in the main body of the HTML document after the body tag. [ Table of Contents ] Administration: Database Manager Under normal use, you will probably never need to access the Database Manager unless you move your guestbook to a different server. However, it does provide some powerful tools for managing your database if you know what you are doing. While HyperBook does not currently have a back-up feature, the file structure has been designed to make it easy for you to back-up your database via FTP or Telnet. All files in the main guestbook directory are static (ie. never change, except when installing an updated version), all dynamic (ie. changing) files are located in the "data" directory located within the directory you created for your guestbook. To back-up your database, simply download (as text) all files located in the data directory to your local drive. To restore your database, upload all files back to the data directory and then CHMOD the files to 777 (ie. full permissions, rwxrwxrwx). The Data Directory Pathway is used by the program to find where your guestbook data is being stored on your host's server. It is not a URL, but rather a pathway, normally starting either with the root directory of you host's hard drive or your account's main directory. The "data" directory should always be located within the directory you created for your guestbook. PHP will attempt to determine this pathway based on the location of the admin.php file. If you change the name of your guestbook directory or the path to that directory changes, you'll need to update this field. The Number of Records Per File should normally be set at 25. This is the maximum number of records HyperBook expects to find in each database file. If you change this setting without also changing the number of records in each file, HyperBook will either fail to load all records (if the setting is lowered) or generate errors when the next record isn't found (if the setting is raised). Since HyperBook uses this setting to "know" how many records are in each file, it is able to determine which file contains a particular record based on that record's number (eg. if there are 25 records in each file, then the 52nd record would be in the 3rd file). This is why HyperBook's database is very efficient, for most operations it doesn't have to search through all files to find a particular record or range of records. The only reason you may wish to change this setting is to increase the number of records in each file, which will increase the size of each file but reduce the total number of files required to hold all records. To do this, first use the "Export Database" function to create a file (records.dat) which contains all the records, then clear the database, change the Number of Records Per File setting, and finally use the "Import Database" function to reload the records with the new setting. This procedure has been tested, however if you have a large database the Import Database function could time out before completing the import routine (see Known Issues for more details). For this reason you should always back-up your database prior to using any of the functions in this section. The Clear Database function will delete all files containing guestbook records and reset the number of posts to 0. This is a quick way to "reset" your guestbook if you've been adding test posts or want to start over. Since accidentally clearing your guestbook could be a disaster, you will be presented with a confirmation screen before the actual clearing takes place. The Export Database function will read each of the "multi-file flat text" database files and save all the records in a single file called "records.dat" in your data directory. The record format remains the same as described below (see Database Structure for details), but since all the records are in a single file they may be easier for you to import into another database program such as Microsoft Access or Excel. Future versions of HyperBook may also support CSV (comma separated values) or tab delimited format if there is a need for these formats. The Import Database function is essentially the reverse of the export function. It will read all records from a file called "records.dat" stored in the data directory and append them to the HyperBook database. This can be a very powerful feature for importing records from another guestbook program (see Importing Databases for more information). However, the lines of data in the record.dat file must be in the HyperBook record format (see Database Structure for details). No error checking is performed on these records, they will be imported "as is" and if they are not in the proper format you will corrupt your HyperBook database. So use this feature with extreme caution if you already have records in your HyperBook database (I recommend you back-up the database prior to importing new records). New records will be appended to your database in the order they are found in the records.dat file, so be sure the oldest entries are listed first. Make certain the records.dat file has been CHMOD'ed to allow reading prior to importing. If all goes well, a confirmation will be displayed reporting the number of new records which were imported. [ Table of Contents ] Administration: Color/Graphic Selection Your HyperBook guestbook should look like it's part of your website. One way to insure this is to configure the colors and add graphics that match your other pages. The best way to become familiar with the Color/Graphics Section is to play with it... keep trying different color combinations until you find one that works for you. Near the bottom of the page you'll find a Preview Box to give you an idea of how the current colors will look. You may also open your guestbook in another browser window and reload/refresh the screen after each color change for an instant "real world" preview. Note that the guestbook is displayed inside a table with a width of 600 pixels. This was done so sites which use frames should be able to display the guestbook within a frame if so desired. Future versions of HyperBook may include separate "header" and "footer" files to further customize the size and look of the guestbook pages. The Guestbook Banner URL is a link to the graphic you wish to display at the top of the pages where posts are displayed. HyperBook comes with a sample banner graphic called "guestbook.jpg"... you are welcome to replace this graphic with one of your own design. If you upload the new graphic into the guestbook directory, you will only need to enter the name of the graphic. If it is located outside the guestbook directory, use a "fully qualified" URL (eg. http://www.somedomain.com/graphicsfolder/bannergraphic.gif). If no graphic is supplied (ie. you leave the Guestbook Banner URL field blank), the name of your guestbook will be displayed inside a table in place of the graphic. Since the width if the guestbook table is 600 pixels, it is recommended that your banner graphic not exceed this width. The Sign Guestbook Button URL is a link to a graphic which will appear on each display page as a link to the Sign Guestbook page. If no graphic is supplied, a text link will be displayed in it's place. The same rules that apply to the Guestbook Banner URL also apply here. The Sign Guestbook Button URL 2 (Mouseover) is a special feature of HyperBook. If both this and a Sign Guestbook Button URL (above) are supplied, they will be used together with a short Javascript to create a mouseover button effect. The first button graphic will be displayed until the mouse pointer passes over it, at which time the second button graphic will be displayed in its place. This can be used to make a button appear to light-up or be pressed into the page when the mouse pointer passes over it. It is recommended that both graphics have exactly the same dimensions (height and width) and have fairly small file sizes (a few kilobytes each). If a visitor to your page has Javascript disabled on their browser, only the first graphic will be displayed, but the link will still work. You may also supply a Guestbook Background Image URL similar to the banner and sign buttons. This graphic will generally appear as the background outside the tables displayed by the guestbook, however, if you don't supply color codes for the tables (see below), some browsers will display the background graphic inside these tables. Experiment and see what looks best, but be advised that you should look at the results with both Netscape and Internet Explorer because there may be differences in the way they display your pages. The Color Selection boxes is where you enter the color codes for the various areas and text that your guestbook will display. Use the Preview Box as a guide to which colors will be changed. Under the Preview Box you'll find a link to the Pop-up Color Chart which contains the hex codes for the 216 "browser safe" colors. You may use these to help select colors for your guestbook, though you are not limited to these 216 colors. Most of today's graphics cards can display thousands, if not millions, of colors, however older computers may not be able to handle the "non-safe" colors which could produce strange (usually ugly) results. It's up to you whether to use a "safe" color or pick one of the millions in between. Tip: if you double click on a color code in the chart, it will select/highlight that color. You may then copy (control-c) and paste (control-v) it into a color selection input box. [ Table of Contents ] Administration: Change Password You may change the Admin password any time you are logged into the Admin section. Your password must be at least 6 characters long (the maximum lenght is 20 characters). Passwords are case sensitive ("MyPassword" is different from "mypassword") and may contain both letters and numbers. It's advisible to use a combination of letters and numbers to make a password difficult to guess. It goes without saying that you should either write your password down or be sure to choose one you can remember. HyperBook saves your password in an encrypted format, it would be very difficult to recover. There are no "back doors" to get into HyperBook, the best you could do is comment out the password check lines in the admin.php source code, use the modified copy to get into the Admin section, set a new password and then restore the unmodified version. [ Table of Contents ] Administration: Reset IP Address Log The IP Log is used to record the IP Address of the last 25 visitors who posted in your guestbook. By logging these IPs, you may use the IP Check feature on the Guestbook Configuration page to put a quota on how many times someone may post in your guestbook (at least within a span of 25 posts). There may be times when you would like to clear the log, which is what this feature will do. [ Table of Contents ] Administration: Check for Version Updates The Version Update page loads a small graphic from Diamond-Back.com based on the version of HyperBook you are currently using. If you have the most current version, you will see a green "No Update Required" graphic. If a routine update has been released with new features, an orange "Update Available" graphic is displayed. If a bug fix or security glitch has been corrected, a red "Update Recommended" message will be displayed. When updates are available, you may click on the link displayed at the bottom of the page for more information and download instructions. Every effort will be made to design updates to be easy to install and without losing any of your existing guestbook posts. [ Table of Contents ] Administration: Register Program (free) In addition to using the Check for Version Updates page, you are invited to register your HyperBook guestbook so critical update messages may be e-mailed to you as soon as they become available. You may also have you website linked from the HyperBook page as a user of the program if you wish. There is no fee for registering HyperBook and your information will be kept strictly confidential. Only e-mails regarding HyperBook will be sent to the e-mail address you submit. Hopefully there will never be a critical update needed, but if there ever is, you'll want to know about it ASAP. Along with your form data, the registration e-mail will also send your HyperBook version number and server software version numbers (from the Apache "SERVER_SOFTWARE" Environment Variable, if present). This information is used so we can determine which version your are using and track the servers under which HyperBook has been successfully installed. Note: If you change your e-mail or website address, please resubmit your new information and indicate the previous URL/e-mail so our records may be updated. [ Table of Contents ] Administration: Feedback Form The Feedback Form is used for submitting bug reports and suggestions for future upgrades. Your general comments regarding HyperBook are also welcome, I would like to know what you find most useful with the program or what you don't like about it. Depending on my workload (which is usually pretty heavy), I may not be able to respond to every message, but I will read them and check into all bug reports. In particular I can't promise to respond to all tech support requests, but will do my best to answer questions pertinent to HyperBook. If you have a question regarding other software products (eg. "How do I upload files with WS_FTP?"), your host's server (eg. "What version of PHP do I have?") or PHP programming (eg. "What does eregi_replace do?") I would suggest checking the product's help file, asking your server admin, reading the PHP docs or joining a PHP developer's list. If your question is about HyperBook, check to see if it was already covered in this document or in the program itself. But if all else fails, ask away and I'll try to get back to you as soon as I can. Note: Along with your form data, the feedback e-mail will also send your HyperBook version number and server software version numbers (from the Apache "SERVER_SOFTWARE" Environment Variable, if present). This information is helpful when responding to tech support requests. [ Table of Contents ] Alternate Language Configuration In response to many requests, alternate language support was added to HyperBook version 1.10. All text displayed to guestbook visitors is contained within the "language.conf" file. You are welcome to translate the words/phrases in this file to the language of your choice and upload the new language.conf file in place of the default English configuration file (be certain to CHMOD the file to 777). Note that each word/phrase is terminated by a character 13 (carriage return), this preserves the order of the phrases and must not be changed. To add a break to a phrase, insert an HTML break tag (ie. <br>). To preserve proper formatting, some phases should be kept as short as possible, especially those appearing in the navigation bar (ie. "Entries", "Displaying page", "of", "Previous", "Next", "Go to page" and "Go") and on the display template (ie "Record Number", "Posted", "Name", "Website", "Found", "E-mail" and "Location"). To complete the translation process, remember to also change the Found Options, Welcome and Thank You Messages in the Guestbook Configuration section. Alternate language configuration files will be posted for download from the HyperBook site as they become available. If you have translated the language.conf file to a language not currently available, we would very much appreciate your sharing it with us... please e-mail your file to hyperbook@diamond-back.com. In addition to supporting languages other than English, the language.conf file can be used to create new uses for HyperBook other than a conventional guestbook. For example, HyperBook has been used as a "Shout Out" page and club notification page. To make HyperBook "look" like something other than a guestbook, all references to "guestbook" may be changed in the language.conf file (eg. "guestbook" changed to "shout out"). If you have an idea for alternate uses of HyperBook we would like to hear about them. [ Table of Contents ] Database Structure All database records are stored in the "data" directory. The "dbconfiguration.dat" file contains the total number of records, next UID, number of record per file and the full pathway to the data directory. The "gbconfiguration.dat" file contains the guestbook configuration (name, colors, additional questions, etc.). The records are contained in the "data" files, numbered from the earliest posts to the most recent (eg. data_1, data_2, etc.). The HyperBook record format is as follows: each record is a single line terminated by a line break (character 13 and a linefeed). Records are divided into fields using "pipes": | chr(124). If a pipe is to appear as part of a field, it should first be converted into an HTML entity (&#124;) so it will not be mistaken for a field delimiter. Likewise, all line breaks should be converted to "<br>" tags so that a record will not be prematurely terminated. URLs are stored with the "http://" prefix and will not work properly without it. The only expected fields are name, date and comments, the rest may be left blank (the pipes will still be required to hold their place, eg. a missing e-mail would be || ). UID is a "unique identifier" used when searching for a particular record, it is only used for identifying posts in e-mail notifications and should be left blank in imported records. Note that there are 23 fields in total (counting starts at "0"). 00| 01| 02| 03| 04| 05| 06| 07| 08| 09| 10| 11| 12| 13| 14| 15| 16| 17| 18| 19| 20| 21| 22   Field   Description   Field   Description 00 Name or Handle 12 Question 2 01 Date of Post 13 Question 3 02 E-mail Address 14 Answer 1 03 Homepage Address 15 Answer 2 04 Homepage Title 16 Answer 3 05 ICQ Number/UIN 17 Admin Comments 06 How Found 18 UID 07 Location 19 Future Expansion 08 Comments 20 Future Expansion 09 IP Address 21 Future Expansion 10 Remote Host 22 Future Expansion 11 Question 1     [ Table of Contents ] Importing Databases Due to the wide variety of guestbooks in use today, there is no easy "one size fits all" solution for importing records from an existing guestbook into HyperBook. "Remote hosted" guestbooks such as GuestGEAR or Bravenet tend to be the most difficult because the raw data files are usually not available, only the display pages may be used to "slurp up" the old posts. CGI or PHP guestbooks which are run on your own host are somewhat easier to import because the database used by these programs is saved within your account and therefore available to be downloaded and manipulated. In either case, the first (and most difficult) step is to extract the post data from the old guestbook and save it in the HyperBook record format (see above). Once saved in that format, it's relatively easy to use HyperBook's "Import Database" function to complete the task of adding records to your database. If you don't have a large number of records in your existing guestbook you could always copy and paste them into HyperBook via the Sign Guestbook form. This is the "low tech" and somewhat tedious approach, but it definitely works. For PHP programmers, the next best solution is to write a "parse script" where an entire page of posts may be entered in a text box, then let the script extract the necessary data (name, date, e-mail, comments, etc.) and save it in HyperBook record format. Just such a script was written during the development of HyperBook for importing one page of GuestGEAR records at a time and will be made available for download as a utility script. However, due to the wide range of formatting options available in GuestGEAR, the utility script will probably require some "tweaking" to work on any particular guestbook. Hence, to be useful as a starting point you'll need some PHP programming ability. If you have a guestbook which saves data within your hosting account, importing the records may be easier. While the record format used by other CGI or PHP guestbooks varies, chances are it will be somewhat similar to HyperBook's format (ie. a flat text database). The goal is it determine what order the fields are saved in, then write a script to read in the existing records and resave them in HyperBook format. A utility script for doing this will also be made available for download as a "jumping off point" for programmers. I wish I had the time to write custom import scripts for all of the popular guestbooks in use today, but unfortunately a task this large is just too much for one person to handle. Instead, I encourage other PHP programmers to take up the challenge and submit scripts for importing records from other guestbooks, which I'll post as utilities at the HyperBook site. If you absolutely, positively must have your old records imported into HyperBook and don't know how to do it yourself, I would suggest hiring a programmer with database experience to assist you. This document contains full details of the HyperBook record format, and the program itself will do half the work via the "Import Database" function. You may also contact me for hire, though I didn't create HyperBook as a "make work" project... most of my clients are corporations interested in developing interactive websites. The amount of further development performed in this area will depend on how much interest HyperBook generates. If there are a large number of webmasters interested in using it and importing their existing databases, then I'll try to support this task as much as possible. If the interest is low, then I'll move on to new projects... we'll just have to see what happens. [ Table of Contents ] Known Issues The number one known issue affecting HyperBook, and all other PHP scripts, is the "max execution time" setting when running PHP in "safe mode." Since most PHP installations on community servers are likely to have safe mode on, so this is a concern for many webmasters running PHP scripts. Max execution time determines how long a PHP script is allowed to run... and a premature shutdown could be disastrous during file updating operations. By default, max exe time is set at 30 seconds, though it may be set to any value by the system administrator (for example, it's set to 20 seconds on my host's server). The max exe time doesn't directly determine how much work a PHP script can perform; the speed of the host computer, disk access times and server load will all have an affect on overall script performance. To give you a general idea of how well HyperBook is performing on your system, approximate script execution time and time remaining are displayed under the link menu in the various admin sections and in the conformation boxes after some operations. Since the script isn't finished at the point where the execution time is calculated, the actual time will be slightly higher, but the time displayed should be very close to the actual time. If HyperBook was able to determine the max exe time setting on your system, the time remaining will also be displayed. Most operations should require less than a second, but there are a few notable exceptions that you need to be aware of. When a record is deleted from the HyperBook database, each higher record (ie. later posts) must be shifted down one to maintain the number of records in each file. If a low record is deleted from a very large database, the number of files that need to be updated could cause a time out error. This would result in a corrupted database due to some data files being updated while others were not. Note that this is only likely to occur with very large databases, and then only when an early (ie. low numbered) post is deleted. When deleting a recently posted message, only the most recent data files will require updating, so there shouldn't be any time out issues regardless of how many total records are present. Therefore, it is advisable to delete unwanted posts sooner rather than later, though under normal circumstances you should be able to safely delete records which are thousands of posts deep. Likewise, if you import a large number of records into the database, it is advisable to remove any unwanted records prior to the import. Of course the database Import and Export functions are also susceptible to time outs, as are name searches since they may require searching all records. Despite these limitations, most HyperBook functions do not require accessing more than a few small files, even if there are millions of records in the database. Displaying a page of posts will only require reading one or two data files, editing or saving a new record only requires reading and/or writing to a single file. Since these are the most common operations, HyperBook should function flawlessly even with huge databases. During testing, a database of over 15 thousand posts was used with all delete, import and export functions completing in under 5 seconds. Your results may vary depending on the speed of you host's computer, disk drives and server load. It is recommended that you back-up your data directory prior to performing an operation which could potentially time out, such as deleting a low numbered record from a very large database or importing a large number of records. Performing these operation during off-peek hours (usually early in the morning) may also improve performance due to lower server load. Make a note of the execution times displayed in the link menu and conformation boxes to gauge how well HyperBook is performing on your host's system. If you experience time out errors or excessive script execution times, you may wish to contact your system administrator and ask if the PHP max_execution_time could be raised. Some hosts tend to overload their servers with more accounts than can be reasonably handled, if this is the case you should consider finding a host who takes better care of their customers. You're welcome to contact me regarding a better host... mine has been excellent when it comes to providing sufficient resources for their customers. Another possible problem area is the inability of PHP to save the Admin's password to a cookie when running HyperBook on a hosting service which displays pop-up ads whenever a page is loaded. Cookie data is sent in the HTTP page header, therefore the "setcookie" function must be executed prior to any data being sent to the browser (which automatically sends the header). Some services add the pop-up script at the start of the page, which seems to trigger the header to be sent before the PHP script has a chance to set the cookie. Alternatives to using cookies will be researched as a work around to this problem. Some browsers do not handle cookies correctly, such as Netscape Communicator 4.05 and Microsoft Internet Explorer 3.x. If you are using one of these browsers we recommend upgrading to a more current version. No testing has been (or will be) performed with AOL browsers. Note that cookies are stored based on domain name. Since some domains can be accessed with and without the "www" (eg. my guestbook can be accessed at both "http://diamond-back.com/guestbook/" and "http://www.diamond-back.com/guestbook/"), if the password cookie is set from "http://yourdomain.com/guestbook/admin.php" the cookie will not be recognized from "http://www.yourdomain.com/guestbook/admin.php". The solution is to either access the Admin program from exactly the same domain name or log-in again and set a new cookie. If the password is changed, only the cookie for the domain you are logged-in from will be updated. File locking in HyperBook version 1.10 is designed to use PHP's operation keywords (LOCK_SH, LOCK_EX and LOCK_UN). For file locking to work properly in versions prior to PHP 4.0.1, these keywords may need to be replaced with the values 1, 2 and 3 respectively. However, if you are using an earlier version of PHP it is strongly recommended that you upgrade. As other issues become known they will be announced and hopefully corrected. HyperBook will also be tweaked for better performance wherever possible. Your suggestions and reports are welcome, please use the Feedback Form to contact me. [ Table of Contents ] About the Developer Thomas Pasawicz began programming computers in 1986 with a TI-99/4a and soon upgraded to an Apple ][. Writing in Applesoft, he developed a BBS (Bulletin Board System) for local dial-up use... his first "on line" project. By 1996 he started developing Internet websites and now works as a freelance programmer/designer. In addition to creating corporate websites using HTML, PHP, MySQL and Flash, he also maintains a personal website at Diamond-Back.com featuring an ICQ rumor section and a site for his friends to chat at Smartasses Online. For commercial website development, please see TRP Web Design for more information. [ Table of Contents ] HyperBook Guestbook v1.00 Copyright © 2001 by Thomas R. Pasawicz. All rights reserved. • Click here for more info.