MDL-9506

grade_category:
    new parent_category object
    new load_parent_category() method
    new flag_for_update() recursive method
grade_item:
    new category object
    changed get_category() to load_category() and updated testgradeitem
    added missing idnumber field
    new flag_for_update() recursive method

lib/grade/grade_category.php

@@ -49,6 +49,12 @@ class grade_category extends grade_object {
      * @var int $parent 
      */
     var $parent;
+    
+    /**
+     * The grade_category object referenced by $this->parent (PK).
+     * @var object $parent_category
+     */
+    var $parent_category;
 
     /**
      * The number of parents this category has.
@@ -214,7 +220,28 @@ class grade_category extends grade_object {
 
         return $result;
     }
-   
+
+    /**
+     * Sets this category's and its parent's grade_item.needsupdate to true.
+     * This is triggered whenever any change in any lower level may cause grade_finals
+     * for this category to require an update. The flag needs to be propagated up all
+     * levels until it reaches the top category. This is then used to determine whether or not
+     * to regenerate the raw and final grades for each category grade_item.
+     * @return boolean Success or failure
+     */
+    function flag_for_update() {
+        $result = true;
+
+        $this->load_grade_item();
+        $this->grade_item->needsupdate = true;
+        $this->load_parent_category();
+        if (!empty($this->parent_category)) {
+            $result = $result && $this->parent_category->flag_for_update();
+        }
+
+        return $result;
+    }
+
     /**
      * Generates and saves raw_grades, based on this category's immediate children, then uses the 
      * associated grade_item to generate matching final grades. These immediate children must first have their own
@@ -508,6 +535,18 @@ class grade_category extends grade_object {
 
         return $this->grade_item;
     }
+
+    /**
+     * Uses $this->parent to instantiate $this->parent_category based on the
+     * referenced record in the DB.
+     * @return object Parent_category
+     */
+    function load_parent_category() {
+        if (empty($this->parent_category) && !empty($this->parent)) {
+            $this->parent_category = grade_category::fetch('id', $this->parent);
+        }
+        return $this->parent_category;
+    }
 }
 
 ?>

lib/grade/grade_item.php

@@ -40,7 +40,7 @@ class grade_item extends grade_object {
      * Array of class variables that are not part of the DB table fields
      * @var array $nonfields
      */
-    var $nonfields = array('table', 'nonfields', 'calculation', 'grade_grades_raw', 'scale');
+    var $nonfields = array('table', 'nonfields', 'calculation', 'grade_grades_raw', 'scale', 'category');
   
     /**
      * The course this grade_item belongs to.
@@ -54,6 +54,12 @@ class grade_item extends grade_object {
      */
     var $categoryid;
     
+    /**
+     * The grade_category object referenced by $this->categoryid.
+     * @var object $category 
+     */
+    var $category;
+    
     /**
      * The name of this grade_item (pushed by the module).
      * @var string $itemname
@@ -90,6 +96,12 @@ class grade_item extends grade_object {
      */
     var $iteminfo;
 
+    /**
+     * Arbitrary idnumber provided by the module responsible.
+     * @var string $idnumber
+     */
+    var $idnumber;
+
     /**
      * The type of grade (0 = value, 1 = scale, 2 = text)
      * @var int $gradetype
@@ -434,16 +446,15 @@ class grade_item extends grade_object {
     }
     
     /**
-    * Returns the grade_category object this grade_item belongs to (if any).
+    * Returns the grade_category object this grade_item belongs to (if any) and sets $this->category.
     * 
     * @return mixed grade_category object if applicable, NULL otherwise
     */
-    function get_category() {
-        if (!empty($this->categoryid)) {
-            return grade_category::fetch('id', $this->categoryid);
-        } else {
-            return null;
+    function load_category() {
+        if (empty($this->category) && !empty($this->categoryid)) {
+            $this->category = grade_category::fetch('id', $this->categoryid);
         }
+        return $this->category;
     }
 
     /**
@@ -653,5 +664,26 @@ class grade_item extends grade_object {
         }         
         return $gradevalue;
     } 
+    
+    /**
+     * Sets this grade_item's needsupdate to true. Also looks at parent category, if any, and calls
+     * its flag_for_update() method.
+     * This is triggered whenever any change in any grade_raw may cause grade_finals
+     * for this grade_item to require an update. The flag needs to be propagated up all
+     * levels until it reaches the top category. This is then used to determine whether or not
+     * to regenerate the raw and final grades for each category grade_item.
+     * @return boolean Success or failure
+     */
+    function flag_for_update() {
+        $result = true;
+
+        $this->needsupdate = true;
+        $this->load_parent_category();
+        if (!empty($this->parent_category)) {
+            $result = $result && $this->parent_category->flag_for_update();
+        }
+
+        return $result;
+    }
 }
 ?>

lib/simpletest/grade/simpletest/testgradeitem.php

@@ -192,12 +192,12 @@ class grade_item_test extends gradelib_test {
         $this->assertEqual($calculation, $new_calculation->calculation);
     }
 
-    function test_grade_item_get_category() {
+    function test_grade_item_load_category() {
         $grade_item = new grade_item($this->grade_items[0]);
-        $this->assertTrue(method_exists($grade_item, 'get_category'));
+        $this->assertTrue(method_exists($grade_item, 'load_category'));
         
-        $category = $grade_item->get_category();
-        $this->assertEqual($this->grade_categories[1]->fullname, $category->fullname);
+        $grade_item->load_category();
+        $this->assertEqual($this->grade_categories[1]->fullname, $grade_item->category->fullname);
     }
 
     /**