Customize how your contest logic works with hooks.

Developers can customize how contests work with easy to implement Wordpress hooks. Below is a list of the available WP Contest Creator Hooks developers can use:

 

Filters

wcc_on_winner_selection : allows to customize the winner selection logic and return your contest winners.

wcc_before_email_notification : allows to customize the email template sent when a participant joins or wins a contest

wcc_before_participant_insert : allows validating & handling the data submitted by the participant upon joining a contest.

 

Actions

 wcc_on_submit_participant : allows handling the participant data at the time the participant submits the signup form

 

wcc_on_winner_selection top of page

Allows to customize the winner selection logic.

This filter gives the developer the freedom to apply any special logic to select the contest winners based on the points or any other criteria special to your contest.

Parameters:

$selection_type holds the winner selection mode set for the contest. Possible values: most_points, manual, random
 $contest_id  holds the post ID of the current contest
 $has_notification  holds the setting that tells if winner notifications are enabled. Possible values: on or empty string

Return:

The function must return the winner(s) of the contest as a string or HTML.

Example:

add_filter('wcc_on_winner_selection', 'set_contest_winners', 10, 3);

function set_contest_winners($selection_type, $contest_id, $has_notifications) {

	global $wpdb;

	// We cannot proceed without a valid contest id
	if(!$contest_id)
		return '';

	// If we already selected a winner display it, otherwise continue.
	if(false !== get_transient('wcc_contest_winner_'.$contest_id))
		return get_transient('wcc_contest_winner_'.$contest_id);

	// Step 1: Lets get the person with most points
	$table = $wpdb->prefix . 'wcc_participant';
	$single_winner = $wpdb->get_row('SELECT * FROM '.$table.' p1 WHERE signups = (SELECT MAX(signups) FROM '.$table.' p2 WHERE contest_id = '.$contest_id.' AND p1.id_participant = p2.id_participant) ORDER BY signups DESC, entry_date DESC');

	// We check if we have found valid winner, otherwise we cannot proceed
	if(!$single_winner)
		return '';

	// Step 2: Now that we have the person with the most points, lets tag them as winner(s)
	// (a similar logic can be used for multiple winners with a foreach loop)
	$values = array('status' => 'winner');
	$where = array('id_participant' => $single_winner->id_participant, 'contest_id' => $contest_id);
	$success = $wpdb->update(($wpdb->prefix . 'wcc_participant'), $values, $where);

	// Step 3: Let's notify our winner (if winner notifications are enabled for this contest)
	if($has_notifications == 'on')
	{
		// Let's check for a notification cache, to prevent notifying our winner multiple times
		if(false === get_transient('wcc_contest_winner_'.$contest_id.'_'.$single_winner->id_participant))
		{
			wcc_admin_loader::send_lead_notification($contest_id, $single_winner->email,'','winner');
			// Now set a notification cache for this winner to avoid sending multiple times
			set_transient(('wcc_contest_winner_'.$contest_id.'_'.$single_winner->id_participant), 1, (86400*3));
		}
	}
	/* Step 4: Now we need to return the actual winners of the contest (for the contest front-end). We can use anything
	 * like the username of the email or any custom field we got from that participant using (a SQL query). To simplify this example we are going
	 * to use the email username (same logic can be applied for multiple winners with a foreach that returns html with many winners)
	 */
	$winner = substr($single_winner->email, 0, strpos($single_winner->email, "@"));
	set_transient('wcc_contest_winner_'.$contest_id, $winner, (86400*3));

	return $winner;
}

wcc_before_email_notification top of page

Allows to customize the email template sent when a participant joins or wins a contest.

This filter allows to customize the email template set on the notifications tab. Using this filter the contest admin can add any special merge fields onto the email template and populate them dynamically on the callback function.

Parameters:

$email_template holds email template set on the notification tab when a participant joins or wins a contest
$notification_type holds the type of notification of the message that will be sent. Possible values: participant, winner
$unique_share_url holds the unique share URL generated for the participant after he or she joined
$contest_url holds the URL of the current contest
$contest_name holds the contest name of the current contest
$contest_id holds the ID of the current contest

Return:

The modified email template as a string or HTML.

Example:

add_filter('wcc_before_email_notification', 'before_notification_email', 10, 6);

function before_notification_email($email_template, $notification_type, $unique_share_url, $contest_url, $contest_name, $contest_id) {

	$join_msg = 'Thank for joining! Continue spreading the word to be the winner of this contest';
	$winner_msg = 'You Won! You are amazing!';

	if($notification_type == 'participant') {
		$email_template = str_replace('{unique_share_link}', $unique_share_url, $email_template);
		$email_template = str_replace('{custom_join_msg}', $join_msg, $email_template);

	} else if($notification_type == 'winner') {
		$email_template = str_replace('{custom_winner_msg}', $winner_msg, $email_template);
	}
	// These are message template tags common to any email messages
	$email_template = str_replace('{contest_headline}', $contest_name, $email_template);
	$email_template = str_replace('{contest_url}', $contest_url, $email_template);

	return $email_template;
}

wcc_before_participant_insert top of page

Allows to validating or handling the participant data before the data is inserted into the database.

Parameters:

$participant_data holds an key / value array with the field names and values submitted when a participant joined the contest.

Return:

The modified email template as a string or HTML.

Example:

add_filter('wcc_before_participant_insert', 'before_participant_insert', 10, 1);

function before_participant_insert($participant_data) {
	// Setting a validation flag to true
	$valid = true;
	// Lets check what the participant submitted as values to our contest
	foreach ($participant_data as $key => $value) {
		// On this example we force that the email is always john@example.com
		if($key == 'email' || $key == 'Email') {
			$participant_data[$key] = 'john@example.com';
		}
		// Next we ensure that the first name is set to "John", otherwise tag this as an invalid entry
		if($key == 'First Name' && $value != 'John') {
			$valid = false;
		}
	}
	// If our participant entry is not valid, we send a fake entry confirmation as a json response.
	if(!$valid) {
		echo  json_encode(array(
			'share_code' => rand(),
			'share_url' => 'http://example.com/random_string_here',
			'already_exists' => 'yes',
			'email' => $participant_data['email'],
			'cid' => $participant_data['contest_id']
		));
		// returning false ensures that no data is inserted into the database
		return false;
	}
	// If the contest entry is valid, we return the participant data array back to WP Contest Creator
	return $participant_data;
}

wcc_on_submit_participant top of page

allows handling the participant data at the time the participant submits the signup form.

This action hook gives the developer the opportunity to capture and handle the participant data submitted on your custom forms. This offers the flexibility to implement any mailing list provider API, or perform any custom task after evaluating the participant data. This hook runs after the participant has been inserted into the database. To interact with the participant data before the database insert use wcc_before_participant_insert

Parameters:

$participant_email holds the participant email address
 $participant_data

holds an array of key / value with keys as field names and values as the actual value submitted by the participant. 

Array('field_name' => 'value_here')

Return:

Void

Example:

add_action('wcc_on_submit_participant', 'submit_particpant_to_provider', 10, 2);
// Example that captures the participant form data and sends an email to email@example.com
// with the participant data formatted as a JSON string function submit_particpant_to_provider($participant_email, $participant_data) { wp_mail('email@example.com', 'a Participant entered API', json_encode($participant_data)); }
Have more questions? Submit a request

0 Comments

Please sign in to leave a comment.
Powered by Zendesk