Tag Archives: Module

CubePoints Modules

14 Replies
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!

How to Display CubePoints Logs on the Front End

13 Replies
Since writing this, development of the CubePoints plugin has slowed to a halt. So I’ve created my own points plugin, WordPoints. It offers a shortcode that you can use to display logs on the front end of your site. Please give it a try!

 

NOTE: The following tutorial is based on CubePoints 3.2.1 and WordPress 3.4.2 (the latest versions as of this writing). I will try to keep it updated if anything changes in future versions.

In this tutorial we will learn how to show a user a paginated list of recent points transactions from the logs on the front end of WordPress. The CubePoints plugin comes with this functionality already built in, for the admin area. All we have to do is bring it to the front end. We will give ourselves the option of doing it one of two ways:

  1. We can do it on any page or post using shortcode.
  2. Or, for those who are more WordPress savvy, we can also do it through an action hook.

(For those of you who don’t know PHP or WordPress, you may want to skip this explanation and just grab the finished code below.)

Getting Started: Understanding the Built-in Functionality

To get started, we need to first understand the functionality that CubePoints has already built-in. Otherwise we might end up doing a lot of extra work that the CubePoints developers have already done for us. For one thing, CubePoints is a modular plugin. That means that we don’t have to build our own plugin to do this, we just need a custom CubePoints module.

Creating a CubePoints Module

CubePoints modules are not too hard to understand, especially if you know a little about WordPress plugins. To create a CubePoints module, you need to create a new file in the CubePoints modules directory (/wp-content/plugins/cubepoints/modules/). You can name the file whatever you like, and in this case we might call it something like ‘frontend_logs.php’.

Inside the module file, the first thing the module needs to do is register itself, so that CubePoints knows that it exists. That code would look something like this:

<?php
/** Front-end Points Log */
cp_module_register(__('Front-end Points Logs', 'cp'), 'frontlogs', '1.0', 'J.D. Grimes',
   'http://efieldguide.com', 'http://efieldguide.com/how-to-display-cubepoints-logs-on-the-front-end',
   __('Allow users to see a history of their point transactions on the front end.', 'cp'), 1);
?>

Lets take a look at exactly what happens here. The comment (/** Front-end Points Log */) doesn’t really do anything, accept tell us the name of the module. The real meat of this, of course, is the cp_module_register() bit (this function is defined in /plugins/cubepoints/cp_core.php). As you can see, this function takes 8 parameters. Here is what each of them is:

  1. The name of the module (displayed on the CubePoints->Modules page)
  2. The module’s id or slug (the unique name of the module)
  3. The version of the module (displayed on the CubePoints->Modules page)
  4. The module’s Author (displayed on the CubePoints->Modules page)
  5. The module Author’s URL (used on the CubePoints->Modules page)
  6. The module’s URL (used on the CubePoints->Modules page)
  7. The module’s description (displayed on the CubePoints->Modules page)
  8. Whether the module can deactivate (1 = yes, 0 = no)

As you can see, parameters 1 and 7 are wrapped in WordPress’s __() function. This is not absolutely necessary, but it enables translation of the message into different languages, without directly editing the plugin files.

Using the cp_show_logs() Function

Now that we have registered our module, we need to add the code to enable front-end display of the points logs. As I noted above, CubePoints already has the ability to display the logs. All we need to do is bring that functionality to the front end. In order to do that, we need to understand how CubePoints does it. The code that shows a user their recent points transactions is in the My Points module which is included with CubePoints (/cubepoints/modules/my_points.php). If you have this module enabled, you can navigate to the CubePoints->My Points page on your WordPress Dashboard, and see your last 15 point transactions. Here is that module’s code:

<?php

/** My Points Module */

cp_module_register(__('My Points', 'cp') , 'mypoints' , '1.0', 'CubePoints', 'http://cubepoints.com', 'http://cubepoints.com' , __('Allow users to see a history of their point transactions.', 'cp'), 1);

if(cp_module_activated('mypoints')){

	add_action('admin_print_scripts-cubepoints_page_cp_modules_mypoints_admin', 'cp_datatables_script');
	add_action('admin_print_styles-cubepoints_page_cp_modules_mypoints_admin', 'cp_datatables_style');

	function cp_module_mypoints_add_admin_page(){
		add_submenu_page('cp_admin_manage', 'CubePoints - ' .__('My Points','cp'), __('My Points','cp'), 'read', 'cp_modules_mypoints_admin', 'cp_modules_mypoints_admin');
	}
	add_action('cp_admin_pages','cp_module_mypoints_add_admin_page');

	function cp_modules_mypoints_admin(){

		echo '<div class="wrap">';
		echo '<h2>CubePoints - ' . __('My Points', 'cp') . '</h2>';
		echo __('Manage and view information about your points.', 'cp');
		echo '<br /><br />';
		echo '<div style="background:#EFEFEF;display:inline-block;margin-right:25px;"><div style="float:left;font-size:17px;font-weight:bold;background:#E0E0E0;padding:18px;color:#565656;">' . __('My Points', 'cp') . ':</div><div style="float:left;padding:18px;font-size:20px;">' . cp_getPoints(cp_currentUser()) . '</div></div>';
		if(cp_module_activated('ranks')){
			echo '<div style="background:#EFEFEF;display:inline-block;"><div style="float:left;font-size:17px;font-weight:bold;background:#E0E0E0;padding:18px;color:#565656;">' . __('My Rank', 'cp') . ':</div><div style="float:left;padding:18px;font-size:20px;">' . cp_module_ranks_getRank(cp_currentUser()) . '</div></div>';
		}
		echo '<div style="clear:both;"></div><br />';
		
		echo '<p style="font-weight:bold;">' . __('Your recent point transactions:', 'cp') . '</p>';
		
		cp_show_logs(cp_currentUser(), 15 , false);
		
		echo '</div>';
	}
	
}
	
?>

It adds the CubePoints->My Points page, and on that page it displays a table with the last 15 points transactions for the current user. The part of this which is most important is on line 31:

cp_show_logs(cp_currentUser(), 15 , false);

This is the part that actually displays the point logs table. The declaration of the cp_show_logs() function is in /cubepoints/cp_logs.php. As you can see, the function takes three parameters. The first parameter is either 'all', meaning display the logs for all users, or the id of the specific user to show logs for, as in this case. The second parameter is the maximum number of transactions we want to display. In this case, we only display the last 15 logs. The third parameter tells CubePoints whether we want the results paginated or not. In this case, we are only displaying the 15 most recent transactions, so there is no need to paginate the tables.

This is the same function that is used in /cubepoints/cp_admin_logs.php to display all of the logs to the administrator. The only difference is that it uses different parameter values:

cp_show_logs('all', apply_filters('cp_admin_logs_limit', 0 ) , true);

In this case, CubePoints shows transaction logs for all of the users, so the first parameter is 'all'. The second parameter is 0. It is filtered through the 'cp_admin_logs_limit'. This enables compatibility with the Limit Logs Display module that comes with CubePoints, which allows administrators to define a limit to the number of logs displayed on the CubePoints->Logs page. And the third parameter is true, since we are displaying many logs, and want to paginate them.

In a moment we will learn how to use this function with a shortcode to display the logs on the front end of your site. But there is one thing we need to do first.

Bringing the JavaScript and CSS to the front end

The CSS styling is necessary for the tables to display properly. And without the JavaScript, the pagination will not work. The My Points module shown above, does that with this code:

add_action('admin_print_scripts-cubepoints_page_cp_modules_mypoints_admin', 'cp_datatables_script');
add_action('admin_print_styles-cubepoints_page_cp_modules_mypoints_admin', 'cp_datatables_style');

However, that will only work on the Admin side of the site. Here is the code we need to add these scripts to the front end:

       // Adding the necessary JS and CSS files to the front end.
       function cp_frontload_scripts(){
              wp_register_script('datatables', CP_PATH . 'assets/datatables/js/jquery.dataTables.min.js', array('jquery'), '1.7.4', true);
              wp_enqueue_script('datatables');
              wp_register_style('datatables', CP_PATH . 'assets/datatables/css/style.css');
              wp_enqueue_style('datatables');
       }
       add_action( 'wp_enqueue_scripts', 'cp_frontload_scripts' );

This code is based on the code from CubePoints itself, found in cp_admin.php. We can’t just enqueue the scripts, we have to actually register them, because CubePoints only registers them on the Admin side of the site. If you don’t know exactly what’s going on in this code, check out the WordPress Codex. Note that I have the final value of wp_register_script(‘datatables’) set to true. This causes the JavaScript to load at the bottom of the page. I did this because it wasn’t working properly when loaded in the <head>. I don’t know exactly why, perhaps because of a conflict with another script. Anyway, it only worked when loaded at the bottom for me, though I suggest you try setting that to false to see if it will load from the top for you.

Note that if you are only displaying the logs on one or two pages (and you probably are), you could add a conditional statement to only load the CSS and JS on those page(s). Something like if ( is_page($page) )  { /* add scripts here*/ } (see Codex)

Building a Function to Display the Logs

Now we have our CSS and JS ready, our points logs will display properly. We just need to build a function to display them. We can base it on the code from the My Points module above. But we can change it a little to give us the option to set each of the three parameters of the cp_show_logs() function. Then, we can either show all of the logs, or show just the logs for the current user with the same function. We can also specify any limit to the number of recent points transactions to display when we call the function, or ultimately in our shortcode. And we can also set whether we want to paginate the logs or not. This requires a few modifications, but is still fairly straightforward.

	function cp_modules_frontlogs_display($type = 'user', $limit = 0, $paginate = 1){

		echo '<style>.widefat{border-radius:3px 3px 3px 3px;border-width:1px;border-style:solid;border-spacing:0px;
				width:100%;clear:both;margin:0px;border-color:rgb(223,223,223);background-color:rgb(249,249,249);}</style>';
		echo '<div class="wrap"><div style="background:#EFEFEF;display:inline-block;margin-right:25px;">';
		
		if ($type == 'user'){
		
			if ( is_user_logged_in() ){

				echo '<div style="float:left;font-size:17px;font-weight:bold;background:#E0E0E0;padding:18px;color:#565656;">' . __('My Points', 'cp') . ':</div>
					<div style="float:left;padding:18px;font-size:20px;">' . cp_getPoints(cp_currentUser()) . '</div></div>';
		
				// If the 'ranks' module is activated...
				if(cp_module_activated('ranks')){
					echo '<div style="background:#EFEFEF;display:inline-block;">
						<div style="float:left;font-size:17px;font-weight:bold;background:#E0E0E0;padding:18px;color:#565656;">' . __('My Rank', 'cp') . ':</div>
						<div style="float:left;padding:18px;font-size:20px;">' . cp_module_ranks_getRank(cp_currentUser()) . '</div></div>';
				}
		
				echo '<div style="clear:both;"></div><br />';
				echo '<p style="font-weight:bold;">' . __('Your recent point transactions:', 'cp') . '</p>';
			
				$type = cp_currentUser();

			} else {
				echo '<p><b>'.__('You must be logged in to view your points.').'</b><p>';
				echo '</div>';
				return;
			}
			
		} elseif ($type == 'all') {
			$limit = apply_filters('cp_admin_logs_limit', $limit);
		}
		
		cp_show_logs($type, $limit , $paginate);
		
		echo '</div>';
	}
	add_action( 'cp_modules_show_logs_front_end', 'cp_modules_frontlogs_display' );

For clarity, the three parameters are:

  1. The type of log we want to display ('user' for current user only, 'all' for all users)
  2. The maximum number of logs to display (0 = no limit)
  3. Do we want the logs to be paginated? (1 = yes, 0 = no)

If we are loading the logs only for the current user ( if ($type == 'user') ), then we also want to show the user how many points they have. That is what the first if statement does. Inside of that we have to check if the user is logged in. If they aren’t, then we just give them a message that tells them they need to log in to view their points. At the bottom of that if statement, we also do $type = cp_currentUser(); to set the id of the user which we are displaying the logs for. On the other hand, if we are displaying all the logs, we want to filter the $limit through apply_filters('cp_admin_logs_limit', $limit); so that this module is compatible with the Limit Logs Display module. Finally, at the bottom we call the function to display the logs with whatever the parameters are, like this cp_show_logs($type, $limit , $paginate);.

We also have to add one more piece of CSS so that the table will display properly. That’s what this part does:

		echo '<style>.widefat{border-radius:3px 3px 3px 3px;border-width:1px;border-style:solid;border-spacing:0px;
				width:100%;clear:both;margin:0px;border-color:rgb(223,223,223);background-color:rgb(249,249,249);}</style>';

If you want to display the logs in a custom template, then you can do_action( 'cp_modules_show_logs_front_end' ), or if you want to pass parameters other than the default, you can simply call the function like this: cp_modules_frontlogs_display($type, $limit, $paginate). However, we could also do this with a shortcode on any post or page.

Creating the Shortcode

The next thing we need to do is create a function to handle the shortcode. That will look something like this:

function cp_modules_show_logs_shortcode( $atts ){
              extract( shortcode_atts( array(
                     'type' => 'user',
                     'paginate' => '1',
                     'limit' => '0',
              ), $atts ) );

              ob_start();
              cp_modules_frontlogs_display($type, $limit, $paginate);
              $html = ob_get_contents();
              ob_end_clean();

              return $html;
       }
       add_shortcode( 'cp_modules_show_logs', 'cp_modules_show_logs_shortcode' );

If you aren’t familiar with how to add WordPress shortcodes, here is a link to the Codex. All this function does is get any parameters that were set in the shortcode, and filters them through extract( shortcode_atts() ). Then we call the cp_modules_frontlogs_display($type, $limit, $paginate) function. But we need to call that function within PHP output buffering, so that the logs will appear in the right place on the page. If you are familiar with PHP output buffering, you know that this will catch everything that would have otherwise have been echo‘ed directly to the page. We turn output buffering on, execute cp_modules_frontlogs_display(), and then empty all of the stuff we caught into the $html variable, which we then return to WordPress to display on the page in place of the shortcode. Now you can include the shortcode in your WordPress pages and posts like this:

[cp_modules_show_logs]

Or with parameters:

[cp_modules_show_logs type="all" limit="15" paginate="0"]

And that’s all there is to it.

Conclusion

Putting all the code together, our module looks like this:

<?php

/** Front-end Points Log Module */

// Register the module.
cp_module_register(__('Front-end Points Logs', 'cp') , 'frontlogs' , '1.0', 'J.D. Grimes', 'http://efieldguide.com', 'http://efieldguide.com' , __('Allow users to see a history of their point transactions on the front end.', 'cp'), 1);

// If the module is active...
if(cp_module_activated('frontlogs')){
	
	// Adding the necessary JS and CSS files to the front end.
	function cp_frontload_scripts(){
		wp_register_script('datatables', CP_PATH . 'assets/datatables/js/jquery.dataTables.min.js', array('jquery'), '1.7.4', true);
		wp_enqueue_script('datatables');
		wp_register_style('datatables', CP_PATH . 'assets/datatables/css/style.css');
		wp_enqueue_style('datatables');
	}
	add_action( 'wp_enqueue_scripts', 'cp_frontload_scripts' );

	// Function to display the logs...
	function cp_modules_frontlogs_display($type = 'user', $limit = 0, $paginate = 1){

		echo '<style>.widefat{border-radius:3px 3px 3px 3px;border-width:1px;border-style:solid;border-spacing:0px;
				width:100%;clear:both;margin:0px;border-color:rgb(223,223,223);background-color:rgb(249,249,249);}</style>';
		echo '<div class="wrap"><div style="background:#EFEFEF;display:inline-block;margin-right:25px;">';
		
		if ($type == 'user'){
		
			if ( is_user_logged_in() ){

				echo '<div style="float:left;font-size:17px;font-weight:bold;background:#E0E0E0;padding:18px;color:#565656;">' . __('My Points', 'cp') . ':</div>
					<div style="float:left;padding:18px;font-size:20px;">' . cp_getPoints(cp_currentUser()) . '</div></div>';
		
				// If the 'ranks' module is activated...
				if(cp_module_activated('ranks')){
					echo '<div style="background:#EFEFEF;display:inline-block;">
						<div style="float:left;font-size:17px;font-weight:bold;background:#E0E0E0;padding:18px;color:#565656;">' . __('My Rank', 'cp') . ':</div>
						<div style="float:left;padding:18px;font-size:20px;">' . cp_module_ranks_getRank(cp_currentUser()) . '</div></div>';
				}
		
				echo '<div style="clear:both;"></div><br />';
				echo '<p style="font-weight:bold;">' . __('Your recent point transactions:', 'cp') . '</p>';
			
				$type = cp_currentUser();

			} else {
				echo '<p><b>'.__('You must be logged in to view your points.').'</b><p>';
				echo '</div>';
				return;
			}
			
		} elseif ($type == 'all') {
			$limit = apply_filters('cp_admin_logs_limit', $limit);
		}
		
		cp_show_logs($type, $limit , $paginate);
		
		echo '</div>';
	}
	add_action( 'cp_modules_show_logs_front_end', 'cp_modules_frontlogs_display' );

	// Function to add shortcode...
	function cp_modules_show_logs_shortcode( $atts ){
		extract( shortcode_atts( array(
			'type' => 'user',
			'paginate' => '1',
			'limit' => '0',
		), $atts ) );
		
		ob_start();
		cp_modules_frontlogs_display($type, $limit, $paginate);
		$html = ob_get_contents();
		ob_end_clean();
		
		return $html;
	}
	add_shortcode( 'cp_modules_show_logs', 'cp_modules_show_logs_shortcode' );
}

?>

Once you have saved that to a file in the /modules/ directory, you can go to your WordPress Dashboard, and navigate to CubePoints->Modules, and activate the Front-end Points Logs module that you just created. You can then display the logs on the front end using the shortcode, or, if you prefer, with a custom template.

Remember, I am not one of CubePoints’ developers, so I don’t know everything, and what you see here is just the product of a few hours of studying the plugin’s code. If you have any tips or find something I missed, please leave a comment and let me know.