2 // This file is part of Moodle - http://moodle.org/
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.
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.
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/>.
18 * File containing the grade_report class
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
25 require_once($CFG->libdir
.'/gradelib.php');
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
32 abstract class grade_report
{
45 /** Grade plugin return tracking object.
57 * The grade_tree object.
63 * User preferences related to this report.
66 public $prefs = array();
69 * The roles for this report.
70 * @var string $gradebookroles
72 public $gradebookroles;
75 * base url for sorting by first/last name.
76 * @var string $baseurl
81 * base url for paging.
82 * @var string $pbarurl
87 * Current page (for paging).
93 * Array of cached language strings (using get_string() all the time takes a long time!).
94 * @var array $lang_strings
96 public $lang_strings = array();
98 // GROUP VARIABLES (including SQL)
101 * The current group being displayed.
102 * @var int $currentgroup
104 public $currentgroup;
107 * The current groupname being displayed.
108 * @var string $currentgroupname
110 public $currentgroupname;
113 * Current course group mode
114 * @var int $groupmode
119 * A HTML select element used to select the current group.
120 * @var string $group_selector
122 public $group_selector;
125 * An SQL fragment used to add linking information to the group tables.
126 * @var string $groupsql
131 * An SQL constraint to append to the queries used by this object to build the report.
132 * @var string $groupwheresql
134 protected $groupwheresql;
137 * The ordered params for $groupwheresql
138 * @var array $groupwheresql_params
140 protected $groupwheresql_params = array();
142 // USER VARIABLES (including SQL).
145 * An SQL constraint to append to the queries used by this object to build the report.
146 * @var string $userwheresql
148 protected $userwheresql;
151 * The ordered params for $userwheresql
152 * @var array $userwheresql_params
154 protected $userwheresql_params = array();
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)
163 public function __construct($courseid, $gpr, $context, $page=null) {
164 global $CFG, $COURSE, $DB;
166 if (empty($CFG->gradebookroles
)) {
167 print_error('norolesdefined', 'grades');
170 $this->courseid
= $courseid;
171 if ($this->courseid
== $COURSE->id
) {
172 $this->course
= $COURSE;
174 $this->course
= $DB->get_record('course', array('id' => $this->courseid
));
178 $this->context
= $context;
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
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
200 public function get_pref($pref, $objectid=null) {
202 $fullprefname = 'grade_report_' . $pref;
203 $shortprefname = 'grade_' . $pref;
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);
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);
228 $retval = get_user_preferences($fullprefname, $CFG->$fullprefname);
230 $this->prefs
[$pref.$objectid] = $retval;
232 $retval = $this->prefs
[$pref.$objectid];
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.
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);
252 return set_user_preference($fullprefname.$itemid, $pref_value);
257 * Handles form data sent by this report for this report. Abstract method to implement in all children.
260 * @return mixed True or array of errors
262 abstract public function process_data($data);
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...)
270 abstract public function process_action($target, $action);
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
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);
283 return $this->lang_strings
[$strcode];
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
292 public function get_numusers($groups = true, $users = false) {
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);
310 $userwheresql = $this->userwheresql
;
311 $params = array_merge($params, $this->userwheresql_params
);
315 $groupsql = $this->groupsql
;
316 $groupwheresql = $this->groupwheresql
;
317 $params = array_merge($params, $this->groupwheresql_params
);
320 $sql = "SELECT DISTINCT u.id
322 JOIN ($enrolledsql) je
324 JOIN {role_assignments} ra
327 WHERE ra.roleid $gradebookrolessql
331 AND ra.contextid $relatedctxsql";
332 $selectedusers = $DB->get_records_sql($sql, $params);
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))) {
355 * Sets up this object's group variables, mainly to restrict the selection of users to display.
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
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
);
378 * Sets up this report's user criteria to restrict the selection of users to display.
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'].'%';
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'].'%';
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
400 protected function get_sort_arrow($direction='move', $sortlink=null) {
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));
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
417 protected function blank_hidden_total($courseid, $course_item, $finalgrade) {
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
);
432 if ($this->showtotalsifcontainhidden
[$courseid] == GRADE_REPORT_SHOW_REAL_TOTAL_IF_CONTAINS_HIDDEN
) {
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;
443 if (!$hiding_affected) {
444 $items = grade_item
::fetch_all(array('courseid'=>$courseid));
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);
454 unset($gradesrecords);
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;
463 $grades[$itemid]->grade_item
=& $items[$itemid];
465 $hiding_affected = grade_grade
::get_hiding_affected($grades, $items);
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]) {
474 //use reprocessed marks that exclude hidden items
475 $finalgrade = $hiding_affected['altered'][$course_item->id
];
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]) {
483 //use reprocessed marks that exclude hidden items
484 $finalgrade = $hiding_affected['unknown'][$course_item->id
];