Location: PHPKode > projects > MJGUEST > mjguest/UserGuide_en.htm
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
	<title>MJGUEST User Guide</title>
	<meta name="Author" content="mdsjack" lang="it" />
	<meta http-equiv="Content-Language" content="en" />
	<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
	<meta name="Robots" content="noindex,nofollow" />
	<style type="text/css">
		body { font-size: 70%; line-height:150%; background-color: #f1f1f1; color: #000; font-family: Verdana, Arial, Helvetica, Trebuchet MS, sans-serif; }
		div#body { margin: 0px auto; padding: 5px 0px; width: 500px; border: 1px solid gray; background-color: white }
		div#copyright { font-family: monospace;font-size: 12px; white-space: pre; background-color: beige; overflow:hidden; padding: 5px 0px }
		a, a:active, a:visited, a:hover { color:#6699CC; }
		code { font-family: monospace; font-size: 12px; background-color: #FFFFE0; line-height: 150%; padding: 2px; }
		small { font-size: 85%; color: #6d6d6d; }
		hr {  }
		
		ul { list-style-type: none; margin-left: 20px; }
		ul.par { margin-left: 60px; }
		
		li { line-height: 200%; margin-left: 0px; }
		
		h1 { font-size: 120%;margin-left: 10px; font-weight: bold; }
		p { margin: 5px 10px; width: auto }
		
		h2 { font-size: 100%; margin-left: 20px; font-weight: bold; }
		p.a { margin-left: 40px; width: auto; }
		
		h3 { font-size: 100%; margin-left: 40px; margin-bottom: 0px; font-weight: normal; }
		p.b { margin-left: 60px; width: auto; }
		
		p.todo { white-space: pre; }
	</style>
</head>
<body>
<div id="body">
<p><a href="UserGuide_it.htm">Italiano</a></p>
<div id="copyright">
    MJGUEST
    =============================================================
    Copyright (c) 2002-2008 www.mdsjack.bo.it
    Agreement: http://www.mdsjack.bo.it/files/agreement.htm
    =============================================================
    Official website: http://www.mdsjack.bo.it
    Script email:     mjguest (AT) mdsjack.bo.it
    Agreement info:   agreement (AT) mdsjack.bo.it
</div>
<hr>
<p>
  <cite>
  Thanks for choosing MJGUEST!
  <br>Here it is a quick guide to get started with your
  brand new guestbook.
  <br>For further info or support to any issue occurring while
  installing or using the guestbook, visit official web site.
  <br>In order to improve our service, we'll be glad to receive any
  feedback from you.
  </cite>
</p>
<hr>

<h1>Table of Contents</h1>
<p>
	<ul>
		<li>§ 1.0 - Installation</li>
		<li>§ 2.0 - Script Administration</li>
		<ul>
			<li>2.1) Overview</li>
			<ul>
				<li>2.1.1) Logging in</li>
				<li>2.1.2) Password reminder</li>
				<li>2.1.3) How to edit configuration</li>
			</ul>
			<li>2.2) Managing Entries</li>
			<li>2.3) Graphic Themes</li>
			<li>2.4) Emoticons Management</li>
			<li>2.5) Other Add-ons</li>
			<li>2.6) Advanced Settings</li>
			<li>2.7) RSS Feeds <img src="interface/rss.png" alt="RSS Feed" width="16" height="16" style="vertical-align:text-top" /></li>
		</ul>
		<li>§ 3.0 - Upgrade</li>
		<li>§ 4.0 - Removal</li>
		<li>§ 5.0 - Appendix 1: How to use &quot;Setup Utility&quot;</li>
		<li>§ 6.0 - Appendix 2: Removing title-bar proprietary label (upon request)</li>
		<li>§ 7.0 - Appendix 3: Troubleshooting and Technical Support</li>
	</ul>
</p>
<hr>
<h1><a name="1_0"></a>§ 1.0 - INSTALLATION</h1>
<h2>1.1) Delete unnecessary files <small>(jump this step if you are RE-installing)</small></h2>
<p class="a">
	If you don't have a fast internet connection to
	upload the script and you are not
	interested in automatic guests' country recognition and local date/time formatting features, you
	can delete:
	<br>
	<br>
	<code>FILE    resources/ip-to-country.db</code> <small>(about 1.8 MegaBytes)</small>
	<br>
	<br>
	<small>You can restore this feature by uploading this file at a later time (see <a href="#2_5">§ 2.5</a>).</small>
	<br>
	<br>
	<br>
	If you're not interested in country flags, you can avoid uploading:
	<br>
	<br>
	<code>FOLDER  interface/theme-THEMENAME/flags/</code> <small>(e.g. &quot;theme-hera&quot;)</small>
	<br>
	<br>
	<br>
<!--
	If you're running PHP 5, delete:
	<br>
	<br>
	<code>FOLDER  resources/PEAR/</code>
	<br>
	<code>FOLDER  database/mysql3/</code>
	<br>
	<br>
	<br>
-->
	Then, if you already know which database you'll be
	using, you may delete other database folders, all located inside:
	<br>
	<br>
	<code>FOLDER  database/</code>
	<br>
	<br>
	<small>
	(e.g.: if you are going to use MySQL3, you can delete folders
	&quot;pgsql&quot;, &quot;sqlite&quot;, etc...)
	</small>
</p>
<h2>1.2) Upload the Script <small>(jump this step if you are RE-installing)</small></h2>
<p class="a">
	Upload the whole script to your web server using your
	FTP client software (eg. CuteFTP).
	<br>
	<br>
	<small>
	NOTE:
	<br>
	Language files should be all uploaded, because the script language
	is set according to the location of your guests!
	</small>
</p>
<h2>1.3) Use &quot;Setup Utility&quot;</h2>
<p class="a">
	Jump to <a href="#5_0">§ 5.0</a> to learn how to start
	the &quot;Setup Utility&quot;, then go on reading.
	<br>
	<br>
	Push button &quot;Install&quot; and follow instructions on screen.
	<br>
	<br>
	If installation succeds, using button &quot;Usage Tutorials&quot; of
	the &quot;Setup Utility&quot; will let you choose the most suitable way
	to open the guestbook from your web site. Put the given code
	inside your web page as explained in &quot;Setup Utility&quot;.
	<br>
	<br>
	Close &quot;Setup Utility".
</p>
<h2>1.4) Enter the Guestbook for the first time</h2>
<p class="a">
	You can enter your guestbook from the link you have
	just created (see above).
	<br>
	To log-in as guestbook Administrator for the first time,
	use &quot;password&quot; as default password.
</p>
<hr>
<h1><a name="2_0"></a>§ 2.0 - SCRIPT ADMINISTRATION</h1>
<h2>2.1) Overview</h2>
<p class="a">
	There are two levels of power-users: Moderator and Administrator.
	<br>
	Moderator account must be activated by Administrator via control panel.
	<br>
	<br>
	<table width="90%" style="margin: 0px auto">
		<th width="80%">Special Abilities</th><th width="10%">Mod</th><th width="10%">Admin</th>
		<tr><td width="80%">Edit/restore configuration</td><td width="10%">-</td><td width="10%">+</td></tr>
		<tr><td width="80%">Activate/deactivate the Moderator account</td><td width="10%">-</td><td width="10%">+</td></tr>
		<tr><td width="80%">Delete all entries at a time</td><td width="10%">-</td><td width="10%">+</td></tr>
		<tr><td width="80%">Ban a guest and delete all his messages</td><td width="10%">-</td><td width="10%">+</td></tr>
		<tr><td width="80%">Change your password/email address</td><td width="10%">+</td><td width="10%">+</td></tr>
		<tr><td width="80%">Read and approve pending entries</td><td width="10%">+</td><td width="10%">+</td></tr>
		<tr><td width="80%">Edit or delete single entries</td><td width="10%">+</td><td width="10%">+</td></tr>
		<tr><td width="80%">Reply to entries</td><td width="10%">+</td><td width="10%">+</td></tr>
		<tr><td width="80%">Read private entries</td><td width="10%">+</td><td width="10%">+</td></tr>
		<tr><td width="80%">See through filtered swearwords</td><td width="10%">+</td><td width="10%">+</td></tr>
		<tr><td width="80%">Get IP/Provider info of your guests</td><td width="10%">+</td><td width="10%">+</td></tr>
		</tr>
	</table>
	<br>
	When you write a message as Administrator or Moderator entry approval, all filters and security checks, CAPTCHA code,
	Country recognition are bypassed.
</p>
<h3>Logging in:</h2>
<p class="b">
	To log-in, type your password in the login form next to the top menu.
	<br>
	Once you have logged in, the form will be replaced by a new menu link named &quot;Control panel&quot;.
	<br>
	<br>
	Administrator default password is &quot;password&quot;.
	<br>
	If activated, Moderator default password is &quot;moderator&quot;.
</p>
<h3>Password reminder:</h2>
<p class="b">
	If you have forgotten your keyword, you may receive an email
	reminder by using the SetupUtility (<a href="#5_0">§ 5.0</a>) facility
	named &quot;Password reminder&quot;.
	<br>
	This works only after the first log-in, if valid email addresses were set.
</p>
<h3>How to edit configuration:</h2>
<p class="b">
	Go to &quot;Control panel&quot; and easily tweak settings.
	From this page you can also delete all messages at a time
	and restore original configuration.
</p>
<h2>2.2) Managing Entries</h2>
<h3>How to read private entries:</h2>
<p class="b">
	When you are logged-in as power-user, private entries will be
	visible among the others at the reading page, titled as &quot;<b>Confidential</b>&quot;.
</p>
<p class="b">
	Beware that each private entry can be read <u>also by the guest who wrote it</u> (but not by others)!
	So you may see your private entries wrote as a guest (when not logged), as long as your IP address doesn't change.
</p>
<h3>How to manage single entries:</h2>
<p class="b">
	When you are logged-in as power-user and you are reading the guestbook, special
	icons will show up next to each entry.
	<br>
	<br>
	Please remember that if you are a Moderator, you can't manage entries added by the Administrator.
	<br>
	<br>
	These icons let you easiliy perform administration tasks
	on any single entry:
	<ul class="par">
		<li><img src="interface/theme-hera/approve.gif" /> =
		Approve this pending message: until then, the message is hidden to any
		Guests, except the author, and visible to Moderator and Administrator</li>
		<li><img src="interface/theme-hera/edit.gif" /> =
		Edit this entry</li>
		<li><img src="interface/theme-hera/id.gif" /> =
		Delete this entry</li>
		<li><img src="interface/theme-hera/del_user.gif" /> =
		Ban this guest and delete all his messages: Moderator and Administrator can't be banned</li>
		<li><img src="interface/theme-hera/ip.gif" /> =
		Get IP/Provider information about this guest</li>
	</ul>
</p>
<h3>Replying to entries:</h2>
<p class="b">
	You can easily add a reply to any entry, by clicking on this special icon:
</p>
	<ul class="par">
		<li><img src="interface/theme-hera/reply.gif" /> =
		Add/Edit your reply to this entry</li>
	</ul>
<p class="b">
	If Javascript is <u>disabled</u>, you will be brought to a classic form to fill, before
	being redirected right back to the entry you were replying to.
	<br>
	<br>
	Instead, if you have Javascript <u>enabled</u>, you will benefit of the quick-edit feature.
	<br>
	<br>
	To <u>write</u>, <i>click on the icon</i> displayed above, or
	<i>doubleclick on the text</i> of you reply previously added.
	<br>The text cursor will be placed in the text-field where you can write your reply.
	<br>
	<br>
	If you wish to remove your reply, simply remove its contents.
	<br>
	<br>
	To <u>save</u> your reply and exit from writing-mode, simply
	<i>click anywhere outside</i> the reply text field.
	<br>
	<br>
	According of your level of authorization, your reply may look two
	different ways:
	<br>
	<br>&quot; <i><b>Administrator</b>: your reply here...</i> &quot; 
	<br>
	<br>&quot; <i><b>Moderator</b>: your reply here...</i> &quot;
</p>
<h2>2.3) Graphic Themes</h2>
<h3>A) Official Themes</h3>
<p class="b">
	Download the graphic theme package from the official
	web site, among those compatible with the version of your
	guestbook.
	<br>
	<br>
	Unzip it and you will find:
	<br>
	<br>
	<code>FOLDER  theme-THEMENAME</code> <small>(e.g. &quot;theme-hera&quot;)</small>
	<br>
	<br>
	Upload the whole folder to you remote server, inside:
	<br>
	<br>
	<code>FOLDER  interface/</code>
	<br>
	<br>
	The graphic theme will be immediately available inside
	administrator control panel of the guestbook.
	<br>
	<br>
	<small>
	NOTE FOR WEB DESIGNERS:
	<br>
	At the official website you can download a special
	package file called &quot;themeName.SDK&quot; containing all the
	PNG vector files for web designers who want to customize
	the grahics of the corresponding theme.
	This folder is NOT meant to be uploaded.
	</small>
</p>
<h3>B) Custom Themes</h3>
<p class="b">
	If you are familiar to CSS and graphics, you can create a
	custom theme.
	<br>
	I suggest you to create a different folder from the default
	one and renaming it (e.g. &quot;theme-customName&quot;), because in case
	of problems, you can always restore the original default
	theme.
	<br>
	To customize the layout edit ONLY the files inside themes
	folder!
</p>
<h2>2.4) Emoticons Management</h2>
<p class="a">
	Adding and removing emoticons is very easy!
	<br>
	Go to folder:
	<br>
	<br>
	<code>FOLDER  interface/emoticons/</code>
	<br>
	<br>
	Simply add, delete, rename the files inside.
	Changes will be effective immediately.
</p>
<h2><a name="2_5"></a>2.5) Other Add-ons</h2>
<p class="a">   
	At official web site, you can find a few other components
	to keep your guestbook up-to-date.
</p>
<h3>Anti-SPAM Filter:</h3>
<p class="b">   
	<code>FILE    resources/spam.db</code>
	<br>
	Keep this file always up-to-date to erase more and more possible.
</p>
<h3>Swearing Filter:</h3>
<p class="b">   
	<code>FILE    resources/swearwords.db</code>
	<br>
	You should upgrade this file often, so your guestbook can
	intercept and filter more and more bad words and profanities.
</p>
<h3>IP-to-Country Database:</h3>
<p class="b">   
	<code>FILE    resources/ip-to-country.db</code>
	<br>
	This big file lets the guestbook recognize users' country
	from their IP address. If you care about this feature, keep
	this file updated (get a new one at MJGUEST web site).
</p>
<h2>2.6) Advanced Settings</h2>
<p class="a">
	You can find more settings if you open, with a text editor, the file:
	<br>
	<br>
	<code>FILE    mjguest.class.php</code>
	<br>
	<br>
	A breif explanation is given for each setting.
	<br>
	<br>
	Beware you're directly editing the source code, here. Therefore
	any modification is attempted at your own risk.
</p>
<h2>2.7) RSS Feeds <img src="interface/rss.png" alt="RSS Feed" width="16" height="16" style="vertical-align:text-top" /></h2>
<p class="a">
	RSS feeds are a new, widely used technology which allows you to read the latest entries of your guestbook
	through dedicated RSS reader programs (aggregators) or websites, where you can read many RSS sources on one
	page, such as the custom Google home-page.
	<br>
	<br>
	To read MJGUEST RSS feed, simply click on the <img src="interface/rss.png" alt="RSS Feed" width="16" height="16" style="vertical-align:text-top" />
	icon that will show up when you are logged as Administrator or Moderator.
	<br>
	<br>
	You may use this web page url to let RSS readers access your guestbook and show you the latest entries.
</p>
<hr>    
<h1>§ 3.0 - UPGRADE</h1>
<h2>3.1) Upload the Script</h2>
<p class="a">
	Overwrite the old script with the new one via FTP software.
	<br>
	<br>
	<small>
	<b>NOTE #7:</b>
	<br>
	In version 6.8, date/time management has changed. This means that
	the date/time of old entries will not be displayed correctly, reporting a
	variable hours gap, according to the geographical location of your
	web server.
	<br>
	<br>
	<b>NOTE #6:</b>
	<br>
	In version 6.7, theme folder names have changed:
	<br>
	<br><code>interface/NAME.pak</code> -&gt; <code>interface/theme-NAME</code>
	<br>
	<br>Please rename manually all your theme folders.
	<br>
	<br>
	<b>NOTE #5:</b>
	<br>
	In version 6.7:
	<br>
	<br><code>FOLDER install/</code>
	<br>
	<br>was replaced by:
	<br><code>FOLDER setup/</code>
	<br>
	<br>You must upload the new folder, deleting the old one.
	<br>
	<br>
	<b>NOTE #4:</b>
	<br>
	From version 6.5, all language translation files were renamed like this:
	<br>
	<br><code>FILE.lang.php</code> -&gt; <code>FILE.utf8.php</code>
	<br>
	<br>Delete old files inside:
	<br><code>FOLDER interface/language/</code>
	<br>
	<br>
	<b>NOTE #3:</b>
	<br>
	Starting from version 6.3, all templates files were renamed:
	<br>
	<br><code>interface/TEMPLATE.tpl.php</code> -&gt; <code>interface/TEMPLATE.htm.php</code>
	<br>
	<br>Delete old files inside:
	<br><code>FOLDER interface/</code>
	<br>
	<br>
	<b>NOTE #2:</b>
	<br>
	Starting from version 6.3, every folder having names
	preceded by underscore &quot;_&quot; are no longer needed
	and may be erased.
	<br>
	<br>
	<b>NOTE #1:</b>
	<br>
	In version 6.2 default names of smileys have changed.
	Upgrading might corrupt smileys inserted previously
	by your guests.
	</small>
</p>
<h2>3.2) Use &quot;Setup Utility&quot;</h2>
<p class="a">
	Jump to <a href="#5_0">§ 5.0</a> to learn how to start
	the &quot;Setup Utility&quot;, then go on reading.
	<br>
	<br>
	Select the version of the script you currently own
	and push button &quot;Upgrade&quot;.
	<br>
	<br>
	If upgrade succeds, using button &quot;Web integration&quot; of
	the &quot;Setup Utility&quot; will let you get the most suitable code
	to open the guestbook from your web site. Put this code
	inside your web page (more info given in &quot;Setup Utility&quot;)
</p>
<hr>
<h1>§ 4.0 - REMOVAL</h1>

<h2>4.1) Use &quot;Setup Utility&quot;</h2>
<p class="a">
	Jump to <a href="#5_0">§ 5.0</a> to learn how to start
	the &quot;Setup Utility&quot;, then go on reading.
	<br>
	<br>
	To delete the script, push button &quot;Remove&quot;.
	This option will delete all your data!
	<br>
	<br>
	Now, if you want to RE-install, jump to <a href="#1_0">§ 1.0</a>.
</p>
<h2>4.2) Delete Files</h2>
<p class="a">
	After you have cleaned up the database, use your FTP client
	to remove all files and folders.
</p>
<hr>
<h1><a name="5_0"></a>§ 5.0 - APPENDIX 1: How to use &quot;Setup Utility&quot;</h1>
<p class="a">    
	1) Open your browser to the page:
	<br>
	<br>
	www.YourSite.com/MjguestDirectory/setup/
	<br>
	<br>
	2) Click on the link &quot;Open Setup Utility&quot;, it will open in
	a popup window.
	<br>
	<br>
	3) Follow the easy step-by-step instructions.
	<br>
	<br>	
	<small>
	NOTE:
	<br>
	If your guestbook is already installed, for safety reasons
	you will be asked to type your Administrator password.
	If you have just installed the script, default password
	is &quot;password&quot;.
	<br>
	Safety password is required to: Install, Upgrade, Remove but not
	for Usage Tutorials and Password Reminder.
	</small>
</p>
<hr>
<h1>§ 6.0 - APPENDIX 2: Removing title-bar proprietary label (upon request)</h1>
<h2>Why?</h2>
<p class="a">
	Although this guestbook is 100% free for any kind of use,
	if you would like to hide at the eyes your visitors where your guestbook
	comes from, without breaching the contract, you
	may buy the right to remove the copyright label that
	appears on title-bar, by paying a symbolic one-time fee.
</p>
<h2>How?</h2>
<p class="a">
	Simply go to the dedicated section of 
	<a href="http://www.mdsjack.bo.it/index.php?page=mjguest#copy_remove">mdsjack web site</a>
	and read carefully all terms of service.
</p>
<hr>
<h1>§ 7.0 - APPENDIX 3: Troubleshooting</h1>
<p class="a">
	Before asking any technical questions on the
	<a href="http://www.mdsjack.bo.it/public/phpBB3/viewforum.php?f=2">official forums</a>
	please read carefully what follows:
</p>
	<ul class="par">
		<li>1) Check if you have downloaded the latest version of the guestbook and of any add-on file (please check the website)</li>
		<li>2) Check if every file and folder was correctly uploaded. If you're not sure, upload it again.</li>
		<li>3) If you have succesfully installed the guestbook, open file &quot;setup.ini.php&quot; with a text editor and set <code>mjguest_debugmode</code> to <code>true</code>. Save and upload the file.</li>
		<li>4) When asking for support, provide the web address where the guestbook is located.</li>
		<li>5) Read this forum discussion about <a href="http://www.mdsjack.bo.it/public/phpBB3/viewtopic.php?t=1968">FAQs + Tips&amp;Tricks</a>.</li>
	</ul>
<hr />
<p style="text-align: center;">END OF USER GUIDE</p>
</div>
</body>
</html>
Return current item: MJGUEST