User Points 5.x-3.x API Tutorial

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

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:

// 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

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.