Location: PHPKode > projects > KISGB (Keep It Simple Guest Book) > docs/QUICK-START-GUIDE.html



		b {color:blue;}

		table {background-color:#D3D3E3;border-color:blue;}

		hr {color:blue;}

		p {font-weight:bold;}




<table border="3" width="100%" align="center">


<p style="color:blue;">For phpNuke users, please read the separate NUKE-USERS-GUIDE.  Everything in this Guide still applies.  There's more specific information in the NUKE-USERS-GUIDE because of the unique application environment.  And, it is a separate download.</p>

<hr />

<p>KISGB configuration files really allow you to have almost 100% control over the look and feel of the guest book.  As usual, when offering this much control, some ease of use is the trade off.  While this may not be a true user's guide in a purist's sense, between the config.explain.html file and the history.html file, there is a wealth of information.  So, hopefully, this Quick Start Guide will be of some value to you!</p>

<p>First of all, let me explain a few setup notes that will help you in a successful installation.  When you unzip KISGB, it is truly ready to run, right out of the box.  But, you do need to make sure that permissions are set correctly.  The KISGB and Themes folder must be writable. In addition, the user.prefs.php and kisgb.csv.php files must be writable.  Other than that, you can leave the permissions as unzipped.  Once that is done, you should be able to point your browser to http://www.yoursite.com/kisgb and have a guest book!</p>

<p>Now, for some settings that you will want to check/change first off.Let me explain a little about the purpose of the 2 configuration files: config.php and user.prefs.php.  Conceptually, the user.prefs.php file "inherits" settings from config.php.  You should NEVER change the config.php file, as it can change with each new release.  That's why it's there.  All of your modifications should be done to the user.prefs.php file.  There are a couple of settings in the config.php file that are NOT in user.prefs.php.  (For brevity, from here on out, For brevity, form here on out  config.php will be referred to as "config" and user.prefs.php as "prefs".) The most important one is<br /><br />

<b>$app_version = "v5.1.0";</b><br />


<p>This goes back to what was said earlier about this file changing with each release.  Prefs does not contain the setting, so KISGB "inherits" from config.  Config, in it's purest form, is more conservative than Prefs.  To keep you from having to modify all new settings from release to release and/or be constantly updating your Prefs file with new releases, technically speaking, you usually will not have to replace your Prefs file when you install a new release.  Whatever settings are missing from Prefs will be inherited from Config.  If you need to modify a setting that is in Config and NOT in Prefs, you should first copy the setting to Prefs and then modify it in Prefs.  Hopefully no one is lost up to this point :).</p>


<p>OKAY!  Now that we have the basics out of the way, let's discuss some of the settings that you MUST change after installing.  There a several levels of security in KISGB that can be utilized.  The basic security is very secure and most sites will not require more than the basic level.  The basic level of security is controlled with these 2 settings.  You should change them IMMEDIATELY to your own values.  These settings are ADMINISTRATIVE in nature.  They do NOT control access to the site, but just to the admin functions. Most sites only need to use these.

<br /><br />

<b>$admin_id = "admin";</b><br />

<b>$admin_pw = "password";</b><br /><br />


<p>There is a trick that you can use to not reveal that there are admin functions available.  There is a setting <b>$show_admin_menu</b> which is set to TRUE by default.  If you set this to FALSE, you will need to specifically type in admin.php in the URL to get to the admin screen(s).  The security is not affected; it still functions as stated above.  This setting just hides the link/icon.<br /><br />

Should you find that you need/want to have a PRIVATE club, then kick it up a notch with these two settings.  They control access to the site itself.  Should you decide to have a private site, then set <b>$secure_site</b> to TRUE and modify the <b>$site_id</b> and <b>$site_pw</b>.  Please note that you will still be required to know the <b>$admin_id</b> and <b>$admin_pw</b> to perform admin tasks.<br /><br />

<b>$secure_site = false;</b><br />

<b>$secure_site_id = "secure";</b><br />

<b>$secure_site_pw = "password";</b><br /><br />

There is still a third, or PARANOID, level of security, for the admin functionality.  There has never been a request  to use these, but it is built in, just in case.<br /><br />

<b>$myIP = "*";</b><br />

<b>$lock_admin_to_myIP = false;</b><br /><br />

If you put an absolute IP address in <b>$myIP</b> and set <b>$lock_admin_to_myIP</b> to TRUE, then you cannot perform admin functions from any machine EXCEPT the machine mapped to that IP.<br /><br />

<b>$encryptPassword = TRUE;</b><br /><br />

If you set <b>$encryptPassword</b> to TRUE, then all user passwords will be encrypted using the MD5 encryption.  This is NOT reversible, so if a user forgets his password admin will need to reassign a password to him.<br /><br />

<b>$moderateEntries = FALSE;</b><br /><br />

If you want to moderate the entries, meaning you want to review the entries before releasing them to the public, set <b>$moderateEntries</b> to TRUE. All entries will be 'hidden' until you release them via the Edit All Entires screen.  The new 'Hold' and 'Release' buttons control this.<br /><br />

Lastly, if you want to be able to perform admin functions from the web and/or you are allowing message level editing, you will need to set <b>$admin_from_web</b> to TRUE, which it is by default.  This concludes the discussion about KISGB security.



<p>Here is a list of the settings that you will most likely need to change, right off the bat.  There could be others, but these are most likely.  Unless an in-depth discussion is needed, a brief synopsis for each will be given.  The settings are shown with their default values.  If a particular setting is not commented on, it is assumed it is self-explanatory :).<br /><br />

<b>$site_url = "http://www.your_site.com";</b><br />

<b>$guestbook_name = "KISGB";</b><br /><br />

/*** $site_url is assigned above ***/<br />

<b>$guestbook_signature = "Sincerely,\n\nThe Webmaster\n$site_url";</b><br /><br />

/*** These 2 settings allow you to control if users/admins can modify messages from the View Guest Book screen ***/<br />

/*** The admin can still modify the messages, but from the Admin screen instead ***/<br />

<b>$allow_msg_lvl_edit_by_admin = false;</b><br />

<b>$allow_msg_lvl_edit_by_user = false;</b><br />

<b>$allow_msg_lvl_delete_by_user = false;</b><br />

<b>$admin_email_advice_on_gb_edit = false;</b><br />

<b>$admin_email_subject_on_gb_edit = "Guest Book Entry Modified";</b><br />

<b>$admin_email_address = "hide@address.com";</b><br />

<b>$admin_email_address_addl = "";</b><br /><br /><br />

/*** send confirmation emails to user and/or admin ***/<br />

<b>$admin_email_advice = false;</b><br />

<b>$guest_email_advice = false;</b><br /><br />

<b>$admin_email_subject = "Guest Book Entry Added";</b><br />

<b>$guest_email_subject = "Thank you for signing our Guest Book!";</b><br /><br />

/*** Default languages and theme.  If $use_languages and/or $use_themes is set to false, then the  ***/<br />

/*** user cannot change them, i.e., the select box isn't even offered.                             ***/<br />

<b>$language = "english.lang.php";</b><br />

<b>$use_languages = true;</b><br />

<b>$theme = "iceblue.thm.php";</b><br />

<b>$use_themes = true;</b><br /><br />

/*** Where to position the Themes select box.  If set to false, then the Language box is to the far left ***/<br />

/*** and the Theme box to the far right.                                                                 ***/<br />

<b>$theme_by_language = true;</b><br /><br />

/*** Determines whether select boxes appear at the top and/or bottom. ***/<br />

<b>$use_themes_languages_header = true;</b><br />

<b>$use_themes_languages_footer = false;</b><br />

<b>$rows_per_page = 10;</b><br /><br />

/*** If set to TRUE then the guest book entries will be a dual column table.  Otherwise, a single column table. ***/<br />

<b>$icons_in_separate_column = true;</b><br /><br />

/*** Controls appearance of the menu items.  Hyper-links or images.  There are settings that allow you to ***/<br />

/*** assign the images.                                                                                   ***/<br />

<b>$use_links_instead_of_images = false;</b><br /><br />

/*** The license requires that you keep the footer in place that links back to my site.    ***/<br />

/*** However, if you will link back elsewhere on your site, you may then set this to FALSE ***/<br />

/*** to clean up the appearance of the guest book screen. Logo images are also supplied.   ***/<br />

/*** In the images folder are several images named kisgb-logo0, logo1, logo2, etc.         ***/<br />

/*** Feel free to substitute these in other places on your website.                        ***/<br />

<b>$use_footer = true;</b><br /><br />

/*** The header.php file is for your use to place banners, menus, messages, instructions, etc.   ***/<br />

/*** at the top of your pages.  These settings control whether you want the same message to      ***/<br />

/*** appear on the View and Sign pages.  There is not presently a way to have separate messages. ***/<br />

<b>$use_header_view = true;</b><br />

<b>$use_header_sign = false;</b><br /><br />

/*** Set the date and time format for your messages. If you modify these after initial setup, the  ***/<br />

/*** guest book will dynamically adjust.  This functionality is NOT backwards compatible however.  ***/<br />

<b>$date_format = "Y-m-d";</b><br />

<b>$time_format = "H:i:s";</b><br /><br />

/*** Adjust time zone settings if your locality is not the same as your server. ***/<br />

<b>$hours_to_offset = 0;</b><br /><br />

/*** If you allow user editing of their messages, this date will allow you to set a cutoff date ***/<br />

/*** to keep them from modifying messages older than that date.  If left blank, then there is no***/<br />

/*** limit.  They can modify a message 2 years old!                                             ***/<br />

<b>$cutoff_date_for_updates = "";</b><br /><br />

/*** Control how often the same IP can post messages.  If set to zero, it is ignored ***/<br />

/*** and flooding can happen.  Value is in seconds, so 60 would 60 seconds.          ***/<br />

<b>$flood_control_timer = 0;</b><br />



<p>Now, some general instructions about controlling the appearance of KISGB.  You can tailor so much of the layout of KISGB!  To control what information is collected and/or required, use these settings:<br /><br />

<b>$require_name = true;</b><br />

<b>$require_email = true;</b><br />

<b>$require_nation = false;</b><br />

<b>$show_all = false;</b><br />

<b>$hide_all = false;</b><br />

<b>$show_name = true;</b><br />

<b>$show_email = true;</b><br />

<b>$show_home = true;</b><br />

<b>$show_pic = true;</b><br />

<b>##################################################</b><br />

<b># use_pic is for using the actual picture.       #</b><br />

<b># pic_width sets the image display width.        #</b><br />

<b># pic_height sets the image display height.      #</b><br />

<b>##################################################</b><br />

<b>$use_pic = true;</b><br />

<b>$pic_width = 48;</b><br />

<b>$pic_height = 64;</b><br />

<b>$show_icq = true;</b><br />

<b>$show_aim = true;</b><br />

<b>$show_yim = true;</b><br />

<b>$show_msn = true;</b><br />

<b>$show_nation = true;</b><br />

<b>$show_ip = true;</b><br />

<b>$show_private = true;</b><br />

<b>$show_date = true;</b><br />

<b>$show_time = false;</b><br />

<b>$show_search = true;</b><br /></br />

You will note that you can require fields but not display them.  The most common use of this is the e-mail.

The <b>$show_admin_menu</b> and <b>$show_home_menu</b> control the menu link/images.

If you do not want the password prompt on the Sign screen, then set <b>$show_password</b> to FALSE.



<p>A brief note on the filter.php file.  This is a combination IP blocker and word blocker file.  You can ban individual IP's or IP ranges, or wild cards. Set <b>$use_filter_file</b> to FALSE to have KISGB ignore the file.</p>


<p>A small discussion on how message level editing is implemented in KISGB. There are several settings that work together to control the functionality in KISGB.  First of all <b>$admin_from_web</b> MUST be set to TRUE before editing is allowed.  Regardless of all the other settings, if this is not set to TRUE, the other settings are ignored. These 3 settings, as explained earlier, control who and what level of message level editing is allowed.<br />

<b>$allow_msg_lvl_edit_by_admin = false;</b><br />

<b>$allow_msg_lvl_edit_by_user = false;</b><br />

<b>$allow_msg_lvl_delete_by_user = false;</b><br />

Then the setting <b>$cutoff_date_for_updates</b> must be set to a non-zero value to designate the number of seconds after the time stamp that a user can edit messages.  A -1 allows updates forever, which this author would not personally want.  If you wanted to allow updates within 5 minutes after posting, then set the value to 300 or 60*5.  One day would be 60*60*24 or 86400.



<p>Well, it's been a long time coming, but this is the start of the user's guide.  I trust that this has been of some help!  The best way to learn the ropes is to just get in and start changing settings.  I would like to offer thanks to everyone who was so instrumental in bringing this to fruition.  Please understand that listing everyone by name is not possible, but a great thanks to all the translators and testers!  I am compelled to say a special note of gratitude to the following by name - Hiro, Jerry, Peter, Roy, Cody, Bob, Steve, and Martin for your endless hours of testing, your encouragement, your suggestions, and your insights, to perfect this release!  Enjoy!







Return current item: KISGB (Keep It Simple Guest Book)