MDL-10515 - Change HTML to make it easier to style multiple choice questions. Merged...
[moodle.git] / grade / report / lib.php
CommitLineData
eea6690a 1<?php // $Id$
38b9e8a8 2/**
eea6690a 3 * File containing the grade_report class.
4 * @package gradebook
38b9e8a8 5 */
eea6690a 6
7require_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 */
14class 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
eea6690a 72 /**
73 * Constructor. Sets local copies of user preferences and initialises grade_tree.
74 * @param int $courseid
d30c4481 75 * @param object $gpr grade plugin return tracking object
eea6690a 76 * @param string $context
77 * @param int $page The current page being viewed (when report is paged)
78 */
d30c4481 79 function grade_report($courseid, $gpr, $context, $page=null) {
eea6690a 80 global $CFG;
81
82 $this->courseid = $courseid;
d30c4481 83 $this->gpr = $gpr;
84 $this->context = $context;
85 $this->page = $page;
eea6690a 86
87 // roles to be displayed in the gradebook
88 $this->gradebookroles = $CFG->gradebookroles;
89
90 // Grab the grade_tree for this course
938e00b6 91 $this->gtree = new grade_tree($this->courseid, true, $this->get_pref('aggregationposition'));
38b9e8a8 92 }
93
eea6690a 94 /**
95 * Given the name of a user preference (without grade_report_ prefix), locally saves then returns
96 * the value of that preference. If the preference has already been fetched before,
97 * the saved value is returned. If the preference is not set at the User level, the $CFG equivalent
98 * is given (site default).
501e0e34 99 * @static (Can be called statically, but then doesn't benefit from caching)
eea6690a 100 * @param string $pref The name of the preference (do not include the grade_report_ prefix)
bb384a8e 101 * @param int $itemid An optional itemid to check for a more fine-grained preference
eea6690a 102 * @return mixed The value of the preference
103 */
bb384a8e 104 function get_pref($pref, $itemid=null) {
eea6690a 105 global $CFG;
501e0e34 106 $fullprefname = 'grade_report_' . $pref;
38b9e8a8 107
e50ce569 108 $retval = null;
109
501e0e34 110 if (!isset($this)) {
bb384a8e 111 if (!empty($itemid)) {
e50ce569 112 $retval = get_user_preferences($fullprefname . $itemid, grade_report::get_pref($pref));
bb384a8e 113 } else {
e50ce569 114 $retval = get_user_preferences($fullprefname, $CFG->$fullprefname);
bb384a8e 115 }
501e0e34 116 } else {
e50ce569 117 if (empty($this->prefs[$pref.$itemid])) {
118
501e0e34 119 if (!empty($itemid)) {
e50ce569 120 $retval = get_user_preferences($fullprefname . $itemid);
121 if (empty($retval)) {
122 // No item pref found, we are returning the global preference
123 $retval = $this->get_pref($pref);
124 $itemid = null;
125 }
501e0e34 126 } else {
e50ce569 127 $retval = get_user_preferences($fullprefname, $CFG->$fullprefname);
501e0e34 128 }
e50ce569 129 $this->prefs[$pref.$itemid] = $retval;
130 } else {
131 $retval = $this->prefs[$pref.$itemid];
501e0e34 132 }
eea6690a 133 }
e50ce569 134
135 return $retval;
eea6690a 136 }
bb384a8e 137
eea6690a 138 /**
501e0e34 139 * Uses set_user_preferences() to update the value of a user preference. If 'default' is given as the value,
140 * the preference will be removed in favour of a higher-level preference.
141 * @static
eea6690a 142 * @param string $pref_name The name of the preference.
143 * @param mixed $pref_value The value of the preference.
bb384a8e 144 * @param int $itemid An optional itemid to which the preference will be assigned
eea6690a 145 * @return bool Success or failure.
146 * TODO print visual feedback
147 */
501e0e34 148 function set_pref($pref, $pref_value='default', $itemid=null) {
bb384a8e 149 $fullprefname = 'grade_report_' . $pref;
501e0e34 150 if ($pref_value == 'default') {
151 return unset_user_preference($fullprefname.$itemid);
152 } else {
153 return set_user_preference($fullprefname.$itemid, $pref_value);
eea6690a 154 }
38b9e8a8 155 }
38b9e8a8 156
eea6690a 157 /**
158 * Handles form data sent by this report for this report. Abstract method to implement in all children.
159 * @abstract
160 * @param array $data
161 * @return mixed True or array of errors
162 */
163 function process_data($data) {
164 // Implement in children classes
165 }
38b9e8a8 166
eea6690a 167 /**
168 * Processes a single action against a category, grade_item or grade.
169 * @param string $target Sortorder
170 * @param string $action Which action to take (edit, delete etc...)
171 * @return
172 * TODO Update this, it's quite old and needs a major makeover
173 */
174 function process_action($target, $action) {
175 $element = $this->gtree->locate_element($target);
176
177 switch ($action) {
178 case 'edit':
179 break;
180 case 'delete':
181 if ($confirm == 1) { // Perform the deletion
182 //TODO: add proper delete support for grade items and categories
183 //$element['object']->delete();
184 // Print result message
185
186 } else { // Print confirmation dialog
187 $eid = $element['eid'];
388234f4 188 $strdeletecheckfull = $this->get_lang_string('deletecheck', '', $element['object']->get_name());
eea6690a 189 $linkyes = GRADE_EDIT_URL . "/tree.php?target=$eid&amp;action=delete&amp;confirm=1$this->gtree->commonvars";
190 $linkno = GRADE_EDIT_URL . "/tree.php?$this->gtree->commonvars";
191 notice_yesno($strdeletecheckfull, $linkyes, $linkno);
192 }
193 break;
194
195 case 'hide':
196 // TODO Implement calendar for selection of a date to hide element until
197 $element['object']->set_hidden(1);
938e00b6 198 $this->gtree = new grade_tree($this->courseid, true, $this->get_pref('aggregationposition'));
eea6690a 199 break;
200 case 'show':
201 $element['object']->set_hidden(0);
938e00b6 202 $this->gtree = new grade_tree($this->courseid, true, $this->get_pref('aggregationposition'));
eea6690a 203 break;
204 case 'lock':
205 // TODO Implement calendar for selection of a date to lock element after
206 if (!$element['object']->set_locked(1)) {
207 debugging("Could not update the element's locked state!");
208 }
938e00b6 209 $this->gtree = new grade_tree($this->courseid, true, $this->get_pref('aggregationposition'));
eea6690a 210 break;
211 case 'unlock':
212 if (!$element['object']->set_locked(0)) {
213 debugging("Could not update the element's locked state!");
214 }
938e00b6 215 $this->gtree = new grade_tree($this->courseid, true, $this->get_pref('aggregationposition'));
eea6690a 216 break;
217 default:
218 break;
219 }
220 }
221
222 /**
223 * format grade using lang specific decimal point and thousand separator
224 * the result is suitable for printing on html page
225 * @static
226 * @param float $gradeval raw grade value pulled from db
e50ce569 227 * @param int $decimalpoints Optional integers to override global decimalpoints preference
eea6690a 228 * @return string $gradeval formatted grade value
229 */
e50ce569 230 function get_grade_clean($gradeval, $decimalpoints=null) {
eea6690a 231 global $CFG;
38b9e8a8 232
eea6690a 233 if (is_null($gradeval)) {
234 $gradeval = '';
235 } else {
236 // decimal points as specified by user
e50ce569 237 if (empty($decimalpoints)) {
238 $decimalpoints = $this->get_pref('decimalpoints');
239 }
240 $gradeval = number_format($gradeval, $decimalpoints, $this->get_lang_string('decpoint', 'langconfig'),
1fdab481 241 $this->get_lang_string('thousandsep', 'langconfig'));
eea6690a 242 }
243
244 return $gradeval;
245
246 /*
247 // commenting this out, if this is added, we also need to find the number of decimal place preserved
248 // so it can go into number_format
249 if ($gradeval != 0) {
250 $gradeval = rtrim(trim($gradeval, "0"), ".");
251 } else {
252 $gradeval = 0;
253 }
254 */
255
256 }
257
258 /**
259 * Given a user input grade, format it to standard format i.e. no thousand separator, and . as decimal point
260 * @static
261 * @param string $gradeval grade value from user input, language specific format
262 * @return string - grade value for storage, en format
263 */
264 function format_grade($gradeval) {
265
388234f4 266 $decimalpt = $this->get_lang_string('decpoint', 'langconfig');
267 $thousandsep = $this->get_lang_string('thousandsep', 'langconfig');
eea6690a 268 // replace decimal point with '.';
269 $gradeval = str_replace($decimalpt, '.', $gradeval);
270 // thousand separator is not useful
271 $gradeval = str_replace($thousandsep, '', $gradeval);
272
273 return clean_param($gradeval, PARAM_NUMBER);
274 }
38b9e8a8 275
388234f4 276 /**
277 * First checks the cached language strings, then returns match if found, or uses get_string()
278 * to get it from the DB, caches it then returns it.
279 * @param string $strcode
280 * @param string $section Optional language section
281 * @return string
282 */
283 function get_lang_string($strcode, $section=null) {
284 if (empty($this->lang_strings[$strcode])) {
285 $this->lang_strings[$strcode] = get_string($strcode, $section);
286 }
287 return $this->lang_strings[$strcode];
288 }
289
bb384a8e 290 /**
291 * Computes then returns the percentage value of the grade value within the given range.
292 * @param float $gradeval
293 * @param float $grademin
294 * @param float $grademx
295 * @return float $percentage
296 */
297 function grade_to_percentage($gradeval, $grademin, $grademax) {
298 if ($grademin >= $grademax) {
299 debugging("The minimum grade ($grademin) was higher than or equal to the maximum grade ($grademax)!!! Cannot proceed with computation.");
300 }
301 $offset_value = $gradeval - $grademin;
302 $offset_max = $grademax - $grademin;
303 $factor = 100 / $offset_max;
304 $percentage = $offset_value * $factor;
305 return $percentage;
306 }
32b97bb2 307
308 /**
309 * Fetches and returns an array of grade letters indexed by their grade boundaries, as stored in preferences.
310 * @return array
311 */
312 function get_grade_letters() {
313 $letters = array();
314 for ($i = 1; $i <= 10; $i++) {
315 $boundary = grade_report::get_pref('gradeboundary' . $i);
316 $letter = grade_report::get_pref('gradeletter' . $i);
317 if (!is_null($boundary) && $boundary != -1 && !empty($letter)) {
318 $letters[$boundary] = $letter;
319 }
320 }
321 return $letters;
322 }
38b9e8a8 323}
eea6690a 324?>