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.

{$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

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');
   }

}