Automatically generated installer lang files
[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 $previewrows; // number of rows in preview
35 public $export_letters; // export letters
36 public $export_feedback; // export feedback
37 public $userkey; // export using private user key
caffc55a 38
5c75a0a3 39 public $updatedgradesonly; // only export updated grades
40 public $displaytype; // display type (e.g. real, percentages, letter) for exports
41 public $decimalpoints; // number of decimal points for exports
78ab98bc 42 public $onlyactive; // only include users with an active enrolment
c10ddfb3 43 /**
44 * Constructor should set up all the private variables ready to be pulled
5c75a0a3 45 * @access public
caffc55a 46 * @param object $course
47 * @param int $groupid id of selected group, 0 means all
48 * @param string $itemlist comma separated list of item ids, empty means all
49 * @param boolean $export_feedback
50 * @param boolean $export_letters
0eeada79 51 * @note Exporting as letters will lead to data loss if that exported set it re-imported.
c10ddfb3 52 */
78ab98bc 53 public function grade_export($course, $groupid=0, $itemlist='', $export_feedback=false, $updatedgradesonly = false, $displaytype = GRADE_DISPLAY_TYPE_REAL, $decimalpoints = 2, $onlyactive = false) {
caffc55a 54 $this->course = $course;
55 $this->groupid = $groupid;
56 $this->grade_items = grade_item::fetch_all(array('courseid'=>$this->course->id));
57
112fdf47
AD
58 //Populating the columns here is required by /grade/export/(whatever)/export.php
59 //however index.php, when the form is submitted, will construct the collection here
60 //with an empty $itemlist then reconstruct it in process_form() using $formdata
caffc55a 61 $this->columns = array();
62 if (!empty($itemlist)) {
112fdf47
AD
63 if ($itemlist=='-1') {
64 //user deselected all items
65 } else {
66 $itemids = explode(',', $itemlist);
67 // remove items that are not requested
68 foreach ($itemids as $itemid) {
69 if (array_key_exists($itemid, $this->grade_items)) {
70 $this->columns[$itemid] =& $this->grade_items[$itemid];
71 }
caffc55a 72 }
73 }
74 } else {
75 foreach ($this->grade_items as $itemid=>$unused) {
76 $this->columns[$itemid] =& $this->grade_items[$itemid];
77 }
78 }
0e2d708e 79
caffc55a 80 $this->export_feedback = $export_feedback;
81 $this->userkey = '';
82 $this->previewrows = false;
59a7447a 83 $this->updatedgradesonly = $updatedgradesonly;
d24832f9 84
864d1f8c 85 $this->displaytype = $displaytype;
86 $this->decimalpoints = $decimalpoints;
78ab98bc 87 $this->onlyactive = $onlyactive;
caffc55a 88 }
89
90 /**
91 * Init object based using data from form
92 * @param object $formdata
93 */
94 function process_form($formdata) {
95 global $USER;
96
97 $this->columns = array();
98 if (!empty($formdata->itemids)) {
112fdf47
AD
99 if ($formdata->itemids=='-1') {
100 //user deselected all items
101 } else {
102 foreach ($formdata->itemids as $itemid=>$selected) {
103 if ($selected and array_key_exists($itemid, $this->grade_items)) {
104 $this->columns[$itemid] =& $this->grade_items[$itemid];
105 }
caffc55a 106 }
107 }
108 } else {
109 foreach ($this->grade_items as $itemid=>$unused) {
110 $this->columns[$itemid] =& $this->grade_items[$itemid];
111 }
0e2d708e 112 }
113
0e2d708e 114 if (isset($formdata->key)) {
caffc55a 115 if ($formdata->key == 1 && isset($formdata->iprestriction) && isset($formdata->validuntil)) {
116 // Create a new key
117 $formdata->key = create_user_key('grade/export', $USER->id, $this->course->id, $formdata->iprestriction, $formdata->validuntil);
0e2d708e 118 }
119 $this->userkey = $formdata->key;
120 }
ba74762b 121
caffc55a 122 if (isset($formdata->export_letters)) {
123 $this->export_letters = $formdata->export_letters;
c10ddfb3 124 }
ba74762b 125
caffc55a 126 if (isset($formdata->export_feedback)) {
127 $this->export_feedback = $formdata->export_feedback;
128 }
c10ddfb3 129
78ab98bc
AD
130 if (isset($formdata->export_onlyactive)) {
131 $this->onlyactive = $formdata->export_onlyactive;
132 }
133
caffc55a 134 if (isset($formdata->previewrows)) {
135 $this->previewrows = $formdata->previewrows;
0bfbab47 136 }
137
caffc55a 138 }
139
140 /**
141 * Update exported field in grade_grades table
142 * @return boolean
143 */
5c75a0a3 144 public function track_exports() {
caffc55a 145 global $CFG;
146
147 /// Whether this plugin is entitled to update export time
148 if ($expplugins = explode(",", $CFG->gradeexport)) {
149 if (in_array($this->plugin, $expplugins)) {
150 return true;
11745964 151 } else {
caffc55a 152 return false;
153 }
154 } else {
155 return false;
11745964 156 }
caffc55a 157 }
b8ff92b6 158
caffc55a 159 /**
160 * Returns string representation of final grade
161 * @param $object $grade instance of grade_grade class
162 * @return string
163 */
5c75a0a3 164 public function format_grade($grade) {
864d1f8c 165 return grade_format_gradevalue($grade->finalgrade, $this->grade_items[$grade->itemid], false, $this->displaytype, $this->decimalpoints);
11745964 166 }
d9617050 167
caffc55a 168 /**
169 * Returns the name of column in export
170 * @param object $grade_item
171 * @param boolena $feedback feedback colum
172 * &return string
173 */
5c75a0a3 174 public function format_column_name($grade_item, $feedback=false) {
caffc55a 175 if ($grade_item->itemtype == 'mod') {
995f2d51 176 $name = get_string('modulename', $grade_item->itemmodule).get_string('labelsep', 'langconfig').$grade_item->get_name();
f67e327e 177 } else {
caffc55a 178 $name = $grade_item->get_name();
d9617050 179 }
ba74762b 180
caffc55a 181 if ($feedback) {
182 $name .= ' ('.get_string('feedback').')';
ba74762b 183 }
caffc55a 184
185 return strip_tags($name);
c10ddfb3 186 }
ba74762b 187
c10ddfb3 188 /**
caffc55a 189 * Returns formatted grade feedback
190 * @param object $feedback object with properties feedback and feedbackformat
191 * @return string
c10ddfb3 192 */
5c75a0a3 193 public function format_feedback($feedback) {
caffc55a 194 return strip_tags(format_text($feedback->feedback, $feedback->feedbackformat));
195 }
ba74762b 196
1b074625 197 /**
caffc55a 198 * Implemented by child class
1b074625 199 */
5c75a0a3 200 public abstract function print_grades();
11745964 201
caffc55a 202 /**
203 * Prints preview of exported grades on screen as a feedback mechanism
30f188f0 204 * @param bool $require_user_idnumber true means skip users without idnumber
caffc55a 205 */
30f188f0 206 public function display_preview($require_user_idnumber=false) {
c018f973 207 global $OUTPUT;
208 echo $OUTPUT->heading(get_string('previewrows', 'grades'));
567883c8 209
f5f4967e 210 echo '<table>';
211 echo '<tr>';
212 echo '<th>'.get_string("firstname")."</th>".
213 '<th>'.get_string("lastname")."</th>".
214 '<th>'.get_string("idnumber")."</th>".
215 '<th>'.get_string("institution")."</th>".
216 '<th>'.get_string("department")."</th>".
217 '<th>'.get_string("email")."</th>";
caffc55a 218 foreach ($this->columns as $grade_item) {
219 echo '<th>'.$this->format_column_name($grade_item).'</th>';
ba74762b 220
221 /// add a column_feedback column
caffc55a 222 if ($this->export_feedback) {
223 echo '<th>'.$this->format_column_name($grade_item, true).'</th>';
ba74762b 224 }
1b074625 225 }
f5f4967e 226 echo '</tr>';
1b074625 227 /// Print all the lines of data.
ba74762b 228
f6eb15ad 229 $i = 0;
caffc55a 230 $gui = new graded_users_iterator($this->course, $this->columns, $this->groupid);
78ab98bc 231 $gui->require_active_enrolment($this->onlyactive);
caffc55a 232 $gui->init();
233 while ($userdata = $gui->next_user()) {
f6eb15ad 234 // number of preview rows
bb9f1b4a 235 if ($this->previewrows and $this->previewrows <= $i) {
97599c0a 236 break;
f6eb15ad 237 }
caffc55a 238 $user = $userdata->user;
30f188f0 239 if ($require_user_idnumber and empty($user->idnumber)) {
7ce5df86 240 // some exports require user idnumber so we can match up students when importing the data
30f188f0 241 continue;
242 }
d24832f9 243
bb9f1b4a 244 $gradeupdated = false; // if no grade is update at all for this user, do not display this row
245 $rowstr = '';
caffc55a 246 foreach ($this->columns as $itemid=>$unused) {
247 $gradetxt = $this->format_grade($userdata->grades[$itemid]);
d24832f9 248
59a7447a 249 // get the status of this grade, and put it through track to get the status
250 $g = new grade_export_update_buffer();
251 $grade_grade = new grade_grade(array('itemid'=>$itemid, 'userid'=>$user->id));
252 $status = $g->track($grade_grade);
558cb86b 253
59a7447a 254 if ($this->updatedgradesonly && ($status == 'nochange' || $status == 'unknown')) {
bb9f1b4a 255 $rowstr .= '<td>'.get_string('unchangedgrade', 'grades').'</td>';
59a7447a 256 } else {
bb9f1b4a 257 $rowstr .= "<td>$gradetxt</td>";
258 $gradeupdated = true;
59a7447a 259 }
d24832f9 260
caffc55a 261 if ($this->export_feedback) {
bb9f1b4a 262 $rowstr .= '<td>'.$this->format_feedback($userdata->feedbacks[$itemid]).'</td>';
ba74762b 263 }
1b074625 264 }
bb9f1b4a 265
d24832f9 266 // if we are requesting updated grades only, we are not interested in this user at all
bb9f1b4a 267 if (!$gradeupdated && $this->updatedgradesonly) {
d24832f9 268 continue;
bb9f1b4a 269 }
270
271 echo '<tr>';
d24832f9 272 echo "<td>$user->firstname</td><td>$user->lastname</td><td>$user->idnumber</td><td>$user->institution</td><td>$user->department</td><td>$user->email</td>";
bb9f1b4a 273 echo $rowstr;
f5f4967e 274 echo "</tr>";
d24832f9 275
bb9f1b4a 276 $i++; // increment the counter
f5f4967e 277 }
278 echo '</table>';
caffc55a 279 $gui->close();
1b074625 280 }
0e2d708e 281
282 /**
caffc55a 283 * Returns array of parameters used by dump.php and export.php.
284 * @return array
285 */
5c75a0a3 286 public function get_export_params() {
caffc55a 287 $itemids = array_keys($this->columns);
112fdf47
AD
288 $itemidsparam = implode(',', $itemids);
289 if (empty($itemidsparam)) {
290 $itemidsparam = '-1';
291 }
caffc55a 292
59a7447a 293 $params = array('id' =>$this->course->id,
294 'groupid' =>$this->groupid,
112fdf47 295 'itemids' =>$itemidsparam,
59a7447a 296 'export_letters' =>$this->export_letters,
297 'export_feedback' =>$this->export_feedback,
864d1f8c 298 'updatedgradesonly' =>$this->updatedgradesonly,
299 'displaytype' =>$this->displaytype,
78ab98bc
AD
300 'decimalpoints' =>$this->decimalpoints,
301 'export_onlyactive' =>$this->onlyactive);
caffc55a 302
303 return $params;
304 }
305
306 /**
307 * Either prints a "Export" box, which will redirect the user to the download page,
308 * or prints the URL for the published data.
0e2d708e 309 * @return void
310 */
5c75a0a3 311 public function print_continue() {
c018f973 312 global $CFG, $OUTPUT;
0e2d708e 313
6c3ef410 314 $params = $this->get_export_params();
567883c8 315
c018f973 316 echo $OUTPUT->heading(get_string('export', 'grades'));
567883c8 317
03fcc729 318 echo $OUTPUT->container_start('gradeexportlink');
319
567883c8 320 if (!$this->userkey) { // this button should trigger a download prompt
a6855934 321 echo $OUTPUT->single_button(new moodle_url('/grade/export/'.$this->plugin.'/export.php', $params), get_string('download', 'admin'));
0e2d708e 322
323 } else {
caffc55a 324 $paramstr = '';
325 $sep = '?';
326 foreach($params as $name=>$value) {
327 $paramstr .= $sep.$name.'='.$value;
03fcc729 328 $sep = '&';
caffc55a 329 }
330
52f1a9ff 331 $link = $CFG->wwwroot.'/grade/export/'.$this->plugin.'/dump.php'.$paramstr.'&key='.$this->userkey;
0e2d708e 332
75015e5f 333 echo get_string('download', 'admin').': ' . html_writer::link($link, $link);
0e2d708e 334 }
03fcc729 335 echo $OUTPUT->container_end();
0e2d708e 336 }
c10ddfb3 337}
338
eb859919 339/**
340 * This class is used to update the exported field in grade_grades.
341 * It does internal buffering to speedup the db operations.
342 */
343class grade_export_update_buffer {
5c75a0a3 344 public $update_list;
345 public $export_time;
eb859919 346
347 /**
348 * Constructor - creates the buffer and initialises the time stamp
349 */
5c75a0a3 350 public function grade_export_update_buffer() {
eb859919 351 $this->update_list = array();
352 $this->export_time = time();
353 }
354
5c75a0a3 355 public function flush($buffersize) {
356 global $CFG, $DB;
eb859919 357
358 if (count($this->update_list) > $buffersize) {
5c75a0a3 359 list($usql, $params) = $DB->get_in_or_equal($this->update_list);
360 $params = array_merge(array($this->export_time), $params);
361
362 $sql = "UPDATE {grade_grades} SET exported = ? WHERE id $usql";
655b09ca 363 $DB->execute($sql, $params);
eb859919 364 $this->update_list = array();
365 }
366 }
367
368 /**
369 * Track grade export status
370 * @param object $grade_grade
371 * @return string $status (unknow, new, regrade, nochange)
372 */
5c75a0a3 373 public function track($grade_grade) {
59a7447a 374
eb859919 375 if (empty($grade_grade->exported) or empty($grade_grade->timemodified)) {
376 if (is_null($grade_grade->finalgrade)) {
377 // grade does not exist yet
378 $status = 'unknown';
379 } else {
380 $status = 'new';
381 $this->update_list[] = $grade_grade->id;
382 }
383
384 } else if ($grade_grade->exported < $grade_grade->timemodified) {
385 $status = 'regrade';
386 $this->update_list[] = $grade_grade->id;
387
388 } else if ($grade_grade->exported >= $grade_grade->timemodified) {
389 $status = 'nochange';
390
391 } else {
392 // something is wrong?
393 $status = 'unknown';
394 }
395
396 $this->flush(100);
397
398 return $status;
399 }
400
401 /**
402 * Flush and close the buffer.
403 */
5c75a0a3 404 public function close() {
eb859919 405 $this->flush(0);
406 }
407}
6c3ef410 408
abd110f8
AD
409/**
410 * Verify that there is a valid set of grades to export.
411 * @param $courseid int The course being exported
412 */
413function export_verify_grades($courseid) {
414 $regraderesult = grade_regrade_final_grades($courseid);
415 if (is_array($regraderesult)) {
955a081e 416 throw new moodle_exception('gradecantregrade', 'error', '', implode(', ', array_unique($regraderesult)));
abd110f8
AD
417 }
418}