| 1441 |
ariadna |
1 |
---
|
|
|
2 |
layout: docs
|
|
|
3 |
title: "Task indicator"
|
|
|
4 |
description: "A progress indicator for background tasks"
|
|
|
5 |
date: 2024-08-21T00:00:00+01:00
|
|
|
6 |
draft: false
|
|
|
7 |
tags:
|
|
|
8 |
- MDL-81714
|
|
|
9 |
- 5.0
|
|
|
10 |
---
|
|
|
11 |
|
|
|
12 |
{{< mustache template="core/task_indicator" >}}
|
|
|
13 |
{{< /mustache >}}
|
|
|
14 |
|
|
|
15 |
## How to use
|
|
|
16 |
|
|
|
17 |
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
|
|
|
18 |
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
|
|
|
19 |
the user that the current content is out-of-date, and will be updated when the task is complete.
|
|
|
20 |
|
|
|
21 |
## Source files
|
|
|
22 |
|
|
|
23 |
* lib/amd/src/task_indicator.js
|
|
|
24 |
* lib/classes/output/task_indicator.php
|
|
|
25 |
* lib/templates/task_indicator.mustache
|
|
|
26 |
|
|
|
27 |
## Usage
|
|
|
28 |
|
|
|
29 |
The task indicator can only be used to display the progress of a task if its class uses `core\task\stored_progress_task_trait`.
|
|
|
30 |
|
|
|
31 |
When the task is queued, you must call the `initialise_stored_progress()` method to store the progress record in a pending state,
|
|
|
32 |
for the indicator to display while the task is queued.
|
|
|
33 |
|
|
|
34 |
{{< php >}}
|
|
|
35 |
$task = new \core\task\mytask($id);
|
|
|
36 |
$taskid = \core\task\manager::queue_adhoc_task($task, true);
|
|
|
37 |
if ($taskid) {
|
|
|
38 |
$task->set_id($taskid);
|
|
|
39 |
$task->initialise_stored_progress();
|
|
|
40 |
}
|
|
|
41 |
{{< /php >}}
|
|
|
42 |
|
|
|
43 |
When the task runs, it must start, progress and complete its stored progress bar.
|
|
|
44 |
See `core_course\task\regrade_final_grades` for a real-life example.
|
|
|
45 |
|
|
|
46 |
{{< php >}}
|
|
|
47 |
|
|
|
48 |
class mytask extends adhoc_task {
|
|
|
49 |
use \core\task\stored_progress_task_trait;
|
|
|
50 |
|
|
|
51 |
public function execute(): void {
|
|
|
52 |
$this->start_stored_progress();
|
|
|
53 |
$storedprogress = $this->get_progress();
|
|
|
54 |
foreach ($this->get_records() as $record) {
|
|
|
55 |
$this->process_record($record);
|
|
|
56 |
$storedprogress->progress();
|
|
|
57 |
}
|
|
|
58 |
$storedprogress->end_progress();
|
|
|
59 |
}
|
|
|
60 |
}
|
|
|
61 |
|
|
|
62 |
{{< /php >}}
|
|
|
63 |
|
|
|
64 |
Any page that wishes to display the status of the task must create an instance of the task object with the same parameters,
|
|
|
65 |
and pass it to a `task_indicator`.
|
|
|
66 |
|
|
|
67 |
{{< php >}}
|
|
|
68 |
|
|
|
69 |
$task = new mytask($id);
|
|
|
70 |
$taskindicator = new \core\output\task_indicator(
|
|
|
71 |
task: $task,
|
|
|
72 |
heading: 'Task processing',
|
|
|
73 |
message: get_string('recalculatinggradesadhoc', 'grades'),
|
|
|
74 |
icon: new \core\output\pix_icon('i/grades', ''),
|
|
|
75 |
redirecturl: $PAGE->url,
|
|
|
76 |
extraclasses: ['mytask'],
|
|
|
77 |
);
|
|
|
78 |
|
|
|
79 |
{{< /php >}}
|
|
|
80 |
|
|
|
81 |
If there is currently a queued instance of the task, `$taskindicator->has_task_record()` will return true. We can use this to
|
|
|
82 |
decide whether we display the indicator. See `grade/report/summary/index.php` for a real-life example.
|
|
|
83 |
|
|
|
84 |
{{< php >}}
|
|
|
85 |
|
|
|
86 |
if ($taskindicator->has_task_record()) {
|
|
|
87 |
echo $OUTPUT->render($taskindicator);
|
|
|
88 |
}
|
|
|
89 |
|
|
|
90 |
{{< /php >}}
|
|
|
91 |
|
|
|
92 |
When the task begins running and the progress is updated, the progress bar will automatically be displayed.
|
|
|
93 |
|
|
|
94 |
If the optional `redirecturl` parameter is set when creating the indicator, the page will automatically reload or redirect to
|
|
|
95 |
this URL when the progress bar completes.
|
|
|
96 |
|
|
|
97 |
While the task is still queued, admins will see a "Run now" button below the indicator. This is designed for convenience if
|
|
|
98 |
a user is blocked on a job and needs the task run immediately. It will run the specific instance of the task tracked by the
|
|
|
99 |
indicator.
|
|
|
100 |
|
|
|
101 |
{{< mustache template="core/task_indicator" >}}
|
|
|
102 |
{
|
|
|
103 |
"heading": "Regrade in progress",
|
|
|
104 |
"icon": {
|
|
|
105 |
"attributes": [
|
|
|
106 |
{"name": "src", "value": "/pix/i/timer.svg"},
|
|
|
107 |
{"name": "alt", "value": ""}
|
|
|
108 |
]
|
|
|
109 |
},
|
|
|
110 |
"message": "Grades are being recalculated due to recent changes.",
|
|
|
111 |
"progress": {
|
|
|
112 |
"id": "progressbar_test",
|
|
|
113 |
"message": "Task pending",
|
|
|
114 |
"idnumber": "progressbar_test",
|
|
|
115 |
"class": "stored-progress-bar stored-progress-notstarted",
|
|
|
116 |
"width": "500",
|
|
|
117 |
"value": "0"
|
|
|
118 |
},
|
|
|
119 |
"runurl": "http://example.com/runtask.php?id=1",
|
|
|
120 |
"runlabel": "Run now"
|
|
|
121 |
}
|
|
|
122 |
{{< /mustache >}}
|