Advanced grading API

Overview

Advanced grading is introduced in Moodle 2.2 for grading of assignments. It is intended to be used for grading of other types of activities in the later versions. Moodle will try to minimize the future API changes but still they are possible.

Glossary

In advanced grading we operate with three main entities: grading area, grading form definition and grading form instance.

Grading area

Grading area is basically the area that can be graded. At the moment it is a submission in an assignment module. Each grading area may have several grading definitions but only one for each grading method. In assignment edit form (or on Advanced grading page) the teacher may set one of the advanced grading methods as current. Class grading_manager is responsible for operations with grading methods in one area.

Grading form definition

Grading form definitions is the set of rules on how the grading is performed. For example in rubrics this is the set of criteria and levels and their display options. The basic information about definition is stored in the standard DB table grading_definitions. A separate entry is created for each grading area (i.e. for each module). Users with permission moodle/grade:managegradingforms are able to edit the definitions and mark them as Ready.

Grading form instance

Grading form instance is created for each evaluation of student using advanced grading. One instance (usually the latest) has the status INSTANCE_STATUS_ACTIVE. Sometimes it may happen that teacher wants to change the definition when some students have already been graded. In this case their instances change status to INSTANCE_STATUS_NEEDUPDATE. The grade pushed to the gradebook remains unchanged but students will not see the grade in advanced grading format unless teacher updates them. Plugins are also welcome to use the statuses

Examples

Using advanced grading in grade-able modules

see mod/assignment/lib.php for example

1. function MODNAME_supports(FEATURE_ADVANCED_GRADING) must return true

2. module should define function MODNAME_grading_areas_list()

3. Check if there is set advanced grading method for this area and it is available. If yes, retrieve it and set the grade range used in this module.

       if ($controller = get_grading_manager(...)->get_active_controller()) {
           $controller->set_grade_range(...);
           ...
       }

There are two ways to create an instance object:

       $gradinginstance = $controller->get_current_instance(...);
       $gradinginstance = $controller->get_or_create_instance(...);

- during population of grading form the simple grading element should be substituted with advanced grading element

       $mform->addElement('grading', 'ELEMENTNAME', '...', array('gradinginstance' => $gradinginstance));

- on submit of grading form the advanced grading shall be also submitted and the grade for the gradebook retrieved from plugin and saved to gradebook.

       $grade = $gradinginstance->submit_and_get_grade($data->ELEMENTNAME, ...)

- when the grade is displayed to the student it is displayed as:

       $output .= $controller->render_grade(...);