MDL-29920 Gradebook grader report now supports grade analysis link

When grade analysis link is enabled, an icon is displayed next to each
grade of a module that supports grade.php file. The parameters needed to
identify the particular user and grade are passed to the grade.php
script.

grade/lib.php

@@ -1174,6 +1174,74 @@ class grade_structure {
         }
     }
 
+    /**
+     * Returns URL of a page that is supposed to contain detailed grade analysis
+     *
+     * Please note this method does not check if the referenced file actually exists,
+     * the caller is usually able to do it in more effective way.
+     *
+     * At the moment, only activity modules are supported. The method generates link
+     * to the module's file grade.php with the parameters id (cmid), itemid, itemnumber,
+     * gradeid and userid.
+     *
+     * @return moodle_url|null URL or null if unable to construct it
+     */
+    public function get_grade_analysis_url(grade_grade $grade) {
+
+        if (empty($grade->grade_item) or !($grade->grade_item instanceof grade_item)) {
+            throw new coding_exception('Passed grade without the associated grade item');
+        }
+        $item = $grade->grade_item;
+
+        if (!$item->is_external_item()) {
+            // at the moment, only activity modules are supported
+            return null;
+        }
+        if ($item->itemtype !== 'mod') {
+            throw new coding_exception('Unknown external itemtype: '.$item->itemtype);
+        }
+        if (empty($item->iteminstance) or empty($item->itemmodule) or empty($this->modinfo)) {
+            return null;
+        }
+
+        $instances = $this->modinfo->get_instances();
+        if (empty($instances[$item->itemmodule][$item->iteminstance])) {
+            return null;
+        }
+        $cm = $instances[$item->itemmodule][$item->iteminstance];
+        if (!$cm->uservisible) {
+            return null;
+        }
+
+        $url = new moodle_url('/mod/'.$item->itemmodule.'/grade.php', array(
+            'id'         => $cm->id,
+            'itemid'     => $item->id,
+            'itemnumber' => $item->itemnumber,
+            'gradeid'    => $grade->id,
+            'userid'     => $grade->userid,
+        ));
+
+        return $url;
+    }
+
+    /**
+     * Returns an action icon leading to the grade analysis page
+     *
+     * @param grade_grade $grade
+     * @return string
+     */
+    public function get_grade_analysis_icon(grade_grade $grade) {
+        global $OUTPUT;
+
+        $url = $this->get_grade_analysis_url($grade);
+        if (is_null($url)) {
+            return '';
+        }
+
+        return $OUTPUT->action_icon($url, new pix_icon('i/search',
+            get_string('gradeanalysis', 'core_grades')));
+    }
+
     /**
      * Returns the grade eid - the grade may not exist yet.
      *

grade/report/grader/lib.php

@@ -802,9 +802,11 @@ class grade_report_grader extends grade_report {
 
         $rows = $this->get_right_icons_row($rows);
 
-        // Preload scale objects for items with a scaleid
+        // Preload scale objects for items with a scaleid, initialize tab indices and prepare the list
+        // of all activity modules that have the file grade.php present if showanalysisicon is enabled
         $scaleslist = array();
         $tabindices = array();
+        $modgrades  = array();
 
         foreach ($this->gtree->get_items() as $itemid=>$item) {
             $scale = null;
@@ -817,6 +819,16 @@ class grade_report_grader extends grade_report {
             $tabindices[$item->id]['grade'] = $gradetabindex;
             $tabindices[$item->id]['feedback'] = $gradetabindex + $numusers;
             $gradetabindex += $numusers * 2;
+
+            if ($this->get_pref('showanalysisicon')) {
+                if ($item->itemtype == 'mod' and !array_key_exists($item->itemmodule, $modgrades)) {
+                    if (file_exists($CFG->dirroot . '/mod/' . $item->itemmodule . '/grade.php')) {
+                        $modgrades[$item->itemmodule] = true;
+                    } else {
+                        $modgrades[$item->itemmodule] = false;
+                    }
+                }
+            }
         }
         $scalesarray = array();
 
@@ -1007,6 +1019,11 @@ class grade_report_grader extends grade_report {
                     if ($item->needsupdate) {
                         $itemcell->text .= html_writer::tag('span', get_string('error'), array('class'=>"gradingerror$hidden$gradepass"));
                     } else {
+                        if ($this->get_pref('showanalysisicon') and !is_null($gradeval)) {
+                            if ($item->itemtype == 'mod' and !empty($modgrades[$item->itemmodule])) {
+                                $itemcell->text .= $this->gtree->get_grade_analysis_icon($grade);
+                            }
+                        }
                         $itemcell->text .= html_writer::tag('span', grade_format_gradevalue($gradeval, $item, true, $gradedisplaytype, null), array('class'=>"gradevalue$hidden$gradepass"));
                     }
                 }

grade/report/grader/preferences_form.php

@@ -112,6 +112,7 @@ class grader_report_preferences_form extends moodleform {
             $preferences['prefshow']['showuseridnumber'] = $checkbox_default;
             $preferences['prefshow']['showactivityicons'] = $checkbox_default;
             $preferences['prefshow']['showranges'] = $checkbox_default;
+            $preferences['prefshow']['showanalysisicon'] = $checkbox_default;
 
             if ($canviewhidden) {
                 $preferences['prefrows']['shownumberofgrades'] = $checkbox_default;

grade/report/grader/settings.php

@@ -60,6 +60,9 @@ if ($ADMIN->fulltree) {
     $settings->add(new admin_setting_configcheckbox('grade_report_showranges', get_string('showranges', 'grades'),
                                                 get_string('showranges_help', 'grades'), 0));
 
+    $settings->add(new admin_setting_configcheckbox('grade_report_showanalysisicon', get_string('showanalysisicon', 'core_grades'),
+                                                get_string('showanalysisicon_desc', 'core_grades'), 1));
+
     $settings->add(new admin_setting_configcheckbox('grade_report_showuserimage', get_string('showuserimage', 'grades'),
                                                 get_string('showuserimage_help', 'grades'), 1));
 

lang/en/grades.php

@@ -212,6 +212,7 @@ $string['fullview'] = 'Full view';
 $string['generalsettings'] = 'General settings';
 $string['grade'] = 'Grade';
 $string['gradeadministration'] = 'Grade administration';
+$string['gradeanalysis'] = 'Grade analysis';
 $string['gradebook'] = 'Gradebook';
 $string['gradebookhiddenerror'] = 'The gradebook is currently set to hide everything from students.';
 $string['gradebookhistories'] = 'Grade histories';
@@ -533,6 +534,9 @@ $string['setpreferences'] = 'Set preferences';
 $string['setting'] = 'Setting';
 $string['settings'] = 'Settings';
 $string['setweights'] = 'Set weights';
+$string['showanalysisicon'] = 'Show grade analysis icon';
+$string['showanalysisicon_desc'] = 'Whether to show grade analysis icon by default. If the activity module supports it, the grade analysis icon links to a page with more detailed explanation of the grade and how it was obtained.';
+$string['showanalysisicon_help'] = 'If the activity module supports it, the grade analysis icon links to a page with more detailed explanation of the grade and how it was obtained.';
 $string['showaverage'] = 'Show average';
 $string['showaverage_help'] = 'Show the average column? Students may be able to estimate other student\'s grades if the average is calculated from a small number of grades. For performance reasons the average is approximate if it is dependent on any hidden items.';
 $string['showfeedback'] = 'Show feedback';