Location: PHPKode > projects > WSN Guest > wsn-guest/readme.txt
----------------------
WSN Guest 1.23
----------------------

Please note that WSN Guest, while a powerful guestbook script, has not been actively developed since 2003. You can however change that according to the terms of the license.

Requirements: PHP 4.3.0+, MySQL, cookie-enabled browser (for administration login, and member logins)

----------------------
New Install
----------------------

To install WSN Guest 1.23:

(1) Extract files from the ZIP.
(2) Upload all the extracted files to your hosting space.
(3) Rename config.php.txt to config.php, and then CHMOD 666 that file.
(4 - optional) If you wish to use online template editing, CHMOD 666 all files in your /templates/default directory. (Do NOT chmod 666 a directory itself, as this will prevent access to it... just the files.)
(5) CHMOD 777 your attachments directory.
(5) If you don't already have a database created, create one using your host's provided tools. (You may use an existing database if you like, if you have one. If you plan to integrate your member system with another script, install in that database.) Also be sure you've set up a username and given the username access to this database.
(6) Using your web browser, visit setup.php (in the directory you uploaded it to) and supply the database info. Follow the instructions on screen, supplying your database info and creating your administrative user account.
(7) Visit index.php to browse your guestbook directory as a visitor, or /admin/ to administrate it.

-------
Upgrade
-------

To upgrade from 1.20 - 1.22:
(1) Upload all files to overwrite the existing files, EXCEPT your /templates/ and /attachments/ directories and config.php (keep your old copies of those).

To upgrade from 1.11:
(1) Upload all files to overwrite the existing files, EXCEPT your templates and attachments directories and config.php.
(2) Overwrite the templates sign.tpl, register.tpl, viewcomments.tpl

To upgrade from 1.10:
(1) Upload all files to overwrite the existing files, EXCEPT your templates and attachments directories and config.php.
(2) Overwrite the /admin subdirectory of your templates directory.
(3) Overwrite the templates sign.tpl, register.tpl, viewcomments.tpl
(4) Re-do all WSN Codes in your admin panel -- you will now need to specify the [] and <> inside the codes instead of them being assumed as they were before. (This change makes an image tag possible, along with some other new types of tags.)

To upgrade from 1.0x:
(1) Upload all files to overwrite the existing files, EXCEPT your templates directory and config.php.
(2) CHMOD 777 your attachments directory.
(3) Overwrite the /admin subdirectory of your templates directory.
(4) Overwrite or update these templates: codes.tpl, edit.tpl, editmembers.tpl, editcomments.tpl, main.tpl, memberlist.tpl, register.tpl, sign.tpl, viewprofile.tpl, viewcomments.tpl
(5) Visit upgrade.php in your web browser.

----------------------
Administration
----------------------

To login to your admin center, use the username and password you created during the setup process. After you login, you'll see all the settings you can change.

At the top of the screen you'll see any entries or comments or members which are awaiting validation. Below that are the main administration links, where you can change your settings, language, templates, etc. Be sure to change your settings after you install.

To change the permissions users have, such as what pages they can view and tasks they can perform, click 'manage usergroups'. If you want to add a new field, such as a new entry field for guests to fill in when signing your guestbook, click 'add fields'. If you wish to add smilies or codes, or censor words, click 'WSN Codes and Smilies'. If something odd has happened to cause the count of the number of comments per entry or number of entries or comments per member to be off, choose 'regenerate counters' to fix it. If for some reason you wish a static page rather than a PHP page, click 'generate static page' to write to an HTML file.

Further down you have the option of selecting entries or categories or members to edit. Select terms from the dropdowns and write in values to form the query you want, and if there are multiple matches you'll then have a chance to select which one you want. Editing also allows you to delete.

----------------------
Customizing
----------------------

You will, no doubt, want your own thank you messages and other confirmations in place of the generalized default e-mails. To customize the text of outgoing e-mails, along with all other text, click 'manage languages' in your admin panel. Then select 'E-mails' from the list. 

Basic colors and style can be changed all at once by using style.css, which is in your /templates/default directory. Familiarity with CSS is recommended, but the file is organized so that playing around with the existing color values should make it easy to change the colors of page elements.

WSN Guest is fully customizable. 100% of HTML and language is customizable. The HTML is in template files, which can be edited using any text editor or more conviniently through the online interface. (Click 'manage templates' on your admin panel.) These files are stored in your /templates/default subdirectory, and are named with the .tpl extension. To edit templates, either use the interface in your admin section or use your favorite text or HTML editor to load the .tpl file which you wish to edit as plain text. You can edit this just like any other HTML, but with one difference: there are template variables involved. Template variables look like this: {VARNAME}. Their function is to serve as a place holder for the dynamic content which the php files will generate. For example, a variable {ENTRYNAME} in a template might be a place holder for the name of the guest for each particular entry in your guestbook. Customize the HTML around this however you wish... for example, you could use the HTML <i>{ENTRYNAME}</i> to display the name in italics.In your online template editing section, you can click to view a list of some of the template variables. Experiment, see what they do. Note that many of the template variables are of the form {LANG_SOMETHING}... these are language variables, and you can customize the text which they will be replaced with at run time by visiting the 'manage languages' section of your admin panel. To find a specific template language variable in the language section, select to filter the view to items where the name is what you have when you remove {LANG_ and } from what you saw in the template.

You may use multiple template sets simply by uploading the files and then adding through the 'manage templates' area of your admin section. You may also use multiple language sets.

----------------------
Adding Fields
----------------------

Suppose you want to let guests specify their occupation, in addition to all the other items on the 'sign guestbook' page. To do this, click 'add fields' in your admin panel. Select 'entry field', and type a unique name for the new field... in this case, we'll call it 'occupation'. Simply click to add it. If your templates are chmoded correctly, the script will automatically make some changes to your current template set... the HTML inserted is simply a rough version with the essential content, so you'll want to go back and edit it to fit your design. You'll also see a screen telling you that your new entry variable is {ENTRYOCCUPATION}.

Edit your 'main' template, and place {ENTRYOCCUPATION} where you want it on the entry display... perhaps, for example, you might insert "Occupation: {ENTRYOCCUPATION}" right above "{LANG_VIEW_CITY} {ENTRYCITY}". Submit these changes. Next, visit your 'edit entry' template and scroll to the bottom until you see the area that says "occupation: <input type=text name=occupation value="{ENTRYOCCUPATION}"". Move this up to where you want it to appear on the entry editing page when you edit an entry. Presuming you checked the box to make it a user submittable field, you'll also find similar text at the bottom of your 'sign guestbook' template... adapt it to your template in the same way.

You can add as many new fields as you like, there are no limits.

----------------------
Custom Templates
----------------------

If you wish to add custom templates, this is a simple process. You can make an existing WSN Guest page use a template other than the normal one, or you can add a new page which will use the WSN Guest header and footer but will be otherwise new content.

In notepad or some other text editor, simply create a file and give it the name you want, then upload it to your templates directory. Use it anywhere by adding &custom=yes&TID=yourtemplatefilename to the URL. This works for any .tpl file... for other extensions, use &custom=yes&TID=yourtemplatefilename&ext=yourotherextension

For a new template where the file is called example.tpl, for example, you might use http://yoursite.com/guestbook/index.php?custom=yes&TID=example&ext=tpl

If for whatever reason you don't want the header and footer to show around your custom template, use &headerfooter=no at the end of your URL.

Add these custom templates to the template editing section of your administrative area by editing the 'templates' template... put the link to the custom templates in the same form as the URLs of the others, but with the TID being your template file's name. Note that to indicate a subdirectory there you'll need to use - instead of /

Note that you can use toplists and member template variables in any custom template.

----------------------
Toplists
----------------------

You can place a toplist on any page. Use code in this style:
<!-- BEGIN TOPLIST 1 -->
<CONFIG>entries,numcomments,10,descending,country='Canada',0</CONFIG>
{ENTRYNAME} from {ENTRYCITY} <br>
<!-- END TOPLIST 1 -->

This would display the names of the 10 most commented on Canadian guests and the cities they're from.

The config section there controls the type of toplist you get: type,field,number,order,condition,start. The last two items are optional, leave them off if you don't want to filter and you want to start at the beginning.

The example config line above makes a toplist of entries ordered by their number of comments, showing 10 entries in descending order, limited to only Canadians, and not skipping past any of these defined results. 

The first term in the example specifies that this is a list of entries. You could put comments or members there instead to make a list of those. The 2nd term specifies the field which we're ordering by... in this case, the number of comments. The third term specifies that we want to display the top 10. The fourth term says that we wish to start from the highest number and descend... if we wished to show lowest to highest, we'd use 'ascending' instead. The fifth term, which is optional, says that we want to only use those items where the country field is equal to 'Canada'... if instead we wanted to for example limit this to where there are more than 5 comments, we'd put numcomments>5. The sixth term is also optional, and lets you specify to skip over x number of results. If you wanted to split this into multiple pages, for example, you could want to start at 10 for the 2nd page.

If you want more than one toplist on the same page, the 2nd one must use the number 2 in the beginning and end declaration... and the third uses 3, et cetera. If they're on different pages this doesn't matter and you can just use 1.

If you want to show randomly selected entries, use rand() in place of the field. For example, <CONFIG>entries,rand(),10,ascending</CONFIG> would display 10 random entries.

If you want a numbered list (for example, a top 10), use {NUMBER} where you want the number displayed. 

Be careful to check after changing a toplist to be sure it worked. If you make a little mistake, you'll end up with errors on the page... thus, always be prepared to change it back and don't assume that you couldn't have made a typo. Of course it won't cause any problems that can't be fixed by simply changing/removing the toplist, but it's not good for visitors to see such errors.

----------------------
Custom Permissions
----------------------

You may wish to restrict a page to only be viewable to particular usergroups. For example, you may have a custom template page which you only want registered members to be able to view. This can be done very simply by placing a comment like this at the very top of the template:

<!-- RESTRICT TO GROUPS 2,3 -->

Change 2,3 to the numbers of the usergroups you wish to allow to view the page. Separate each usergroup number with a comma, no spaces. By default, of course, pages are visible to all groups (except where usergroup permissions specify otherwise).

----------------------
PHP in templates
----------------------

PHP can be used in any template, including custom templates. Simply put <?php at the beginning and ?> at the end of your PHP section. The one main point to be aware of is that you should not put any database or password info in this templated php -- if you need to use important info, save it in a file with a .php extension and then include that file into your template. Only files with .php extensions are safe... it would be easy for anyone to come along and read your template file by looking for /templates/yourtemplate.tpl on your site. 

To use any pre-existing variables from the script you will have to declare them as global first. When using your own variables, as of course most users would be, this is a non-issue. 

-------------------
Integrating Member Databases
----------------------

If you wish to use an existing member database, such as one from a forum, you will need to install WSN Guest in the same database as the script whose member system you will be using. Then, have a look at the pre-made integration scripts in your 'integration' subdirectory. You may adapt these files to integrate with other scripts. To make your new integration script selectable from the settings page, edit the lists at the top of admin/admincommonfuncs.php: 

 $integrationscripts = ", vbulletin, invision, phpbb";
 $integrationscripttitles = "None, vBulletin 3.00, Invision Board, phpBB";

To add on an OpenBB convertor which you have named openbb.php, you would change the above to 

 $integrationscripts = ", vbulletin, invision, phpbb, openbb";
 $integrationscripttitles = "none, vBulletin 3.00, Invision Board, phpBB, OpenBB";

If the script you're integrating with uses a method other than md5 to encode passwords, you will need to make an encoder file similar to the one for vBulletin which has been provided. You must name this with the same name as your main integration file plus 'encoder', the same naming style  as used with the vbulletin example.

Please note that you will need to remove the edit profile and register links, the memberlist link, and the profile links from your templates (the links are in footer.tpl, main.tpl, and viewcomments.tpl respectively) -- those features will not function correctly when you're using the foreign member database, it's up to the script whose member database you're using to handle those tasks. You may wish to replace the links in the WSN Guest templates with direct links to the other script's registration, memberlist, profiles and profile editing sections.

If the username field is not 'name' you will also need to change {MEMBERNAME} in your footer tempate to {MEMBERNEWNAME} (where NEWNAME is whatever the name field has now become).

If you wish to be able to track the number of entries or comments per member while using a custom member database, you must add these fields to your script's database table: entries, comments.
Then add these lines to your integration script below "$newemail = 'email';":

$newentries = 'entries';
$newcomments = 'comments';

The same procedure applies if you're using multiple languages and template sets and wish to allow users to select those. Custom member fields would also work the same way, by adding a $newthefield = 'thefield' line.

Note: If you're integrating with another WSN script (WSN Links, etc.) then registration should work seemlessly and if you add $newlanguage = 'language'; and $newtemplate = 'template'; then all fields will work and the member list and profiles will function just as if it were the natural members table. Of course this will require that you first ensure that your templates and language are named the same in both scripts.

If you choose an integration system and it does not function, use this query in phpmyadmin to fix it so that you can login again: UPDATE wsnguest_settings SET content='' WHERE name='integration'

----------------------
Further Help
----------------------

If you're wondering how to do something or don't understand a feature, ask around on the forum: http://www.webmastersite.net/forums/WSN_Guest

----------------------
WSN Software
----------------------

Thanks for choosing WSN Guest. If you like it, please consider the more recent, more powerful and well-maintained WSN scripts: 

WSN Links ( http://www.wsnlinks.com ) - A powerful and customizable directory script.
WSN Gallery ( http://www.wsngallery.com ) - A media gallery for everything from images to videos.
WSN Knowledge Base ( http://scripts.webmastersite.net/wsnkb ) - FAQ / manual / knowledge base script.
WSN FormEmail ( http://scripts.webmastersite.net/wsnform ) - Simple yet very flexible form-to-email script.
WSN Forum ( http://www.wsnforum.com ) - A full-featured and highly customizable discussion forum script.
Return current item: WSN Guest