MDL-36559 usability: Gradebook CSS styling for new icons
[moodle.git] / grade / report / lib.php
CommitLineData
e060e33d 1<?php
e060e33d 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/>.
8ad36f4c 16
38b9e8a8 17/**
a153c9f2
AD
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
38b9e8a8 23 */
eea6690a 24
25require_once($CFG->libdir.'/gradelib.php');
26
27/**
28 * An abstract class containing variables and methods used by all or most reports.
a153c9f2 29 * @package core_grades
eea6690a 30 */
d24832f9 31abstract class grade_report {
eea6690a 32 /**
33 * The courseid.
34 * @var int $courseid
35 */
d24832f9 36 public $courseid;
eea6690a 37
b2bc96d1 38 /**
39 * The course.
40 * @var object $course
41 */
d24832f9 42 public $course;
b2bc96d1 43
d30c4481 44 /** Grade plugin return tracking object.
4889285b 45 * @var object $gpr
46 */
47 public $gpr;
d30c4481 48
eea6690a 49 /**
50 * The context.
51 * @var int $context
52 */
d24832f9 53 public $context;
eea6690a 54
55 /**
56 * The grade_tree object.
57 * @var object $gtree
58 */
d24832f9 59 public $gtree;
eea6690a 60
61 /**
62 * User preferences related to this report.
e50ce569 63 * @var array $prefs
eea6690a 64 */
d24832f9 65 public $prefs = array();
eea6690a 66
67 /**
68 * The roles for this report.
69 * @var string $gradebookroles
70 */
d24832f9 71 public $gradebookroles;
eea6690a 72
73 /**
74 * base url for sorting by first/last name.
75 * @var string $baseurl
76 */
d24832f9 77 public $baseurl;
eea6690a 78
79 /**
80 * base url for paging.
81 * @var string $pbarurl
82 */
d24832f9 83 public $pbarurl;
eea6690a 84
85 /**
86 * Current page (for paging).
87 * @var int $page
88 */
d24832f9 89 public $page;
eea6690a 90
388234f4 91 /**
92 * Array of cached language strings (using get_string() all the time takes a long time!).
93 * @var array $lang_strings
94 */
d24832f9 95 public $lang_strings = array();
388234f4 96
90d3960c 97//// GROUP VARIABLES (including SQL)
98
99 /**
100 * The current group being displayed.
101 * @var int $currentgroup
102 */
d24832f9 103 public $currentgroup;
90d3960c 104
35079f53 105 /**
106 * Current course group mode
107 * @var int $groupmode
108 */
109 var $groupmode;
110
90d3960c 111 /**
112 * A HTML select element used to select the current group.
113 * @var string $group_selector
114 */
d24832f9 115 public $group_selector;
90d3960c 116
117 /**
118 * An SQL fragment used to add linking information to the group tables.
119 * @var string $groupsql
120 */
d24832f9 121 protected $groupsql;
90d3960c 122
123 /**
124 * An SQL constraint to append to the queries used by this object to build the report.
125 * @var string $groupwheresql
126 */
d24832f9 127 protected $groupwheresql;
128
129 /**
130 * The ordered params for $groupwheresql
131 * @var array $groupwheresql_params
132 */
133 protected $groupwheresql_params = array();
90d3960c 134
135
eea6690a 136 /**
137 * Constructor. Sets local copies of user preferences and initialises grade_tree.
138 * @param int $courseid
d30c4481 139 * @param object $gpr grade plugin return tracking object
eea6690a 140 * @param string $context
141 * @param int $page The current page being viewed (when report is paged)
142 */
d24832f9 143 public function __construct($courseid, $gpr, $context, $page=null) {
5c75a0a3 144 global $CFG, $COURSE, $DB;
eea6690a 145
dde8e548 146 if (empty($CFG->gradebookroles)) {
771dc7b2 147 print_error('norolesdefined', 'grades');
0893aa30 148 }
284abb09 149
0893aa30 150
4faf5f99 151 $this->courseid = $courseid;
b2bc96d1 152 if ($this->courseid == $COURSE->id) {
153 $this->course = $COURSE;
154 } else {
5c75a0a3 155 $this->course = $DB->get_record('course', array('id' => $this->courseid));
b2bc96d1 156 }
41f22daa 157
4faf5f99 158 $this->gpr = $gpr;
159 $this->context = $context;
160 $this->page = $page;
eea6690a 161
162 // roles to be displayed in the gradebook
163 $this->gradebookroles = $CFG->gradebookroles;
164
dc482cfa 165 // Set up link to preferences page
166 $this->preferences_page = $CFG->wwwroot.'/grade/report/grader/preferences.php?id='.$courseid;
167
4faf5f99 168 // init gtree in child class
38b9e8a8 169 }
170
eea6690a 171 /**
172 * Given the name of a user preference (without grade_report_ prefix), locally saves then returns
173 * the value of that preference. If the preference has already been fetched before,
174 * the saved value is returned. If the preference is not set at the User level, the $CFG equivalent
175 * is given (site default).
501e0e34 176 * @static (Can be called statically, but then doesn't benefit from caching)
eea6690a 177 * @param string $pref The name of the preference (do not include the grade_report_ prefix)
8c5a416e 178 * @param int $objectid An optional itemid or categoryid to check for a more fine-grained preference
eea6690a 179 * @return mixed The value of the preference
180 */
d24832f9 181 public function get_pref($pref, $objectid=null) {
eea6690a 182 global $CFG;
501e0e34 183 $fullprefname = 'grade_report_' . $pref;
54294d3b 184 $shortprefname = 'grade_' . $pref;
38b9e8a8 185
e50ce569 186 $retval = null;
187
438a5aa9 188 if (!isset($this) OR get_class($this) != 'grade_report') {
8c5a416e 189 if (!empty($objectid)) {
190 $retval = get_user_preferences($fullprefname . $objectid, grade_report::get_pref($pref));
54294d3b 191 } elseif (isset($CFG->$fullprefname)) {
e50ce569 192 $retval = get_user_preferences($fullprefname, $CFG->$fullprefname);
54294d3b 193 } elseif (isset($CFG->$shortprefname)) {
d24832f9 194 $retval = get_user_preferences($fullprefname, $CFG->$shortprefname);
54294d3b 195 } else {
196 $retval = null;
bb384a8e 197 }
501e0e34 198 } else {
8c5a416e 199 if (empty($this->prefs[$pref.$objectid])) {
e50ce569 200
8c5a416e 201 if (!empty($objectid)) {
202 $retval = get_user_preferences($fullprefname . $objectid);
e50ce569 203 if (empty($retval)) {
204 // No item pref found, we are returning the global preference
205 $retval = $this->get_pref($pref);
8c5a416e 206 $objectid = null;
e50ce569 207 }
501e0e34 208 } else {
e50ce569 209 $retval = get_user_preferences($fullprefname, $CFG->$fullprefname);
501e0e34 210 }
8c5a416e 211 $this->prefs[$pref.$objectid] = $retval;
e50ce569 212 } else {
8c5a416e 213 $retval = $this->prefs[$pref.$objectid];
501e0e34 214 }
eea6690a 215 }
e50ce569 216
217 return $retval;
eea6690a 218 }
bb384a8e 219
eea6690a 220 /**
501e0e34 221 * Uses set_user_preferences() to update the value of a user preference. If 'default' is given as the value,
222 * the preference will be removed in favour of a higher-level preference.
223 * @static
eea6690a 224 * @param string $pref_name The name of the preference.
225 * @param mixed $pref_value The value of the preference.
bb384a8e 226 * @param int $itemid An optional itemid to which the preference will be assigned
eea6690a 227 * @return bool Success or failure.
eea6690a 228 */
d24832f9 229 public function set_pref($pref, $pref_value='default', $itemid=null) {
bb384a8e 230 $fullprefname = 'grade_report_' . $pref;
501e0e34 231 if ($pref_value == 'default') {
232 return unset_user_preference($fullprefname.$itemid);
233 } else {
234 return set_user_preference($fullprefname.$itemid, $pref_value);
eea6690a 235 }
38b9e8a8 236 }
38b9e8a8 237
eea6690a 238 /**
239 * Handles form data sent by this report for this report. Abstract method to implement in all children.
240 * @abstract
241 * @param array $data
242 * @return mixed True or array of errors
243 */
d24832f9 244 abstract function process_data($data);
38b9e8a8 245
eea6690a 246 /**
247 * Processes a single action against a category, grade_item or grade.
248 * @param string $target Sortorder
249 * @param string $action Which action to take (edit, delete etc...)
250 * @return
eea6690a 251 */
d24832f9 252 abstract function process_action($target, $action);
eea6690a 253
388234f4 254 /**
255 * First checks the cached language strings, then returns match if found, or uses get_string()
256 * to get it from the DB, caches it then returns it.
257 * @param string $strcode
258 * @param string $section Optional language section
259 * @return string
260 */
d24832f9 261 public function get_lang_string($strcode, $section=null) {
388234f4 262 if (empty($this->lang_strings[$strcode])) {
263 $this->lang_strings[$strcode] = get_string($strcode, $section);
264 }
265 return $this->lang_strings[$strcode];
266 }
267
90d3960c 268 /**
269 * Fetches and returns a count of all the users that will be shown on this page.
28bcbc38 270 * @param boolean $groups include groups limit
90d3960c 271 * @return int Count of users
272 */
d24832f9 273 public function get_numusers($groups=true) {
274 global $CFG, $DB;
90d3960c 275
28bcbc38 276 $groupsql = "";
277 $groupwheresql = "";
387815db 278
279 //limit to users with a gradeable role
280 list($gradebookrolessql, $gradebookrolesparams) = $DB->get_in_or_equal(explode(',', $this->gradebookroles), SQL_PARAMS_NAMED, 'grbr0');
281
282 //limit to users with an active enrollment
283 list($enrolledsql, $enrolledparams) = get_enrolled_sql($this->context);
284
285 $params = array_merge($gradebookrolesparams, $enrolledparams);
d24832f9 286
28bcbc38 287 if ($groups) {
288 $groupsql = $this->groupsql;
bbadce53 289 $groupwheresql = $this->groupwheresql;
d24832f9 290 $params = array_merge($params, $this->groupwheresql_params);
28bcbc38 291 }
292
90d3960c 293 $countsql = "SELECT COUNT(DISTINCT u.id)
b50371da 294 FROM {user} u
25081b95
SH
295 JOIN ($enrolledsql) je
296 ON je.id = u.id
297 JOIN {role_assignments} ra
298 ON u.id = ra.userid
299 $groupsql
300 WHERE ra.roleid $gradebookrolessql
301 AND u.deleted = 0
b50371da 302 $groupwheresql
303 AND ra.contextid ".get_related_contexts_string($this->context);
d24832f9 304 return $DB->count_records_sql($countsql, $params);
90d3960c 305 }
306
307 /**
308 * Sets up this object's group variables, mainly to restrict the selection of users to display.
309 */
0fd8bc00 310 protected function setup_groups() {
90d3960c 311 /// find out current groups mode
35079f53 312 if ($this->groupmode = groups_get_course_groupmode($this->course)) {
7a9ba4b4 313 $this->currentgroup = groups_get_course_group($this->course, true);
35079f53 314 $this->group_selector = groups_print_course_menu($this->course, $this->pbarurl, true);
7a9ba4b4 315
316 if ($this->groupmode == SEPARATEGROUPS and !$this->currentgroup and !has_capability('moodle/site:accessallgroups', $this->context)) {
6ef4878b 317 $this->currentgroup = -2; // means can not access any groups at all
7a9ba4b4 318 }
35079f53 319
320 if ($this->currentgroup) {
321 $this->groupsql = " JOIN {groups_members} gm ON gm.userid = u.id ";
322 $this->groupwheresql = " AND gm.groupid = :gr_grpid ";
323 $this->groupwheresql_params = array('gr_grpid'=>$this->currentgroup);
324 }
90d3960c 325 }
326 }
2e3987a9 327
328 /**
329 * Returns an arrow icon inside an <a> tag, for the purpose of sorting a column.
330 * @param string $direction
319770d7 331 * @param moodle_url $sort_link
2e3987a9 332 * @param string HTML
333 */
319770d7 334 protected function get_sort_arrow($direction='move', $sortlink=null) {
335 global $OUTPUT;
0cddd851 336 $pix = array('up' => 't/sort_desc', 'down' => 't/sort_asc', 'move' => 't/sort');
dc482cfa 337 $matrix = array('up' => 'desc', 'down' => 'asc', 'move' => 'desc');
2e3987a9 338 $strsort = $this->get_lang_string('sort' . $matrix[$direction]);
dc482cfa 339
0cddd851 340 $arrow = $OUTPUT->pix_icon($pix[$direction], $strsort, '', array('class' => 'sorticon'));
75015e5f 341 return html_writer::link($sortlink, $arrow, array('title'=>$strsort));
2e3987a9 342 }
61541a5a
AD
343
344 /**
345 * Optionally blank out course/category totals if they contain any hidden items
346 * @param string $courseid the course id
347 * @param string $course_item an instance of grade_item
348 * @param string $finalgrade the grade for the course_item
349 * @return string The new final grade
350 */
351 protected function blank_hidden_total($courseid, $course_item, $finalgrade) {
352 global $CFG, $DB;
353 static $hiding_affected = null;//array of items in this course affected by hiding
354
8eabc1d8
AD
355 //if we're dealing with multiple users we need to know when we've moved on to a new user
356 static $previous_userid = null;
357
61541a5a
AD
358 if( $this->showtotalsifcontainhidden==GRADE_REPORT_SHOW_REAL_TOTAL_IF_CONTAINS_HIDDEN ) {
359 return $finalgrade;
360 }
361
8eabc1d8
AD
362 //if we've moved on to another user don't return the previous user's affected grades
363 if ($previous_userid!=$this->user->id) {
364 $hiding_affected = null;
365 $previous_userid = $this->user->id;
366 }
367
61541a5a
AD
368 if( !$hiding_affected ) {
369 $items = grade_item::fetch_all(array('courseid'=>$courseid));
370 $grades = array();
371 $sql = "SELECT g.*
ffe50258
EL
372 FROM {grade_grades} g
373 JOIN {grade_items} gi ON gi.id = g.itemid
61541a5a
AD
374 WHERE g.userid = {$this->user->id} AND gi.courseid = {$courseid}";
375 if ($gradesrecords = $DB->get_records_sql($sql)) {
376 foreach ($gradesrecords as $grade) {
377 $grades[$grade->itemid] = new grade_grade($grade, false);
378 }
379 unset($gradesrecords);
380 }
381 foreach ($items as $itemid=>$unused) {
382 if (!isset($grades[$itemid])) {
383 $grade_grade = new grade_grade();
384 $grade_grade->userid = $this->user->id;
385 $grade_grade->itemid = $items[$itemid]->id;
386 $grades[$itemid] = $grade_grade;
387 }
388 $grades[$itemid]->grade_item =& $items[$itemid];
389 }
390 $hiding_affected = grade_grade::get_hiding_affected($grades, $items);
391 }
392
393 //if the item definitely depends on a hidden item
394 if (array_key_exists($course_item->id, $hiding_affected['altered'])) {
395 if( !$this->showtotalsifcontainhidden ) {
396 //hide the grade
397 $finalgrade = null;
398 }
399 else {
400 //use reprocessed marks that exclude hidden items
401 $finalgrade = $hiding_affected['altered'][$course_item->id];
402 }
403 } else if (!empty($hiding_affected['unknown'][$course_item->id])) {
404 //not sure whether or not this item depends on a hidden item
405 if( !$this->showtotalsifcontainhidden ) {
406 //hide the grade
407 $finalgrade = null;
408 }
409 else {
410 //use reprocessed marks that exclude hidden items
411 $finalgrade = $hiding_affected['unknown'][$course_item->id];
412 }
413 }
414
415 return $finalgrade;
416 }
38b9e8a8 417}
6c3ef410 418