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