Add an option $CFG->CSSEdit or $THEME->CSSEdit to Moodle. If one of both is set to...
[moodle.git] / lib / grade / grade_category.php
CommitLineData
8a31e65c 1<?php // $Id$
2
3///////////////////////////////////////////////////////////////////////////
4// //
5// NOTICE OF COPYRIGHT //
6// //
7// Moodle - Modular Object-Oriented Dynamic Learning Environment //
8// http://moodle.com //
9// //
10// Copyright (C) 2001-2003 Martin Dougiamas http://dougiamas.com //
11// //
12// This program is free software; you can redistribute it and/or modify //
13// it under the terms of the GNU General Public License as published by //
14// the Free Software Foundation; either version 2 of the License, or //
15// (at your option) any later version. //
16// //
17// This program is distributed in the hope that it will be useful, //
18// but WITHOUT ANY WARRANTY; without even the implied warranty of //
19// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the //
20// GNU General Public License for more details: //
21// //
22// http://www.gnu.org/copyleft/gpl.html //
23// //
24///////////////////////////////////////////////////////////////////////////
25
26require_once('grade_object.php');
27
3058964f 28class grade_category extends grade_object {
8a31e65c 29 /**
7c8a963f 30 * The DB table.
8a31e65c 31 * @var string $table
32 */
33 var $table = 'grade_categories';
4a490db0 34
8a31e65c 35 /**
36 * Array of class variables that are not part of the DB table fields
37 * @var array $nonfields
38 */
ac9b0805 39 var $nonfields = array('table', 'nonfields', 'children', 'all_children', 'grade_item', 'parent_category');
4a490db0 40
8a31e65c 41 /**
42 * The course this category belongs to.
43 * @var int $courseid
44 */
45 var $courseid;
4a490db0 46
8a31e65c 47 /**
48 * The category this category belongs to (optional).
4a490db0 49 * @var int $parent
8a31e65c 50 */
e5c674f1 51 var $parent;
4a490db0 52
8c846243 53 /**
54 * The grade_category object referenced by $this->parent (PK).
55 * @var object $parent_category
56 */
57 var $parent_category;
27f95e9b 58
88e794d6 59 /**
60 * A grade_category object this category used to belong to before getting updated. Will be deleted shortly.
61 * @var object $old_parent
62 */
63 var $old_parent;
64
e5c674f1 65 /**
66 * The number of parents this category has.
67 * @var int $depth
68 */
69 var $depth = 0;
70
71 /**
72 * Shows the hierarchical path for this category as /1/2/3 (like course_categories), the last number being
73 * this category's autoincrement ID number.
74 * @var string $path
75 */
76 var $path;
77
8a31e65c 78 /**
79 * The name of this category.
80 * @var string $fullname
81 */
82 var $fullname;
4a490db0 83
8a31e65c 84 /**
85 * A constant pointing to one of the predefined aggregation strategies (none, mean, median, sum etc) .
4a490db0 86 * @var int $aggregation
8a31e65c 87 */
88 var $aggregation;
4a490db0 89
8a31e65c 90 /**
91 * Keep only the X highest items.
92 * @var int $keephigh
93 */
94 var $keephigh;
4a490db0 95
8a31e65c 96 /**
97 * Drop the X lowest items.
98 * @var int $droplow
99 */
100 var $droplow;
4a490db0 101
8a31e65c 102 /**
103 * Array of grade_items or grade_categories nested exactly 1 level below this category
104 * @var array $children
105 */
106 var $children;
8a31e65c 107
7c8a963f 108 /**
4a490db0 109 * A hierarchical array of all children below this category. This is stored separately from
7c8a963f 110 * $children because it is more memory-intensive and may not be used as often.
111 * @var array $all_children
112 */
113 var $all_children;
114
f151b073 115 /**
116 * An associated grade_item object, with itemtype=category, used to calculate and cache a set of grade values
117 * for this category.
118 * @var object $grade_item
119 */
120 var $grade_item;
121
e5c674f1 122 /**
123 * Constructor. Extends the basic functionality defined in grade_object.
124 * @param array $params Can also be a standard object.
f151b073 125 * @param boolean $fetch Whether or not to fetch the corresponding row from the DB.
126 * @param object $grade_item The associated grade_item object can be passed during construction.
e5c674f1 127 */
b8ff92b6 128 function grade_category($params=NULL, $fetch=true) {
e5c674f1 129 $this->grade_object($params, $fetch);
2df71235 130 $this->path = grade_category::build_path($this);
e5c674f1 131 }
132
4a490db0 133
e5c674f1 134 /**
135 * Builds this category's path string based on its parents (if any) and its own id number.
136 * This is typically done just before inserting this object in the DB for the first time,
ce385eb4 137 * or when a new parent is added or changed. It is a recursive function: once the calling
138 * object no longer has a parent, the path is complete.
139 *
140 * @static
141 * @param object $grade_category
142 * @return int The depth of this category (2 means there is one parent)
e5c674f1 143 */
ce385eb4 144 function build_path($grade_category) {
145 if (empty($grade_category->parent)) {
146 return "/$grade_category->id";
147 } else {
148 $parent = get_record('grade_categories', 'id', $grade_category->parent);
149 return grade_category::build_path($parent) . "/$grade_category->id";
150 }
e5c674f1 151 }
152
8a31e65c 153
8a31e65c 154 /**
155 * Finds and returns a grade_category object based on 1-3 field values.
156 *
8a31e65c 157 * @param string $field1
158 * @param string $value1
159 * @param string $field2
160 * @param string $value2
161 * @param string $field3
162 * @param string $value3
163 * @param string $fields
164 * @return object grade_category object or false if none found.
165 */
4a490db0 166 function fetch($field1, $value1, $field2='', $value2='', $field3='', $value3='', $fields="*") {
8a31e65c 167 if ($grade_category = get_record('grade_categories', $field1, $value1, $field2, $value2, $field3, $value3, $fields)) {
7c8a963f 168 if (isset($this) && get_class($this) == 'grade_category') {
8a31e65c 169 foreach ($grade_category as $param => $value) {
170 $this->$param = $value;
171 }
172 return $this;
7c8a963f 173 } else {
174 $grade_category = new grade_category($grade_category);
175 return $grade_category;
8a31e65c 176 }
177 } else {
178 return false;
179 }
ce385eb4 180 }
181
8f4a626d 182 /**
2cc4b0f9 183 * In addition to update() as defined in grade_object, call force_regrading of parent categories, if applicable.
8f4a626d 184 */
4a490db0 185 function update() {
2cc4b0f9 186 $qualifies = $this->qualifies_for_regrading();
8f4a626d 187
0fc7f624 188 // Update the grade_item's sortorder if needed
189 if (!empty($this->sortorder)) {
190 $this->load_grade_item();
191 if (!empty($this->grade_item)) {
192 $this->grade_item->sortorder = $this->sortorder;
193 $this->grade_item->update();
194 }
195 unset($this->sortorder);
4a490db0 196 }
0fc7f624 197
8f4a626d 198 $result = parent::update();
4a490db0 199
cb64c6b2 200 // Use $this->path to update all parent categories
8f4a626d 201 if ($result && $qualifies) {
2cc4b0f9 202 $this->force_regrading();
4a490db0 203 }
8f4a626d 204 return $result;
205 }
4a490db0 206
8f4a626d 207 /**
2cc4b0f9 208 * If parent::delete() is successful, send force_regrading message to parent category.
8f4a626d 209 * @return boolean Success or failure.
210 */
211 function delete() {
212 $result = parent::delete();
4a490db0 213
8f4a626d 214 if ($result) {
215 $this->load_parent_category();
216 if (!empty($this->parent_category)) {
2cc4b0f9 217 $result = $result && $this->parent_category->force_regrading();
8f4a626d 218 }
4a490db0 219
220 // Update children's categoryid/parent field
221 global $db;
222 $set_field_result = set_field('grade_items', 'categoryid', null, 'categoryid', $this->id);
223 $set_field_result = set_field('grade_categories', 'parent', null, 'parent', $this->id);
8f4a626d 224 }
225
226 return $result;
227 }
4a490db0 228
ce385eb4 229 /**
230 * In addition to the normal insert() defined in grade_object, this method sets the depth
231 * and path for this object, and update the record accordingly. The reason why this must
232 * be done here instead of in the constructor, is that they both need to know the record's
4a490db0 233 * id number, which only gets created at insertion time.
f151b073 234 * This method also creates an associated grade_item if this wasn't done during construction.
ce385eb4 235 */
236 function insert() {
b8ff92b6 237 if (!parent::insert()) {
238 debugging("Could not insert this category: " . print_r($this, true));
239 return false;
240 }
4a490db0 241
77d2540e 242 $this->path = grade_category::build_path($this);
ce385eb4 243
244 // Build path and depth variables
245 if (!empty($this->parent)) {
ce385eb4 246 $this->depth = $this->get_depth_from_path();
247 } else {
248 $this->depth = 1;
ce385eb4 249 }
4a490db0 250
ce385eb4 251 $this->update();
4a490db0 252
b8ff92b6 253 // initialize grade_item for this category
254 $this->grade_item = $this->get_grade_item();
4a490db0 255
b8ff92b6 256 // Notify parent category of need to update.
257 $this->load_parent_category();
258 if (!empty($this->parent_category)) {
2cc4b0f9 259 if (!$this->parent_category->force_regrading()) {
b8ff92b6 260 debugging("Could not notify parent category of the need to update its final grades.");
6527197b 261 return false;
262 }
f151b073 263 }
4a490db0 264
b8ff92b6 265 return true;
ce385eb4 266 }
4a490db0 267
8f4a626d 268 /**
269 * Compares the values held by this object with those of the matching record in DB, and returns
270 * whether or not these differences are sufficient to justify an update of all parent objects.
271 * This assumes that this object has an id number and a matching record in DB. If not, it will return false.
272 * @return boolean
273 */
2cc4b0f9 274 function qualifies_for_regrading() {
8f4a626d 275 if (empty($this->id)) {
276 return false;
277 }
278
279 $db_item = new grade_category(array('id' => $this->id));
4a490db0 280
8f4a626d 281 $aggregationdiff = $db_item->aggregation != $this->aggregation;
282 $keephighdiff = $db_item->keephigh != $this->keephigh;
283 $droplowdiff = $db_item->droplow != $this->droplow;
284
285 if ($aggregationdiff || $keephighdiff || $droplowdiff) {
286 return true;
287 } else {
288 return false;
289 }
290 }
8c846243 291
292 /**
293 * Sets this category's and its parent's grade_item.needsupdate to true.
294 * This is triggered whenever any change in any lower level may cause grade_finals
295 * for this category to require an update. The flag needs to be propagated up all
296 * levels until it reaches the top category. This is then used to determine whether or not
cb64c6b2 297 * to regenerate the raw and final grades for each category grade_item. This is accomplished
298 * thanks to the path variable, so we don't need to use recursion.
8c846243 299 * @return boolean Success or failure
300 */
2cc4b0f9 301 function force_regrading() {
b8ff92b6 302 if (empty($this->id)) {
303 debugging("Needsupdate requested before insering grade category.");
304 return true;
305 }
306
8c846243 307 $this->load_grade_item();
8f4a626d 308
2e53372c 309 if ($this->grade_item->needsupdate) {
310 // this grade_item (and category) already needs update, no need to set it again here or in parent categories
311 return true;
312 }
313
cb64c6b2 314 $paths = explode('/', $this->path);
4a490db0 315
77d2540e 316 // Remove the first index, which is always empty
317 unset($paths[0]);
4a490db0 318
2e53372c 319 $result = true;
320
77d2540e 321 if (!empty($paths)) {
322 $wheresql = '';
4a490db0 323
77d2540e 324 foreach ($paths as $categoryid) {
325 $wheresql .= "iteminstance = $categoryid OR ";
326 }
327 $wheresql = substr($wheresql, 0, strrpos($wheresql, 'OR'));
a3d55942 328 $grade_items = set_field_select('grade_items', 'needsupdate', '1', $wheresql . ' AND courseid = ' . $this->courseid);
77d2540e 329 $this->grade_item->update_from_db();
2cc4b0f9 330
331 }
332
8c846243 333 return $result;
334 }
335
0aa32279 336 /**
ac9b0805 337 * Generates and saves raw_grades in associated category grade item.
338 * These immediate children must alrady have their own final grades.
339 * The category's aggregation method is used to generate raw grades.
340 *
341 * Please note that category grade is either calculated or aggregated - not both at the same time.
342 *
343 * This method must be used ONLY from grade_item::update_final_grades(),
344 * because the calculation must be done in correct order!
b8ff92b6 345 *
4a490db0 346 * Steps to follow:
ac9b0805 347 * 1. Get final grades from immediate children
2df71235 348 * 3. Aggregate these grades
ac9b0805 349 * 4. Save them in raw grades of associated category grade item
0aa32279 350 */
351 function generate_grades() {
b8ff92b6 352 global $CFG;
4a490db0 353
ac9b0805 354 $this->load_grade_item();
2cc4b0f9 355
356 if ($this->grade_item->is_locked()) {
357 return true; // no need to recalculate locked items
358 }
359
ac9b0805 360 $this->grade_item->load_scale();
2df71235 361
2cc4b0f9 362
ac9b0805 363 // find grde items of immediate children (category or grade items)
364 $dependson = $this->grade_item->dependson();
b8ff92b6 365 $items = array();
4a490db0 366
b8ff92b6 367 foreach($dependson as $dep) {
368 $items[$dep] = grade_item::fetch('id', $dep);
369 }
4a490db0 370
ac9b0805 371 // where to look for final grades - include or grade item too
372 $gis = implode(',', array_merge($dependson, array($this->grade_item->id)));
b8ff92b6 373
ac9b0805 374 $sql = "SELECT g.*
375 FROM {$CFG->prefix}grade_grades g, {$CFG->prefix}grade_items gi
376 WHERE gi.id = g.itemid AND gi.courseid={$this->grade_item->courseid} AND gi.id IN ($gis)
377 ORDER BY g.userid";
b8ff92b6 378
ac9b0805 379 // group the results by userid and aggregate the grades in this group
b8ff92b6 380 if ($rs = get_recordset_sql($sql)) {
381 if ($rs->RecordCount() > 0) {
382 $prevuser = 0;
383 $grades = array();
ac9b0805 384 $final = null;
385 while ($used = rs_fetch_next_record($rs)) {
386 if ($used->userid != $prevuser) {
387 $this->aggregate_grades($prevuser, $items, $grades, $dependson, $final);
388 $prevuser = $used->userid;
b8ff92b6 389 $grades = array();
ac9b0805 390 $final = null;
391 }
392 if ($used->itemid == $this->grade_item->id) {
393 $final = new grade_grades($used, false);
2cc4b0f9 394 $final->grade_item =& $this->grade_item;
b8ff92b6 395 }
ac9b0805 396 $grades[$used->itemid] = $used->finalgrade;
2df71235 397 }
ac9b0805 398 $this->aggregate_grades($prevuser, $items, $grades, $dependson, $final);
b8ff92b6 399 }
400 }
401
b8ff92b6 402 return true;
403 }
404
405 /**
ac9b0805 406 * internal function for category grades aggregation
b8ff92b6 407 */
ac9b0805 408 function aggregate_grades($userid, $items, $grades, $dependson, $final) {
b8ff92b6 409 if (empty($userid)) {
ac9b0805 410 //ignore first run
b8ff92b6 411 return;
412 }
4a490db0 413
ac9b0805 414 // no circular references allowed
415 unset($grades[$this->grade_item->id]);
b8ff92b6 416
2cc4b0f9 417 // insert final grade - it will be needed later anyway
ac9b0805 418 if (empty($final)) {
419 $final = new grade_grades(array('itemid'=>$this->grade_item->id, 'userid'=>$userid), false);
420 $final->insert();
2cc4b0f9 421 $final->grade_item =& $this->grade_item;
422
423 } else if ($final->is_locked()) {
424 // no need to recalculate locked grades
425 return;
ac9b0805 426 }
427
428 // if no grades calculation possible or grading not allowed clear both final and raw
429 if (empty($grades) or empty($items) or ($this->grade_item->gradetype != GRADE_TYPE_VALUE and $this->grade_item->gradetype != GRADE_TYPE_SCALE)) {
430 $final->finalgrade = null;
431 $final->rawgrade = null;
432 $final->update();
b8ff92b6 433 return;
434 }
4a490db0 435
b8ff92b6 436 // normalize the grades first - all will have value 0...1
ac9b0805 437 // ungraded items are not used in aggreagation
b8ff92b6 438 foreach ($grades as $k=>$v) {
439 if (is_null($v)) {
440 // null means no grade
441 unset($grades[$k]);
442 continue;
0aa32279 443 }
ac9b0805 444 $grades[$k] = grade_grades::standardise_score($v, $items[$k]->grademin, $items[$k]->grademax, 0, 1);
0aa32279 445 }
dda0c7e6 446
ac9b0805 447 //limit and sort
b8ff92b6 448 $this->apply_limit_rules($grades);
449 sort($grades, SORT_NUMERIC);
4a490db0 450
ac9b0805 451 // let's see we have still enough grades to do any statisctics
b8ff92b6 452 if (count($grades) == 0) {
ac9b0805 453 // not enough attempts yet
454 if (!is_null($final->finalgrade) or !is_null($final->rawgrade)) {
455 $final->finalgrade = null;
456 $final->rawgrade = null;
457 $final->update();
b8ff92b6 458 }
459 return;
460 }
2df71235 461
b8ff92b6 462 switch ($this->aggregation) {
463 case GRADE_AGGREGATE_MEDIAN: // Middle point value in the set: ignores frequencies
464 $num = count($grades);
465 $halfpoint = intval($num / 2);
466
467 if($num % 2 == 0) {
ac9b0805 468 $rawgrade = ($grades[ceil($halfpoint)] + $grades[floor($halfpoint)]) / 2;
b8ff92b6 469 } else {
ac9b0805 470 $rawgrade = $grades[$halfpoint];
b8ff92b6 471 }
472 break;
ac9b0805 473
b8ff92b6 474 case GRADE_AGGREGATE_MIN:
ac9b0805 475 $rawgrade = reset($grades);
b8ff92b6 476 break;
477
478 case GRADE_AGGREGATE_MAX:
ac9b0805 479 $rawgrade = array_pop($grades);
b8ff92b6 480 break;
481
95affb8a 482 case GRADE_AGGREGATE_MEAN_ALL: // Arithmetic average of all grade items including even NULLs; NULL grade caunted as minimum
483 $num = count($dependson); // you can calculate sum from this one if you multiply it with count($this->dependson() ;-)
b8ff92b6 484 $sum = array_sum($grades);
ac9b0805 485 $rawgrade = $sum / $num;
b8ff92b6 486 break;
487
95affb8a 488 case GRADE_AGGREGATE_MODE: // the most common value, the highest one if multimode
489 $freq = array_count_values($grades);
490 arsort($freq); // sort by frequency keeping keys
491 $top = reset($freq); // highest frequency count
492 $modes = array_keys($freq, $top); // search for all modes (have the same highest count)
493 rsort($modes, SORT_NUMERIC); // get highes mode
ac9b0805 494 $rawgrade = reset($modes);
95affb8a 495
496 case GRADE_AGGREGATE_MEAN_GRADED: // Arithmetic average of all final grades, unfinished are not calculated
ac9b0805 497 default:
b8ff92b6 498 $num = count($grades);
499 $sum = array_sum($grades);
ac9b0805 500 $rawgrade = $sum / $num;
b8ff92b6 501 break;
502 }
503
ac9b0805 504 // recalculate the rawgrade back to requested range
505 $rawgrade = $this->grade_item->adjust_grade($rawgrade, 0, 1);
b8ff92b6 506
ac9b0805 507 // prepare update of new raw grade
508 $final->rawgrade = $rawgrade;
509 $final->finalgrade = null;
510 $final->rawgrademin = $this->grade_item->grademin;
511 $final->rawgrademax = $this->grade_item->grademax;
512 $final->rawscaleid = $this->grade_item->scaleid;
2df71235 513
ac9b0805 514 // TODO - add some checks to prevent updates when not needed
515 $final->update();
0aa32279 516 }
517
adc2f286 518 /**
519 * Given an array of grade values (numerical indices), applies droplow or keephigh
520 * rules to limit the final array.
521 * @param array $grades
522 * @return array Limited grades.
523 */
b8ff92b6 524 function apply_limit_rules(&$grades) {
adc2f286 525 rsort($grades, SORT_NUMERIC);
526 if (!empty($this->droplow)) {
527 for ($i = 0; $i < $this->droplow; $i++) {
528 array_pop($grades);
529 }
4a490db0 530 } elseif (!empty($this->keephigh)) {
adc2f286 531 while (count($grades) > $this->keephigh) {
4a490db0 532 array_pop($grades);
adc2f286 533 }
534 }
0aa32279 535 }
536
0fc7f624 537 /**
538 * Given an array of stdClass children of a certain $object_type, returns a flat or nested
539 * array of these children, ready for appending to a tree built by get_children.
540 * @static
541 * @param array $children
542 * @param string $arraytype
543 * @param string $object_type
544 * @return array
545 */
546 function children_to_array($children, $arraytype='nested', $object_type='grade_item') {
547 $children_array = array();
548
549 foreach ($children as $id => $child) {
550 $child = new $object_type($child, false);
551 if ($arraytype == 'nested') {
552 $children_array[$child->get_sortorder()] = array('object' => $child);
553 } else {
554 $children_array[$child->get_sortorder()] = $child;
555 }
4a490db0 556 }
0fc7f624 557
558 return $children_array;
559 }
560
561 /**
562 * Returns true if this category has any child grade_category or grade_item.
563 * @return int number of direct children, or false if none found.
564 */
565 function has_children() {
566 return count_records('grade_categories', 'parent', $this->id) + count_records('grade_items', 'categoryid', $this->id);
567 }
568
569 /**
4a490db0 570 * Checks whether an existing child exists for this category. If the new child is of a
210611f6 571 * different type, the method will return false (not allowed). Otherwise it will return true.
0fc7f624 572 * @param object $child This must be a complete object, not a stdClass
573 * @return boolean Success or failure
574 */
575 function can_add_child($child) {
576 if ($this->has_children()) {
577 if (get_class($child) != $this->get_childrentype()) {
578 return false;
579 } else {
580 return true;
581 }
582 } else {
583 return true;
584 }
585 }
586
1c307f21 587 /**
588 * Disassociates this category from its category parent(s). The object is then updated in DB.
589 * @return boolean Success or Failure
590 */
591 function divorce_parent() {
4a490db0 592 $this->old_parent = $this->get_parent_category();
1c307f21 593 $this->parent = null;
594 $this->parent_category = null;
595 $this->depth = 1;
596 $this->path = '/' . $this->id;
4a490db0 597 return $this->update();
1c307f21 598 }
599
ce385eb4 600 /**
601 * Looks at a path string (e.g. /2/45/56) and returns the depth level represented by this path (in this example, 3).
602 * If no string is given, it looks at the obect's path and assigns the resulting depth to its $depth variable.
603 * @param string $path
604 * @return int Depth level
605 */
606 function get_depth_from_path($path=NULL) {
607 if (empty($path)) {
608 $path = $this->path;
609 }
610 preg_match_all('/\/([0-9]+)+?/', $path, $matches);
611 $depth = count($matches[0]);
612
613 return $depth;
614 }
7c8a963f 615
616 /**
4a490db0 617 * Fetches and returns all the children categories and/or grade_items belonging to this category.
618 * By default only returns the immediate children (depth=1), but deeper levels can be requested,
a39cac25 619 * as well as all levels (0). The elements are indexed by sort order.
7c8a963f 620 * @param int $depth 1 for immediate children, 0 for all children, and 2+ for specific levels deeper than 1.
621 * @param string $arraytype Either 'nested' or 'flat'. A nested array represents the true hierarchy, but is more difficult to work with.
622 * @return array Array of child objects (grade_category and grade_item).
623 */
624 function get_children($depth=1, $arraytype='nested') {
27f95e9b 625 $children_array = array();
4a490db0 626
27f95e9b 627 // Set up $depth for recursion
628 $newdepth = $depth;
629 if ($depth > 1) {
630 $newdepth--;
631 }
4a490db0 632
27f95e9b 633 $childrentype = $this->get_childrentype();
4a490db0 634
27f95e9b 635 if ($childrentype == 'grade_item') {
f151b073 636 $children = get_records('grade_items', 'categoryid', $this->id);
27f95e9b 637 // No need to proceed with recursion
638 $children_array = $this->children_to_array($children, $arraytype, 'grade_item');
639 $this->children = $this->children_to_array($children, 'flat', 'grade_item');
640 } elseif ($childrentype == 'grade_category') {
641 $children = get_records('grade_categories', 'parent', $this->id, 'id');
4a490db0 642
27f95e9b 643 if ($depth == 1) {
644 $children_array = $this->children_to_array($children, $arraytype, 'grade_category');
645 $this->children = $this->children_to_array($children, 'flat', 'grade_category');
7c8a963f 646 } else {
27f95e9b 647 foreach ($children as $id => $child) {
648 $cat = new grade_category($child, false);
649
650 if ($cat->has_children()) {
651 if ($arraytype == 'nested') {
a39cac25 652 $children_array[$cat->get_sortorder()] = array('object' => $cat, 'children' => $cat->get_children($newdepth, $arraytype));
27f95e9b 653 } else {
a39cac25 654 $children_array[$cat->get_sortorder()] = $cat;
27f95e9b 655 $cat_children = $cat->get_children($newdepth, $arraytype);
656 foreach ($cat_children as $id => $cat_child) {
a39cac25 657 $children_array[$cat_child->get_sortorder()] = new grade_category($cat_child, false);
27f95e9b 658 }
659 }
660 } else {
661 if ($arraytype == 'nested') {
a39cac25 662 $children_array[$cat->get_sortorder()] = array('object' => $cat);
27f95e9b 663 } else {
a39cac25 664 $children_array[$cat->get_sortorder()] = $cat;
27f95e9b 665 }
666 }
7c8a963f 667 }
27f95e9b 668 }
669 } else {
670 return null;
671 }
672
673 return $children_array;
674 }
4a490db0 675
27f95e9b 676 /**
4a490db0 677 * Check the type of the first child of this category, to see whether it is a
27f95e9b 678 * grade_category or a grade_item, and returns that type as a string (get_class).
679 * @return string
680 */
681 function get_childrentype() {
27f95e9b 682 if (empty($this->children)) {
683 $count_item_children = count_records('grade_items', 'categoryid', $this->id);
684 $count_cat_children = count_records('grade_categories', 'parent', $this->id);
4a490db0 685
27f95e9b 686 if ($count_item_children > 0) {
687 return 'grade_item';
688 } elseif ($count_cat_children > 0) {
689 return 'grade_category';
690 } else {
691 return null;
7c8a963f 692 }
7c8a963f 693 }
a15428a2 694 reset($this->children);
695 return get_class(current($this->children));
7c8a963f 696 }
f151b073 697
698 /**
ab53054f 699 * Uses get_grade_item to load or create a grade_item, then saves it as $this->grade_item.
f151b073 700 * @return object Grade_item
701 */
702 function load_grade_item() {
ac9b0805 703 if (empty($this->grade_item)) {
704 $this->grade_item = $this->get_grade_item();
705 }
ab53054f 706 return $this->grade_item;
707 }
4a490db0 708
ab53054f 709 /**
710 * Retrieves from DB and instantiates the associated grade_item object.
711 * If no grade_item exists yet, create one.
712 * @return object Grade_item
713 */
714 function get_grade_item() {
c91ed4be 715 if (empty($this->id)) {
716 debugging("Attempt to obtain a grade_category's associated grade_item without the category's ID being set.");
717 return false;
718 }
719
b8ff92b6 720 $grade_item = new grade_item(array('courseid'=>$this->courseid, 'itemtype'=>'category', 'iteminstance'=>$this->id), false);
721 if (!$grade_items = $grade_item->fetch_all_using_this()) {
722 // create a new one
723 $grade_item->gradetype = GRADE_TYPE_VALUE;
724 $grade_item->insert();
4a490db0 725
b8ff92b6 726 } else if (count($grade_items) == 1){
727 // found existing one
728 $grade_item = reset($grade_items);
4a490db0 729
b8ff92b6 730 } else {
731 debugging("Found more than one grade_item attached to category id:".$this->id);
ac9b0805 732 // return first one
733 $grade_item = reset($grade_items);
2c72af1f 734 }
735
ab53054f 736 return $grade_item;
f151b073 737 }
8c846243 738
739 /**
740 * Uses $this->parent to instantiate $this->parent_category based on the
741 * referenced record in the DB.
742 * @return object Parent_category
743 */
744 function load_parent_category() {
745 if (empty($this->parent_category) && !empty($this->parent)) {
ab53054f 746 $this->parent_category = $this->get_parent_category();
8c846243 747 }
748 return $this->parent_category;
4a490db0 749 }
750
ab53054f 751 /**
752 * Uses $this->parent to instantiate and return a grade_category object.
753 * @return object Parent_category
754 */
755 function get_parent_category() {
756 if (!empty($this->parent)) {
757 $parent_category = new grade_category(array('id' => $this->parent));
4a490db0 758 return $parent_category;
ab53054f 759 } else {
760 return null;
761 }
762 }
763
03f01edd 764 /**
c91ed4be 765 * Sets this category as the parent for the given children. If the category's courseid isn't set, it uses that of the children items.
03f01edd 766 * A number of constraints are necessary:
767 * - The children must all be of the same type and at the same level
03f01edd 768 * - The children cannot already be top categories
c91ed4be 769 * - The children all belong to the same course
03f01edd 770 * @param array $children An array of fully instantiated grade_category OR grade_item objects
ffa6e8d3 771 *
03f01edd 772 * @return boolean Success or Failure
ffa6e8d3 773 * @TODO big problem of performance
03f01edd 774 */
775 function set_as_parent($children) {
776 global $CFG;
777
210611f6 778 if (empty($children) || !is_array($children)) {
779 debugging("Passed an empty or non-array variable to grade_category::set_as_parent()");
780 return false;
781 }
782
03f01edd 783 // Check type and sortorder of first child
784 $first_child = current($children);
785 $first_child_type = get_class($first_child);
9f9afbdb 786
787 // If this->courseid is not set, set it to the first child's courseid
788 if (empty($this->courseid)) {
789 $this->courseid = $first_child->courseid;
790 }
791
792 $grade_tree = new grade_tree();
03f01edd 793
794 foreach ($children as $child) {
795 if (get_class($child) != $first_child_type) {
796 debugging("Violated constraint: Attempted to set a category as a parent over children of 2 different types.");
797 return false;
798 }
4a490db0 799
526e1a8a 800 if ($grade_tree->get_element_type($child) == 'topcat') {
03f01edd 801 debugging("Violated constraint: Attempted to set a category over children which are already top categories.");
802 return false;
803 }
4a490db0 804
9f9afbdb 805 if ($first_child_type == 'grade_category' or $first_child_type == 'grade_item') {
03f01edd 806 if (!empty($child->parent)) {
807 debugging("Violated constraint: Attempted to set a category over children that already have a top category.");
4a490db0 808 return false;
03f01edd 809 }
810 } else {
811 debugging("Attempted to set a category over children that are neither grade_items nor grade_categories.");
812 return false;
4a490db0 813 }
c91ed4be 814
9f9afbdb 815 if ($child->courseid != $this->courseid) {
c91ed4be 816 debugging("Attempted to set a category over children which do not belong to the same course.");
817 return false;
818 }
4a490db0 819 }
03f01edd 820
821 // We passed all the checks, time to set the category as a parent.
822 foreach ($children as $child) {
1c307f21 823 $child->divorce_parent();
824 $child->set_parent_id($this->id);
825 if (!$child->update()) {
826 debugging("Could not set this category as a parent for one of its children, DB operation failed.");
827 return false;
4a490db0 828 }
03f01edd 829 }
830
831 // TODO Assign correct sortorders to the newly assigned children and parent. Simply add 1 to all of them!
832 $this->load_grade_item();
833 $this->grade_item->sortorder = $first_child->get_sortorder();
4a490db0 834
03f01edd 835 if (!$this->update()) {
836 debugging("Could not update this category's sortorder in DB.");
837 return false;
838 }
4a490db0 839
750b0550 840 $query = "UPDATE {$CFG->prefix}grade_items SET sortorder = sortorder + 1 WHERE sortorder >= {$this->grade_item->sortorder}";
ffa6e8d3 841 $query .= " AND courseid = $this->courseid";
842
03f01edd 843 if (!execute_sql($query)) {
844 debugging("Could not update the sortorder of grade_items listed after this category.");
750b0550 845 return false;
03f01edd 846 } else {
847 return true;
848 }
849 }
2186f72c 850
851 /**
4a490db0 852 * Returns the most descriptive field for this object. This is a standard method used
2186f72c 853 * when we do not know the exact type of an object.
854 * @return string name
855 */
856 function get_name() {
857 return $this->fullname;
858 }
c91ed4be 859
860 /**
861 * Returns this category's grade_item's id. This is specified for cases where we do not
862 * know an object's type, and want to get either an item's id or a category's item's id.
863 *
864 * @return int
865 */
866 function get_item_id() {
867 $this->load_grade_item();
868 return $this->grade_item->id;
869 }
0fc7f624 870
871 /**
872 * Returns this category's parent id. A generic method shared by objects that have a parent id of some kind.
873 * @return id $parentid
874 */
875 function get_parent_id() {
876 return $this->parent;
877 }
878
879 /**
880 * Sets this category's parent id. A generic method shared by objects that have a parent id of some kind.
881 * @param id $parentid
882 */
883 function set_parent_id($parentid) {
884 $this->parent = $parentid;
88e794d6 885 $this->path = grade_category::build_path($this);
886 $this->depth = $this->get_depth_from_path();
0fc7f624 887 }
4a490db0 888
0fc7f624 889 /**
4a490db0 890 * Returns the sortorder of the associated grade_item. This method is also available in
5fad5061 891 * grade_item, for cases where the object type is not known.
0fc7f624 892 * @return int Sort order
893 */
894 function get_sortorder() {
895 if (empty($this->sortorder)) {
896 $this->load_grade_item();
897 if (!empty($this->grade_item)) {
898 return $this->grade_item->sortorder;
899 }
900 } else {
901 return $this->sortorder;
902 }
903 }
904
905 /**
4a490db0 906 * Sets a temporary sortorder variable for this category. It is used in the update() method to update the grade_item.
907 * This method is also available in grade_item, for cases where the object type is not know.
0fc7f624 908 * @param int $sortorder
909 * @return void
910 */
911 function set_sortorder($sortorder) {
912 $this->sortorder = $sortorder;
913 }
4a490db0 914
5fad5061 915 /**
4a490db0 916 * Returns the locked state/date of the associated grade_item. This method is also available in
917 * grade_item, for cases where the object type is not known.
5fad5061 918 * @return int 0, 1 or timestamp int(10)
919 */
2cc4b0f9 920 function is_locked() {
5fad5061 921 $this->load_grade_item();
922 if (!empty($this->grade_item)) {
2cc4b0f9 923 return $this->grade_item->is_locked();
5fad5061 924 } else {
925 return false;
926 }
927 }
928
929 /**
930 * Sets the grade_item's locked variable and updates the grade_item.
931 * Method named after grade_item::set_locked().
932 * @param int $locked 0, 1 or a timestamp int(10) after which date the item will be locked.
2cc4b0f9 933 * @return boolean success
5fad5061 934 */
2cc4b0f9 935 function set_locked($lockedstate) {
5fad5061 936 $this->load_grade_item();
2cc4b0f9 937
5fad5061 938 if (!empty($this->grade_item)) {
2cc4b0f9 939 return $this->grade_item->set_locked($lockedstate);
940
5fad5061 941 } else {
942 return false;
943 }
944 }
4a490db0 945
5fad5061 946 /**
4a490db0 947 * Returns the hidden state/date of the associated grade_item. This method is also available in
948 * grade_item, for cases where the object type is not known.
5fad5061 949 * @return int 0, 1 or timestamp int(10)
950 */
951 function get_hidden() {
952 $this->load_grade_item();
953 if (!empty($this->grade_item)) {
954 return $this->grade_item->hidden;
955 } else {
956 return false;
957 }
958 }
959
960 /**
4a490db0 961 * Sets the grade_item's hidden variable and updates the grade_item.
5fad5061 962 * Method named after grade_item::set_hidden().
963 * @param int $hidden 0, 1 or a timestamp int(10) after which date the item will be hidden.
964 * @return void
965 */
966 function set_hidden($hidden) {
967 $this->load_grade_item();
968 if (!empty($this->grade_item)) {
969 $this->grade_item->hidden = $hidden;
970 return $this->grade_item->update();
971 } else {
972 return false;
973 }
974 }
975
4a490db0 976 /**
88e794d6 977 * If the old parent is set (after an update), this checks and returns whether it has any children. Important for
978 * deleting childless categories.
979 * @return boolean
980 */
981 function is_old_parent_childless() {
982 if (!empty($this->old_parent)) {
983 return !$this->old_parent->has_children();
984 } else {
985 return false;
986 }
4a490db0 987 }
988}
8a31e65c 989?>