Last updated January 5, 2008. Created by jredding on December 6, 2007.
Edited by ezyang. Log in to edit this page.

Warning: This tutorial is for User Points 5.x-3.x-dev, which has a different API than 5.x-2.x. If you want to use this for the older versions, change the userpoints_userpointsapi calls in the examples to be compatible with the older API.

This tutorial shows some of the basic features that User Points offers. We will:

  • Create a page that grants points to the reader
  • Create a module for userpoints that grants points to people who post pages with attachments

Some PHP knowledge is expected, although knowledge of the Drupal core, while nice, is not necessary. The idea is that with this API, you can build arbitrarily complex schemes for assigning points based on whatever your readers can do.

Using the PHP filter and User Points

When creating content in Drupal, various input formats can be used. One of Drupal's default input formats, available only to administrators, is the PHP filter, which parses and executes PHP in the content, allowing for unparalleled flexibility. These instructions will create a simple page that gives the reader 10 points.

  1. Click Create content
  2. Click Page
  3. Type in Title: "This page gives free points!"
  4. In Body, paste this code:
    Hi, thank you for visiting this page! You have been awarded some points.
    <?php
    if (module_exists('userpoints')) {
     
    // Number of points to give to a user for viewing this page
     
    $num_of_points = 10;
     
    userpoints_userpointsapi($num_of_points);
    } else {
      echo
    "<p>Userpoints is disabled!</p>";
    }
    ?>
  5. Click Input format and select PHP Code
  6. Submit!

A few notes about the PHP code:

  • It's a good idea to check that userpoints is installed with module_exists('userpoints'), just in case you decide to disable it some time in the future. Otherwise, your pages will get mysterious fatal errors.
  • You can vary the amount of points awarded by changing $num_of_points. A low value is recommended, as people can repeatedly click Refresh to gain more points with this page
  • The function userpoints_userpointsapi does the magic. You can read more about it at the README.txt file. In this case, only one argument is being passed, which represents the number of points to assign. For added flexibility, an array can be passed.

Creating a module for User Points

Let's now create a simple module that checks if newly added pages have attachments, and then give points to the user. First, create a directory named userpoints_attachment in your modules directory. Place these two files in it:

userpoints_attachment.info

name = Userpoints Attachment
description = Gives points to users who create attachments
package = Userpoints
dependencies = userpoints

userpoints_attachment.module

<?php
function userpoints_attachment_nodeapi(&$node, $op) {
  switch(
$op) {
    case
'insert':
      if (isset(
$node->file)) {
       
userpoints_userpointsapi(10);
      }
      return;
  }
}
?>

This is a very simple module. The info file, standard module fare, describes what this module does, and the module page defines a hook_nodeapi which responds to the insert operation.

Go over to Administer and click Modules and enable this module, which should appear as Userpoints Attachment under the Userpoints module group. You can now test the module out by uploading a file.

Left as an exercise for the reader (you'll need to know about Drupal's internals to do these):

  • Make the number of points assignable by this module configurable via a administrative form
  • Try making a module for another node operation

Using the Extended API

Now, having userpoints_userpointsapi add points to the currently logged in user is quite useful, but often times you may want to assign points to another user. The syntax is a little different in that case:

<?php
// UID 1 is usually the admin account (if not, change this)
$uid = 1;
userpoints_userpointsapi(array(
 
'uid' => $uid,
 
'points' => 10
));
?>

You can substitute this in for the original userpoints_userpointsapi call to make page views give points, rather than to the reader, to the admin. You can use this in interesting ways, for example, a module that gives points to the creator of the content, awarding people for creating pages that get lots of page views. Be sure to enable this module just as before.

userpoints_pageviews.info

name = Userpoints Page Views
description = Gives points to content creators based on page views
package = Userpoints
dependencies = userpoints

userpoints_pageviews.module

<?php
function userpoints_pageviews_nodeapi(&$node, $op) {
  switch(
$op) {
    case
'view':
      global
$user;
     
// If current user is not anonymous and did not create this node...
     
if ($user->uid && $node->uid !== $user->uid) {
       
// Give the node creator some points!
       
userpoints_userpointsapi(array(
         
'uid' => $node->uid,
         
'points' => 10,
        ));
      }
      return;
  }
}
?>

The possibilities are unlimited! Go forth, and make user points plentiful among your people.

Looking for support? Visit the Drupal.org forums, or join #drupal-support in IRC.

Comments

If, instead of

<?php>
    
// If current user is not anonymous and did not create this node...
     
if ($user->uid && $node->uid !== $user->uid) {
?>

You put
<?php>
     
// If current user is not anonymous, did not create this node, the node is being viewed for the first time, and it is not being showed in the front page...
     
if ($user->uid && $node->uid !== $user->uid  && !(node_last_viewed($node->nid)) && !(drupal_is_front_page())) {
?>

You will avoid almost any means of earning points by hitting 'refresh'. But if he visits a /taxonomy/term/X page, the user will still collect undue points by refreshing the page.

Update: there's a problem with the search results page, too.

Durval Tabach

I really need the userpoints_pageviews.module module, so I followed the above directions and get the following error:
Parse error: syntax error, unexpected T_SWITCH in /home/server/public_html/techtalkforfamilies/modules/userpoints_pageviews/userpoints_pageviews.module on line 3

I'm not a php coder at all, so could someone tell me what I'm doing wrong or need to change?

Dale
http://techtalkforfamilies.com

Dale

I included this module in 5.x-3.x-dev, and 6.x-1.x-dev download. It should be available 10 hours from now.
--
Drupal performance tuning, development, customization and consulting: 2bits.com, Inc.
Personal blog: Baheyeldin.com.

--
Drupal performance tuning and optimization, hosting, development, and consulting: 2bits.com, Inc. and Twitter at: @2bits
Personal blog: Ba

Hi,

Sorry if this is a wrong place to put this question, but I would like to know how do I use the "userpoints_role_exempt" feature to exclude the admins to get points?

Thanks in advance!

Somebody can say? How to make the table where the list of users, with total points of each user will be shown?

You can accomplish that using VIEWs. Create a table of all users, their points etc and you can make it sortable as you wish.