Yesterday I gave a general overview of point-based incentive systems as used by weblit writers. I'd suggest giving that article a read first if you aren't familiar with point systems and their usage. Today I'd like to discuss Drupal's answer to the point system: Khalid Baheyeldin's User Points Module.

User Points "provides an API for users to gain or lose points for performing certain actions on your site." Essentially, the module adds a value (or values) to each user that can be incremented up or incremented down in response to certain actions.

What You'll Need
User Points is available for Drupal 6 and Drupal 5 -- in the interest of time, I'll cover the D6 version in this article, since D6 seems more common among weblit writers. Since the basic User Points module doesn't do much on its own, we'll also be using the User Points Contributed Module Pack to give us some functionality to play around with. Since we're using Drupal 6, you'll also want to grab the User Points Nodes and Comments Module (a similar module is built into the D5 version of User Points, so you won't need Nodes and Comments if you're using D5).

This article assumes a basic working knowledge of the Drupal. If you don't know much about Drupal, I suggest checking out some of the helpful files at Drupal.org. I'm also available for specific questions through my contact form, but I'm by no means an expert on the system -- just an experienced amateur.

Installing the User Points Module
Installation of the User Points Module is a breeze. Just download and unpack the module, upload it to the modules folder of the directory that stores your Drupal site, then navigate to your "/admin/build/modules" and enable the new modules that have been added. Go ahead and upload everything from the main User Points Module, the User Points Contributed Modules Pack, and User Points Nodes and Comments. For now, let's just enable the core User Points module (it's the one with the big "Required by" list). We'll deal with the rest in a moment.

What Does What?
Go to your "administration by module" page (found at "/admin/by-module") and look for the User Points heading. First, let's set some permissions:

Permissions

• administer userpoints -- this setting lets users with this permission add, remove, and moderate point transactions. Use this only for admins.
• view own userpoints -- this setting lets users view their own userpoints, but doesn't allow them to view other people's userpoints.
• view userpoints -- this setting lets users view everyone's userpoints. Users with this permission will be able to view the userpoints total of any other user by viewing their profile.

Go ahead and enable either of the bottom two for your authenticated user role, save, then go back to your administration by module page.

Points Settings
This page offers a list of expandable options that contain settings you can tweak.

• Moderation
  -- This option gives you the choice between Approved and Moderated userpoints. Selecting Approved means that all transactions will automatically approved, while Moderated means that you (or someone else with the administer userpoints permission) must approve transactions before they'll be reflected in point totals. For the automated point system we'll be trying to construct, you'll probably want to use the Approved option.
• Points Branding
  
  -- This option lets you set what you want to call your points. For the purpose of this article, we'll continue to use the term userpoints, but you could name them whatever you want: gold, experience, coffee beans, tokens, etc. You can also set the name of the Uncategorized category of points (the main category all points will be added to unless otherwise specified). If you aren't planning on having multiple point currencies, you might as well leave this alone.
• Points Expiration
  
  -- This option lets you decide when (and if) points expire, based either on an arbitrary period in the future (i.e., one hour/one day/two weeks/one year from the time points are awarded) or on a specific date (i.e., all points expire on Jan 1, 2025). You can also set a description to be applied to expired points so users will know why their points expired. If you don't have a plan for expiration of points, it's probably best to set their expire rate to Never.
• Messages
  
  -- This option lets you decide whether or not to show a message (styled like normal Drupal system messages, usually at the top of the content block) to the user whenever points are awarded. If you set this to No, points will still be awarded, but there'll be no notification saying so.
• Report Settings
  
  -- This option lets you decide how to show your reports, including how many point transactions to show per page, whether or not to display users with zero points, and how many users to show per page.
• Points Categorization
  
  -- Lets you set the default category for points (if you have more than one category) and decide which category to show on the profile page. Best to leave this alone unless you have multiple point currencies.
• Transaction Stamping
  
  -- Lets you decide whether or not to use system time to stamp transactions. Enabled by default, and unless you have some need for special time stamps, best to just leave it enabled.

Change any settings you like, save, then go back to your Administration by Module page.

Points
This page, by default set to the List tab, lets you view a list of users and their point totals. The username is linked to the user's profile, followed by a link that will show you a detailed list of point transactions involving that user. The Moderation tab shows you point transactions that need to be approved (will be blank if you've set point transactions to auto-approve). The Add tab allows you to manually add points to a user, including the ability to add a reference note and/or description to the transaction. Go ahead and play around with manually adding and subtracting points from users if you want to. You can also manually give a user points by viewing their profile and clicking the Adjust link next to their point total.

Adding Functionality
As you can see, the core user points module doesn't do much on its own. Now we'll enable some of those contributed modules that we installed to automate a few parts of our point system. Go back to your modules page (/admin/build/modules).

Go ahead and enable the following modules:

• Role Exempt
• User Points Node Limit
• User to User Points
• Userpoints Admin Email
• Userpoints Cap
• Userpoints Comments by Type
• Userpoints No Negative
• Userpoints Nodes and Comments
• Userpoints Page Views
• Userpoints Register
• Userpoints Reset
• Userpoints Retroactive
• Userpoints Role

Some of these modules will create their own administration pages, some will add new options to the main User Points settings page, and some don't have administration pages at all. We'll take them in order:

Role Exempt
Configurable under the Points setting (/admin/settings/userpoints) page. This simply lets you pick one or multiple roles that are exempt from earning points. Useful for admins, or if you want to create a punishment role to temporary prevent belligerent users from earning points.

User Points Node Limit
Configurable under your Content types page (/admin/content/types). Edit an existing content type and you'll see a new expandable option at the top titled "User points node limit settings." For each content type, you can choose to enable userpoints node limitation, and decide how many points a user needs to be able to create a content of that type. Since your users likely won't be creating many nodes themselves, this is of limited use to the weblit author, but you might find some ideas for it -- for example, require that a user has 10 points before they're allowed to post forum topics.

User to User Points
Configurable under the Points setting page. This module lets your users send points to one another. The settings page lets you set a few details about the send userpoints interface, whether or not to allow users to pick a category to draw points from (only useful if you have multiple currencies) and whether or not to show a Send Points link on nodes that will allow users to send points to the Node's Author. Even with the module enabled, only users with the user2userpoints_send permission (configurable on the Permissions page) will be able to use the functionality.

Userpoints Admin Email
Configurable under the Points setting page. Allows you to set a point threshold. Whenever any user reaches the specified number of points, the system will send an e-mail to the admin. Only allows one threshold to be set; it's possible to set multiple thresholds, but that's a topic for the advanced article.

Userpoints Cap
Configurable under the Points setting page. Allows you to set a cap on the number of points that a user may earn. If the user reaches the cap, they won't be able to earn more points and will instead be shown a configurable message. I'm not sure how this module handles multiple currencies -- if I had to guess, it probably takes a total of all points across all categories and compares that against the cap: i.e., if you set your cap at 5 and your user has 2 Gold and 3 Cookies, they wouldn't be able to earn more Gold or more Cookies until they get rid of one or the other. Again, just a guess.

Userpoints Comments by Type
Configurable under the Points setting page under the heading "Points for posting comments per node type". Allows you to automatically award points to users for making comments. You can specify a max number of comments per node that will award points: i.e., if you want to limit things such that users will only earn points for the first three replies they make to a forum topic, set this to three. Leave at 0 for no limit. You can also set different point awards for comments on different types of content -- for example, you could award 2 points for a comment on a story chapter, 1 point for a comment on a forum topic, and zero points for comments on a blog post.

Userpoints No Negative
Has no administration functions. If this module is enabled, userpoints will not be allowed to go into the negative. Highly recommended, because otherwise users could simply spend userpoints to their heart's content. Any transaction that would reduce userpoints to a negative number now reduces userpoints to zero.

Userpoints Nodes and Comments
Configurable under the Points setting page under two headings, "Points for posting nodes" and "Points for posting comments". Allows you to automatically award points to users for making nodes and comments.

Points for posting nodes -- lets you specify how many points to award for the creation of new nodes, with different awards for different content types. I.e., award users 5 points for a new forum topic, but 0 points for a blog post. Of limited use for the weblit author -- you'll probably only use this to award points for new forum topics.


Points for posting comments -- lets you specify how many points to award for comments. Note that this differs from the Userpoints Comments by Type module above in that this is a global setting, affecting all comments, whereas the previous module allows you to specify different amounts for comments on different content types. Use one or the other, but not both -- I suggest using Userpoints Comments by Type, personally.)


Page Views In Practice
Let's say IP Click Ignore is set to 24 hours. We have three users: Writer, Reader 1 and Reader 2. Writer produces a Short Story. Reader 1 views Writer's Short Story. Writer earns 1 point. Reader 1 comes back 8 hours later and reads Writer's Short Story again. Writer doesn't earn another point, since IP Click Ignore interval is set to 24 hours. Reader 2 views Writer's Short Story. Since Reader 2 has a different IP address than Reader 1, Writer earns 1 point.

Userpoints Page Views
Configurable under the Points setting page. Allows you to award node creators points whenever a node they create is viewed. You can specify different point awards per view for each content type and a category to award points to. You can also set an IP Click Ignore interval: whenever a user views a node, this setting will check to see if that user has viewed the same content within the specified interval period -- if so, the node creator doesn't earn another point.

You can also specify a Page Limit of All or One; if All is selected, the IP Click Ignore function will only prevent point awards from the same page -- if the user views a different node created by the author, the author will still earn points. If One is selected, the IP Click Ignore function will prevent point awards from all of the author's page -- if the user has viewed one of the author's nodes, that author won't earn any more points from that user's views (regardless of the node they look at) until the interval expires. Note that this module also adds a new permission, userpoints pageview click. I'm not entirely sure what this does, but I assume it means that node creators will only earn points from views by users that have this permission enabled.

Userpoints Register
Configurable from the Points setting page. Simply lets you set an amount of points to award a user when they first register for the site, and the category to apply those points to.

Userpoints Reset
Creates its own administration page on the Administration by Module page. Simply provides a function to automatically delete all points from all users of the site.

Userpoints Retroactive
Creates its own administration page on the Administration by Module page. Simply provides a function to automatically award users points based on nodes and/or comments they created before the User Points module was enabled.

Userpoints Role
Configurable from the Points setting page. Lets you automatically assign roles to users when they reach a certain point total. You can manage configurable emails to send to the user to inform them of new roles they've acquired or lost, and set different point thresholds for different roles. Whenever the user possesses the specified amount of points, they will automatically be given the role. If their point total drops below the specified threshold, they will automatically lose the role.

What We Can Do Now
As you can see, we've added a fair bit of functionality to our point system. We can now automatically award users points for registering, posting comments or forum topics, allow them to send points to one another, and give them a few goals by offering special roles or content types for which they need certain point totals.

You'll notice that we neglected to enable a handful of modules from the Contributed Modules Pack -- many of these are tie-in modules that allows User Points to link into other modules for Drupal. We'll deal with those in tomorrow's article, User Points Magic: A Weblit Writer's Guide To Extending Drupal's User Points Module.