eea6690a |
1 | <?php // $Id$ |
38b9e8a8 |
2 | /** |
eea6690a |
3 | * File containing the grade_report class. |
4 | * @package gradebook |
38b9e8a8 |
5 | */ |
eea6690a |
6 | |
7 | require_once($CFG->libdir.'/gradelib.php'); |
8 | |
9 | /** |
10 | * An abstract class containing variables and methods used by all or most reports. |
11 | * @abstract |
12 | * @package gradebook |
13 | */ |
14 | class grade_report { |
15 | /** |
16 | * The courseid. |
17 | * @var int $courseid |
18 | */ |
19 | var $courseid; |
20 | |
d30c4481 |
21 | /** Grade plugin return tracking object. |
22 | var $gpr; |
23 | |
eea6690a |
24 | /** |
25 | * The context. |
26 | * @var int $context |
27 | */ |
28 | var $context; |
29 | |
30 | /** |
31 | * The grade_tree object. |
32 | * @var object $gtree |
33 | */ |
34 | var $gtree; |
35 | |
36 | /** |
37 | * User preferences related to this report. |
e50ce569 |
38 | * @var array $prefs |
eea6690a |
39 | */ |
e50ce569 |
40 | var $prefs = array(); |
eea6690a |
41 | |
42 | /** |
43 | * The roles for this report. |
44 | * @var string $gradebookroles |
45 | */ |
46 | var $gradebookroles; |
47 | |
48 | /** |
49 | * base url for sorting by first/last name. |
50 | * @var string $baseurl |
51 | */ |
52 | var $baseurl; |
53 | |
54 | /** |
55 | * base url for paging. |
56 | * @var string $pbarurl |
57 | */ |
58 | var $pbarurl; |
59 | |
60 | /** |
61 | * Current page (for paging). |
62 | * @var int $page |
63 | */ |
64 | var $page; |
65 | |
388234f4 |
66 | /** |
67 | * Array of cached language strings (using get_string() all the time takes a long time!). |
68 | * @var array $lang_strings |
69 | */ |
70 | var $lang_strings = array(); |
71 | |
90d3960c |
72 | //// GROUP VARIABLES (including SQL) |
73 | |
74 | /** |
75 | * The current group being displayed. |
76 | * @var int $currentgroup |
77 | */ |
78 | var $currentgroup; |
79 | |
80 | /** |
81 | * A HTML select element used to select the current group. |
82 | * @var string $group_selector |
83 | */ |
84 | var $group_selector; |
85 | |
86 | /** |
87 | * An SQL fragment used to add linking information to the group tables. |
88 | * @var string $groupsql |
89 | */ |
90 | var $groupsql; |
91 | |
92 | /** |
93 | * An SQL constraint to append to the queries used by this object to build the report. |
94 | * @var string $groupwheresql |
95 | */ |
96 | var $groupwheresql; |
97 | |
98 | |
eea6690a |
99 | /** |
100 | * Constructor. Sets local copies of user preferences and initialises grade_tree. |
101 | * @param int $courseid |
d30c4481 |
102 | * @param object $gpr grade plugin return tracking object |
eea6690a |
103 | * @param string $context |
104 | * @param int $page The current page being viewed (when report is paged) |
105 | */ |
d30c4481 |
106 | function grade_report($courseid, $gpr, $context, $page=null) { |
eea6690a |
107 | global $CFG; |
108 | |
109 | $this->courseid = $courseid; |
d30c4481 |
110 | $this->gpr = $gpr; |
111 | $this->context = $context; |
112 | $this->page = $page; |
eea6690a |
113 | |
114 | // roles to be displayed in the gradebook |
115 | $this->gradebookroles = $CFG->gradebookroles; |
116 | |
117 | // Grab the grade_tree for this course |
938e00b6 |
118 | $this->gtree = new grade_tree($this->courseid, true, $this->get_pref('aggregationposition')); |
90d3960c |
119 | |
38b9e8a8 |
120 | } |
121 | |
eea6690a |
122 | /** |
123 | * Given the name of a user preference (without grade_report_ prefix), locally saves then returns |
124 | * the value of that preference. If the preference has already been fetched before, |
125 | * the saved value is returned. If the preference is not set at the User level, the $CFG equivalent |
126 | * is given (site default). |
501e0e34 |
127 | * @static (Can be called statically, but then doesn't benefit from caching) |
eea6690a |
128 | * @param string $pref The name of the preference (do not include the grade_report_ prefix) |
8c5a416e |
129 | * @param int $objectid An optional itemid or categoryid to check for a more fine-grained preference |
eea6690a |
130 | * @return mixed The value of the preference |
131 | */ |
8c5a416e |
132 | function get_pref($pref, $objectid=null) { |
eea6690a |
133 | global $CFG; |
501e0e34 |
134 | $fullprefname = 'grade_report_' . $pref; |
38b9e8a8 |
135 | |
e50ce569 |
136 | $retval = null; |
137 | |
438a5aa9 |
138 | if (!isset($this) OR get_class($this) != 'grade_report') { |
8c5a416e |
139 | if (!empty($objectid)) { |
140 | $retval = get_user_preferences($fullprefname . $objectid, grade_report::get_pref($pref)); |
bb384a8e |
141 | } else { |
e50ce569 |
142 | $retval = get_user_preferences($fullprefname, $CFG->$fullprefname); |
bb384a8e |
143 | } |
501e0e34 |
144 | } else { |
8c5a416e |
145 | if (empty($this->prefs[$pref.$objectid])) { |
e50ce569 |
146 | |
8c5a416e |
147 | if (!empty($objectid)) { |
148 | $retval = get_user_preferences($fullprefname . $objectid); |
e50ce569 |
149 | if (empty($retval)) { |
150 | // No item pref found, we are returning the global preference |
151 | $retval = $this->get_pref($pref); |
8c5a416e |
152 | $objectid = null; |
e50ce569 |
153 | } |
501e0e34 |
154 | } else { |
e50ce569 |
155 | $retval = get_user_preferences($fullprefname, $CFG->$fullprefname); |
501e0e34 |
156 | } |
8c5a416e |
157 | $this->prefs[$pref.$objectid] = $retval; |
e50ce569 |
158 | } else { |
8c5a416e |
159 | $retval = $this->prefs[$pref.$objectid]; |
501e0e34 |
160 | } |
eea6690a |
161 | } |
e50ce569 |
162 | |
163 | return $retval; |
eea6690a |
164 | } |
bb384a8e |
165 | |
eea6690a |
166 | /** |
501e0e34 |
167 | * Uses set_user_preferences() to update the value of a user preference. If 'default' is given as the value, |
168 | * the preference will be removed in favour of a higher-level preference. |
169 | * @static |
eea6690a |
170 | * @param string $pref_name The name of the preference. |
171 | * @param mixed $pref_value The value of the preference. |
bb384a8e |
172 | * @param int $itemid An optional itemid to which the preference will be assigned |
eea6690a |
173 | * @return bool Success or failure. |
174 | * TODO print visual feedback |
175 | */ |
501e0e34 |
176 | function set_pref($pref, $pref_value='default', $itemid=null) { |
bb384a8e |
177 | $fullprefname = 'grade_report_' . $pref; |
501e0e34 |
178 | if ($pref_value == 'default') { |
179 | return unset_user_preference($fullprefname.$itemid); |
180 | } else { |
181 | return set_user_preference($fullprefname.$itemid, $pref_value); |
eea6690a |
182 | } |
38b9e8a8 |
183 | } |
38b9e8a8 |
184 | |
eea6690a |
185 | /** |
186 | * Handles form data sent by this report for this report. Abstract method to implement in all children. |
187 | * @abstract |
188 | * @param array $data |
189 | * @return mixed True or array of errors |
190 | */ |
191 | function process_data($data) { |
192 | // Implement in children classes |
193 | } |
38b9e8a8 |
194 | |
eea6690a |
195 | /** |
196 | * Processes a single action against a category, grade_item or grade. |
197 | * @param string $target Sortorder |
198 | * @param string $action Which action to take (edit, delete etc...) |
199 | * @return |
eea6690a |
200 | */ |
201 | function process_action($target, $action) { |
2cc773f5 |
202 | //implement if needed |
eea6690a |
203 | } |
204 | |
205 | /** |
206 | * format grade using lang specific decimal point and thousand separator |
207 | * the result is suitable for printing on html page |
208 | * @static |
209 | * @param float $gradeval raw grade value pulled from db |
e50ce569 |
210 | * @param int $decimalpoints Optional integers to override global decimalpoints preference |
eea6690a |
211 | * @return string $gradeval formatted grade value |
212 | */ |
e50ce569 |
213 | function get_grade_clean($gradeval, $decimalpoints=null) { |
eea6690a |
214 | global $CFG; |
38b9e8a8 |
215 | |
eea6690a |
216 | if (is_null($gradeval)) { |
217 | $gradeval = ''; |
218 | } else { |
219 | // decimal points as specified by user |
d5f0aa01 |
220 | if (is_null($decimalpoints)) { |
e50ce569 |
221 | $decimalpoints = $this->get_pref('decimalpoints'); |
222 | } |
223 | $gradeval = number_format($gradeval, $decimalpoints, $this->get_lang_string('decpoint', 'langconfig'), |
1fdab481 |
224 | $this->get_lang_string('thousandsep', 'langconfig')); |
eea6690a |
225 | } |
226 | |
227 | return $gradeval; |
228 | |
229 | /* |
230 | // commenting this out, if this is added, we also need to find the number of decimal place preserved |
231 | // so it can go into number_format |
232 | if ($gradeval != 0) { |
233 | $gradeval = rtrim(trim($gradeval, "0"), "."); |
234 | } else { |
235 | $gradeval = 0; |
236 | } |
237 | */ |
238 | |
239 | } |
240 | |
241 | /** |
242 | * Given a user input grade, format it to standard format i.e. no thousand separator, and . as decimal point |
243 | * @static |
244 | * @param string $gradeval grade value from user input, language specific format |
245 | * @return string - grade value for storage, en format |
246 | */ |
247 | function format_grade($gradeval) { |
248 | |
388234f4 |
249 | $decimalpt = $this->get_lang_string('decpoint', 'langconfig'); |
250 | $thousandsep = $this->get_lang_string('thousandsep', 'langconfig'); |
eea6690a |
251 | // replace decimal point with '.'; |
252 | $gradeval = str_replace($decimalpt, '.', $gradeval); |
253 | // thousand separator is not useful |
254 | $gradeval = str_replace($thousandsep, '', $gradeval); |
255 | |
256 | return clean_param($gradeval, PARAM_NUMBER); |
257 | } |
38b9e8a8 |
258 | |
388234f4 |
259 | /** |
260 | * First checks the cached language strings, then returns match if found, or uses get_string() |
261 | * to get it from the DB, caches it then returns it. |
262 | * @param string $strcode |
263 | * @param string $section Optional language section |
264 | * @return string |
265 | */ |
266 | function get_lang_string($strcode, $section=null) { |
267 | if (empty($this->lang_strings[$strcode])) { |
268 | $this->lang_strings[$strcode] = get_string($strcode, $section); |
269 | } |
270 | return $this->lang_strings[$strcode]; |
271 | } |
272 | |
bb384a8e |
273 | /** |
274 | * Computes then returns the percentage value of the grade value within the given range. |
275 | * @param float $gradeval |
276 | * @param float $grademin |
277 | * @param float $grademx |
278 | * @return float $percentage |
279 | */ |
280 | function grade_to_percentage($gradeval, $grademin, $grademax) { |
281 | if ($grademin >= $grademax) { |
282 | debugging("The minimum grade ($grademin) was higher than or equal to the maximum grade ($grademax)!!! Cannot proceed with computation."); |
283 | } |
284 | $offset_value = $gradeval - $grademin; |
285 | $offset_max = $grademax - $grademin; |
286 | $factor = 100 / $offset_max; |
287 | $percentage = $offset_value * $factor; |
288 | return $percentage; |
289 | } |
32b97bb2 |
290 | |
291 | /** |
292 | * Fetches and returns an array of grade letters indexed by their grade boundaries, as stored in preferences. |
293 | * @return array |
294 | */ |
295 | function get_grade_letters() { |
296 | $letters = array(); |
297 | for ($i = 1; $i <= 10; $i++) { |
298 | $boundary = grade_report::get_pref('gradeboundary' . $i); |
299 | $letter = grade_report::get_pref('gradeletter' . $i); |
300 | if (!is_null($boundary) && $boundary != -1 && !empty($letter)) { |
301 | $letters[$boundary] = $letter; |
302 | } |
303 | } |
304 | return $letters; |
305 | } |
90d3960c |
306 | |
307 | /** |
308 | * Fetches and returns a count of all the users that will be shown on this page. |
309 | * @return int Count of users |
310 | */ |
311 | function get_numusers() { |
312 | global $CFG; |
313 | |
314 | $countsql = "SELECT COUNT(DISTINCT u.id) |
315 | FROM {$CFG->prefix}grade_grades g RIGHT OUTER JOIN |
316 | {$CFG->prefix}user u ON u.id = g.userid |
317 | LEFT JOIN {$CFG->prefix}role_assignments ra ON u.id = ra.userid |
318 | $this->groupsql |
319 | WHERE ra.roleid in ($this->gradebookroles) |
320 | $this->groupwheresql |
321 | AND ra.contextid ".get_related_contexts_string($this->context); |
322 | return count_records_sql($countsql); |
323 | } |
324 | |
325 | /** |
326 | * Sets up this object's group variables, mainly to restrict the selection of users to display. |
327 | */ |
328 | function setup_groups() { |
329 | global $CFG; |
330 | |
331 | /// find out current groups mode |
332 | $course = get_record('course', 'id', $this->courseid); |
333 | $groupmode = $course->groupmode; |
334 | ob_start(); |
335 | $this->currentgroup = setup_and_print_groups($course, $groupmode, $this->pbarurl); |
336 | $this->group_selector = ob_get_clean(); |
337 | |
338 | // update paging after group |
339 | $this->baseurl .= 'group='.$this->currentgroup.'&'; |
340 | $this->pbarurl .= 'group='.$this->currentgroup.'&'; |
341 | |
342 | if ($this->currentgroup) { |
343 | $this->groupsql = " LEFT JOIN {$CFG->prefix}groups_members gm ON gm.userid = u.id "; |
344 | $this->groupwheresql = " AND gm.groupid = $this->currentgroup "; |
345 | } |
346 | } |
38b9e8a8 |
347 | } |
eea6690a |
348 | ?> |