MDL-30085 core_grades functions moved to correct location
[moodle.git] / grade / report / lib.php
1 <?php
2 // This file is part of Moodle - http://moodle.org/
3 //
4 // Moodle is free software: you can redistribute it and/or modify
5 // it under the terms of the GNU General Public License as published by
6 // the Free Software Foundation, either version 3 of the License, or
7 // (at your option) any later version.
8 //
9 // Moodle is distributed in the hope that it will be useful,
10 // but WITHOUT ANY WARRANTY; without even the implied warranty of
11 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
12 // GNU General Public License for more details.
13 //
14 // You should have received a copy of the GNU General Public License
15 // along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
17 /**
18  * File containing the grade_report class
19  *
20  * @package   core_grades
21  * @copyright 2007 Moodle Pty Ltd (http://moodle.com)
22  * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
23  */
25 require_once($CFG->libdir.'/gradelib.php');
27 /**
28  * An abstract class containing variables and methods used by all or most reports.
29  * @copyright 2007 Moodle Pty Ltd (http://moodle.com)
30  * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
31  */
32 abstract class grade_report {
33     /**
34      * The courseid.
35      * @var int $courseid
36      */
37     public $courseid;
39     /**
40      * The course.
41      * @var object $course
42      */
43     public $course;
45     /** Grade plugin return tracking object.
46      * @var object $gpr
47      */
48     public $gpr;
50     /**
51      * The context.
52      * @var int $context
53      */
54     public $context;
56     /**
57      * The grade_tree object.
58      * @var object $gtree
59      */
60     public $gtree;
62     /**
63      * User preferences related to this report.
64      * @var array $prefs
65      */
66     public $prefs = array();
68     /**
69      * The roles for this report.
70      * @var string $gradebookroles
71      */
72     public $gradebookroles;
74     /**
75      * base url for sorting by first/last name.
76      * @var string $baseurl
77      */
78     public $baseurl;
80     /**
81      * base url for paging.
82      * @var string $pbarurl
83      */
84     public $pbarurl;
86     /**
87      * Current page (for paging).
88      * @var int $page
89      */
90     public $page;
92     /**
93      * Array of cached language strings (using get_string() all the time takes a long time!).
94      * @var array $lang_strings
95      */
96     public $lang_strings = array();
98     // GROUP VARIABLES (including SQL)
100     /**
101      * The current group being displayed.
102      * @var int $currentgroup
103      */
104     public $currentgroup;
106     /**
107      * The current groupname being displayed.
108      * @var string $currentgroupname
109      */
110     public $currentgroupname;
112     /**
113      * Current course group mode
114      * @var int $groupmode
115      */
116     public $groupmode;
118     /**
119      * A HTML select element used to select the current group.
120      * @var string $group_selector
121      */
122     public $group_selector;
124     /**
125      * An SQL fragment used to add linking information to the group tables.
126      * @var string $groupsql
127      */
128     protected $groupsql;
130     /**
131      * An SQL constraint to append to the queries used by this object to build the report.
132      * @var string $groupwheresql
133      */
134     protected $groupwheresql;
136     /**
137      * The ordered params for $groupwheresql
138      * @var array $groupwheresql_params
139      */
140     protected $groupwheresql_params = array();
142     // USER VARIABLES (including SQL).
144     /**
145      * An SQL constraint to append to the queries used by this object to build the report.
146      * @var string $userwheresql
147      */
148     protected $userwheresql;
150     /**
151      * The ordered params for $userwheresql
152      * @var array $userwheresql_params
153      */
154     protected $userwheresql_params = array();
156     /**
157      * Constructor. Sets local copies of user preferences and initialises grade_tree.
158      * @param int $courseid
159      * @param object $gpr grade plugin return tracking object
160      * @param string $context
161      * @param int $page The current page being viewed (when report is paged)
162      */
163     public function __construct($courseid, $gpr, $context, $page=null) {
164         global $CFG, $COURSE, $DB;
166         if (empty($CFG->gradebookroles)) {
167             print_error('norolesdefined', 'grades');
168         }
170         $this->courseid  = $courseid;
171         if ($this->courseid == $COURSE->id) {
172             $this->course = $COURSE;
173         } else {
174             $this->course = $DB->get_record('course', array('id' => $this->courseid));
175         }
177         $this->gpr       = $gpr;
178         $this->context   = $context;
179         $this->page      = $page;
181         // roles to be displayed in the gradebook
182         $this->gradebookroles = $CFG->gradebookroles;
184         // Set up link to preferences page
185         $this->preferences_page = $CFG->wwwroot.'/grade/report/grader/preferences.php?id='.$courseid;
187         // init gtree in child class
188     }
190     /**
191      * Given the name of a user preference (without grade_report_ prefix), locally saves then returns
192      * the value of that preference. If the preference has already been fetched before,
193      * the saved value is returned. If the preference is not set at the User level, the $CFG equivalent
194      * is given (site default).
195      * Can be called statically, but then doesn't benefit from caching
196      * @param string $pref The name of the preference (do not include the grade_report_ prefix)
197      * @param int $objectid An optional itemid or categoryid to check for a more fine-grained preference
198      * @return mixed The value of the preference
199      */
200     public function get_pref($pref, $objectid=null) {
201         global $CFG;
202         $fullprefname = 'grade_report_' . $pref;
203         $shortprefname = 'grade_' . $pref;
205         $retval = null;
207         if (!isset($this) OR get_class($this) != 'grade_report') {
208             if (!empty($objectid)) {
209                 $retval = get_user_preferences($fullprefname . $objectid, self::get_pref($pref));
210             } else if (isset($CFG->$fullprefname)) {
211                 $retval = get_user_preferences($fullprefname, $CFG->$fullprefname);
212             } else if (isset($CFG->$shortprefname)) {
213                 $retval = get_user_preferences($fullprefname, $CFG->$shortprefname);
214             } else {
215                 $retval = null;
216             }
217         } else {
218             if (empty($this->prefs[$pref.$objectid])) {
220                 if (!empty($objectid)) {
221                     $retval = get_user_preferences($fullprefname . $objectid);
222                     if (empty($retval)) {
223                         // No item pref found, we are returning the global preference
224                         $retval = $this->get_pref($pref);
225                         $objectid = null;
226                     }
227                 } else {
228                     $retval = get_user_preferences($fullprefname, $CFG->$fullprefname);
229                 }
230                 $this->prefs[$pref.$objectid] = $retval;
231             } else {
232                 $retval = $this->prefs[$pref.$objectid];
233             }
234         }
236         return $retval;
237     }
239     /**
240      * Uses set_user_preferences() to update the value of a user preference. If 'default' is given as the value,
241      * the preference will be removed in favour of a higher-level preference.
242      * @param string $pref The name of the preference.
243      * @param mixed $pref_value The value of the preference.
244      * @param int $itemid An optional itemid to which the preference will be assigned
245      * @return bool Success or failure.
246      */
247     public function set_pref($pref, $pref_value='default', $itemid=null) {
248         $fullprefname = 'grade_report_' . $pref;
249         if ($pref_value == 'default') {
250             return unset_user_preference($fullprefname.$itemid);
251         } else {
252             return set_user_preference($fullprefname.$itemid, $pref_value);
253         }
254     }
256     /**
257      * Handles form data sent by this report for this report. Abstract method to implement in all children.
258      * @abstract
259      * @param array $data
260      * @return mixed True or array of errors
261      */
262     abstract public function process_data($data);
264     /**
265      * Processes a single action against a category, grade_item or grade.
266      * @param string $target Sortorder
267      * @param string $action Which action to take (edit, delete etc...)
268      * @return
269      */
270     abstract public function process_action($target, $action);
272     /**
273      * First checks the cached language strings, then returns match if found, or uses get_string()
274      * to get it from the DB, caches it then returns it.
275      * @param string $strcode
276      * @param string $section Optional language section
277      * @return string
278      */
279     public function get_lang_string($strcode, $section=null) {
280         if (empty($this->lang_strings[$strcode])) {
281             $this->lang_strings[$strcode] = get_string($strcode, $section);
282         }
283         return $this->lang_strings[$strcode];
284     }
286     /**
287      * Fetches and returns a count of all the users that will be shown on this page.
288      * @param boolean $groups include groups limit
289      * @param boolean $users include users limit - default false, used for searching purposes
290      * @return int Count of users
291      */
292     public function get_numusers($groups = true, $users = false) {
293         global $CFG, $DB;
294         $userwheresql = "";
295         $groupsql      = "";
296         $groupwheresql = "";
298         // Limit to users with a gradeable role.
299         list($gradebookrolessql, $gradebookrolesparams) = $DB->get_in_or_equal(explode(',', $this->gradebookroles), SQL_PARAMS_NAMED, 'grbr0');
301         // Limit to users with an active enrollment.
302         list($enrolledsql, $enrolledparams) = get_enrolled_sql($this->context);
304         // We want to query both the current context and parent contexts.
305         list($relatedctxsql, $relatedctxparams) = $DB->get_in_or_equal($this->context->get_parent_context_ids(true), SQL_PARAMS_NAMED, 'relatedctx');
307         $params = array_merge($gradebookrolesparams, $enrolledparams, $relatedctxparams);
309         if ($users) {
310             $userwheresql = $this->userwheresql;
311             $params       = array_merge($params, $this->userwheresql_params);
312         }
314         if ($groups) {
315             $groupsql      = $this->groupsql;
316             $groupwheresql = $this->groupwheresql;
317             $params        = array_merge($params, $this->groupwheresql_params);
318         }
320         $sql = "SELECT DISTINCT u.id
321                        FROM {user} u
322                        JOIN ($enrolledsql) je
323                             ON je.id = u.id
324                        JOIN {role_assignments} ra
325                             ON u.id = ra.userid
326                        $groupsql
327                       WHERE ra.roleid $gradebookrolessql
328                             AND u.deleted = 0
329                             $userwheresql
330                             $groupwheresql
331                             AND ra.contextid $relatedctxsql";
332         $selectedusers = $DB->get_records_sql($sql, $params);
334         $count = 0;
335         // Check if user's enrolment is active and should be displayed.
336         if (!empty($selectedusers)) {
337             $coursecontext = $this->context->get_course_context(true);
339             $useractiveenrolments = get_enrolled_users($coursecontext, '', 0, 'u.*',  null, 0, 0, true);
341             $defaultgradeshowactiveenrol = !empty($CFG->grade_report_showonlyactiveenrol);
342             $showonlyactiveenrol = get_user_preferences('grade_report_showonlyactiveenrol', $defaultgradeshowactiveenrol);
343             $showonlyactiveenrol = $showonlyactiveenrol || !has_capability('moodle/course:viewsuspendedusers', $coursecontext);
345             foreach ($selectedusers as $id => $value) {
346                 if (!$showonlyactiveenrol || ($showonlyactiveenrol && array_key_exists($id, $useractiveenrolments))) {
347                     $count++;
348                 }
349             }
350         }
351         return $count;
352     }
354     /**
355      * Sets up this object's group variables, mainly to restrict the selection of users to display.
356      */
357     protected function setup_groups() {
358         // find out current groups mode
359         if ($this->groupmode = groups_get_course_groupmode($this->course)) {
360             $this->currentgroup = groups_get_course_group($this->course, true);
361             $this->group_selector = groups_print_course_menu($this->course, $this->pbarurl, true);
363             if ($this->groupmode == SEPARATEGROUPS and !$this->currentgroup and !has_capability('moodle/site:accessallgroups', $this->context)) {
364                 $this->currentgroup = -2; // means can not access any groups at all
365             }
367             if ($this->currentgroup) {
368                 $group = groups_get_group($this->currentgroup);
369                 $this->currentgroupname     = $group->name;
370                 $this->groupsql             = " JOIN {groups_members} gm ON gm.userid = u.id ";
371                 $this->groupwheresql        = " AND gm.groupid = :gr_grpid ";
372                 $this->groupwheresql_params = array('gr_grpid'=>$this->currentgroup);
373             }
374         }
375     }
377     /**
378      * Sets up this report's user criteria to restrict the selection of users to display.
379      */
380     public function setup_users() {
381         global $SESSION, $DB;
383         $this->userwheresql = "";
384         $this->userwheresql_params = array();
385         if (isset($SESSION->gradereport['filterfirstname']) && !empty($SESSION->gradereport['filterfirstname'])) {
386             $this->userwheresql .= ' AND '.$DB->sql_like('u.firstname', ':firstname', false, false);
387             $this->userwheresql_params['firstname'] = $SESSION->gradereport['filterfirstname'].'%';
388         }
389         if (isset($SESSION->gradereport['filtersurname']) && !empty($SESSION->gradereport['filtersurname'])) {
390             $this->userwheresql .= ' AND '.$DB->sql_like('u.lastname', ':lastname', false, false);
391             $this->userwheresql_params['lastname'] = $SESSION->gradereport['filtersurname'].'%';
392         }
393     }
395     /**
396      * Returns an arrow icon inside an <a> tag, for the purpose of sorting a column.
397      * @param string $direction
398      * @param moodle_url $sortlink
399      */
400     protected function get_sort_arrow($direction='move', $sortlink=null) {
401         global $OUTPUT;
402         $pix = array('up' => 't/sort_desc', 'down' => 't/sort_asc', 'move' => 't/sort');
403         $matrix = array('up' => 'desc', 'down' => 'asc', 'move' => 'desc');
404         $strsort = $this->get_lang_string('sort' . $matrix[$direction]);
406         $arrow = $OUTPUT->pix_icon($pix[$direction], $strsort, '', array('class' => 'sorticon'));
407         return html_writer::link($sortlink, $arrow, array('title'=>$strsort));
408     }
410     /**
411      * Optionally blank out course/category totals if they contain any hidden items
412      * @param string $courseid the course id
413      * @param string $course_item an instance of grade_item
414      * @param string $finalgrade the grade for the course_item
415      * @return string The new final grade
416      */
417     protected function blank_hidden_total($courseid, $course_item, $finalgrade) {
418         global $CFG, $DB;
419         static $hiding_affected = null;//array of items in this course affected by hiding
421         // If we're dealing with multiple users we need to know when we've moved on to a new user.
422         static $previous_userid = null;
424         // If we're dealing with multiple courses we need to know when we've moved on to a new course.
425         static $previous_courseid = null;
427         if (!is_array($this->showtotalsifcontainhidden)) {
428             debugging('showtotalsifcontainhidden should be an array', DEBUG_DEVELOPER);
429             $this->showtotalsifcontainhidden = array($courseid => $this->showtotalsifcontainhidden);
430         }
432         if ($this->showtotalsifcontainhidden[$courseid] == GRADE_REPORT_SHOW_REAL_TOTAL_IF_CONTAINS_HIDDEN) {
433             return $finalgrade;
434         }
436         // If we've moved on to another course or user, reload the grades.
437         if ($previous_userid != $this->user->id || $previous_courseid != $courseid) {
438             $hiding_affected = null;
439             $previous_userid = $this->user->id;
440             $previous_courseid = $courseid;
441         }
443         if (!$hiding_affected) {
444             $items = grade_item::fetch_all(array('courseid'=>$courseid));
445             $grades = array();
446             $sql = "SELECT g.*
447                       FROM {grade_grades} g
448                       JOIN {grade_items} gi ON gi.id = g.itemid
449                      WHERE g.userid = {$this->user->id} AND gi.courseid = {$courseid}";
450             if ($gradesrecords = $DB->get_records_sql($sql)) {
451                 foreach ($gradesrecords as $grade) {
452                     $grades[$grade->itemid] = new grade_grade($grade, false);
453                 }
454                 unset($gradesrecords);
455             }
456             foreach ($items as $itemid => $unused) {
457                 if (!isset($grades[$itemid])) {
458                     $grade_grade = new grade_grade();
459                     $grade_grade->userid = $this->user->id;
460                     $grade_grade->itemid = $items[$itemid]->id;
461                     $grades[$itemid] = $grade_grade;
462                 }
463                 $grades[$itemid]->grade_item =& $items[$itemid];
464             }
465             $hiding_affected = grade_grade::get_hiding_affected($grades, $items);
466         }
468         //if the item definitely depends on a hidden item
469         if (array_key_exists($course_item->id, $hiding_affected['altered'])) {
470             if (!$this->showtotalsifcontainhidden[$courseid]) {
471                 //hide the grade
472                 $finalgrade = null;
473             } else {
474                 //use reprocessed marks that exclude hidden items
475                 $finalgrade = $hiding_affected['altered'][$course_item->id];
476             }
477         } else if (!empty($hiding_affected['unknown'][$course_item->id])) {
478             //not sure whether or not this item depends on a hidden item
479             if (!$this->showtotalsifcontainhidden[$courseid]) {
480                 //hide the grade
481                 $finalgrade = null;
482             } else {
483                 //use reprocessed marks that exclude hidden items
484                 $finalgrade = $hiding_affected['unknown'][$course_item->id];
485             }
486         }
488         return $finalgrade;
489     }