Automatically generated installer lang files
[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 $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
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
42     public $onlyactive; // only include users with an active enrolment
43     /**
44      * Constructor should set up all the private variables ready to be pulled
45      * @access public
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
51      * @note Exporting as letters will lead to data loss if that exported set it re-imported.
52      */
53     public function grade_export($course, $groupid=0, $itemlist='', $export_feedback=false, $updatedgradesonly = false, $displaytype = GRADE_DISPLAY_TYPE_REAL, $decimalpoints = 2, $onlyactive = false) {
54         $this->course = $course;
55         $this->groupid = $groupid;
56         $this->grade_items = grade_item::fetch_all(array('courseid'=>$this->course->id));
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
61         $this->columns = array();
62         if (!empty($itemlist)) {
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                     }
72                 }
73             }
74         } else {
75             foreach ($this->grade_items as $itemid=>$unused) {
76                 $this->columns[$itemid] =& $this->grade_items[$itemid];
77             }
78         }
80         $this->export_feedback = $export_feedback;
81         $this->userkey         = '';
82         $this->previewrows     = false;
83         $this->updatedgradesonly = $updatedgradesonly;
85         $this->displaytype = $displaytype;
86         $this->decimalpoints = $decimalpoints;
87         $this->onlyactive = $onlyactive;
88     }
90     /**
91      * Init object based using data from form
92      * @param object $formdata
93      */
94     function process_form($formdata) {
95         global $USER;
97         $this->columns = array();
98         if (!empty($formdata->itemids)) {
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                     }
106                 }
107             }
108         } else {
109             foreach ($this->grade_items as $itemid=>$unused) {
110                 $this->columns[$itemid] =& $this->grade_items[$itemid];
111             }
112         }
114         if (isset($formdata->key)) {
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);
118             }
119             $this->userkey = $formdata->key;
120         }
122         if (isset($formdata->export_letters)) {
123             $this->export_letters = $formdata->export_letters;
124         }
126         if (isset($formdata->export_feedback)) {
127             $this->export_feedback = $formdata->export_feedback;
128         }
130         if (isset($formdata->export_onlyactive)) {
131             $this->onlyactive = $formdata->export_onlyactive;
132         }
134         if (isset($formdata->previewrows)) {
135             $this->previewrows = $formdata->previewrows;
136         }
138     }
140     /**
141      * Update exported field in grade_grades table
142      * @return boolean
143      */
144     public function track_exports() {
145         global $CFG;
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;
151             } else {
152                 return false;
153           }
154         } else {
155             return false;
156         }
157     }
159     /**
160      * Returns string representation of final grade
161      * @param $object $grade instance of grade_grade class
162      * @return string
163      */
164     public function format_grade($grade) {
165         return grade_format_gradevalue($grade->finalgrade, $this->grade_items[$grade->itemid], false, $this->displaytype, $this->decimalpoints);
166     }
168     /**
169      * Returns the name of column in export
170      * @param object $grade_item
171      * @param boolena $feedback feedback colum
172      * &return string
173      */
174     public function format_column_name($grade_item, $feedback=false) {
175         if ($grade_item->itemtype == 'mod') {
176             $name = get_string('modulename', $grade_item->itemmodule).get_string('labelsep', 'langconfig').$grade_item->get_name();
177         } else {
178             $name = $grade_item->get_name();
179         }
181         if ($feedback) {
182             $name .= ' ('.get_string('feedback').')';
183         }
185         return strip_tags($name);
186     }
188     /**
189      * Returns formatted grade feedback
190      * @param object $feedback object with properties feedback and feedbackformat
191      * @return string
192      */
193     public function format_feedback($feedback) {
194         return strip_tags(format_text($feedback->feedback, $feedback->feedbackformat));
195     }
197     /**
198      * Implemented by child class
199      */
200     public abstract function print_grades();
202     /**
203      * Prints preview of exported grades on screen as a feedback mechanism
204      * @param bool $require_user_idnumber true means skip users without idnumber
205      */
206     public function display_preview($require_user_idnumber=false) {
207         global $OUTPUT;
208         echo $OUTPUT->heading(get_string('previewrows', 'grades'));
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>";
218         foreach ($this->columns as $grade_item) {
219             echo '<th>'.$this->format_column_name($grade_item).'</th>';
221             /// add a column_feedback column
222             if ($this->export_feedback) {
223                 echo '<th>'.$this->format_column_name($grade_item, true).'</th>';
224             }
225         }
226         echo '</tr>';
227         /// Print all the lines of data.
229         $i = 0;
230         $gui = new graded_users_iterator($this->course, $this->columns, $this->groupid);
231         $gui->require_active_enrolment($this->onlyactive);
232         $gui->init();
233         while ($userdata = $gui->next_user()) {
234             // number of preview rows
235             if ($this->previewrows and $this->previewrows <= $i) {
236                 break;
237             }
238             $user = $userdata->user;
239             if ($require_user_idnumber and empty($user->idnumber)) {
240                 // some exports require user idnumber so we can match up students when importing the data
241                 continue;
242             }
244             $gradeupdated = false; // if no grade is update at all for this user, do not display this row
245             $rowstr = '';
246             foreach ($this->columns as $itemid=>$unused) {
247                 $gradetxt = $this->format_grade($userdata->grades[$itemid]);
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);
254                 if ($this->updatedgradesonly && ($status == 'nochange' || $status == 'unknown')) {
255                     $rowstr .= '<td>'.get_string('unchangedgrade', 'grades').'</td>';
256                 } else {
257                     $rowstr .= "<td>$gradetxt</td>";
258                     $gradeupdated = true;
259                 }
261                 if ($this->export_feedback) {
262                     $rowstr .=  '<td>'.$this->format_feedback($userdata->feedbacks[$itemid]).'</td>';
263                 }
264             }
266             // if we are requesting updated grades only, we are not interested in this user at all
267             if (!$gradeupdated && $this->updatedgradesonly) {
268                 continue;
269             }
271             echo '<tr>';
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>";
273             echo $rowstr;
274             echo "</tr>";
276             $i++; // increment the counter
277         }
278         echo '</table>';
279         $gui->close();
280     }
282     /**
283      * Returns array of parameters used by dump.php and export.php.
284      * @return array
285      */
286     public function get_export_params() {
287         $itemids = array_keys($this->columns);
288         $itemidsparam = implode(',', $itemids);
289         if (empty($itemidsparam)) {
290             $itemidsparam = '-1';
291         }
293         $params = array('id'                =>$this->course->id,
294                         'groupid'           =>$this->groupid,
295                         'itemids'           =>$itemidsparam,
296                         'export_letters'    =>$this->export_letters,
297                         'export_feedback'   =>$this->export_feedback,
298                         'updatedgradesonly' =>$this->updatedgradesonly,
299                         'displaytype'       =>$this->displaytype,
300                         'decimalpoints'     =>$this->decimalpoints,
301                         'export_onlyactive' =>$this->onlyactive);
303         return $params;
304     }
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.
309      * @return void
310      */
311     public function print_continue() {
312         global $CFG, $OUTPUT;
314         $params = $this->get_export_params();
316         echo $OUTPUT->heading(get_string('export', 'grades'));
318         echo $OUTPUT->container_start('gradeexportlink');
320         if (!$this->userkey) {      // this button should trigger a download prompt
321             echo $OUTPUT->single_button(new moodle_url('/grade/export/'.$this->plugin.'/export.php', $params), get_string('download', 'admin'));
323         } else {
324             $paramstr = '';
325             $sep = '?';
326             foreach($params as $name=>$value) {
327                 $paramstr .= $sep.$name.'='.$value;
328                 $sep = '&';
329             }
331             $link = $CFG->wwwroot.'/grade/export/'.$this->plugin.'/dump.php'.$paramstr.'&key='.$this->userkey;
333             echo get_string('download', 'admin').': ' . html_writer::link($link, $link);
334         }
335         echo $OUTPUT->container_end();
336     }
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  */
343 class grade_export_update_buffer {
344     public $update_list;
345     public $export_time;
347     /**
348      * Constructor - creates the buffer and initialises the time stamp
349      */
350     public function grade_export_update_buffer() {
351         $this->update_list = array();
352         $this->export_time = time();
353     }
355     public function flush($buffersize) {
356         global $CFG, $DB;
358         if (count($this->update_list) > $buffersize) {
359             list($usql, $params) = $DB->get_in_or_equal($this->update_list);
360             $params = array_merge(array($this->export_time), $params);
362             $sql = "UPDATE {grade_grades} SET exported = ? WHERE id $usql";
363             $DB->execute($sql, $params);
364             $this->update_list = array();
365         }
366     }
368     /**
369      * Track grade export status
370      * @param object $grade_grade
371      * @return string $status (unknow, new, regrade, nochange)
372      */
373     public function track($grade_grade) {
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             }
384         } else if ($grade_grade->exported < $grade_grade->timemodified) {
385             $status = 'regrade';
386             $this->update_list[] = $grade_grade->id;
388         } else if ($grade_grade->exported >= $grade_grade->timemodified) {
389             $status = 'nochange';
391         } else {
392             // something is wrong?
393             $status = 'unknown';
394         }
396         $this->flush(100);
398         return $status;
399     }
401     /**
402      * Flush and close the buffer.
403      */
404     public function close() {
405         $this->flush(0);
406     }
409 /**
410  * Verify that there is a valid set of grades to export.
411  * @param $courseid int The course being exported
412  */
413 function export_verify_grades($courseid) {
414     $regraderesult = grade_regrade_final_grades($courseid);
415     if (is_array($regraderesult)) {
416         throw new moodle_exception('gradecantregrade', 'error', '', implode(', ', array_unique($regraderesult)));
417     }