User Points API Documentation
The following applies to User Points API version 3.x. User Points provides an application programming interface (API), which is callable and actionable by other modules. To use this API you simply need to enable the User Points module.
userpoints_userpointsapi(int OR array() )
This is the big daddy of all of the function calls. Use this function to grant points to users. Points can be positive or negative but must be integers and can not be decimal (ex. 5 not 5.2).
The call can either be an integer or an array of parameters. If a single integer is passed points are granted to the currently logged in user using all the site default settings. Pass in an array of parameters to override site settings and/or to ensure that certain settings are used. An direct API call takes precedence over module settings.
When using an array of parameters you must pass in either the points parameters or txn_id. All parameters passed will override site settings. To use the site settings do not pass in the parameter as a set parameter takes precedence (even if null). A list of possible parameters is listed below.
If txn_id is passed in points is not necessary. Passing in a txn_id will update the point record for the transaction ID similar to the use of node_save. It updates all of the point settings stored in the database except for uid or points. To add/subtract or move points from one user to the next you will need to make separate point grants in order to maintain a proper point history. use this function to update a points moderation status, description, expiration date, event, reference, tid, etc.
returns: array.
status: true/false TRUE = successful FALSE = problem
reason: If status is false reason will include a string description of the error for debugging purposes
Listing of parameters
'uid' => (int) User ID to grant the points to
'points' => (int) # of points to award the user (may be positive or negative)
'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)
'operation' => (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 module settings
'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); hook_userpoints($op, $points, $uid, $event)
This hook is provide so that a module may sanity check points before and/or after they are accumulated and also offer module specific settings on the userpoints administrative settings page. Userpoints strives to provide a single administrative page for all core and contributed module settings. Please use this hook to provide your module's specific administrative settings.
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.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