weekly release 2.9dev
[moodle.git] / grade / export / lib.php
CommitLineData
e060e33d 1<?php
c10ddfb3 2
e060e33d 3// This file is part of Moodle - http://moodle.org/
4//
5// Moodle is free software: you can redistribute it and/or modify
6// it under the terms of the GNU General Public License as published by
7// the Free Software Foundation, either version 3 of the License, or
8// (at your option) any later version.
9//
10// Moodle is distributed in the hope that it will be useful,
11// but WITHOUT ANY WARRANTY; without even the implied warranty of
12// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
13// GNU General Public License for more details.
14//
15// You should have received a copy of the GNU General Public License
16// along with Moodle. If not, see <http://www.gnu.org/licenses/>.
ce34ed3a 17
89bd8357 18require_once($CFG->dirroot.'/lib/gradelib.php');
19require_once($CFG->dirroot.'/grade/lib.php');
a5bc4e6e 20require_once($CFG->dirroot.'/grade/export/grade_export_form.php');
0eeada79 21
1b074625 22/**
23 * Base export class
24 */
5c75a0a3 25abstract class grade_export {
ba74762b 26
5c75a0a3 27 public $plugin; // plgin name - must be filled in subclasses!
caffc55a 28
5c75a0a3 29 public $grade_items; // list of all course grade items
30 public $groupid; // groupid, 0 means all groups
31 public $course; // course object
32 public $columns; // array of grade_items selected for export
caffc55a 33
5c75a0a3 34 public $export_letters; // export letters
35 public $export_feedback; // export feedback
36 public $userkey; // export using private user key
caffc55a 37
5c75a0a3 38 public $updatedgradesonly; // only export updated grades
be289f57
SL
39
40 /**
41 * Grade display type (real, percentages or letter).
42 *
43 * This attribute is an integer for XML file export. Otherwise is an array for all other formats (ODS, XLS and TXT).
44 *
45 * @var $displaytype Grade display type constant (1, 2 or 3) or an array of display types where the key is the name
46 * and the value is the grade display type constant or 0 for unchecked display types.
47 * @access public.
48 */
49 public $displaytype;
5c75a0a3 50 public $decimalpoints; // number of decimal points for exports
78ab98bc 51 public $onlyactive; // only include users with an active enrolment
61c8e0d7
FM
52 public $usercustomfields; // include users custom fields
53
c10ddfb3 54 /**
cca51baa
DW
55 * @deprecated since Moodle 2.8
56 * @var $previewrows Number of rows in preview.
57 */
58 public $previewrows;
59
60 /**
61 * Constructor should set up all the private variables ready to be pulled.
62 *
63 * This constructor used to accept the individual parameters as separate arguments, in
64 * 2.8 this was simplified to just accept the data from the moodle form.
65 *
5c75a0a3 66 * @access public
caffc55a 67 * @param object $course
cca51baa
DW
68 * @param int $groupid
69 * @param stdClass|null $formdata
0eeada79 70 * @note Exporting as letters will lead to data loss if that exported set it re-imported.
c10ddfb3 71 */
cca51baa
DW
72 public function __construct($course, $groupid, $formdata) {
73 if (func_num_args() != 3 || ($formdata != null && get_class($formdata) != "stdClass")) {
74 $args = func_get_args();
75 return call_user_func_array(array($this, "deprecated_constructor"), $args);
76 }
caffc55a 77 $this->course = $course;
78 $this->groupid = $groupid;
cca51baa 79
caffc55a 80 $this->grade_items = grade_item::fetch_all(array('courseid'=>$this->course->id));
81
cca51baa
DW
82 $this->process_form($formdata);
83 }
84
85 /**
86 * Old deprecated constructor.
87 *
88 * This deprecated constructor accepts the individual parameters as separate arguments, in
89 * 2.8 this was simplified to just accept the data from the moodle form.
90 *
91 * @deprecated since 2.8 MDL-46548. Instead call the shortened constructor which accepts the data
92 * directly from the grade_export_form.
93 */
94 protected function deprecated_constructor($course,
95 $groupid=0,
96 $itemlist='',
97 $export_feedback=false,
98 $updatedgradesonly = false,
99 $displaytype = GRADE_DISPLAY_TYPE_REAL,
100 $decimalpoints = 2,
101 $onlyactive = false,
102 $usercustomfields = false) {
103
104 debugging('Many argument constructor for class "grade_export" is deprecated. Call the 3 argument version instead.', DEBUG_DEVELOPER);
105
106 $this->course = $course;
107 $this->groupid = $groupid;
108
109 $this->grade_items = grade_item::fetch_all(array('courseid'=>$this->course->id));
112fdf47
AD
110 //Populating the columns here is required by /grade/export/(whatever)/export.php
111 //however index.php, when the form is submitted, will construct the collection here
112 //with an empty $itemlist then reconstruct it in process_form() using $formdata
caffc55a 113 $this->columns = array();
114 if (!empty($itemlist)) {
112fdf47
AD
115 if ($itemlist=='-1') {
116 //user deselected all items
117 } else {
118 $itemids = explode(',', $itemlist);
119 // remove items that are not requested
120 foreach ($itemids as $itemid) {
121 if (array_key_exists($itemid, $this->grade_items)) {
122 $this->columns[$itemid] =& $this->grade_items[$itemid];
123 }
caffc55a 124 }
125 }
126 } else {
127 foreach ($this->grade_items as $itemid=>$unused) {
128 $this->columns[$itemid] =& $this->grade_items[$itemid];
129 }
130 }
0e2d708e 131
caffc55a 132 $this->export_feedback = $export_feedback;
133 $this->userkey = '';
134 $this->previewrows = false;
59a7447a 135 $this->updatedgradesonly = $updatedgradesonly;
d24832f9 136
864d1f8c 137 $this->displaytype = $displaytype;
138 $this->decimalpoints = $decimalpoints;
78ab98bc 139 $this->onlyactive = $onlyactive;
61c8e0d7 140 $this->usercustomfields = $usercustomfields;
caffc55a 141 }
142
143 /**
144 * Init object based using data from form
145 * @param object $formdata
146 */
147 function process_form($formdata) {
148 global $USER;
149
150 $this->columns = array();
151 if (!empty($formdata->itemids)) {
112fdf47
AD
152 if ($formdata->itemids=='-1') {
153 //user deselected all items
154 } else {
155 foreach ($formdata->itemids as $itemid=>$selected) {
156 if ($selected and array_key_exists($itemid, $this->grade_items)) {
157 $this->columns[$itemid] =& $this->grade_items[$itemid];
158 }
caffc55a 159 }
160 }
161 } else {
162 foreach ($this->grade_items as $itemid=>$unused) {
163 $this->columns[$itemid] =& $this->grade_items[$itemid];
164 }
0e2d708e 165 }
166
0e2d708e 167 if (isset($formdata->key)) {
caffc55a 168 if ($formdata->key == 1 && isset($formdata->iprestriction) && isset($formdata->validuntil)) {
169 // Create a new key
170 $formdata->key = create_user_key('grade/export', $USER->id, $this->course->id, $formdata->iprestriction, $formdata->validuntil);
0e2d708e 171 }
172 $this->userkey = $formdata->key;
173 }
ba74762b 174
cca51baa
DW
175 if (isset($formdata->decimals)) {
176 $this->decimalpoints = $formdata->decimals;
177 }
178
caffc55a 179 if (isset($formdata->export_letters)) {
180 $this->export_letters = $formdata->export_letters;
c10ddfb3 181 }
ba74762b 182
caffc55a 183 if (isset($formdata->export_feedback)) {
184 $this->export_feedback = $formdata->export_feedback;
185 }
c10ddfb3 186
78ab98bc
AD
187 if (isset($formdata->export_onlyactive)) {
188 $this->onlyactive = $formdata->export_onlyactive;
189 }
190
caffc55a 191 if (isset($formdata->previewrows)) {
192 $this->previewrows = $formdata->previewrows;
0bfbab47 193 }
194
924cb72b
DW
195 if (isset($formdata->display)) {
196 $this->displaytype = $formdata->display;
be289f57
SL
197
198 // Used by grade exports which accept multiple display types.
199 // If the checkbox value is 0 (unchecked) then remove it.
200 if (is_array($formdata->display)) {
201 $this->displaytype = array_filter($formdata->display);
202 }
924cb72b
DW
203 }
204
205 if (isset($formdata->updatedgradesonly)) {
206 $this->updatedgradesonly = $formdata->updatedgradesonly;
207 }
caffc55a 208 }
209
210 /**
211 * Update exported field in grade_grades table
212 * @return boolean
213 */
5c75a0a3 214 public function track_exports() {
caffc55a 215 global $CFG;
216
217 /// Whether this plugin is entitled to update export time
218 if ($expplugins = explode(",", $CFG->gradeexport)) {
219 if (in_array($this->plugin, $expplugins)) {
220 return true;
11745964 221 } else {
caffc55a 222 return false;
223 }
224 } else {
225 return false;
11745964 226 }
caffc55a 227 }
b8ff92b6 228
caffc55a 229 /**
230 * Returns string representation of final grade
be289f57
SL
231 * @param object $grade instance of grade_grade class
232 * @param integer $gradedisplayconst grade display type constant.
caffc55a 233 * @return string
234 */
be289f57
SL
235 public function format_grade($grade, $gradedisplayconst = null) {
236 $displaytype = $this->displaytype;
237 if (is_array($this->displaytype) && !is_null($gradedisplayconst)) {
238 $displaytype = $gradedisplayconst;
239 }
240 return grade_format_gradevalue($grade->finalgrade, $this->grade_items[$grade->itemid], false, $displaytype, $this->decimalpoints);
11745964 241 }
d9617050 242
caffc55a 243 /**
244 * Returns the name of column in export
245 * @param object $grade_item
be289f57
SL
246 * @param boolean $feedback feedback colum
247 * @param string $gradedisplayname grade display name.
248 * @return string
caffc55a 249 */
be289f57
SL
250 public function format_column_name($grade_item, $feedback=false, $gradedisplayname = null) {
251 $column = new stdClass();
952f3748 252
caffc55a 253 if ($grade_item->itemtype == 'mod') {
be289f57 254 $column->name = get_string('modulename', $grade_item->itemmodule).get_string('labelsep', 'langconfig').$grade_item->get_name();
f67e327e 255 } else {
be289f57 256 $column->name = $grade_item->get_name();
d9617050 257 }
ba74762b 258
be289f57
SL
259 // We can't have feedback and display type at the same time.
260 $column->extra = ($feedback) ? get_string('feedback') : get_string($gradedisplayname, 'grades');
caffc55a 261
be289f57 262 return html_to_text(get_string('gradeexportcolumntype', 'grades', $column), 0, false);
c10ddfb3 263 }
ba74762b 264
c10ddfb3 265 /**
caffc55a 266 * Returns formatted grade feedback
267 * @param object $feedback object with properties feedback and feedbackformat
268 * @return string
c10ddfb3 269 */
5c75a0a3 270 public function format_feedback($feedback) {
caffc55a 271 return strip_tags(format_text($feedback->feedback, $feedback->feedbackformat));
272 }
ba74762b 273
1b074625 274 /**
caffc55a 275 * Implemented by child class
1b074625 276 */
5c75a0a3 277 public abstract function print_grades();
11745964 278
caffc55a 279 /**
280 * Prints preview of exported grades on screen as a feedback mechanism
30f188f0 281 * @param bool $require_user_idnumber true means skip users without idnumber
cca51baa 282 * @deprecated since 2.8 MDL-46548. Previews are not useful on export.
caffc55a 283 */
30f188f0 284 public function display_preview($require_user_idnumber=false) {
c018f973 285 global $OUTPUT;
61c8e0d7 286
cca51baa
DW
287 debugging('function grade_export::display_preview is deprecated.', DEBUG_DEVELOPER);
288
61c8e0d7
FM
289 $userprofilefields = grade_helper::get_user_profile_fields($this->course->id, $this->usercustomfields);
290 $formatoptions = new stdClass();
291 $formatoptions->para = false;
292
c018f973 293 echo $OUTPUT->heading(get_string('previewrows', 'grades'));
567883c8 294
f5f4967e 295 echo '<table>';
296 echo '<tr>';
61c8e0d7 297 foreach ($userprofilefields as $field) {
293f42b6
CF
298 echo '<th>' . $field->fullname . '</th>';
299 }
38c1dd19
RT
300 if (!$this->onlyactive) {
301 echo '<th>'.get_string("suspended")."</th>";
302 }
caffc55a 303 foreach ($this->columns as $grade_item) {
304 echo '<th>'.$this->format_column_name($grade_item).'</th>';
ba74762b 305
306 /// add a column_feedback column
caffc55a 307 if ($this->export_feedback) {
308 echo '<th>'.$this->format_column_name($grade_item, true).'</th>';
ba74762b 309 }
1b074625 310 }
f5f4967e 311 echo '</tr>';
1b074625 312 /// Print all the lines of data.
f6eb15ad 313 $i = 0;
caffc55a 314 $gui = new graded_users_iterator($this->course, $this->columns, $this->groupid);
78ab98bc 315 $gui->require_active_enrolment($this->onlyactive);
61c8e0d7 316 $gui->allow_user_custom_fields($this->usercustomfields);
caffc55a 317 $gui->init();
318 while ($userdata = $gui->next_user()) {
f6eb15ad 319 // number of preview rows
bb9f1b4a 320 if ($this->previewrows and $this->previewrows <= $i) {
97599c0a 321 break;
f6eb15ad 322 }
caffc55a 323 $user = $userdata->user;
30f188f0 324 if ($require_user_idnumber and empty($user->idnumber)) {
7ce5df86 325 // some exports require user idnumber so we can match up students when importing the data
30f188f0 326 continue;
327 }
d24832f9 328
bb9f1b4a 329 $gradeupdated = false; // if no grade is update at all for this user, do not display this row
330 $rowstr = '';
caffc55a 331 foreach ($this->columns as $itemid=>$unused) {
332 $gradetxt = $this->format_grade($userdata->grades[$itemid]);
d24832f9 333
59a7447a 334 // get the status of this grade, and put it through track to get the status
335 $g = new grade_export_update_buffer();
336 $grade_grade = new grade_grade(array('itemid'=>$itemid, 'userid'=>$user->id));
337 $status = $g->track($grade_grade);
558cb86b 338
59a7447a 339 if ($this->updatedgradesonly && ($status == 'nochange' || $status == 'unknown')) {
bb9f1b4a 340 $rowstr .= '<td>'.get_string('unchangedgrade', 'grades').'</td>';
59a7447a 341 } else {
bb9f1b4a 342 $rowstr .= "<td>$gradetxt</td>";
343 $gradeupdated = true;
59a7447a 344 }
d24832f9 345
caffc55a 346 if ($this->export_feedback) {
bb9f1b4a 347 $rowstr .= '<td>'.$this->format_feedback($userdata->feedbacks[$itemid]).'</td>';
ba74762b 348 }
1b074625 349 }
bb9f1b4a 350
d24832f9 351 // if we are requesting updated grades only, we are not interested in this user at all
bb9f1b4a 352 if (!$gradeupdated && $this->updatedgradesonly) {
d24832f9 353 continue;
bb9f1b4a 354 }
355
356 echo '<tr>';
61c8e0d7
FM
357 foreach ($userprofilefields as $field) {
358 $fieldvalue = grade_helper::get_user_field_value($user, $field);
359 // @see profile_field_base::display_data().
360 echo '<td>' . format_text($fieldvalue, FORMAT_MOODLE, $formatoptions) . '</td>';
293f42b6 361 }
38c1dd19
RT
362 if (!$this->onlyactive) {
363 $issuspended = ($user->suspendedenrolment) ? get_string('yes') : '';
364 echo "<td>$issuspended</td>";
365 }
bb9f1b4a 366 echo $rowstr;
f5f4967e 367 echo "</tr>";
d24832f9 368
bb9f1b4a 369 $i++; // increment the counter
f5f4967e 370 }
371 echo '</table>';
caffc55a 372 $gui->close();
1b074625 373 }
0e2d708e 374
375 /**
caffc55a 376 * Returns array of parameters used by dump.php and export.php.
377 * @return array
378 */
5c75a0a3 379 public function get_export_params() {
caffc55a 380 $itemids = array_keys($this->columns);
112fdf47
AD
381 $itemidsparam = implode(',', $itemids);
382 if (empty($itemidsparam)) {
383 $itemidsparam = '-1';
384 }
caffc55a 385
59a7447a 386 $params = array('id' =>$this->course->id,
387 'groupid' =>$this->groupid,
112fdf47 388 'itemids' =>$itemidsparam,
59a7447a 389 'export_letters' =>$this->export_letters,
390 'export_feedback' =>$this->export_feedback,
864d1f8c 391 'updatedgradesonly' =>$this->updatedgradesonly,
392 'displaytype' =>$this->displaytype,
78ab98bc 393 'decimalpoints' =>$this->decimalpoints,
61c8e0d7
FM
394 'export_onlyactive' =>$this->onlyactive,
395 'usercustomfields' =>$this->usercustomfields);
caffc55a 396
397 return $params;
398 }
399
400 /**
401 * Either prints a "Export" box, which will redirect the user to the download page,
402 * or prints the URL for the published data.
cca51baa
DW
403 *
404 * @deprecated since 2.8 MDL-46548. Call get_export_url and set the
405 * action of the grade_export_form instead.
0e2d708e 406 * @return void
407 */
5c75a0a3 408 public function print_continue() {
c018f973 409 global $CFG, $OUTPUT;
0e2d708e 410
cca51baa 411 debugging('function grade_export::print_continue is deprecated.', DEBUG_DEVELOPER);
6c3ef410 412 $params = $this->get_export_params();
567883c8 413
c018f973 414 echo $OUTPUT->heading(get_string('export', 'grades'));
567883c8 415
03fcc729 416 echo $OUTPUT->container_start('gradeexportlink');
417
cca51baa
DW
418 if (!$this->userkey) {
419 // This button should trigger a download prompt.
420 $url = new moodle_url('/grade/export/'.$this->plugin.'/export.php', $params);
421 echo $OUTPUT->single_button($url, get_string('download', 'admin'));
0e2d708e 422
423 } else {
caffc55a 424 $paramstr = '';
425 $sep = '?';
426 foreach($params as $name=>$value) {
427 $paramstr .= $sep.$name.'='.$value;
03fcc729 428 $sep = '&';
caffc55a 429 }
430
52f1a9ff 431 $link = $CFG->wwwroot.'/grade/export/'.$this->plugin.'/dump.php'.$paramstr.'&key='.$this->userkey;
0e2d708e 432
75015e5f 433 echo get_string('download', 'admin').': ' . html_writer::link($link, $link);
0e2d708e 434 }
03fcc729 435 echo $OUTPUT->container_end();
cca51baa
DW
436
437 return;
0e2d708e 438 }
c10ddfb3 439}
440
eb859919 441/**
442 * This class is used to update the exported field in grade_grades.
443 * It does internal buffering to speedup the db operations.
444 */
445class grade_export_update_buffer {
5c75a0a3 446 public $update_list;
447 public $export_time;
eb859919 448
449 /**
450 * Constructor - creates the buffer and initialises the time stamp
451 */
5c75a0a3 452 public function grade_export_update_buffer() {
eb859919 453 $this->update_list = array();
454 $this->export_time = time();
455 }
456
5c75a0a3 457 public function flush($buffersize) {
458 global $CFG, $DB;
eb859919 459
460 if (count($this->update_list) > $buffersize) {
5c75a0a3 461 list($usql, $params) = $DB->get_in_or_equal($this->update_list);
462 $params = array_merge(array($this->export_time), $params);
463
464 $sql = "UPDATE {grade_grades} SET exported = ? WHERE id $usql";
655b09ca 465 $DB->execute($sql, $params);
eb859919 466 $this->update_list = array();
467 }
468 }
469
470 /**
471 * Track grade export status
472 * @param object $grade_grade
473 * @return string $status (unknow, new, regrade, nochange)
474 */
5c75a0a3 475 public function track($grade_grade) {
59a7447a 476
eb859919 477 if (empty($grade_grade->exported) or empty($grade_grade->timemodified)) {
478 if (is_null($grade_grade->finalgrade)) {
479 // grade does not exist yet
480 $status = 'unknown';
481 } else {
482 $status = 'new';
483 $this->update_list[] = $grade_grade->id;
484 }
485
486 } else if ($grade_grade->exported < $grade_grade->timemodified) {
487 $status = 'regrade';
488 $this->update_list[] = $grade_grade->id;
489
490 } else if ($grade_grade->exported >= $grade_grade->timemodified) {
491 $status = 'nochange';
492
493 } else {
494 // something is wrong?
495 $status = 'unknown';
496 }
497
498 $this->flush(100);
499
500 return $status;
501 }
502
503 /**
504 * Flush and close the buffer.
505 */
5c75a0a3 506 public function close() {
eb859919 507 $this->flush(0);
508 }
509}
6c3ef410 510
459843d4
AD
511/**
512 * Verify that there is a valid set of grades to export.
513 * @param $courseid int The course being exported
514 */
515function export_verify_grades($courseid) {
516 $regraderesult = grade_regrade_final_grades($courseid);
517 if (is_array($regraderesult)) {
63d2081e 518 throw new moodle_exception('gradecantregrade', 'error', '', implode(', ', array_unique($regraderesult)));
459843d4
AD
519 }
520}