Merge branch 'm29_MDL-49052' of https://github.com/totara/moodle
[moodle.git] / grade / export / lib.php
1 <?php
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/>.
18 require_once($CFG->dirroot.'/lib/gradelib.php');
19 require_once($CFG->dirroot.'/grade/lib.php');
20 require_once($CFG->dirroot.'/grade/export/grade_export_form.php');
22 /**
23  * Base export class
24  */
25 abstract class grade_export {
27     public $plugin; // plgin name - must be filled in subclasses!
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
34     public $export_letters;  // export letters
35     public $export_feedback; // export feedback
36     public $userkey;         // export using private user key
38     public $updatedgradesonly; // only export updated grades
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;
50     public $decimalpoints; // number of decimal points for exports
51     public $onlyactive; // only include users with an active enrolment
52     public $usercustomfields; // include users custom fields
54     /**
55      * @deprecated since Moodle 2.8
56      * @var $previewrows Number of rows in preview.
57      */
58     public $previewrows;
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      *
66      * @access public
67      * @param object $course
68      * @param int $groupid
69      * @param stdClass|null $formdata
70      * @note Exporting as letters will lead to data loss if that exported set it re-imported.
71      */
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         }
77         $this->course = $course;
78         $this->groupid = $groupid;
80         $this->grade_items = grade_item::fetch_all(array('courseid'=>$this->course->id));
82         $this->process_form($formdata);
83     }
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) {
104         debugging('Many argument constructor for class "grade_export" is deprecated. Call the 3 argument version instead.', DEBUG_DEVELOPER);
106         $this->course = $course;
107         $this->groupid = $groupid;
109         $this->grade_items = grade_item::fetch_all(array('courseid'=>$this->course->id));
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
113         $this->columns = array();
114         if (!empty($itemlist)) {
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                     }
124                 }
125             }
126         } else {
127             foreach ($this->grade_items as $itemid=>$unused) {
128                 $this->columns[$itemid] =& $this->grade_items[$itemid];
129             }
130         }
132         $this->export_feedback = $export_feedback;
133         $this->userkey         = '';
134         $this->previewrows     = false;
135         $this->updatedgradesonly = $updatedgradesonly;
137         $this->displaytype = $displaytype;
138         $this->decimalpoints = $decimalpoints;
139         $this->onlyactive = $onlyactive;
140         $this->usercustomfields = $usercustomfields;
141     }
143     /**
144      * Init object based using data from form
145      * @param object $formdata
146      */
147     function process_form($formdata) {
148         global $USER;
150         $this->columns = array();
151         if (!empty($formdata->itemids)) {
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                     }
159                 }
160             }
161         } else {
162             foreach ($this->grade_items as $itemid=>$unused) {
163                 $this->columns[$itemid] =& $this->grade_items[$itemid];
164             }
165         }
167         if (isset($formdata->key)) {
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);
171             }
172             $this->userkey = $formdata->key;
173         }
175         if (isset($formdata->decimals)) {
176             $this->decimalpoints = $formdata->decimals;
177         }
179         if (isset($formdata->export_letters)) {
180             $this->export_letters = $formdata->export_letters;
181         }
183         if (isset($formdata->export_feedback)) {
184             $this->export_feedback = $formdata->export_feedback;
185         }
187         if (isset($formdata->export_onlyactive)) {
188             $this->onlyactive = $formdata->export_onlyactive;
189         }
191         if (isset($formdata->previewrows)) {
192             $this->previewrows = $formdata->previewrows;
193         }
195         if (isset($formdata->display)) {
196             $this->displaytype = $formdata->display;
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             }
203         }
205         if (isset($formdata->updatedgradesonly)) {
206             $this->updatedgradesonly = $formdata->updatedgradesonly;
207         }
208     }
210     /**
211      * Update exported field in grade_grades table
212      * @return boolean
213      */
214     public function track_exports() {
215         global $CFG;
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;
221             } else {
222                 return false;
223           }
224         } else {
225             return false;
226         }
227     }
229     /**
230      * Returns string representation of final grade
231      * @param object $grade instance of grade_grade class
232      * @param integer $gradedisplayconst grade display type constant.
233      * @return string
234      */
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);
241     }
243     /**
244      * Returns the name of column in export
245      * @param object $grade_item
246      * @param boolean $feedback feedback colum
247      * @param string $gradedisplayname grade display name.
248      * @return string
249      */
250     public function format_column_name($grade_item, $feedback=false, $gradedisplayname = null) {
251         $column = new stdClass();
253         if ($grade_item->itemtype == 'mod') {
254             $column->name = get_string('modulename', $grade_item->itemmodule).get_string('labelsep', 'langconfig').$grade_item->get_name();
255         } else {
256             $column->name = $grade_item->get_name();
257         }
259         // We can't have feedback and display type at the same time.
260         $column->extra = ($feedback) ? get_string('feedback') : get_string($gradedisplayname, 'grades');
262         return html_to_text(get_string('gradeexportcolumntype', 'grades', $column), 0, false);
263     }
265     /**
266      * Returns formatted grade feedback
267      * @param object $feedback object with properties feedback and feedbackformat
268      * @return string
269      */
270     public function format_feedback($feedback) {
271         return strip_tags(format_text($feedback->feedback, $feedback->feedbackformat));
272     }
274     /**
275      * Implemented by child class
276      */
277     public abstract function print_grades();
279     /**
280      * Prints preview of exported grades on screen as a feedback mechanism
281      * @param bool $require_user_idnumber true means skip users without idnumber
282      * @deprecated since 2.8 MDL-46548. Previews are not useful on export.
283      */
284     public function display_preview($require_user_idnumber=false) {
285         global $OUTPUT;
287         debugging('function grade_export::display_preview is deprecated.', DEBUG_DEVELOPER);
289         $userprofilefields = grade_helper::get_user_profile_fields($this->course->id, $this->usercustomfields);
290         $formatoptions = new stdClass();
291         $formatoptions->para = false;
293         echo $OUTPUT->heading(get_string('previewrows', 'grades'));
295         echo '<table>';
296         echo '<tr>';
297         foreach ($userprofilefields as $field) {
298             echo '<th>' . $field->fullname . '</th>';
299         }
300         if (!$this->onlyactive) {
301             echo '<th>'.get_string("suspended")."</th>";
302         }
303         foreach ($this->columns as $grade_item) {
304             echo '<th>'.$this->format_column_name($grade_item).'</th>';
306             /// add a column_feedback column
307             if ($this->export_feedback) {
308                 echo '<th>'.$this->format_column_name($grade_item, true).'</th>';
309             }
310         }
311         echo '</tr>';
312         /// Print all the lines of data.
313         $i = 0;
314         $gui = new graded_users_iterator($this->course, $this->columns, $this->groupid);
315         $gui->require_active_enrolment($this->onlyactive);
316         $gui->allow_user_custom_fields($this->usercustomfields);
317         $gui->init();
318         while ($userdata = $gui->next_user()) {
319             // number of preview rows
320             if ($this->previewrows and $this->previewrows <= $i) {
321                 break;
322             }
323             $user = $userdata->user;
324             if ($require_user_idnumber and empty($user->idnumber)) {
325                 // some exports require user idnumber so we can match up students when importing the data
326                 continue;
327             }
329             $gradeupdated = false; // if no grade is update at all for this user, do not display this row
330             $rowstr = '';
331             foreach ($this->columns as $itemid=>$unused) {
332                 $gradetxt = $this->format_grade($userdata->grades[$itemid]);
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);
339                 if ($this->updatedgradesonly && ($status == 'nochange' || $status == 'unknown')) {
340                     $rowstr .= '<td>'.get_string('unchangedgrade', 'grades').'</td>';
341                 } else {
342                     $rowstr .= "<td>$gradetxt</td>";
343                     $gradeupdated = true;
344                 }
346                 if ($this->export_feedback) {
347                     $rowstr .=  '<td>'.$this->format_feedback($userdata->feedbacks[$itemid]).'</td>';
348                 }
349             }
351             // if we are requesting updated grades only, we are not interested in this user at all
352             if (!$gradeupdated && $this->updatedgradesonly) {
353                 continue;
354             }
356             echo '<tr>';
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>';
361             }
362             if (!$this->onlyactive) {
363                 $issuspended = ($user->suspendedenrolment) ? get_string('yes') : '';
364                 echo "<td>$issuspended</td>";
365             }
366             echo $rowstr;
367             echo "</tr>";
369             $i++; // increment the counter
370         }
371         echo '</table>';
372         $gui->close();
373     }
375     /**
376      * Returns array of parameters used by dump.php and export.php.
377      * @return array
378      */
379     public function get_export_params() {
380         $itemids = array_keys($this->columns);
381         $itemidsparam = implode(',', $itemids);
382         if (empty($itemidsparam)) {
383             $itemidsparam = '-1';
384         }
386         $params = array('id'                =>$this->course->id,
387                         'groupid'           =>$this->groupid,
388                         'itemids'           =>$itemidsparam,
389                         'export_letters'    =>$this->export_letters,
390                         'export_feedback'   =>$this->export_feedback,
391                         'updatedgradesonly' =>$this->updatedgradesonly,
392                         'displaytype'       =>$this->displaytype,
393                         'decimalpoints'     =>$this->decimalpoints,
394                         'export_onlyactive' =>$this->onlyactive,
395                         'usercustomfields'  =>$this->usercustomfields);
397         return $params;
398     }
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.
403      *
404      * @deprecated since 2.8 MDL-46548. Call get_export_url and set the
405      *             action of the grade_export_form instead.
406      * @return void
407      */
408     public function print_continue() {
409         global $CFG, $OUTPUT;
411         debugging('function grade_export::print_continue is deprecated.', DEBUG_DEVELOPER);
412         $params = $this->get_export_params();
414         echo $OUTPUT->heading(get_string('export', 'grades'));
416         echo $OUTPUT->container_start('gradeexportlink');
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'));
423         } else {
424             $paramstr = '';
425             $sep = '?';
426             foreach($params as $name=>$value) {
427                 $paramstr .= $sep.$name.'='.$value;
428                 $sep = '&';
429             }
431             $link = $CFG->wwwroot.'/grade/export/'.$this->plugin.'/dump.php'.$paramstr.'&key='.$this->userkey;
433             echo get_string('download', 'admin').': ' . html_writer::link($link, $link);
434         }
435         echo $OUTPUT->container_end();
437         return;
438     }
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  */
445 class grade_export_update_buffer {
446     public $update_list;
447     public $export_time;
449     /**
450      * Constructor - creates the buffer and initialises the time stamp
451      */
452     public function grade_export_update_buffer() {
453         $this->update_list = array();
454         $this->export_time = time();
455     }
457     public function flush($buffersize) {
458         global $CFG, $DB;
460         if (count($this->update_list) > $buffersize) {
461             list($usql, $params) = $DB->get_in_or_equal($this->update_list);
462             $params = array_merge(array($this->export_time), $params);
464             $sql = "UPDATE {grade_grades} SET exported = ? WHERE id $usql";
465             $DB->execute($sql, $params);
466             $this->update_list = array();
467         }
468     }
470     /**
471      * Track grade export status
472      * @param object $grade_grade
473      * @return string $status (unknow, new, regrade, nochange)
474      */
475     public function track($grade_grade) {
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             }
486         } else if ($grade_grade->exported < $grade_grade->timemodified) {
487             $status = 'regrade';
488             $this->update_list[] = $grade_grade->id;
490         } else if ($grade_grade->exported >= $grade_grade->timemodified) {
491             $status = 'nochange';
493         } else {
494             // something is wrong?
495             $status = 'unknown';
496         }
498         $this->flush(100);
500         return $status;
501     }
503     /**
504      * Flush and close the buffer.
505      */
506     public function close() {
507         $this->flush(0);
508     }
511 /**
512  * Verify that there is a valid set of grades to export.
513  * @param $courseid int The course being exported
514  */
515 function export_verify_grades($courseid) {
516     $regraderesult = grade_regrade_final_grades($courseid);
517     if (is_array($regraderesult)) {
518         throw new moodle_exception('gradecantregrade', 'error', '', implode(', ', array_unique($regraderesult)));
519     }