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 does not have a $user_id argument, you can use $bp->loggedin_user->id.


Changes for version 1.1:
------------------------
Site administrators may manually trigger a check on all users which runs through all active achievements to find out
if that user has already met the criteria to unlock that achievement.  Your custom achievement needs to register the
'dpa_check_retroactive_achievements' action if you want to implement your own evaluation (i.e. to call your function with
dummy/sample arguments).

Your achievement function either needs to be written to cope with this, or you can check to see if the 'DPA_CHECKING'
constant is defined.  See dpa_handle_profileavatar() for an example.

Note that whilst these checks are run, the value of $bp->loggedin_user->id will be replaced with the user ID that is
currently being evaluated.  The value will be restored afterwards.