myCRED_Badge
Description
This object holds all relevant information about a specific myCRED badge, along with a set of methods to manipulate the badge along with assigning it to users.
Available since version 1.7
Interacting with Object
The badge object can be accessed via the mycred_get_badge function.
Object properties
Property | Type | Description | |
---|---|---|---|
myCRED_Badge Object (
|
|||
public $post_id |
int | The badge post object ID. | |
public $title |
string | The badge title. | |
public $earnedby |
int | The number of users that has earned this badge. | |
public $manual |
bool | Indicates if the badge has been set to be manually awarded. | |
public $levels |
array | Array of all the levels setup for this badge. | |
public $main_image |
string | The main badge image (if set). | |
public $level |
array | If a particular level is requested when the object is constructed, that selected levels settings are populated here. | |
public $level_id |
int | If a particular level is requested when the object is constructed, that selected levels title is populated here. | |
public $level_label |
string | If a particular level is requested when the object is constructed, that selected levels label is populated here. | |
public $level_image |
string | If a particular level is requested when the object is constructed, that selected levels image is populated here (if the level has one). | |
public $image_width |
int | The set value for the MYCRED_BADGE_WIDTH constant. | |
public $image_height |
int | The set value for the MYCRED_BADGE_HEIGHT constant. | |
public $references |
array | An array of reference keys that are used as a requirement for this badge. | |
public $references |
array | An array of point type keys that are used as a requirement for this badge. | |
protected $user_meta_key |
string | The user meta key that is used to connect this badge with a particular user. This meta key differs if you use Multisites from regular WordPress installs. | |
public $current_level |
int | If a user is associated with this badge, this will indicate the level a user has reached. Remember that level IDs begin with zero for the first level. | |
)
|
Object Methods
public function __construct( $object = NULL, $level = NULL ) {
|
||||
Description: | Constructs and populates the badge object. | |||
---|---|---|---|---|
Variable | Type | Required | Description | |
$object |
int or obj | Yes | Either the badges post object or the post object ID. | |
$level |
int | No | Option to populate a specific level of the badge. | |
} |
public function get_user_count( $level_id = NULL ) {
|
||||
Description: | Returns the total number of users that has earned this badge. A level ID can be provided to return a count for a specific badge level. | |||
---|---|---|---|---|
Variable | Type | Required | Description | |
$level_id |
int | No | Option to return the count for a specific badge level. | |
} |
public function get_level( $level_id = false ) {
|
||||
Description: | Returns a specific level of this badge. Note that in it's current form, this is an associative array of data. As of version 1.9, this will be replaced with a new myCRED_Badge_Level object. Returns FALSE if the badge level does not exists or an invalid level ID is provided. |
|||
---|---|---|---|---|
Variable | Type | Required | Description | |
$level_id |
int | Yes | The badge level ID. | |
} |
public function get_level_requirements( $level_id = false ) {
|
||||
Description: | Returns a specific levels requirements as an associative array. Returns FALSE if the badge level does not exists or an invalid level ID is provided. |
|||
---|---|---|---|---|
Variable | Type | Required | Description | |
$level_id |
int | Yes | The badge level ID. | |
} |
public function get_level_reward( $level_id = false ) {
|
||||
Description: | Returns a specific levels reward setup as an associative array. Returns FALSE if the badge level does not exists or an invalid level ID is provided. |
|||
---|---|---|---|---|
Variable | Type | Required | Description | |
$level_id |
int | Yes | The badge level ID. | |
} |
public function user_has_badge( $user_id = false, $level_id = 0 ) {
|
||||
Description: | Checks to see if a specific user has earned this badge with the option to check if the user also has reached a certain level. Returns TRUE or FALSE . Note that if no $user_id is provided, this method will return FALSE . |
|||
---|---|---|---|---|
Variable | Type | Required | Description | |
$user_id |
int | Yes | The users numeric ID. | |
$level_id |
int | No | Option to check if a user has reached a certain level. | |
} |
public function get_users_current_level( $user_id = false ) {
|
||||
Description: | Returns the level ID that a given user has reached with this badge. Will return FALSE if the user has not yet earned this badge. |
|||
---|---|---|---|---|
Variable | Type | Required | Description | |
$user_id |
int | Yes | The users numeric ID. | |
} |
public function query_users_level( $user_id = false ) {
|
||||
Description: | This method will run the badge requirements and query the database for which level a user has reached. Will return FALSE if no level was reached (not yet earned the badge). This should only be used when new log entries have been added to the database and we need to run a new query. If you just need to get the users current level, use the get_users_current_level() method instead. |
|||
---|---|---|---|---|
Variable | Type | Required | Description | |
$user_id |
int | Yes | The users numeric ID. | |
} |
public function get_users_next_level( $user_id = false ) {
|
||||
Description: | Returns the next level user can reach based on their current position. If the user has reached the highest level, that levels is returned. | |||
---|---|---|---|---|
Variable | Type | Required | Description | |
$user_id |
int | Yes | The users numeric ID. | |
} |
public function assign( $user_id = false, $level_id = 0 ) {
|
||||
Description: | Assigns a specific user to this badge with the option to also set a particular level that the user has reached. | |||
---|---|---|---|---|
Variable | Type | Required | Description | |
$user_id |
int | Yes | The users numeric ID. | |
$level_id |
int | Yes | The badge level ID the user has reached. For the first level or if no levels are used, use zero. | |
} |
public function payout_reward( $previous_level = -1, $new_level = 0 ) {
|
||||
Description: | This method will payout the reward (if set) set for the levels a user reaches. If the user jumps multiple levels in one event, this method will payout the reward for every level the user jumped over. | |||
---|---|---|---|---|
Variable | Type | Required | Description | |
$previous_level |
int | Yes | The previous level a user reached with this badge. If the user just now earned the badge, this variable should be -1 since level IDs start from zero. |
|
$new_level |
int | Yes | The ID of the new level the user reached. | |
} |
public function assign_all() {
|
||||
Description: | This method will try to assign those users that have earned this badge. This is used when a badge is published for the first time or when the "Assign" button is used when editing a badge. Depending on your log size and user count, this method can require a lot of server resources to run. Please make sure you only run this when necessary! | |||
---|---|---|---|---|
} |
public function divest( $user_id = false ) {
|
||||
Description: | Removes this badge from a given user. | |||
---|---|---|---|---|
Variable | Type | Required | Description | |
$user_id |
int | Yes | The users numeric ID. | |
} |
public function divest_all() {
|
||||
Description: | Removes this badge from all users. | |||
---|---|---|---|---|
} |
public function delete( $delete_post = false ) {
|
||||
Description: | This method will delete this badge. Note that this method uses divest_all() to delete the badge form your users before deleting the badge's setup. | |||
---|---|---|---|---|
Variable | Type | Required | Description | |
$delete_post |
bool | No | Option to also delete the WordPress post object. Warning! This will delete the object not trash it! | |
} |
public function get_image( $image = NULL ) {
|
||||
Description: | This method will return either the main badge image (used for when a badge has not yet been earned) or a specific levels image. | |||
---|---|---|---|---|
Variable | Type | Required | Description | |
$image |
int or string | Yes | Either the keyword main to show the main image or the level ID for the image of a particular level. |
|
} |
Object Example
myCRED_Badge Object ( [post_id] => 29 [title] => Best User [earnedby] => 1 [manual] => [levels] => Array ( [0] => Array ( [attachment_id] => 165 [image_url] => [label] => Commended [compare] => AND [requires] => Array ( [0] => Array ( [type] => mycred_default [1] => manual [amount] => 1000 [by] => sum ) ) [reward] => Array ( [type] => mycred_default [log] => [amount] => 0 ) ) [1] => Array ( [attachment_id] => 166 [image_url] => [label] => Hero [compare] => AND [requires] => Array ( [0] => Array ( [type] => mycred_default [1] => manual [amount] => 5000 [by] => sum ) ) [reward] => Array ( [type] => mycred_default [log] => [amount] => 0 ) ) ) [main_image] => '' [level] => Array ( ) [level_id] => 0 [level_label] => '' [level_image] => Best User [image_width] => 100 [image_height] => 100 [references] => Array ( [0] => manual ) [point_types] => Array ( [0] => mycred_default ) [user_meta_key:protected] => mycred_badge29 [user_id] => 125 [current_level] => 0 [compare] => AND )