CubePoints Modules

Since writing this, development of the CubePoints plugin has slowed to a halt. So I’ve created my own points plugin, WordPoints. It also supports modules. Please give it a try!

 

The CubePoints plugin has some very nice features, and one of those is its modules. CubePoints modules allow you to extend the functionality of the CubePoints plugin. In this tutorial, we’ll take a look at some of the things that you can do with your own CubePoints modules.

What can a CubePoints Module do? #

A CubePoints module can do anything that a WordPress plugin can do. The only difference is that is treated like it’s part of CubePoints, not a separate plugin. The main advantage of creating a custom CubePoints module as opposed to writing your own plugin, is that it keeps everything nice and organized. You are just extending the CubePoints plugin, not creating something completely new, so it is more intuitive to write a CubePoints module than to write a separate plugin. Having said that, the two are in most respects identical, so you could really do either.

Registering the Module #

When you create your own module, the first thing that it needs to do is register itself with CubePoints. If you don’t, then the module won’t show up on the CubePoints->Modules page. This is done using the cp_module_register() function. This function takes 8 different parameters. It might look something like this:

cp_module_register(
	'My Module',
	'my_module',
	'1.0',
	'Me',
	'http://example.com/me/',
	'http://example.com/my-module/',
	'This is my own module that does my really cool stuff!',
	1
);

Now lets take a look at what each of these parameters is:

  1. The module’s name.
  2. The module’s slug.
  3. The version.
  4. The modules author.
  5. The module author’s URL
  6. The module’s URL
  7. The module’s description.
  8. Can the module be deactivated? (1 = yes, 0 = no)

That’s pretty simple, no? There’s just a couple things to remember. Notice that last parameter. CubePoints looks at this to see whether the module can be deactivated. If its value is 1, then the module can be activated and deactivated via the CubePoints->Modules page. But if you set it to 0, then the module will be activated automatically as soon as it’s installed, and if you try to deactivate it from the CubePoints->Modules page you will get the message: “This module cannot be deactivated through this page. To deactivate this module, remove it manually.”

Performing actions on Module Activation #

Maybe you have some things that you want your module to do when it gets activated. Stuff it only needs to do once. Well, for that we do something like this:

function cp_module_my_module_install() {

	// Do stuff here
}
add_action( 'cp_module_my_module_activate', 'cp_module_my_module_install' );

We create a function to do whatever we need to do, and then hook it to the 'cp_module_*_activate' action hook. (Replace the * with your module’s slug). Now the function cp_module_my_module_install() will be run whenever the module is activated. It will also run if you change the module’s version (it will be run when the version changes, whether you increase or decrease it). Beware, that it will not run if your module can’t be deactivated. I guess since the module can’t be deactivated, it really can’t be activated either!

Module Content #

Before we talk about what you can do with module, I need to note that the contents of your CubePoints module (except for the registration and activation functions) need to be wrapped in an if statement that checks that the module is actually active:

if ( cp_module_activated( 'my_module_slug' ) ) {

	// The module is activated! Do stuff here.
}

The cp_module_activated() function will check whether the module with that slug is active. If it is, then your module’s functions will get run. If it isn’t, we don’t want to run its functions!

The CubePoints functions #

Here is an explanation of all of the most useful functions in CubePoints. These are the ones you are probably going to want to use in your custom module!

cp_currentUser() #

You can use this function to get the ID of the current user. It doesn’t take any parameters, so can be called like this:

$current_user = cp_currentUser();
// $current_user now contains the current user's ID!

cp_getPoints() #

This function is used to get the number of points a user has. It has only one parameter: a user’s ID. You might use it like this:

// Get the number of points for the user whose ID is 3.
$points = cp_getPoints( 3 );

cp_updatePoints() #

You can use this function to update the number of points a particular user has. It takes two parameters: the user’s ID, and the number of points you want the user to have.

// Set user 3's 250 points.
cp_updatePoints( 3, 250 );

cp_alterPoints() #

Use this function to alter the number of points a user has. The last function just set the users points to a certain amount, but this function will add (or subtract) a certain number of points from a user.

// Give user 3 ten points.
cp_alterPoints( '3', '10' );

// Subtract ten from user 3's points.
cp_alterPoints( '3', '-10' );

cp_formatPoints() #

This function formats the points value with the prefix and suffix. (These are set on the plugin’s settings page.)

$formatted_points = cp_formatPoints( '150' );
// $formatted_points will now look something like '$150points'.

cp_displayPoints() #

This function may be used to display the points of a given user. It takes three parameters:

  1. The ID of the user you want to get points for (or you can set this to 0 to display the points of the current user).
  2. Whether to return the points as a string or echo() them immediately (echo()‘s by default).
  3. Whether to format the points with the prefix and suffix (set to true by default).

Examples:

// We can call the function without passing any parameters.
cp_displayPoints();

// The points of the current user will be formatted with prefix and suffix and echo'ed to the browser.

// Or we can set some or all of the parameters.
$points = cp_displayPoints( 3, true, false );

// $points now contains the unformatted number of points for user 3.

cp_getAllPoints() #

This function returns an array of information about each user. It takes up to three parameters:

  1. The upper limit to the number of users in the array. (Default: no limit)
  2. An array of user_login names to exclude.
  3. The lower limit to the number of users. (Default: 0)

cp_points() #

This function alters the users points, and logs the transaction. It takes 4 parameters:

  1. The transaction type.
  2. The userID of the user who the transaction is affecting.
  3. The number of points to add to (or subtract from) the user’s points.
  4. The log data.

The log data is filtered into a transaction description, based on the transaction type.

// Give user 3 100 points.
cp_points( 'custom', 3, 100, 'Congratulations! You won 100 points!' );
	
// Take 100 points away from user 3.
cp_points( 'custom', 3, -100, 'Thank you for donating!' );

cp_points_set() #

This function is the same as the last one, except rather than adding (or subtracting) a given number of points, it resets the user’s points to a given amount.

// Set user 3's points to 250
cp_points_set( 'custom', 3, 250, 'Now you have 250 points!' );

cp_getPostCount() #

Get the the number of posts made by a user with a given ID.

// How may posts as user 3 created?
$posts = cp_getPostCount( 3 );

cp_getCommentCount() #

Get the number of comments made by a given user.

// How many comments has user 3 created?
$comments = cp_getCommentCount( 3 );

Action hooks #

Now lets look at some of the action hooks included with CubePoints, and how to use them.

cp_logs_desciption #

You can use this to create your own transaction type, and filter for the log data.

function cp_my_logs_desc( $type, $uid, $points, $data ) {

	if ( $type != 'my_type' )
		return;

	// Filter the log data here.
}
add_action( 'cp_logs_description', 'cp_my_logs_desc', 10, 4 );

This allows you to pass a small piece of data to the when you log a transaction, and then use that data to create a transaction description when the logs are displayed. For example, maybe you want to give user’s points for uploading an image, and want to display the image they uploaded with the logs. You could create a transaction type called 'image_upload'. Then you could just pass the URL of the image as the description data. You could assemble your description, using the ‘cp_logs_description’ filter, something like this:

function cp_image_upload_desc( $type, $uid, $points, $data ) {

	// If it's not an image upload transaction, then we bail out.
	if ( $type != 'image_upload' )
		return;
	
	// Our description would look like 'Image Upload: (image here)'.
	echo( 'Image Upload: <img src="'. $data .'" max-width="20px" max-height="20px" />' );
}
add_action( 'cp_logs_description', 'cp_image_upload_desc', 10, 4 );

Of course, there’s many other things that you could do. This is just an example.

One of the good things about doing it this way, is that you can change exactly how you want your descriptions to look. Just edit your function. If you passed the whole description as the data, there would be no easy way to change it later!

cp_config_form & cp_config_process #

You can use these to action hooks in your module to add your own options to the CubePoints->Configure page. cp_config_form lets you add your own inputs to the form, while cp_config_process lets you process the values submitted by the form. An example of their use is below. Basically what this does is let you update the values of any custom transaction types that you create, from the CubePoints->Configure page.

<?php

// Register the module
cp_module_register( __( 'My Module', 'cp' ) , 'my_module' , '1.0', 'Me', 'http://www.example.com', 'http://example.com/' , __( 'My own module!!', 'cp' ), 1 );

// On installation, we set the default values for our custom points transactions.
function cp_my_module_install() {

	add_option( 'cp_my_module_value1', 10 );
	add_option( 'cp_my_module_value2', 25 );
}
add_action( 'cp_module_my_module_activate', 'cp_my_module_install' );

// If the module is active.
if ( cp_module_activated( 'my_module' ) ) {

	// Add a function to display the form inputs.
	function cp_my_module_config() {

		?>

		<br />
		<h3>My Module Config Options</h3>
		<table class="form-table">
			<tr valign="top">
				<th scope="row">
					<label for="cp_my_module_value1">My Value 1:</label>
				</th>
				<td valign="middle">
					<input type="text" id="cp_my_module_value1" name="cp_my_module_value1" value="<?php echo( get_option( 'cp_my_module_value1' ) ); ?>" size="30" />
				</td>
			</tr>
			<tr valign="top">
				<th scope="row">
					<label for="cp_my_module_value2">My Value 2:</label>
				</th>
				<td valign="middle">
					<input type="text" id="cp_my_module_value1" name="cp_my_module_value1" value="<?php echo( get_option( 'cp_my_module_value1' ) ); ?>" size="30" />
				</td>
			</tr>
		</table>

	<?php

	}
	add_action( 'cp_config_form', 'cp_my_module_config' );

	// Create a function to process the form inputs when the form is submitted.
	function cp_my_module_config_process() {

		// We update the options with the submitted values. We cast them as integers.
		update_option( 'cp_my_module_value1', (int) $_POST['cp_my_module_value1'] );
		update_option( 'cp_my_module_value2', (int) $_POST['cp_my_module_value2'] );
	}
	add_action( 'cp_config_process', 'cp_my_module_config_process' );
}

It shouldn’t be too hard to follow that, but I’ll break it down for you anyway:

  • We register the module.
  • We set the default values for our custom transaction types.
  • The rest of the code is only performed when the plugin is active.
  • The first function creates a form table on the CubePoints->Configure page. The id and name attributes of the input tags must match the name of your option. Also, we echo() the current value as the value for the input. The labels could be whatever you want.
  • We create a function to save the values of the out options when the form is submitted.

All that you need to do know is hook your options to a particular action. For example, when a user makes a comment, submits a form, visits a page, or performs any action. Exactly how that happens will depend on what action you are trying to award/subtract points for.

Hooking into other plugins #

Okay, now you know how all of the CubePoints functions work. The question is, how are you going to use them? Chances are, you want to award points for some actions user’s perform, that is enabled by another plugin (maybe a custom one you wrote for yourself). So how do you do that?

This is actually the difficult part. There isn’t just one answer; the answer will vary based on the particular situation. But as a general rule, you are probably going to need to hook into an action that the plugin performs; i.e. create a function and call it through some action hook. If that’s “Greek to you”, then keep reading, but realize you may be in above your head.

Here I am going to give a simple example, based on a module by Tosh Hatch, in which he integrated CubePoints with bbPress. The module lets you set the number of points to give user’s when the create a forum topic and when the reply to a topic. A portion of it is shown below.

<?php

// Create a function to call when a user makes a new bbPress topic.
function bbpress_cb_new_topic() {

	// We include the $current_user global.
	global $current_user;

	// We give the current user the number of points set by the custom option cp_bbpress_topic.
	cp_points( 'bbpress_cb_new_topic', $current_user->ID, get_option( 'cp_bbpress_topic' ), '' );
}

/* 
 * This is the really good part. We hook our new function to the bbp_new_topic
 * action, found in bbp-includes/bbp-topic-functions.php. Now each time a user 
 * creates a new topic, they are awarded the number of points that we have set with
 * the cp_bbpress_topic option.
 */
add_action( 'bbp_new_topic', 'bbpress_cb_new_topic' );


// Then we create a function to display the transaction description.
function bbpress_cb_new_topic_log( $type, $uid, $points, $data ) {

	if ( $type != 'bbpress_cb_new_topic' )
		return;
		
	echo 'New Forum Topic';
}
add_action('cp_logs_description','bbpress_cb_new_topic_log', 10, 4);


/*
 * We do the same thing for when a user created a reply. We hook into the
 * bbp_new_reply action found in bbp-includes/bbp-reply-functions.php
 */
function bbpress_cb_new_reply() {

	global $current_user;
	cp_points( 'bbpress_cb_new_reply', $current_user->ID, get_option( 'cp_bbpress_reply' ), '' );
}
add_action( 'bbp_new_reply', 'bbpress_cb_new_reply' );

// And we add a function for the logs descriptions.
function bbpress_cb_new_reply_log( $type, $uid, $points, $data ) {

	if( $type != 'bbpress_cb_new_reply' )
		return;
		
	echo 'New Forum Reply';
}
add_action( 'cp_logs_description','bbpress_cb_new_reply_log', 10, 4 );

Basically, if you want to give a user points for performing an action, you need to find an action hook that’s fired when the user does that, and then create a function like the ones shown above to hook into it. That means you are going to have to look through some code, and find the actions you want to hook into. If none exist where you need one, you might even have to add your own (which is pretty simple to do). Of course, if you created the plugin in the first place, then adding an action hook here and there should be no problem for you.

Conclusion #

For those that know how, CubePoints modules are a powerful tool. Up to now, though, there has been very little documentation of how to build them. I hope that you have found this tutorial helpful, and if you have any questions, comments, or suggestions, please leave a comment below. I’d love to hear what you have to say!

14 thoughts on “CubePoints Modules

  1. Ken

    Thanks for this cubepoints post. I am just about to try it out, I am a complete php novice but I am going to try and create a module that gives points to users for visiting a post. I’ll let you know how I get on.

    Thanks again.

    Reply
  2. Gaz

    To display rank and user points in comments try adding this to you comments.php file.
    user_id);
    if(function_exists(‘cp_module_ranks_getRank’)){
    echo ‘My Rank: ‘;
    echo cp_module_ranks_getRank($user->ID);
    echo ”;
    }?>

    Reply
  3. Hiram

    I’m looking for a “social module” that gives you points for like on facebook, twitter, etc. Is there anything like that?

    Reply
    1. J.D. Grimes Post author

      No, I don’t think anything like that exists. Actually, I think it is against the terms of Facebook, Twitter, et al to give incentives like that for social actions.

      Reply
  4. Joan

    I absolutely LOVE CubePoints, but it looks like it hasn’t been updated since November 2012. I can’t find any information about anything in the works either. With WordPress’s new update, I’m wondering how long this is going to last. Anyone know more?

    Thanks!

    Reply
    1. J.D. Grimes Post author

      I am actually working on my own points plugin, which I hope to release soon. I had originally offered to take over the CubePoints plugin, but the developers never responded.

      Reply
  5. Jam

    Not really a module query, however does anyone know how to filter the CubePoints top users widget based on xprofile data? i.e Top Female users / Top Male users ?

    Reply
  6. Pingback: Engage Users by Gamifying WordPress | WP Squared | Wordpress

  7. Cubepoints payment module

    Great article. We use a different approach with WooCube. We do not ever actually declare a Cubepoints module. However, we do still use the wordpress hooks, so that our setup options are on the cubepoints configuration page

    This is huge for users who want to install the module like any other plugin instead of via ftp to the modules directory. This is also the only way to get your plugin/module listed on sites like wordpress.org, if thats important to you

    For those worried about cubepoints lasting the test of time, luckily its very modular in nature. Its just a bunch of php functions with a few wordpress hooks and shortcodes. Its highly unlikely that it will suddenly not work with wordpress anymore. WordPress would have to change major base programming features that have been around since the beginning of the cms like “add_action”. The loudest people talking about cubepoints not lasting, are the ones trying to take its place.

    Reply
    1. J.D. Grimes Post author

      It might be easiest to find a comment voting plugin that someone has written, and modify it to call the add points functions. Or, better yet, you might be able to find a comment voting plugin that has do_action() calls in the appropriate code so you wouldn’t have to modify it directly, just create your own plugin that hooks into those actions to award the points.

      Reply
  8. Diego Parente

    Hi, JD.

    I’m in love with CubePoints.
    He is amazing and fit like a glove for what I want, but I need some features.
    I wonder if you could help me, or indicate to help.

    I would like to know to add new ways to find the user and how to do it to gain points on your birthday.

    I use a field called user_cpf, where there is a number in the register of each web user, but do not know how to make the search system plugin locate this numbering.

    I believe that link to the “date [] command, but do not know how to do.

    Reply

Leave a Reply to Jam Cancel reply

Your email address will not be published.