Gradebook API

Overview

This document explains how custom Moodle activity modules may use the Gradebook API to read and write student grades.

The Gradebook API allows you to read and write from the gradebook. It also allows you to provide an interface for detailed grading information.

File Locations

The main file of interest for the gradebook API is /lib/gradelib.php

Functions

grade_update() is used to submit new or updated grades.

grade_update_outcomes() is used to submit new or updated outcomes.

grade_get_grades() is used to retrieve grade information about a given activity. Optionally you can retrieve student grades for that activity.

Infrastructure Required From a Custom Activity Module

/mod/$modname/grade.php

A teacher or student clicking on the activity name in the gradebook is sent to grade.php within the activities directory. It should redirect the user to the appropriate page. For example, sending students to the activity itself while sending teachers to a list of students who have completed the activity.

grade.php is supplied with the following parameters.

$id = required_param('id', PARAM_INT); // Course module ID $itemnumber = optional_param('itemnumber', 0, PARAM_INT); // Item number, may be != 0 for activities that allow more than one grade per user $userid = optional_param('userid', 0, PARAM_INT); // Graded user ID (optional)

Typically you will use has_capability() to determine where to send the user then call redirect().

Callbacks

Gradebook callbacks should be available in /mod/$modname/lib.php For example the assignment activity module gradebook callbacks are in /mod/assignment/lib.php

There are two required callbacks.

{$modname}_grade_item_update($modinstance, $grades=NULL)

For example, this callback for the assignment module is assignment_grade_item_update().

This callback should create or update the grade item for a given activity module instance by calling grade_update(). It can update both the activity grade item information and grade's for users if they are supplied via the $grades parameter.

Typically the $grades parameter also accepts the string 'reset' which means that the grades in the gradebook should be reset. This assists with course reset functionality which is described below.

{$modname}_update_grades($modinstance, $userid=0, $nullifnone=true)

For example, this callback for the assignment module is assignment_update_grades().

This callback should update the grade(s) for the supplied user. This may be as simple as retrieving the grades for the user from the activity module's own tables then calling {$modname}_grade_item_update().

Its parameters are:

1. stdClass $quiz the quiz settings.
2. int $userid specific user only, 0 means all users.
3. bool $nullifnone If a single user is specified and $nullifnone is true a grade item with a null rawgrade should be inserted

Examples

{$modname}_grade_item_update($modinstance, $grades=NULL)

This is the forum activity module's implementation of this callback taken from /mod/forum/lib.php. Note that Moodle scales are stored as a positive integer if they are numeric, as a negative integer if they are a custom scale and 0 means the forum is ungraded (this system may be changed by MDL-17258).

function forum_grade_item_update($forum, $grades=NULL) {

   global $CFG;
   if (!function_exists('grade_update')) { //workaround for buggy PHP versions
       require_once($CFG->libdir.'/gradelib.php');
   }

   $params = array('itemname'=>$forum->name, 'idnumber'=>$forum->cmidnumber);

   if (!$forum->assessed or $forum->scale == 0) {
       $params['gradetype'] = GRADE_TYPE_NONE;

   } else if ($forum->scale > 0) {
       $params['gradetype'] = GRADE_TYPE_VALUE;
       $params['grademax']  = $forum->scale;
       $params['grademin']  = 0;

   } else if ($forum->scale < 0) {
       $params['gradetype'] = GRADE_TYPE_SCALE;
       $params['scaleid']   = -$forum->scale;
   }

   if ($grades  === 'reset') {
       $params['reset'] = true;
       $grades = NULL;
   }

   return grade_update('mod/forum', $forum->course, 'mod', 'forum', $forum->id, 0, $grades, $params);

}

{$modname}_update_grades($modinstance, $userid=0, $nullifnone=true)

This is the forum activity module's implementation of this callback taken from /mod/forum/lib.php.

It checks if the forum is assessed (has a grade). If it is it attempts to load the user's grade. The forum function forum_get_user_grades() does this by accessing the Rating_API however your activity module will probably access its own tables. If the user has no grade and $nullifnone is true then a grade with rawgrade == NULL is inserted.

function forum_update_grades($forum, $userid=0, $nullifnone=true) {

   global $CFG, $DB;
   require_once($CFG->libdir.'/gradelib.php');

   if (!$forum->assessed) {
       forum_grade_item_update($forum);

   } else if ($grades = forum_get_user_grades($forum, $userid)) {
       forum_grade_item_update($forum, $grades);

   } else if ($userid and $nullifnone) {
       $grade = new stdClass();
       $grade->userid   = $userid;
       $grade->rawgrade = NULL;
       forum_grade_item_update($forum, $grade);

   } else {
       forum_grade_item_update($forum);
   }

}

Additional Reading

Reset Course

Reset Course allows a user to remove all user data from a course while retaining settings and activities. Here is a general introduction to resetting a course. Here is a guide to Implementing_Reset_course_functionality_in_a_module

Resetting grades isn't specifically covered in the reset course implementation guide. The quiz activity module provides a simple example of how that is done. quiz_reset_userdata() contains this function call.

if (empty($data->reset_gradebook_grades)) {

   quiz_reset_gradebook($data->courseid);

}

quiz_reset_gradebook() find all quiz instances then calls quiz_grade_item_update() with the special 'reset' parameter.

/**

* Removes all grades from gradebook
*
* @param int $courseid
* @param string optional type
*/

function quiz_reset_gradebook($courseid, $type=) {

   global $CFG, $DB;

   $quizzes = $DB->get_records_sql("
           SELECT q.*, cm.idnumber as cmidnumber, q.course as courseid
           FROM {modules} m
           JOIN {course_modules} cm ON m.id = cm.module
           JOIN {quiz} q ON cm.instance = q.id
           WHERE m.name = 'quiz' AND cm.course = ?", array($courseid));

   foreach ($quizzes as $quiz) {
       quiz_grade_item_update($quiz, 'reset');
   }

}