Merge branch 'MDL-36680_hidden' of git://github.com/andyjdavis/moodle
[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  * @package core_grades
30  */
31 abstract class grade_report {
32     /**
33      * The courseid.
34      * @var int $courseid
35      */
36     public $courseid;
38     /**
39      * The course.
40      * @var object $course
41      */
42     public $course;
44     /** Grade plugin return tracking object.
45      * @var object $gpr
46      */
47     public $gpr;
49     /**
50      * The context.
51      * @var int $context
52      */
53     public $context;
55     /**
56      * The grade_tree object.
57      * @var object $gtree
58      */
59     public $gtree;
61     /**
62      * User preferences related to this report.
63      * @var array $prefs
64      */
65     public $prefs = array();
67     /**
68      * The roles for this report.
69      * @var string $gradebookroles
70      */
71     public $gradebookroles;
73     /**
74      * base url for sorting by first/last name.
75      * @var string $baseurl
76      */
77     public $baseurl;
79     /**
80      * base url for paging.
81      * @var string $pbarurl
82      */
83     public $pbarurl;
85     /**
86      * Current page (for paging).
87      * @var int $page
88      */
89     public $page;
91     /**
92      * Array of cached language strings (using get_string() all the time takes a long time!).
93      * @var array $lang_strings
94      */
95     public $lang_strings = array();
97 //// GROUP VARIABLES (including SQL)
99     /**
100      * The current group being displayed.
101      * @var int $currentgroup
102      */
103     public $currentgroup;
105     /**
106      * Current course group mode
107      * @var int $groupmode
108      */
109     var $groupmode;
111     /**
112      * A HTML select element used to select the current group.
113      * @var string $group_selector
114      */
115     public $group_selector;
117     /**
118      * An SQL fragment used to add linking information to the group tables.
119      * @var string $groupsql
120      */
121     protected $groupsql;
123     /**
124      * An SQL constraint to append to the queries used by this object to build the report.
125      * @var string $groupwheresql
126      */
127     protected $groupwheresql;
129     /**
130      * The ordered params for $groupwheresql
131      * @var array $groupwheresql_params
132      */
133     protected $groupwheresql_params = array();
136     /**
137      * Constructor. Sets local copies of user preferences and initialises grade_tree.
138      * @param int $courseid
139      * @param object $gpr grade plugin return tracking object
140      * @param string $context
141      * @param int $page The current page being viewed (when report is paged)
142      */
143     public function __construct($courseid, $gpr, $context, $page=null) {
144         global $CFG, $COURSE, $DB;
146         if (empty($CFG->gradebookroles)) {
147             print_error('norolesdefined', 'grades');
148         }
151         $this->courseid  = $courseid;
152         if ($this->courseid == $COURSE->id) {
153             $this->course = $COURSE;
154         } else {
155             $this->course = $DB->get_record('course', array('id' => $this->courseid));
156         }
158         $this->gpr       = $gpr;
159         $this->context   = $context;
160         $this->page      = $page;
162         // roles to be displayed in the gradebook
163         $this->gradebookroles = $CFG->gradebookroles;
165         // Set up link to preferences page
166         $this->preferences_page = $CFG->wwwroot.'/grade/report/grader/preferences.php?id='.$courseid;
168         // init gtree in child class
169     }
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).
176      * @static (Can be called statically, but then doesn't benefit from caching)
177      * @param string $pref The name of the preference (do not include the grade_report_ prefix)
178      * @param int $objectid An optional itemid or categoryid to check for a more fine-grained preference
179      * @return mixed The value of the preference
180      */
181     public function get_pref($pref, $objectid=null) {
182         global $CFG;
183         $fullprefname = 'grade_report_' . $pref;
184         $shortprefname = 'grade_' . $pref;
186         $retval = null;
188         if (!isset($this) OR get_class($this) != 'grade_report') {
189             if (!empty($objectid)) {
190                 $retval = get_user_preferences($fullprefname . $objectid, grade_report::get_pref($pref));
191             } elseif (isset($CFG->$fullprefname)) {
192                 $retval = get_user_preferences($fullprefname, $CFG->$fullprefname);
193             } elseif (isset($CFG->$shortprefname)) {
194                 $retval = get_user_preferences($fullprefname, $CFG->$shortprefname);
195             } else {
196                 $retval = null;
197             }
198         } else {
199             if (empty($this->prefs[$pref.$objectid])) {
201                 if (!empty($objectid)) {
202                     $retval = get_user_preferences($fullprefname . $objectid);
203                     if (empty($retval)) {
204                         // No item pref found, we are returning the global preference
205                         $retval = $this->get_pref($pref);
206                         $objectid = null;
207                     }
208                 } else {
209                     $retval = get_user_preferences($fullprefname, $CFG->$fullprefname);
210                 }
211                 $this->prefs[$pref.$objectid] = $retval;
212             } else {
213                 $retval = $this->prefs[$pref.$objectid];
214             }
215         }
217         return $retval;
218     }
220     /**
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
224      * @param string $pref_name The name of the preference.
225      * @param mixed $pref_value The value of the preference.
226      * @param int $itemid An optional itemid to which the preference will be assigned
227      * @return bool Success or failure.
228      */
229     public function set_pref($pref, $pref_value='default', $itemid=null) {
230         $fullprefname = 'grade_report_' . $pref;
231         if ($pref_value == 'default') {
232             return unset_user_preference($fullprefname.$itemid);
233         } else {
234             return set_user_preference($fullprefname.$itemid, $pref_value);
235         }
236     }
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      */
244     abstract function process_data($data);
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
251      */
252     abstract function process_action($target, $action);
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      */
261     public function get_lang_string($strcode, $section=null) {
262         if (empty($this->lang_strings[$strcode])) {
263             $this->lang_strings[$strcode] = get_string($strcode, $section);
264         }
265         return $this->lang_strings[$strcode];
266     }
268     /**
269      * Fetches and returns a count of all the users that will be shown on this page.
270      * @param boolean $groups include groups limit
271      * @return int Count of users
272      */
273     public function get_numusers($groups=true) {
274         global $CFG, $DB;
276         $groupsql      = "";
277         $groupwheresql = "";
279         //limit to users with a gradeable role
280         list($gradebookrolessql, $gradebookrolesparams) = $DB->get_in_or_equal(explode(',', $this->gradebookroles), SQL_PARAMS_NAMED, 'grbr0');
282         //limit to users with an active enrollment
283         list($enrolledsql, $enrolledparams) = get_enrolled_sql($this->context);
285         $params = array_merge($gradebookrolesparams, $enrolledparams);
287         if ($groups) {
288             $groupsql      = $this->groupsql;
289             $groupwheresql = $this->groupwheresql;
290             $params        = array_merge($params, $this->groupwheresql_params);
291         }
293         $countsql = "SELECT COUNT(DISTINCT u.id)
294                        FROM {user} u
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
302                             $groupwheresql
303                             AND ra.contextid ".get_related_contexts_string($this->context);
304         return $DB->count_records_sql($countsql, $params);
305     }
307     /**
308      * Sets up this object's group variables, mainly to restrict the selection of users to display.
309      */
310     protected function setup_groups() {
311         /// find out current groups mode
312         if ($this->groupmode = groups_get_course_groupmode($this->course)) {
313             $this->currentgroup = groups_get_course_group($this->course, true);
314             $this->group_selector = groups_print_course_menu($this->course, $this->pbarurl, true);
316             if ($this->groupmode == SEPARATEGROUPS and !$this->currentgroup and !has_capability('moodle/site:accessallgroups', $this->context)) {
317                 $this->currentgroup = -2; // means can not access any groups at all
318             }
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             }
325         }
326     }
328     /**
329      * Returns an arrow icon inside an <a> tag, for the purpose of sorting a column.
330      * @param string $direction
331      * @param moodle_url $sort_link
332      * @param string HTML
333      */
334     protected function get_sort_arrow($direction='move', $sortlink=null) {
335         global $OUTPUT;
336         $pix = array('up' => 't/sort_desc', 'down' => 't/sort_asc', 'move' => 't/sort');
337         $matrix = array('up' => 'desc', 'down' => 'asc', 'move' => 'desc');
338         $strsort = $this->get_lang_string('sort' . $matrix[$direction]);
340         $arrow = $OUTPUT->pix_icon($pix[$direction], $strsort, '', array('class' => 'sorticon'));
341         return html_writer::link($sortlink, $arrow, array('title'=>$strsort));
342     }
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
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;
358         // If we're dealing with multiple courses we need to know when we've moved on to a new course.
359         static $previous_courseid = null;
361         if( $this->showtotalsifcontainhidden==GRADE_REPORT_SHOW_REAL_TOTAL_IF_CONTAINS_HIDDEN ) {
362             return $finalgrade;
363         }
365         // If we've moved on to another course or user, reload the grades.
366         if ($previous_userid != $this->user->id || $previous_courseid != $courseid) {
367             $hiding_affected = null;
368             $previous_userid = $this->user->id;
369             $previous_courseid = $courseid;
370         }
372         if( !$hiding_affected ) {
373             $items = grade_item::fetch_all(array('courseid'=>$courseid));
374             $grades = array();
375             $sql = "SELECT g.*
376                       FROM {grade_grades} g
377                       JOIN {grade_items} gi ON gi.id = g.itemid
378                      WHERE g.userid = {$this->user->id} AND gi.courseid = {$courseid}";
379             if ($gradesrecords = $DB->get_records_sql($sql)) {
380                 foreach ($gradesrecords as $grade) {
381                     $grades[$grade->itemid] = new grade_grade($grade, false);
382                 }
383                 unset($gradesrecords);
384             }
385             foreach ($items as $itemid=>$unused) {
386                 if (!isset($grades[$itemid])) {
387                     $grade_grade = new grade_grade();
388                     $grade_grade->userid = $this->user->id;
389                     $grade_grade->itemid = $items[$itemid]->id;
390                     $grades[$itemid] = $grade_grade;
391                 }
392                 $grades[$itemid]->grade_item =& $items[$itemid];
393             }
394             $hiding_affected = grade_grade::get_hiding_affected($grades, $items);
395         }
397         //if the item definitely depends on a hidden item
398         if (array_key_exists($course_item->id, $hiding_affected['altered'])) {
399             if( !$this->showtotalsifcontainhidden ) {
400                 //hide the grade
401                 $finalgrade = null;
402             }
403             else {
404                 //use reprocessed marks that exclude hidden items
405                 $finalgrade = $hiding_affected['altered'][$course_item->id];
406             }
407         } else if (!empty($hiding_affected['unknown'][$course_item->id])) {
408             //not sure whether or not this item depends on a hidden item
409             if( !$this->showtotalsifcontainhidden ) {
410                 //hide the grade
411                 $finalgrade = null;
412             }
413             else {
414                 //use reprocessed marks that exclude hidden items
415                 $finalgrade = $hiding_affected['unknown'][$course_item->id];
416             }
417         }
419         return $finalgrade;
420     }