MDL-81714 grades: Add regrading progress indicator to grade reports

Author: marxjohnson

admin/tool/componentlibrary/content/moodle/components/task-indicator.md

@@ -0,0 +1,93 @@
+---
+layout: docs
+title: "Task indicator"
+description: "A progress indicator for background tasks"
+date: 2024-08-21T00:00:00+01:00
+draft: false
+tags:
+- MDL-81714
+- 4.5
+---
+
+{{< mustache template="core/task_indicator" >}}
+{{< /mustache >}}
+
+## How to use
+
+The task indicator component is used to display on any page the status and progress of an ad-hoc or scheduled task running in the
+background. If a task is running that will update the content on the page, it can be displayed in place of the content to inform
+the user that the current content is out-of-date, and will be updated when the task is complete.
+
+## Source files
+
+* lib/amd/src/task_indicator.js
+* lib/classes/output/task_indicator.php
+* lib/templates/task_indicator.mustache
+
+## Usage
+
+The task indicator can only be used to display the progress of a task if its class uses `core\task\stored_progress_task_trait`.
+
+When the task is queued, you must call the `initialise_stored_progress()` method to store the progress record in a pending state,
+for the indicator to display while the task is queued.
+
+{{< php >}}
+$task = new \core\task\mytask($id);
+$taskid = \core\task\manager::queue_adhoc_task($task, true);
+if ($taskid) {
+    $task->set_id($taskid);
+    $task->initialise_stored_progress();
+}
+{{< /php  >}}
+
+When the task runs, it must start, progress and complete its stored progress bar.
+See `core_course\task\regrade_final_grades` for a real-life example.
+
+{{< php >}}
+
+class mytask extends adhoc_task {
+    use \core\task\stored_progress_task_trait;
+
+    public function execute(): void {
+        $this->start_stored_progress();
+        $storedprogress = $this->get_progress();
+        foreach ($this->get_records() as $record) {
+            $this->process_record($record);
+            $storedprogress->progress();
+        }
+        $storedprogress->end_progress();
+    }
+}
+
+{{< /php  >}}
+
+Any page that wishes to display the status of the task must create an instance of the task object with the same parameters,
+and pass it to a `task_indicator`.
+
+{{< php >}}
+
+$task = new mytask($id);
+$taskindicator = new \core\output\task_indicator(
+    task: $task,
+    heading: 'Task processing',
+    message: get_string('recalculatinggradesadhoc', 'grades'),
+    icon: new \core\output\pix_icon('i/grades', ''),
+    redirecturl: $PAGE->url,
+    extraclasses: ['mytask'],
+);
+
+{{< /php  >}}
+
+If there is currently a queued instance of the task, `$taskindicator->has_task_record()` will return true. We can use this to
+decide whether we display the indicator. See `grade/report/summary/index.php` for a real-life example.
+
+{{< php >}}
+
+if ($taskindicator->has_task_record()) {
+    echo $OUTPUT->render($taskindicator);
+}
+
+{{< /php  >}}
+
+If the optional `redirecturl` parameter is set when creating the indicator, the page will automatically reload or redirect to
+this URL when the progress bar completes.

grade/report/grader/index.php

@@ -49,10 +49,6 @@
 
 $PAGE->set_url(new moodle_url('/grade/report/grader/index.php', array('id'=>$courseid)));
 $PAGE->set_pagelayout('report');
-$PAGE->requires->js_call_amd('gradereport_grader/stickycolspan', 'init');
-$PAGE->requires->js_call_amd('gradereport_grader/user', 'init', [$baseurl->out(false)]);
-$PAGE->requires->js_call_amd('gradereport_grader/feedback_modal', 'init');
-$PAGE->requires->js_call_amd('core_grades/gradebooksetup_forms', 'init');
 
 // basic access checks
 if (!$course = $DB->get_record('course', array('id' => $courseid))) {
@@ -125,9 +121,16 @@
 }
 
 $reportname = get_string('pluginname', 'gradereport_grader');
-
-// Do this check just before printing the grade header (and only do it once).
-grade_regrade_final_grades_if_required($course);
+$regradetask = \core_course\task\regrade_final_grades::create($courseid);
+$indicatorheader = get_string('recalculatinggrades', 'grades');
+$indicatormessage = get_string('recalculatinggradesadhoc', 'grades');
+$indictoricon = new pix_icon('i/grades', '');
+$taskindicator = new \core\output\task_indicator($regradetask, $indicatorheader, $indicatormessage, $indictoricon, $PAGE->url);
+if (!$taskindicator->has_task_record()) {
+    // Do this check just before printing the grade header (and only do it once).
+    grade_regrade_final_grades_if_required($course);
+    $taskindicator = new \core\output\task_indicator($regradetask, $indicatorheader, $indicatormessage, $indictoricon, $PAGE->url);
+}
 
 //Initialise the grader report object that produces the table
 //the class grade_report_grader_ajax was removed as part of MDL-21562
@@ -139,13 +142,6 @@
 
 $report = new grade_report_grader($courseid, $gpr, $context, $page, $sortitemid, $sort);
 
-// We call this a little later since we need some info from the grader report.
-$PAGE->requires->js_call_amd('gradereport_grader/collapse', 'init', [
-    'userID' => $USER->id,
-    'courseID' => $courseid,
-    'defaultSort' => $report->get_default_sortable()
-]);
-
 $numusers = $report->get_numusers(true, true);
 
 $actionbar = new \gradereport_grader\output\action_bar($context, $report, $numusers);
@@ -166,6 +162,23 @@
     $warnings = $report->process_data($data);
 }
 
+if ($taskindicator->has_task_record()) {
+    echo $OUTPUT->render($taskindicator);
+    echo $OUTPUT->footer();
+    exit;
+}
+
+// We call this a little later since we need some info from the grader report.
+$PAGE->requires->js_call_amd('gradereport_grader/collapse', 'init', [
+    'userID' => $USER->id,
+    'courseID' => $courseid,
+    'defaultSort' => $report->get_default_sortable(),
+]);
+$PAGE->requires->js_call_amd('gradereport_grader/stickycolspan', 'init');
+$PAGE->requires->js_call_amd('gradereport_grader/user', 'init', [$baseurl->out(false)]);
+$PAGE->requires->js_call_amd('gradereport_grader/feedback_modal', 'init');
+$PAGE->requires->js_call_amd('core_grades/gradebooksetup_forms', 'init');
+
 // Final grades MUST be loaded after the processing.
 $report->load_users();
 $report->load_final_grades();

grade/report/outcomes/index.php

@@ -44,7 +44,13 @@
 }
 
 // First make sure we have proper final grades.
-grade_regrade_final_grades_if_required($course);
+$regradetask = \core_course\task\regrade_final_grades::create($courseid);
+$indicatormessage = get_string('recalculatinggradesadhoc', 'grades');
+$taskindicator = new \core\output\task_indicator($regradetask, $indicatormessage);
+if (!$taskindicator->has_task_record()) {
+    grade_regrade_final_grades_if_required($course);
+    $taskindicator = new \core\output\task_indicator($regradetask, $indicatormessage);
+}
 
 // Grab all outcomes used in course.
 $report_info = array();
@@ -96,6 +102,14 @@
     }
 }
 
+print_grade_page_head($courseid, 'report', 'outcomes');
+
+if ($taskindicator->has_task_record()) {
+    echo $OUTPUT->render($taskindicator);
+    echo $OUTPUT->footer();
+    exit;
+}
+
 $html = '<table class="generaltable boxaligncenter" width="90%" cellspacing="1" cellpadding="5" summary="Outcomes Report">' . "\n";
 $html .= '<tr><th class="header c0" scope="col">' . get_string('outcomeshortname', 'grades') . '</th>';
 $html .= '<th class="header c1" scope="col">' . get_string('courseavg', 'grades') . '</th>';
@@ -176,8 +190,6 @@
 
 $html .= '</table>';
 
-print_grade_page_head($courseid, 'report', 'outcomes');
-
 echo $html;
 
 $event = \gradereport_outcomes\event\grade_report_viewed::create(

grade/report/overview/index.php

@@ -90,6 +90,14 @@
 $actionbar = new \core_grades\output\general_action_bar($context,
     new moodle_url('/grade/report/overview/index.php', ['id' => $courseid]), 'report', 'overview');
 
+$taskindicator = new \core\output\task_indicator(
+    \core_course\task\regrade_final_grades::create($courseid),
+    get_string('recalculatinggrades', 'grades'),
+    get_string('recalculatinggradesadhoc', 'grades'),
+    new \core\output\pix_icon('i/grades', ''),
+    $PAGE->url,
+);
+
 if (has_capability('moodle/grade:viewall', $context) && $courseid != SITEID) {
     // Please note this would be extremely slow if we wanted to implement this properly for all teachers.
     $groupmode    = groups_get_course_groupmode($course);   // Groups are being used
@@ -115,6 +123,12 @@
 
         groups_print_course_menu($course, $gpr->get_return_url('index.php?id='.$courseid, array('userid'=>0)));
 
+        if ($taskindicator->has_task_record()) {
+            echo $OUTPUT->render($taskindicator);
+            echo $OUTPUT->footer();
+            exit;
+        }
+
         if ($user_selector) {
             $renderer = $PAGE->get_renderer('gradereport_overview');
             echo $renderer->graded_users_selector('overview', $course, $userid, $currentgroup, false);
@@ -131,6 +145,12 @@
             $report->user, $actionbar);
         groups_print_course_menu($course, $gpr->get_return_url('index.php?id='.$courseid, array('userid'=>0)));
 
+        if ($taskindicator->has_task_record()) {
+            echo $OUTPUT->render($taskindicator);
+            echo $OUTPUT->footer();
+            exit;
+        }
+
         if ($user_selector) {
             $renderer = $PAGE->get_renderer('gradereport_overview');
             echo $renderer->graded_users_selector('overview', $course, $userid, $currentgroup, false);
@@ -168,6 +188,11 @@
             }
 
             echo $OUTPUT->header();
+            if ($taskindicator->has_task_record()) {
+                echo $OUTPUT->render($taskindicator);
+                echo $OUTPUT->footer();
+                exit;
+            }
             if ($report->fill_table(true, true)) {
                 echo html_writer::tag('h3', get_string('coursesiamtaking', 'grades'));
                 echo '<br />' . $report->print_table(true);
@@ -176,6 +201,11 @@
             print_grade_page_head($courseid, 'report', 'overview', get_string('pluginname', 'gradereport_overview')
                 . ' - ' . fullname($report->user), false, false, true, null, null,
                 $report->user, $actionbar);
+            if ($taskindicator->has_task_record()) {
+                echo $OUTPUT->render($taskindicator);
+                echo $OUTPUT->footer();
+                exit;
+            }
             if ($report->fill_table()) {
                 echo '<br />' . $report->print_table(true);
             }
@@ -189,6 +219,11 @@
     }
 
     if (count($report->teachercourses)) {
+        if ($taskindicator->has_task_record()) {
+            echo $OUTPUT->render($taskindicator);
+            echo $OUTPUT->footer();
+            exit;
+        }
         echo html_writer::tag('h3', get_string('coursesiamteaching', 'grades'));
         $report->print_teacher_table();
     }

grade/report/singleview/index.php

@@ -133,8 +133,6 @@
         break;
 }
 
-$report = new gradereport_singleview\report\singleview($courseid, $gpr, $context, $itemtype, $itemid);
-
 $pageparams = [
     'id'        => $courseid,
     'userid'    => $userid,
@@ -150,6 +148,32 @@
 
 $PAGE->set_url(new moodle_url('/grade/report/singleview/index.php', $pageparams));
 
+// Make sure we have proper final grades.
+$taskindicator = new \core\output\task_indicator(
+    \core_course\task\regrade_final_grades::create($courseid),
+    get_string('recalculatinggrades', 'grades'),
+    get_string('recalculatinggradesadhoc', 'grades'),
+    new \core\output\pix_icon('i/grades', ''),
+    $PAGE->url,
+);
+
+if ($taskindicator->has_task_record()) {
+    // We need to bail out early on as the report requires recalculations to be complete, so just display a basic header
+    // with navigation, and the indicator.
+    $actionbar = new \core_grades\output\general_action_bar(
+        $context,
+        new moodle_url('/grade/report/singleview/index.php', ['id' => $courseid]),
+        'report',
+        'singleview'
+    );
+    print_grade_page_head($course->id, 'report', 'singleview', actionbar: $actionbar);
+    echo $OUTPUT->render($taskindicator);
+    echo $OUTPUT->footer();
+    exit;
+}
+
+$report = new gradereport_singleview\report\singleview($courseid, $gpr, $context, $itemtype, $itemid);
+
 // Build editing on/off button for themes that need it.
 $button = '';
 if ($PAGE->user_allowed_editing() && !$PAGE->theme->haseditswitch) {
@@ -208,9 +232,6 @@
     }
 }
 
-// Make sure we have proper final grades.
-grade_regrade_final_grades_if_required($course);
-
 // Save the screen state in a session variable as last viewed state.
 $SESSION->gradereport_singleview["itemtype-{$context->id}"] = $itemtype;
 if ($itemid) {

grade/report/summary/index.php

@@ -45,11 +45,21 @@
 require_capability('gradereport/summary:view', $context);
 require_capability('moodle/grade:viewall', $context);
 
-print_grade_page_head($courseid, 'report', 'summary', false,
-    false, false, true, null, null,
-    null, null);
+$taskindicator = new \core\output\task_indicator(
+    \core_course\task\regrade_final_grades::create($courseid),
+    get_string('recalculatinggrades', 'grades'),
+    get_string('recalculatinggradesadhoc', 'grades'),
+    new \core\output\pix_icon('i/grades', ''),
+    $PAGE->url,
+);
 
-$report = system_report_factory::create(summary::class, context_course::instance($courseid));
+print_grade_page_head($courseid, 'report', 'summary');
+
+if ($taskindicator->has_task_record()) {
+    echo $OUTPUT->render($taskindicator);
+} else {
+    $report = system_report_factory::create(summary::class, context_course::instance($courseid));
+    echo $report->output();
+}
 
-echo $report->output();
 echo $OUTPUT->footer();

grade/report/user/classes/external/user.php

@@ -161,7 +161,7 @@ protected static function get_report_data(
         require_once($CFG->dirroot . '/grade/report/user/lib.php');
 
         // Force regrade to update items marked as 'needupdate'.
-        grade_regrade_final_grades($course->id);
+        grade_regrade_final_grades($course->id, async: false);
 
         $gpr = new grade_plugin_return(
             [