This file contains developer documentation for the Achievements plugin for BuddyPress.  Please email me at
djpaul@gmail.com or http://twitter.com/pgibbs if you have any suggestions, comments or feature requests.

Future development of the plugin will be in part based on feedback from all types of end-users; from those who
do little more than run the plugin on their website, as well as those people who wish to rename some of the
achievements, or use it as a starting point for their own, more elaborate projects.

Code samples are indented with tabs.


If you wish to customise the UI pages:
--------------------------------------
1) Copy /dp-achievements/achievements-member-theme/ to /wp-content/bp-themes/[bpmember]/, so that you have the 
following path: /wp-content/bp-themes/[bpmember]/achievements-member-theme/.

2) Make your changes to those member theme files which you just copied. They will *not* be overwritten by any
future versions of this plugin.


If you wish to implement your own achievement:
----------------------------------------------
1) Add your achievement into the 'dpa_achievements' table.  Make sure the short_name value contains characters
that you can also use in the name of a PHP function.  As an example, our short_name is 'moo'.

2) You need to know the name of an WPMU/BuddyPress action which you are going to hook into.  Implement a
function called 'dpa_register_[short_name]'.

	function dpa_register_moo() { add_action( 'groups_promoted_member', 'moo_action', 10, 2 ); }

3) Then implement your 'moo_action' function.  Give the short_name value to the 'name' array, as below:

	function moo_action( $user_id, ... ) {
		$moo_action = new dpa_achievement( array( 'user_id' => $user_id, 'name' => 'moo' ) );
		if ( $moo_action->is_unlocked() )
			return;

		$moo_action->unlock_achievement();
	}


Ranked achievements:
--------------------
You may want to implement a "ranked" achievement.  An example of this is capturing a user's 1st forum post, 5th post
and the 10th post.  What makes this a "ranked" achievement is that virtually all of the code is the same, just
a different integer or 'counting' variable.

To implement a ranked achievement, you need to:

1) Add each rank of your achievement into the 'dpa_achievements' table.  For example, and referring to the short_names,
add records for each of 'moo_1', 'moo_5' and 'moo_10'.  These suffixes are *essential*, and must take the format of an
underscore followed by whatever you want.

2) However, you only need to write a single 'dpa_register_[short_name]' function - i.e. "dpa_register_moo()" from the
above example.  You have to structure this function differently for a ranked achievement.  Take a look at the 
dpa_handle_replyranked() function that comes with this plugin for an example.


Achievement implementation hints:
---------------------------------
If your action doesn't have a $user_id or similar as one of its argument, you can use $bp->loggedin_user->id.