Fixed a typo added during last update
[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 */
7c8a963f 39 var $nonfields = array('table', 'nonfields', 'children', 'all_children');
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 */
f151b073 128 function grade_category($params=NULL, $fetch=true, $grade_item=NULL) {
e5c674f1 129 $this->grade_object($params, $fetch);
f151b073 130 if (!empty($grade_item) && $grade_item->itemtype == 'category') {
131 $this->grade_item = $grade_item;
132 if (empty($this->grade_item->iteminstance)) {
133 $this->grade_item->iteminstance = $this->id;
134 $this->grade_item->update();
135 }
136 }
2df71235 137
138 $this->path = grade_category::build_path($this);
e5c674f1 139 }
140
4a490db0 141
e5c674f1 142 /**
143 * Builds this category's path string based on its parents (if any) and its own id number.
144 * This is typically done just before inserting this object in the DB for the first time,
ce385eb4 145 * or when a new parent is added or changed. It is a recursive function: once the calling
146 * object no longer has a parent, the path is complete.
147 *
148 * @static
149 * @param object $grade_category
150 * @return int The depth of this category (2 means there is one parent)
e5c674f1 151 */
ce385eb4 152 function build_path($grade_category) {
153 if (empty($grade_category->parent)) {
154 return "/$grade_category->id";
155 } else {
156 $parent = get_record('grade_categories', 'id', $grade_category->parent);
157 return grade_category::build_path($parent) . "/$grade_category->id";
158 }
e5c674f1 159 }
160
8a31e65c 161
8a31e65c 162 /**
163 * Finds and returns a grade_category object based on 1-3 field values.
164 *
8a31e65c 165 * @param string $field1
166 * @param string $value1
167 * @param string $field2
168 * @param string $value2
169 * @param string $field3
170 * @param string $value3
171 * @param string $fields
172 * @return object grade_category object or false if none found.
173 */
4a490db0 174 function fetch($field1, $value1, $field2='', $value2='', $field3='', $value3='', $fields="*") {
8a31e65c 175 if ($grade_category = get_record('grade_categories', $field1, $value1, $field2, $value2, $field3, $value3, $fields)) {
7c8a963f 176 if (isset($this) && get_class($this) == 'grade_category') {
8a31e65c 177 foreach ($grade_category as $param => $value) {
178 $this->$param = $value;
179 }
180 return $this;
7c8a963f 181 } else {
182 $grade_category = new grade_category($grade_category);
183 return $grade_category;
8a31e65c 184 }
185 } else {
186 return false;
187 }
ce385eb4 188 }
189
8f4a626d 190 /**
191 * In addition to update() as defined in grade_object, call flag_for_update of parent categories, if applicable.
192 */
4a490db0 193 function update() {
8f4a626d 194 $qualifies = $this->qualifies_for_update();
195
0fc7f624 196 // Update the grade_item's sortorder if needed
197 if (!empty($this->sortorder)) {
198 $this->load_grade_item();
199 if (!empty($this->grade_item)) {
200 $this->grade_item->sortorder = $this->sortorder;
201 $this->grade_item->update();
202 }
203 unset($this->sortorder);
4a490db0 204 }
0fc7f624 205
8f4a626d 206 $result = parent::update();
4a490db0 207
cb64c6b2 208 // Use $this->path to update all parent categories
8f4a626d 209 if ($result && $qualifies) {
cb64c6b2 210 $this->flag_for_update();
4a490db0 211 }
8f4a626d 212 return $result;
213 }
4a490db0 214
8f4a626d 215 /**
216 * If parent::delete() is successful, send flag_for_update message to parent category.
217 * @return boolean Success or failure.
218 */
219 function delete() {
220 $result = parent::delete();
4a490db0 221
8f4a626d 222 if ($result) {
223 $this->load_parent_category();
224 if (!empty($this->parent_category)) {
225 $result = $result && $this->parent_category->flag_for_update();
226 }
4a490db0 227
228 // Update children's categoryid/parent field
229 global $db;
230 $set_field_result = set_field('grade_items', 'categoryid', null, 'categoryid', $this->id);
231 $set_field_result = set_field('grade_categories', 'parent', null, 'parent', $this->id);
8f4a626d 232 }
233
234 return $result;
235 }
4a490db0 236
ce385eb4 237 /**
238 * In addition to the normal insert() defined in grade_object, this method sets the depth
239 * and path for this object, and update the record accordingly. The reason why this must
240 * be done here instead of in the constructor, is that they both need to know the record's
4a490db0 241 * id number, which only gets created at insertion time.
f151b073 242 * This method also creates an associated grade_item if this wasn't done during construction.
ce385eb4 243 */
244 function insert() {
245 $result = parent::insert();
4a490db0 246
77d2540e 247 $this->path = grade_category::build_path($this);
ce385eb4 248
249 // Build path and depth variables
250 if (!empty($this->parent)) {
ce385eb4 251 $this->depth = $this->get_depth_from_path();
252 } else {
253 $this->depth = 1;
ce385eb4 254 }
4a490db0 255
ce385eb4 256 $this->update();
4a490db0 257
f151b073 258 if (empty($this->grade_item)) {
259 $grade_item = new grade_item();
260 $grade_item->iteminstance = $this->id;
261 $grade_item->itemtype = 'category';
4a490db0 262
6527197b 263 if (!$grade_item->insert()) {
a39cac25 264 debugging("Could not insert this grade_item in the database: " . print_r($grade_item, true));
6527197b 265 return false;
266 }
4a490db0 267
f151b073 268 $this->grade_item = $grade_item;
269 }
4a490db0 270
8f4a626d 271 // Notify parent category of need to update.
272 if ($result) {
273 $this->load_parent_category();
274 if (!empty($this->parent_category)) {
275 if (!$this->parent_category->flag_for_update()) {
a39cac25 276 debugging("Could not notify parent category of the need to update its final grades.");
8f4a626d 277 return false;
278 }
279 }
4a490db0 280 }
ce385eb4 281 return $result;
282 }
4a490db0 283
8f4a626d 284 /**
285 * Compares the values held by this object with those of the matching record in DB, and returns
286 * whether or not these differences are sufficient to justify an update of all parent objects.
287 * This assumes that this object has an id number and a matching record in DB. If not, it will return false.
288 * @return boolean
289 */
290 function qualifies_for_update() {
291 if (empty($this->id)) {
292 return false;
293 }
294
295 $db_item = new grade_category(array('id' => $this->id));
4a490db0 296
8f4a626d 297 $aggregationdiff = $db_item->aggregation != $this->aggregation;
298 $keephighdiff = $db_item->keephigh != $this->keephigh;
299 $droplowdiff = $db_item->droplow != $this->droplow;
300
301 if ($aggregationdiff || $keephighdiff || $droplowdiff) {
302 return true;
303 } else {
304 return false;
305 }
306 }
8c846243 307
308 /**
309 * Sets this category's and its parent's grade_item.needsupdate to true.
310 * This is triggered whenever any change in any lower level may cause grade_finals
311 * for this category to require an update. The flag needs to be propagated up all
312 * levels until it reaches the top category. This is then used to determine whether or not
cb64c6b2 313 * to regenerate the raw and final grades for each category grade_item. This is accomplished
314 * thanks to the path variable, so we don't need to use recursion.
8c846243 315 * @return boolean Success or failure
316 */
317 function flag_for_update() {
318 $result = true;
4a490db0 319
8c846243 320 $this->load_grade_item();
8f4a626d 321
322 if (empty($this->grade_item)) {
4a490db0 323 die("Associated grade_item object does not exist for this grade_category!" . print_object($this));
77d2540e 324 // TODO Send error message, this is a critical error: each category MUST have a matching grade_item object and load_grade_item() is supposed to create one!
8f4a626d 325 }
8f4a626d 326
cb64c6b2 327 $paths = explode('/', $this->path);
4a490db0 328
77d2540e 329 // Remove the first index, which is always empty
330 unset($paths[0]);
4a490db0 331
77d2540e 332 if (!empty($paths)) {
333 $wheresql = '';
4a490db0 334
77d2540e 335 foreach ($paths as $categoryid) {
336 $wheresql .= "iteminstance = $categoryid OR ";
337 }
338 $wheresql = substr($wheresql, 0, strrpos($wheresql, 'OR'));
a3d55942 339 $grade_items = set_field_select('grade_items', 'needsupdate', '1', $wheresql . ' AND courseid = ' . $this->courseid);
77d2540e 340 $this->grade_item->update_from_db();
8c846243 341 }
8c846243 342 return $result;
343 }
344
0aa32279 345 /**
4a490db0 346 * Generates and saves raw_grades, based on this category's immediate children, then uses the
0aa32279 347 * associated grade_item to generate matching final grades. These immediate children must first have their own
348 * raw and final grades, which means that ultimately we must get grade_items as children. The category's aggregation
349 * method is used to generate these raw grades, which can then be used by the category's associated grade_item
350 * to apply calculations to and generate final grades.
4a490db0 351 * Steps to follow:
2df71235 352 * 1. If the children are categories, AND their grade_item's needsupdate is true call generate_grades() on each of them (recursion)
353 * 2. Get final grades from immediate children (if the children are categories, get the final grades from their grade_item)
354 * 3. Aggregate these grades
355 * 4. Save them under $this->grade_item->grade_grades_raw
356 * 5. Use the grade_item's methods for generating the final grades.
0aa32279 357 */
358 function generate_grades() {
2df71235 359 // 1. Get immediate children
360 $children = $this->get_children(1, 'flat');
4a490db0 361
2df71235 362 if (empty($children)) {
a39cac25 363 debugging("Could not generate grades for this category, it has no children.");
2df71235 364 return false;
0aa32279 365 }
2df71235 366
367 // This assumes that all immediate children are of the same type (category OR item)
368 $childrentype = get_class(current($children));
4a490db0 369
2df71235 370 $final_grades_for_aggregation = array();
4a490db0 371
2df71235 372 // 2. Get final grades from immediate children, after generating them if needed.
373 // NOTE: Make sure that the arrays of final grades are indexed by userid. The resulting arrays are unlikely to match in sizes.
374 if ($childrentype == 'grade_category') {
375 foreach ($children as $id => $category) {
376 $category->load_grade_item();
4a490db0 377
2df71235 378 if ($category->grade_item->needsupdate) {
379 $category->generate_grades();
380 }
4a490db0 381
2df71235 382 $final_grades_for_aggregation[] = $category->grade_item->get_standardised_final();
2c72af1f 383 }
2df71235 384 } elseif ($childrentype == 'grade_item') {
385 foreach ($children as $id => $item) {
386 if ($item->needsupdate) {
387 $item->generate_final();
388 }
4a490db0 389
2df71235 390 $final_grades_for_aggregation[] = $item->get_standardised_final();
0aa32279 391 }
0aa32279 392 }
dda0c7e6 393
2df71235 394 // 3. Aggregate the grades
395 $aggregated_grades = $this->aggregate_grades($final_grades_for_aggregation);
4a490db0 396
2df71235 397 // 4. Save the resulting array of grades as raw grades
398 $this->load_grade_item();
399 $this->grade_item->save_raw($aggregated_grades);
400
401 // 5. Use the grade_item's generate_final method
402 $this->grade_item->generate_final();
403
404 return true;
0aa32279 405 }
406
adc2f286 407 /**
408 * Given an array of grade values (numerical indices), applies droplow or keephigh
409 * rules to limit the final array.
410 * @param array $grades
411 * @return array Limited grades.
412 */
413 function apply_limit_rules($grades) {
414 rsort($grades, SORT_NUMERIC);
415 if (!empty($this->droplow)) {
416 for ($i = 0; $i < $this->droplow; $i++) {
417 array_pop($grades);
418 }
4a490db0 419 } elseif (!empty($this->keephigh)) {
adc2f286 420 while (count($grades) > $this->keephigh) {
4a490db0 421 array_pop($grades);
adc2f286 422 }
423 }
424 sort($grades, SORT_NUMERIC);
425 return $grades;
426 }
427
0aa32279 428 /**
4a490db0 429 * Given an array of arrays of values, standardised from 0 to 1 and indexed by userid,
430 * uses this category's aggregation method to
431 * compute and return a single array of grade_raw objects with the aggregated gradevalue.
0aa32279 432 * @param array $raw_grade_sets
433 * @return array Raw grade objects
434 */
2df71235 435 function aggregate_grades($final_grade_sets) {
436 if (empty($final_grade_sets)) {
a39cac25 437 debugging("Could not aggregate grades: no array of grades given to aggregate.");
2c72af1f 438 return null;
439 }
4a490db0 440
2c72af1f 441 $aggregated_grades = array();
442 $pooled_grades = array();
443
2df71235 444 foreach ($final_grade_sets as $setkey => $set) {
445 foreach ($set as $userid => $final_grade) {
2c72af1f 446 $this->load_grade_item();
2df71235 447 $value = standardise_score((float) $final_grade, 0, 1, $this->grade_item->grademin, $this->grade_item->grademax);
ab53054f 448 $pooled_grades[$userid][] = (string) $value;
2c72af1f 449 }
450 }
096858ff 451
2c72af1f 452 foreach ($pooled_grades as $userid => $grades) {
453 $aggregated_value = null;
4a490db0 454
adc2f286 455 $grades = $this->apply_limit_rules($grades);
4a490db0 456
ab53054f 457 if (count($grades) > 1) {
458
459 switch ($this->aggregation) {
460 case GRADE_AGGREGATE_MEAN : // Arithmetic average
461 $num = count($grades);
462 $sum = array_sum($grades);
463 $aggregated_value = $sum / $num;
464 break;
465 case GRADE_AGGREGATE_MEDIAN : // Middle point value in the set: ignores frequencies
466 sort($grades);
467 $num = count($grades);
468 $halfpoint = intval($num / 2);
4a490db0 469
470 if($num % 2 == 0) {
471 $aggregated_value = ($grades[ceil($halfpoint)] + $grades[floor($halfpoint)]) / 2;
472 } else {
473 $aggregated_value = $grades[$halfpoint];
ab53054f 474 }
475
476 break;
477 case GRADE_AGGREGATE_MODE : // Value that occurs most frequently. Not always useful (all values are likely to be different)
478 // TODO implement or reject
479 break;
480 case GRADE_AGGREGATE_SUM : // I don't see much point to this one either
481 $aggregated_value = array_sum($grades);
482 break;
483 default:
484 $num = count($grades);
485 $sum = array_sum($grades);
4a490db0 486 $aggregated_value = $sum / $num;
ab53054f 487 break;
488 }
489 } elseif (count($grades) == 1) {
490 $aggregated_value = $grades[0];
491 } else {
492 // TODO what happens if the droplow and keephigh rules have deleted all grades?
493 $aggregated_value = 0;
494 }
4a490db0 495
2c72af1f 496 $grade_raw = new grade_grades_raw();
4a490db0 497
2c72af1f 498 $grade_raw->userid = $userid;
499 $grade_raw->gradevalue = $aggregated_value;
500 $grade_raw->grademin = $this->grade_item->grademin;
501 $grade_raw->grademax = $this->grade_item->grademax;
502 $grade_raw->itemid = $this->grade_item->id;
503 $aggregated_grades[$userid] = $grade_raw;
504 }
4a490db0 505
2c72af1f 506 return $aggregated_grades;
0aa32279 507 }
508
0fc7f624 509 /**
510 * Given an array of stdClass children of a certain $object_type, returns a flat or nested
511 * array of these children, ready for appending to a tree built by get_children.
512 * @static
513 * @param array $children
514 * @param string $arraytype
515 * @param string $object_type
516 * @return array
517 */
518 function children_to_array($children, $arraytype='nested', $object_type='grade_item') {
519 $children_array = array();
520
521 foreach ($children as $id => $child) {
522 $child = new $object_type($child, false);
523 if ($arraytype == 'nested') {
524 $children_array[$child->get_sortorder()] = array('object' => $child);
525 } else {
526 $children_array[$child->get_sortorder()] = $child;
527 }
4a490db0 528 }
0fc7f624 529
530 return $children_array;
531 }
532
533 /**
534 * Returns true if this category has any child grade_category or grade_item.
535 * @return int number of direct children, or false if none found.
536 */
537 function has_children() {
538 return count_records('grade_categories', 'parent', $this->id) + count_records('grade_items', 'categoryid', $this->id);
539 }
540
541 /**
4a490db0 542 * Checks whether an existing child exists for this category. If the new child is of a
210611f6 543 * different type, the method will return false (not allowed). Otherwise it will return true.
0fc7f624 544 * @param object $child This must be a complete object, not a stdClass
545 * @return boolean Success or failure
546 */
547 function can_add_child($child) {
548 if ($this->has_children()) {
549 if (get_class($child) != $this->get_childrentype()) {
550 return false;
551 } else {
552 return true;
553 }
554 } else {
555 return true;
556 }
557 }
558
1c307f21 559 /**
560 * Disassociates this category from its category parent(s). The object is then updated in DB.
561 * @return boolean Success or Failure
562 */
563 function divorce_parent() {
4a490db0 564 $this->old_parent = $this->get_parent_category();
1c307f21 565 $this->parent = null;
566 $this->parent_category = null;
567 $this->depth = 1;
568 $this->path = '/' . $this->id;
4a490db0 569 return $this->update();
1c307f21 570 }
571
ce385eb4 572 /**
573 * Looks at a path string (e.g. /2/45/56) and returns the depth level represented by this path (in this example, 3).
574 * If no string is given, it looks at the obect's path and assigns the resulting depth to its $depth variable.
575 * @param string $path
576 * @return int Depth level
577 */
578 function get_depth_from_path($path=NULL) {
579 if (empty($path)) {
580 $path = $this->path;
581 }
582 preg_match_all('/\/([0-9]+)+?/', $path, $matches);
583 $depth = count($matches[0]);
584
585 return $depth;
586 }
7c8a963f 587
588 /**
4a490db0 589 * Fetches and returns all the children categories and/or grade_items belonging to this category.
590 * By default only returns the immediate children (depth=1), but deeper levels can be requested,
a39cac25 591 * as well as all levels (0). The elements are indexed by sort order.
7c8a963f 592 * @param int $depth 1 for immediate children, 0 for all children, and 2+ for specific levels deeper than 1.
593 * @param string $arraytype Either 'nested' or 'flat'. A nested array represents the true hierarchy, but is more difficult to work with.
594 * @return array Array of child objects (grade_category and grade_item).
595 */
596 function get_children($depth=1, $arraytype='nested') {
27f95e9b 597 $children_array = array();
4a490db0 598
27f95e9b 599 // Set up $depth for recursion
600 $newdepth = $depth;
601 if ($depth > 1) {
602 $newdepth--;
603 }
4a490db0 604
27f95e9b 605 $childrentype = $this->get_childrentype();
4a490db0 606
27f95e9b 607 if ($childrentype == 'grade_item') {
f151b073 608 $children = get_records('grade_items', 'categoryid', $this->id);
27f95e9b 609 // No need to proceed with recursion
610 $children_array = $this->children_to_array($children, $arraytype, 'grade_item');
611 $this->children = $this->children_to_array($children, 'flat', 'grade_item');
612 } elseif ($childrentype == 'grade_category') {
613 $children = get_records('grade_categories', 'parent', $this->id, 'id');
4a490db0 614
27f95e9b 615 if ($depth == 1) {
616 $children_array = $this->children_to_array($children, $arraytype, 'grade_category');
617 $this->children = $this->children_to_array($children, 'flat', 'grade_category');
7c8a963f 618 } else {
27f95e9b 619 foreach ($children as $id => $child) {
620 $cat = new grade_category($child, false);
621
622 if ($cat->has_children()) {
623 if ($arraytype == 'nested') {
a39cac25 624 $children_array[$cat->get_sortorder()] = array('object' => $cat, 'children' => $cat->get_children($newdepth, $arraytype));
27f95e9b 625 } else {
a39cac25 626 $children_array[$cat->get_sortorder()] = $cat;
27f95e9b 627 $cat_children = $cat->get_children($newdepth, $arraytype);
628 foreach ($cat_children as $id => $cat_child) {
a39cac25 629 $children_array[$cat_child->get_sortorder()] = new grade_category($cat_child, false);
27f95e9b 630 }
631 }
632 } else {
633 if ($arraytype == 'nested') {
a39cac25 634 $children_array[$cat->get_sortorder()] = array('object' => $cat);
27f95e9b 635 } else {
a39cac25 636 $children_array[$cat->get_sortorder()] = $cat;
27f95e9b 637 }
638 }
7c8a963f 639 }
27f95e9b 640 }
641 } else {
642 return null;
643 }
644
645 return $children_array;
646 }
4a490db0 647
27f95e9b 648 /**
4a490db0 649 * Check the type of the first child of this category, to see whether it is a
27f95e9b 650 * grade_category or a grade_item, and returns that type as a string (get_class).
651 * @return string
652 */
653 function get_childrentype() {
27f95e9b 654 if (empty($this->children)) {
655 $count_item_children = count_records('grade_items', 'categoryid', $this->id);
656 $count_cat_children = count_records('grade_categories', 'parent', $this->id);
4a490db0 657
27f95e9b 658 if ($count_item_children > 0) {
659 return 'grade_item';
660 } elseif ($count_cat_children > 0) {
661 return 'grade_category';
662 } else {
663 return null;
7c8a963f 664 }
7c8a963f 665 }
a15428a2 666 reset($this->children);
667 return get_class(current($this->children));
7c8a963f 668 }
f151b073 669
670 /**
ab53054f 671 * Uses get_grade_item to load or create a grade_item, then saves it as $this->grade_item.
f151b073 672 * @return object Grade_item
673 */
674 function load_grade_item() {
ab53054f 675 $this->grade_item = $this->get_grade_item();
676 return $this->grade_item;
677 }
4a490db0 678
ab53054f 679 /**
680 * Retrieves from DB and instantiates the associated grade_item object.
681 * If no grade_item exists yet, create one.
682 * @return object Grade_item
683 */
684 function get_grade_item() {
c91ed4be 685 if (empty($this->id)) {
686 debugging("Attempt to obtain a grade_category's associated grade_item without the category's ID being set.");
687 return false;
688 }
689
8f4a626d 690 $grade_items = get_records_select('grade_items', "iteminstance = $this->id AND itemtype = 'category'", null, '*', 0, 1);
4a490db0 691
692 if ($grade_items){
1d4b6668 693 $params = current($grade_items);
ab53054f 694 $grade_item = new grade_item($params);
1d4b6668 695 } else {
ab53054f 696 $grade_item = new grade_item();
1d4b6668 697 }
4a490db0 698
8f4a626d 699 // If the associated grade_item isn't yet created, do it now. But first try loading it, in case it exists in DB.
ab53054f 700 if (empty($grade_item->id)) {
701 $grade_item->iteminstance = $this->id;
a3d55942 702 $grade_item->courseid = $this->courseid;
ab53054f 703 $grade_item->itemtype = 'category';
704 $grade_item->insert();
2c72af1f 705 }
706
ab53054f 707 return $grade_item;
f151b073 708 }
8c846243 709
710 /**
711 * Uses $this->parent to instantiate $this->parent_category based on the
712 * referenced record in the DB.
713 * @return object Parent_category
714 */
715 function load_parent_category() {
716 if (empty($this->parent_category) && !empty($this->parent)) {
ab53054f 717 $this->parent_category = $this->get_parent_category();
8c846243 718 }
719 return $this->parent_category;
4a490db0 720 }
721
ab53054f 722 /**
723 * Uses $this->parent to instantiate and return a grade_category object.
724 * @return object Parent_category
725 */
726 function get_parent_category() {
727 if (!empty($this->parent)) {
728 $parent_category = new grade_category(array('id' => $this->parent));
4a490db0 729 return $parent_category;
ab53054f 730 } else {
731 return null;
732 }
733 }
734
03f01edd 735 /**
c91ed4be 736 * 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 737 * A number of constraints are necessary:
738 * - The children must all be of the same type and at the same level
03f01edd 739 * - The children cannot already be top categories
c91ed4be 740 * - The children all belong to the same course
03f01edd 741 * @param array $children An array of fully instantiated grade_category OR grade_item objects
ffa6e8d3 742 *
03f01edd 743 * @return boolean Success or Failure
ffa6e8d3 744 * @TODO big problem of performance
03f01edd 745 */
746 function set_as_parent($children) {
747 global $CFG;
748
210611f6 749 if (empty($children) || !is_array($children)) {
750 debugging("Passed an empty or non-array variable to grade_category::set_as_parent()");
751 return false;
752 }
753
03f01edd 754 // Check type and sortorder of first child
755 $first_child = current($children);
756 $first_child_type = get_class($first_child);
9f9afbdb 757
758 // If this->courseid is not set, set it to the first child's courseid
759 if (empty($this->courseid)) {
760 $this->courseid = $first_child->courseid;
761 }
762
763 $grade_tree = new grade_tree();
03f01edd 764
765 foreach ($children as $child) {
766 if (get_class($child) != $first_child_type) {
767 debugging("Violated constraint: Attempted to set a category as a parent over children of 2 different types.");
768 return false;
769 }
4a490db0 770
526e1a8a 771 if ($grade_tree->get_element_type($child) == 'topcat') {
03f01edd 772 debugging("Violated constraint: Attempted to set a category over children which are already top categories.");
773 return false;
774 }
4a490db0 775
9f9afbdb 776 if ($first_child_type == 'grade_category' or $first_child_type == 'grade_item') {
03f01edd 777 if (!empty($child->parent)) {
778 debugging("Violated constraint: Attempted to set a category over children that already have a top category.");
4a490db0 779 return false;
03f01edd 780 }
781 } else {
782 debugging("Attempted to set a category over children that are neither grade_items nor grade_categories.");
783 return false;
4a490db0 784 }
c91ed4be 785
9f9afbdb 786 if ($child->courseid != $this->courseid) {
c91ed4be 787 debugging("Attempted to set a category over children which do not belong to the same course.");
788 return false;
789 }
4a490db0 790 }
03f01edd 791
792 // We passed all the checks, time to set the category as a parent.
793 foreach ($children as $child) {
1c307f21 794 $child->divorce_parent();
795 $child->set_parent_id($this->id);
796 if (!$child->update()) {
797 debugging("Could not set this category as a parent for one of its children, DB operation failed.");
798 return false;
4a490db0 799 }
03f01edd 800 }
801
802 // TODO Assign correct sortorders to the newly assigned children and parent. Simply add 1 to all of them!
803 $this->load_grade_item();
804 $this->grade_item->sortorder = $first_child->get_sortorder();
4a490db0 805
03f01edd 806 if (!$this->update()) {
807 debugging("Could not update this category's sortorder in DB.");
808 return false;
809 }
4a490db0 810
750b0550 811 $query = "UPDATE {$CFG->prefix}grade_items SET sortorder = sortorder + 1 WHERE sortorder >= {$this->grade_item->sortorder}";
ffa6e8d3 812 $query .= " AND courseid = $this->courseid";
813
03f01edd 814 if (!execute_sql($query)) {
815 debugging("Could not update the sortorder of grade_items listed after this category.");
750b0550 816 return false;
03f01edd 817 } else {
818 return true;
819 }
820 }
2186f72c 821
822 /**
4a490db0 823 * Returns the most descriptive field for this object. This is a standard method used
2186f72c 824 * when we do not know the exact type of an object.
825 * @return string name
826 */
827 function get_name() {
828 return $this->fullname;
829 }
c91ed4be 830
831 /**
832 * Returns this category's grade_item's id. This is specified for cases where we do not
833 * know an object's type, and want to get either an item's id or a category's item's id.
834 *
835 * @return int
836 */
837 function get_item_id() {
838 $this->load_grade_item();
839 return $this->grade_item->id;
840 }
0fc7f624 841
842 /**
843 * Returns this category's parent id. A generic method shared by objects that have a parent id of some kind.
844 * @return id $parentid
845 */
846 function get_parent_id() {
847 return $this->parent;
848 }
849
850 /**
851 * Sets this category's parent id. A generic method shared by objects that have a parent id of some kind.
852 * @param id $parentid
853 */
854 function set_parent_id($parentid) {
855 $this->parent = $parentid;
88e794d6 856 $this->path = grade_category::build_path($this);
857 $this->depth = $this->get_depth_from_path();
0fc7f624 858 }
4a490db0 859
0fc7f624 860 /**
4a490db0 861 * Returns the sortorder of the associated grade_item. This method is also available in
5fad5061 862 * grade_item, for cases where the object type is not known.
0fc7f624 863 * @return int Sort order
864 */
865 function get_sortorder() {
866 if (empty($this->sortorder)) {
867 $this->load_grade_item();
868 if (!empty($this->grade_item)) {
869 return $this->grade_item->sortorder;
870 }
871 } else {
872 return $this->sortorder;
873 }
874 }
875
876 /**
4a490db0 877 * Sets a temporary sortorder variable for this category. It is used in the update() method to update the grade_item.
878 * This method is also available in grade_item, for cases where the object type is not know.
0fc7f624 879 * @param int $sortorder
880 * @return void
881 */
882 function set_sortorder($sortorder) {
883 $this->sortorder = $sortorder;
884 }
4a490db0 885
5fad5061 886 /**
4a490db0 887 * Returns the locked state/date of the associated grade_item. This method is also available in
888 * grade_item, for cases where the object type is not known.
5fad5061 889 * @return int 0, 1 or timestamp int(10)
890 */
891 function get_locked() {
892 $this->load_grade_item();
893 if (!empty($this->grade_item)) {
894 return $this->grade_item->locked;
895 } else {
896 return false;
897 }
898 }
899
900 /**
901 * Sets the grade_item's locked variable and updates the grade_item.
902 * Method named after grade_item::set_locked().
903 * @param int $locked 0, 1 or a timestamp int(10) after which date the item will be locked.
904 * @return void
905 */
906 function set_locked($locked) {
907 $this->load_grade_item();
908 if (!empty($this->grade_item)) {
909 $this->grade_item->locked = $locked;
910 return $this->grade_item->update();
911 } else {
912 return false;
913 }
914 }
4a490db0 915
5fad5061 916 /**
4a490db0 917 * Returns the hidden state/date of the associated grade_item. This method is also available in
918 * grade_item, for cases where the object type is not known.
5fad5061 919 * @return int 0, 1 or timestamp int(10)
920 */
921 function get_hidden() {
922 $this->load_grade_item();
923 if (!empty($this->grade_item)) {
924 return $this->grade_item->hidden;
925 } else {
926 return false;
927 }
928 }
929
930 /**
4a490db0 931 * Sets the grade_item's hidden variable and updates the grade_item.
5fad5061 932 * Method named after grade_item::set_hidden().
933 * @param int $hidden 0, 1 or a timestamp int(10) after which date the item will be hidden.
934 * @return void
935 */
936 function set_hidden($hidden) {
937 $this->load_grade_item();
938 if (!empty($this->grade_item)) {
939 $this->grade_item->hidden = $hidden;
940 return $this->grade_item->update();
941 } else {
942 return false;
943 }
944 }
945
4a490db0 946 /**
88e794d6 947 * If the old parent is set (after an update), this checks and returns whether it has any children. Important for
948 * deleting childless categories.
949 * @return boolean
950 */
951 function is_old_parent_childless() {
952 if (!empty($this->old_parent)) {
953 return !$this->old_parent->has_children();
954 } else {
955 return false;
956 }
4a490db0 957 }
958}
8a31e65c 959?>