From version 6.0.4 WatuPro has a filter that allows plugging in your own custom grade calculation that replaces the built-in calculation. This can be useful in very specific quizzes where the grade is calculated in a non-standard way and cannot be handled by the existing functions.

This filter is a bit more complicated to explain hence we have created a separate post for it. If you are looking for the general developer’s API guide it’s here.

Using the filter:

You need to add the filter in the following way:

add_filter('watupro_calculate_grade', 'your_callback_function', 10, 8);

As you can see the filter needs 8 arguments. Here is how your callback function should be structured, with explanation of all arguments:

function your_callback_function($return_arr, $taking_id, $exam_id, $points, $percent, $cat_id, $user_grade_ids, $points_percent) {
   // expand $return_arr in the 4 constructing variables if you need:
   list($grade_text, $certificate_id, $redirect_url, $grade_object) = $return_arr;

   // your custom calculation here which may modify each of the 4 $return_arr elements
   // ...

   // return array of 4 elements
   return array($grade_text, $certificate_id, $redirect_url, $grade_object);
}

Attributes / Arguments

Here are the attributes in detail:

$return_arr is an array of 4 variables: $grade_text is the human-readable grade or personality type returned from the test (title and description); $certificate_id is ID of the assigned certificate, if any, otherwise 0; $redirect_url is optional URL where the user should be redirected to at the end of quiz, or false if no redirect; $grade_object is the grade as DB object returned from the wp_watupro_grades table. You can construct it yourself with the minimum required properties: “title” and “description”.

$taking_id is the ID from the watupro_taken_exams table which corresponds to this quiz attempt. VERY IMPORTANT: at the time of grade calculation the $taking_id already exists however the full details are not yet populated in watupro_taken_exams table. That’s why we pass points, percent correct, etc. as additional variables. The purpose of passing $taking_id is that it allows you to access all the individual answers from wp_watupro_student_answers table in your custom grade calculator, should you need so. Example query:

$answers = $wpdb->get_results($wpdb->prepare("SELECT * FROM ".WATUPRO_STUDENT_ANSWERS." WHERE taking_id=%d ORDER BY ID", $taking_id));

$exam_id is the ID of the test / quiz.

$points is the number of points collected. If $cat_id is 0, then $points are the total points collected on the attempt. If $cat_id is not 0, then $points is the number of points collected for that specific category ID.

$percent is the % correct answers collected. If $cat_id is 0, then $percent is the % correct answers on the whole attempt. If $cat_id is no 0, then $percent is the % correct answers for that specific category ID.

$cat_id is the ID of the category for which the grade is calculated. When 0 this means we are calculating the grade / result for the test attempt. When not 0 we are calculating grade for that specific category and you should return grade for that specific category, or none.

$user_grade_ids is used only on personality tests. It contains array with IDs of the personality types in a specific format.

$points_percent contains the percent of maximum points on this quiz attempt. If $cat_id is not 0, then it’s the percent of maximum points for that category ID.

Your custom function should always return an array of 4 elements as explained in $return_arr above – changed or unchanged. Be very careful not to mess the order of variables as you won’t be getting the expected result.