Copyright (c) 2002 by Brian K. Virgin (webmaster@madhatt.info)
http://www.madhatt.info
PostNuke Web Portal System - http://www.postnuke.com

 
===============================================================================
LICENSE
===============================================================================


This program is free software; you can redistribute it and/or modify it under
the terms of the GNU General Public License (GPL) as published by the Free
Software Foundation; either version 2 of the License, or (at your option) any
later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY
WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
PARTICULAR PURPOSE.  See the GNU General Public License for more details.

To read the license please read the docs/license.txt or visit:
http://www.gnu.org/copyleft/gpl.html


===============================================================================


Filename:			User Points		readme.txt
Original Author of file:	Vincent Tan Teck How
Based on:			User Points System	(phpnuke)
Conversion/Cleaning/Addons:	Brian K. Virgin (aka 'MADHATter7')
Purpose of file:		Documentation for the User Points Module


===============================================================================
DESCRIPTION
===============================================================================


Or, what is the User Points Module ? The User Points Module is simply an addon
that calculates points for your site members based upon how much they
contribute to your site. Nearly every action they perform is tracked and
scored, based on each actions value as set by you.


===============================================================================
REQUIREMENTS
===============================================================================


Base Requirements:			PostNuke 0.70+
					properly configured database
					Members to your site	:-)


===============================================================================
PACKAGE CONTENTS
===============================================================================


> NS-User_Points/
	admin/				Future home of the Admin Utility
	docs/				Documentation directory
	lang/				Language definition directory
	plugins/			Module plugins directory (see below)
	funcs.php			Utility functions/settings
	index.php			Main file for the Module
	readme.txt			The file you are reading   :-)
	user_points.sql			SQL database file to build the db table

> NS-User_Points/admin/:
	Currently this section is being written, so this directory is empty

> NS-User_Points/docs/:
	changelog.txt			Changelog for the module
	credits.txt			Credit to those who deserve it  :-)
	install.txt			Installation instructions
	license.txt			Copy of the license for this Module

> NS_User_Points/lang/:
	eng/				English Language defines directory
		global.php		English defines main file

> NS-User_Points/plugins/:
	XForum.php			Scoring function for XForum 1.5B0
	phpBB.php			Scoring function for phpBB 1.4
	Postboard.php			Scoring function for Postboard 0.70


===============================================================================
INSTALLATION
===============================================================================


Module installation is very simple:

(1) Unpack the User Points package into a temporary directory.

(2) Copy the entire NS-User_Points directory into your modules/ directory.

(3) If your database uses a prefix other than "nuke", make the corresponding
    change in the user_points.sql file. If you do use the prefix "nuke", then
    simply proceed to step 4.

(4) Run the user_points.sql file in the method of your choice.

(5) Make any configuration changes you wish to, as explained below.

(6) Enjoy your new Module !


===============================================================================
CONFIGURATION
===============================================================================


This module allows for several configuration options, which we will now discuss.
All configuration changes are to be made in the funcs.php file as this file
holds all of the options which you will want/need to change.

(1) Changing the number of Members displayed:
	Controlled by the $toshow variable, as defined on line 34 in the
	funcs.php file. Change it to how ever many Members you want to be
	displayed. The default is 20.

(2) Changing the refresh period:
	Controlled by the $refreshtime variable, as defined on line 43 in the
	funcs.php file. This setting will allow you to configure when the tables
	are updated again. Using this setup permits us to not calculate points
	and update tables everytime the Module is viewed. Also, it allows you
	to have "Members of the Week" or "Members of the Month", etc. Below is
	a listing of popular settings for the $refreshtime variable:


		If you want	The actual	Set
		the table to	length of	$refreshtime
		refresh every:	time used:	to:
		---------------------------------------
		 1 hour				   3600
		12 hours	(1/2 day)	  43200
		24 hours	(1 day)		  86400
		1 week		(7 days)	 604800
		1/2 month	(15 days)	 907200
		1 month		(30 days)	2592000
	
	So, if you wanted to have a "Member of the Day", for instance, then
	you would set $refreshtime = 86400; in funcs.php on line 43. The
	default is 604800 (1 week).

(3) Changing the Forums:
	The variable $forums, as defined on line 51, is where the Module looks
	to when it prepares to calculate scoring for your users forum posts. This
	has been built in such a way so that all that should be required is for
	you to change this setting to whatever Forums module you are running and
	then putting the appropriate file in the plugins directory.
	
	For example, let's assume you use the Postboard .7 forums module on your
	site. In order to properly configure this Module to calculate points for
	your members posts in the forums, just change the $forums variable from
	"XForum" to "Postboard" at line 51 in the funcs.php file. That's it,
	nothing more required. The Module will read this variable and search
	the plugins/ directory and load the function it needs to score forum
	posts on your site. (Postboard function is included --see below)

	If, however, you do not use a forums module at all on your site, then
	setting $forums = "none"; on line 51 in the funcs.php file is, for all
	intents and purposes, turning off the scoring for forums.

	So what happens if I set forums to equal something that is not in the
	plugins/ directory, you ask ? This will effectively turn off scoring
	for forum posts on your site as well. For those of you wondering why,
	the answer is to provide as much functionality as possible without the
	dreaded "DB Error: 1046 - Table [whatevername] does not exist"...

	Forum scoring functions that are already written and included in this
	package are as follows:

		Forum Name	Version		Relevant Filename
		--------------------------------------------------------	
		XForum		1.5B0		XForum.php
		phpBB		1.4		phpBB.php
		Postboard	0.7		Postboard.php

	If you are running a forum module not listed above, then contact me via
	email and I will write the function for you. If, however, you write
	code yourself and create the function on your own, the send it to me
	and I will include it in the package, giving you full credit of course.
	The default Forums the module looks for is XForum.

(4) Changing the score values:
	The scoring values for each action is controlled by the $score array,
	as defined in lines 57 - 67 in the funcs.php file. This is a simple
	array organized by "action" => value. 

	If, for instance, you wanted to change the value of submitted Stories
	from 4 to 10, then you would change line number 58 from this:
	
		"stories" => 4,		// for every Story
	
	to reflect the new value of submitting a story that you are wanting,
	in this case 10. So, after you edit the line to reflect this, it would
	look like so:

		"stories" => 10,	// for every Story
	
	easy, isn't it ? Just change the values to whatever you would like them
	to be, taking care to leave all of the quotes and commas as they are,
	and you can change them all if you like. The default values for each
	Member action is as follows:

		For every:			Members get:
		----------------------------------------
		Story submitted			4 points
		Review submitted		6 points
		Comment on a Story		2 points
		Comment on a Poll		2 points
		Comment on a Review		2 points
		Download submitted		3 points
		Vote on a Download		2 points
		Web Link submitted		3 points
		Vote on a Web Link		2 points
		Each Forum post/thread		1 point

	Of course, all submission must be approved by the site Admin before any
	points are given to the Member.

(5) Changing what to score for:
	The control for what you actually want to score for is the $calc array,
	as defined on lines 74 - 84 of the funcs.php file. It is a simple on/off
	switch, with 1 [one] being on and 0 [zero] being off. If you wish to
	turn scoring off for a particular action, then simply change the value
	associated with that action in the same manner as you changed the point
	values above, only change the value from 1 to 0. The default is scoring
	on for all actions.

(6) Enjoy your new customized Module !


===============================================================================
TO-DO LIST
===============================================================================


(a)	Complete and release the Admin Utility (will replace the Configuration
	section above)

(b)	Implement the new Rogue User system

(c)	Provide a means to turn off scoring for site Admins

(d)	Implement a "troll" check.


===============================================================================
ADDITIONAL NOTES
===============================================================================


None at this time.


===============================================================================
CHANGELOG
===============================================================================


See the Changelog.txt file located in the docs/ directory.


===============================================================================
FINAL NOTES
===============================================================================


I hope you all enjoy the User Points module, Free software under the GPL
license. It comes without any warranty --but with technical support !!!
Thanks, report any feature suggestions and/or bugs to webmaster@madhatt.info.


Special thanks goes to:	John Hunter (for giving MADhatt a new home)


===============================================================================


MADHATter7 | webmaster@madhatt.info | http://www.madhatt.info


===============================================================================
