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