modules/userpoints/README.txt

$Id: README.txt,v 1.4.2.1.2.7 2008/02/11 03:52:40 kbahey Exp $

Copyright 2005-2008 http://2bits.com

Description
-----------
The userpoints and userpoints_basic module provides the ability for users to gain
points with the do certain actions, such as:

- posting a node (different points can be awarded for different
  node types, e.g. page, story, forum, image, ...etc.)
- posting a comment
- moderating a comment

Upon deleting a node or a comment the number of points is subtracted.
If a node or comment author is changed points are transferred respectively

The number of points for each of the above actions is configurable by
the site adminsitrator.

A transaction log is created for each event. The log is viewable by
the admin.

Points can be moderated, i.e. approval can be done by the admin at a later
time.

A block displays the number of points the user gained. Another block 
displays the top 5 users who earned points.

----
Using modules from the project http://drupal.org/project/userpoints_contrib 
point can be awarded for other actions. 
including:
- voting on a node (requires the nodevote module)
- referring a person to the site (requires referral module)
- a visitor comes to the site via clicking on an affiliate link
  (requires the affiliates module)
- voting up or down a node (requires the vote_up_down module)
- inviting a person to register on the site (requires invite module)
- invited person actually registers on the site
- purchasing from your e-commerce store (reward points)

Using real money, users can purchase points from your ecommerce store
as well. Moreover, the points can be used as currency for ecommerce as well,
as in a form of payment


This module is useful in providing an incentive for users to participate
in the site, and be more active. The module is easily extended through use of 
the API (see below)


Initally sponsored by: http://artalyst.com

Installation
------------
To install this module, do the following:

1. Extract the tar ball that you downloaded from Drupal.org.

2. Upload the userpoints directory and all its contents to your
   modules directory.

Configuration
-------------
To enable this module do the following:

1. Go to Admin -> Modules, and enable userpoints.
   Check the messages to make sure that you did not get any errors
   on database creation.

2. Go to Admin -> Settings -> userpoints.

   Configure the options as per your requirements

3. Go to Admin -> Access Control and enable viewing for the roles you want.

For configuring with e-commerce, you have to have the ecommerce modules
installed and configured.

- User points can be used as a form of payment, with an admin defined
  multiplier

- Users gain points when purchasing items via e-commerce for every dollar
  they spend.

This is useful as a reward system.

This also allows purchasing of points for real money. You have to setup
a non-shippable product, and adjust the multiplier accordingly.

API
---
This modules provides an application programming interface (API), which is
callable and actionable by other modules.

The functions are:

userpoints_userpointsapi()

  Accepts an integer or an array. 
  If the parameter is an integer it is assumed to be points 
  for the currently logged in user (i.e. global $user; $user->uid) 

  If the parameter is an array the array can contain one or more of the
  following options. The only required parameters are 'points' or 'txn_id'
  If a parameter is not set the site settings will used. Setting a parameter 
  to NULL will cause the entry to be NULL, defaults are only used if the 
  parameter is not set

  Returns an array with a status (true/false) and a reason (string) if there
  is an error. example
  return array('status' => false, 'reasaon' => 'DB transaction failed');
  
  'uid'         => (int) User ID 
  'points'      => (int) # of points to award the user 
  'txn_id'      => (int) Transaction ID of a current points record. If
                         present an UPDATE occurs
  'moderate'    => (boolean) TRUE or FALSE. If NULL site settings are adhered to
  'description' => (string) fulltext Description presented to the user
  'expirydate'  => (timestamp) timestamp the date/time when the points will
                               be expired (depends on cron)
  'event'       => (string) varchar32 descriptive identifier administrative purposes
  'reference'   => (string) varchar32 indexed/searchable field on the DB
  'display'     => (boolean) Whether or not to display the "Points awarded"
                             message. If null, fall back to USERPOINTS_DISPLAY_MESSAGE
  'tid'         => (int) Taxonomy ID to place these points into; MUST BE in
                         the userpoints Vocabulary!

  Examples
    //Add 5 points to the currently logged in user
    userpoints_userpointsapi(5);  

    //Also add 5 points to the currently logged in user
    $params = array (
      'uid' => $user->uid,
      'points' => 5,
    );
    userpoints_userpointsapi($params); 

  
//---Hooks
hook_userpoints($op, $points, $uid, $event) 

  Use this hook to act upon certain operations. When other modules award
  points to a user, your hook will be called, among others.

  The arguments are:

  $op: The operation to be acted upon.
    'setting'
      Pass a field set and fields that would be displayed in the userpoints
      settings page. For example, this can be used for your program to ask
      the admin to set a number of points for certain actions your module
      performs. The function should return an array object conforming to
      FormsAPI structure.

    'points before'
      Calls your module, and others, before the points are processed. You can
      prevent points from being awarded by returning FALSE.

    'points after'
      Calls your module, and others, after points are processed. You can take
      certain actions if you so wish. Return value is ignored.

   The rest of the arguments are the same as the userpoints_userpointsapi()
   function.
 
//---Other useful functions

userpoints_get_current_points($uid = NULL, $tid = NULL);
  Returns an integer of the sum of the user's point 
  If a tid is passed in that category's sum is returned otherwise
  the sites default category is used

userpoints_get_max_points($uid = NULL, $tid = NULL);
  Returns an integer of the sum of the user's max points achieved
  If a tid is passed in that category's sum is returned otherwise
  the sites default category is used

userpoints_get_vid()
  Returns an integer of the userpoints Vocabulary

userpoints_get_default_tid()
  Returns an integer for the userpoints default Taxonomy ID
  Note: this is the default when submitting points so you 
        DO NOT need to pass this into userpoints_userpointsapi

userpoints_get_categories()
  Returns an array of the possible categories including
  the special "Uncategorized" category (id=0). This is a keyed
  array that works perfectly with FAPI. If you're creating a 
  settings page wherein a user would select the category to 
  place points into, this will give you exactly what you need.
  See userpoints.module admin_settings function for an example.

userpoints_get_default_expiry_date()
  Returns a UNIX timestamp of the site's default expiration date.
  If an expiration date (or interval) it will be returned otherwise NULL

XML-RPC
-------

Using the userpoints_services module, and the services modules, you 
can allow external applications to query and update points on your
site.

Please refer to the services module documentation for further information.

Userpoints provides the follwing XML-RPC calls:

userpoints.get 

  string api_key (required)
    A valid API key.
  int uid (required)
    A valid Drupal User ID.
  int tid (optional)
    An optional Term ID for the category.

Example:

  $result = xmlrpc($server_url, 'userpoints.get', $key, $uid, $tid);
  // $result is an array
  // 'points' => 123

userpoints.points

  string api_key (required)
    A valid API key.
  int uid (required)
    A valid Drupal User ID.
  int points (required)
    Number of points to add/subtract.
  int tid (optional)
    An optional Term ID for the category.
  string event (optional)
    An optional event ID for this transaction.
  string description (optional)
    An optional description of this transaction.

Example:

  $result = xmlrpc($server_url, 'userpoints.points', $key, $uid, $points, $tid, $event, $description);
  // $result is an array
  // 'status'
  //   1 => Success
  //   0 => Fail
  // 'reason'
  //   Textual reason for failure, if status is 0

Bugs/Features/Patches:
----------------------
If you want to report bugs, feature requests, or submit a patch, please do so
at the project page on the Drupal web site.
http://drupal.org/project/userpoints

Author
------
Khalid Baheyeldin (http://baheyeldin.com/khalid and http://2bits.com)

If you use this module, find it useful, and want to send the author
a thank you note, then use the Feedback/Contact page at the URL above.

The author can also be contacted for paid customizations of this
and other modules.

1	$Id: README.txt,v 1.4.2.1.2.7 2008/02/11 03:52:40 kbahey Exp $
2
3	Copyright 2005-2008 http://2bits.com
4
5	Description
6	-----------
7	The userpoints and userpoints_basic module provides the ability for users to gain
8	points with the do certain actions, such as:
9
10	- posting a node (different points can be awarded for different
11	node types, e.g. page, story, forum, image, ...etc.)
12	- posting a comment
13	- moderating a comment
14
15	Upon deleting a node or a comment the number of points is subtracted.
16	If a node or comment author is changed points are transferred respectively
17
18	The number of points for each of the above actions is configurable by
19	the site adminsitrator.
20
21	A transaction log is created for each event. The log is viewable by
22	the admin.
23
24	Points can be moderated, i.e. approval can be done by the admin at a later
25	time.
26
27	A block displays the number of points the user gained. Another block
28	displays the top 5 users who earned points.
29
30	----
31	Using modules from the project http://drupal.org/project/userpoints_contrib
32	point can be awarded for other actions.
33	including:
34	- voting on a node (requires the nodevote module)
35	- referring a person to the site (requires referral module)
36	- a visitor comes to the site via clicking on an affiliate link
37	(requires the affiliates module)
38	- voting up or down a node (requires the vote_up_down module)
39	- inviting a person to register on the site (requires invite module)
40	- invited person actually registers on the site
41	- purchasing from your e-commerce store (reward points)
42
43	Using real money, users can purchase points from your ecommerce store
44	as well. Moreover, the points can be used as currency for ecommerce as well,
45	as in a form of payment
46
47
48	This module is useful in providing an incentive for users to participate
49	in the site, and be more active. The module is easily extended through use of
50	the API (see below)
51
52
53	Initally sponsored by: http://artalyst.com
54
55	Installation
56	------------
57	To install this module, do the following:
58
59	1. Extract the tar ball that you downloaded from Drupal.org.
60
61	2. Upload the userpoints directory and all its contents to your
62	modules directory.
63
64	Configuration
65	-------------
66	To enable this module do the following:
67
68	1. Go to Admin -> Modules, and enable userpoints.
69	Check the messages to make sure that you did not get any errors
70	on database creation.
71
72	2. Go to Admin -> Settings -> userpoints.
73
74	Configure the options as per your requirements
75
76	3. Go to Admin -> Access Control and enable viewing for the roles you want.
77
78	For configuring with e-commerce, you have to have the ecommerce modules
79	installed and configured.
80
81	- User points can be used as a form of payment, with an admin defined
82	multiplier
83
84	- Users gain points when purchasing items via e-commerce for every dollar
85	they spend.
86
87	This is useful as a reward system.
88
89	This also allows purchasing of points for real money. You have to setup
90	a non-shippable product, and adjust the multiplier accordingly.
91
92	API
93	---
94	This modules provides an application programming interface (API), which is
95	callable and actionable by other modules.
96
97	The functions are:
98
99	userpoints_userpointsapi()
100
101	Accepts an integer or an array.
102	If the parameter is an integer it is assumed to be points
103	for the currently logged in user (i.e. global $user; $user->uid)
104
105	If the parameter is an array the array can contain one or more of the
106	following options. The only required parameters are 'points' or 'txn_id'
107	If a parameter is not set the site settings will used. Setting a parameter
108	to NULL will cause the entry to be NULL, defaults are only used if the
109	parameter is not set
110
111	Returns an array with a status (true/false) and a reason (string) if there
112	is an error. example
113	return array('status' => false, 'reasaon' => 'DB transaction failed');
114
115	'uid' => (int) User ID
116	'points' => (int) # of points to award the user
117	'txn_id' => (int) Transaction ID of a current points record. If
118	present an UPDATE occurs
119	'moderate' => (boolean) TRUE or FALSE. If NULL site settings are adhered to
120	'description' => (string) fulltext Description presented to the user
121	'expirydate' => (timestamp) timestamp the date/time when the points will
122	be expired (depends on cron)
123	'event' => (string) varchar32 descriptive identifier administrative purposes
124	'reference' => (string) varchar32 indexed/searchable field on the DB
125	'display' => (boolean) Whether or not to display the "Points awarded"
126	message. If null, fall back to USERPOINTS_DISPLAY_MESSAGE
127	'tid' => (int) Taxonomy ID to place these points into; MUST BE in
128	the userpoints Vocabulary!
129
130	Examples
131	//Add 5 points to the currently logged in user
132	userpoints_userpointsapi(5);
133
134	//Also add 5 points to the currently logged in user
135	$params = array (
136	'uid' => $user->uid,
137	'points' => 5,
138	);
139	userpoints_userpointsapi($params);
140
141
142	//---Hooks
143	hook_userpoints($op, $points, $uid, $event)
144
145	Use this hook to act upon certain operations. When other modules award
146	points to a user, your hook will be called, among others.
147
148	The arguments are:
149
150	$op: The operation to be acted upon.
151	'setting'
152	Pass a field set and fields that would be displayed in the userpoints
153	settings page. For example, this can be used for your program to ask
154	the admin to set a number of points for certain actions your module
155	performs. The function should return an array object conforming to
156	FormsAPI structure.
157
158	'points before'
159	Calls your module, and others, before the points are processed. You can
160	prevent points from being awarded by returning FALSE.
161
162	'points after'
163	Calls your module, and others, after points are processed. You can take
164	certain actions if you so wish. Return value is ignored.
165
166	The rest of the arguments are the same as the userpoints_userpointsapi()
167	function.
168
169	//---Other useful functions
170
171	userpoints_get_current_points($uid = NULL, $tid = NULL);
172	Returns an integer of the sum of the user's point
173	If a tid is passed in that category's sum is returned otherwise
174	the sites default category is used
175
176	userpoints_get_max_points($uid = NULL, $tid = NULL);
177	Returns an integer of the sum of the user's max points achieved
178	If a tid is passed in that category's sum is returned otherwise
179	the sites default category is used
180
181	userpoints_get_vid()
182	Returns an integer of the userpoints Vocabulary
183
184	userpoints_get_default_tid()
185	Returns an integer for the userpoints default Taxonomy ID
186	Note: this is the default when submitting points so you
187	DO NOT need to pass this into userpoints_userpointsapi
188
189	userpoints_get_categories()
190	Returns an array of the possible categories including
191	the special "Uncategorized" category (id=0). This is a keyed
192	array that works perfectly with FAPI. If you're creating a
193	settings page wherein a user would select the category to
194	place points into, this will give you exactly what you need.
195	See userpoints.module admin_settings function for an example.
196
197	userpoints_get_default_expiry_date()
198	Returns a UNIX timestamp of the site's default expiration date.
199	If an expiration date (or interval) it will be returned otherwise NULL
200
201	XML-RPC
202	-------
203
204	Using the userpoints_services module, and the services modules, you
205	can allow external applications to query and update points on your
206	site.
207
208	Please refer to the services module documentation for further information.
209
210	Userpoints provides the follwing XML-RPC calls:
211
212	userpoints.get
213
214	string api_key (required)
215	A valid API key.
216	int uid (required)
217	A valid Drupal User ID.
218	int tid (optional)
219	An optional Term ID for the category.
220
221	Example:
222
223	$result = xmlrpc($server_url, 'userpoints.get', $key, $uid, $tid);
224	// $result is an array
225	// 'points' => 123
226
227	userpoints.points
228
229	string api_key (required)
230	A valid API key.
231	int uid (required)
232	A valid Drupal User ID.
233	int points (required)
234	Number of points to add/subtract.
235	int tid (optional)
236	An optional Term ID for the category.
237	string event (optional)
238	An optional event ID for this transaction.
239	string description (optional)
240	An optional description of this transaction.
241
242	Example:
243
244	$result = xmlrpc($server_url, 'userpoints.points', $key, $uid, $points, $tid, $event, $description);
245	// $result is an array
246	// 'status'
247	// 1 => Success
248	// 0 => Fail
249	// 'reason'
250	// Textual reason for failure, if status is 0
251
252	Bugs/Features/Patches:
253	----------------------
254	If you want to report bugs, feature requests, or submit a patch, please do so
255	at the project page on the Drupal web site.
256	http://drupal.org/project/userpoints
257
258	Author
259	------
260	Khalid Baheyeldin (http://baheyeldin.com/khalid and http://2bits.com)
261
262	If you use this module, find it useful, and want to send the author
263	a thank you note, then use the Feedback/Contact page at the URL above.
264
265	The author can also be contacted for paid customizations of this
266	and other modules.
267