Search moodle.org's
Developer Documentation
Developer Documentation
- Bug fixes for general core bugs in 4.0.x will end 8 May 2023 (12 months).
- Bug fixes for security issues in 4.0.x will end 13 November 2023 (18 months).
- PHP version: minimum PHP 7.3.0 Note: the minimum PHP version has increased since Moodle 3.10. PHP 7.4.x is also supported.
/lib/grade/ -> grade_category.php (source)
Differences Between: [Versions 310 and 400] [Versions 311 and 400] [Versions 39 and 400] [Versions 400 and 401] [Versions 400 and 402] [Versions 400 and 403]
Definition of a class to represent a grade category
| Copyright: | 2006 Nicolas Connault |
| License: | http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later |
| File Size: | 2791 lines (112 kb) |
| Included or required: | 0 times |
| Referenced: | 1 time |
| Includes or requires: | 1 file lib/grade/grade_object.php |
Defines 1 class
grade_category:: (56 methods):
build_path()
fetch()
fetch_all()
update()
delete()
insert()
insert_course_category()
qualifies_for_regrading()
force_regrading()
pre_regrade_final_grades()
generate_grades()
aggregate_grades()
set_usedinaggregation()
aggregate_values_and_adjust_bounds()
aggregate_values()
auto_update_max()
auto_update_weights()
apply_limit_rules()
can_apply_limit_rules()
is_extracredit_used()
aggregation_uses_extracredit()
is_aggregationcoef_used()
aggregation_uses_aggregationcoef()
get_coefstring()
fetch_course_tree()
_fetch_course_tree_recursion()
get_children()
_get_children_recursion()
load_grade_item()
get_grade_item()
load_parent_category()
get_parent_category()
get_name()
get_description()
set_parent()
get_final()
get_sortorder()
get_idnumber()
set_sortorder()
move_after_sortorder()
is_course_category()
fetch_course_category()
is_editable()
is_locked()
set_locked()
set_properties()
set_hidden()
apply_default_settings()
apply_forced_settings()
updated_forced_settings()
get_default_aggregation_coefficient_values()
notify_changed()
generate_record_set_key()
retrieve_record_set()
set_record_set()
clean_record_set()
Class: grade_category - X-Ref
grade_category is an object mapped to DB table {prefix}grade_categories| build_path($grade_category) X-Ref |
| Builds this category's path string based on its parents (if any) and its own id number. This is typically done just before inserting this object in the DB for the first time, or when a new parent is added or changed. It is a recursive function: once the calling object no longer has a parent, the path is complete. return: string The category's path string param: grade_category $grade_category A Grade_Category object |
| fetch($params) X-Ref |
| Finds and returns a grade_category instance based on params. return: grade_category The retrieved grade_category instance or false if none found. param: array $params associative arrays varname=>value |
| fetch_all($params) X-Ref |
| Finds and returns all grade_category instances based on params. return: array array of grade_category insatnces or false if none found. param: array $params associative arrays varname=>value |
| update($source = null, $isbulkupdate = false) X-Ref |
| In addition to update() as defined in grade_object, call force_regrading of parent categories, if applicable. return: bool success param: string $source from where was the object updated (mod/forum, manual, etc.) param: bool $isbulkupdate If bulk grade update is happening. |
| delete($source=null) X-Ref |
| If parent::delete() is successful, send force_regrading message to parent category. return: bool success param: string $source from where was the object deleted (mod/forum, manual, etc.) |
| insert($source = null, $isbulkupdate = false) X-Ref |
| In addition to the normal insert() defined in grade_object, this method sets the depth and path for this object, and update the record accordingly. We do this here instead of in the constructor as they both need to know the record's ID number, which only gets created at insertion time. This method also creates an associated grade_item if this wasn't done during construction. return: int PK ID if successful, false otherwise param: string $source from where was the object inserted (mod/forum, manual, etc.) param: bool $isbulkupdate If bulk grade update is happening. |
| insert_course_category($courseid) X-Ref |
| Internal function - used only from fetch_course_category() Normal insert() can not be used for course category return: int The ID of the new course category param: int $courseid The course ID |
| qualifies_for_regrading() X-Ref |
| Compares the values held by this object with those of the matching record in DB, and returns whether or not these differences are sufficient to justify an update of all parent objects. This assumes that this object has an ID number and a matching record in DB. If not, it will return false. return: bool |
| force_regrading() X-Ref |
| Marks this grade categories' associated grade item as needing regrading |
| pre_regrade_final_grades() X-Ref |
| Something that should be called before we start regrading the whole course. return: void |
| generate_grades($userid=null, ?\core\progress\base $progress = null) X-Ref |
| Generates and saves final grades in associated category grade item. These immediate children must already have their own final grades. The category's aggregation method is used to generate final grades. Please note that category grade is either calculated or aggregated, not both at the same time. This method must be used ONLY from grade_item::regrade_final_grades(), because the calculation must be done in correct order! Steps to follow: 1. Get final grades from immediate children 3. Aggregate these grades 4. Save them in final grades of associated category grade item return: bool param: int $userid The user ID if final grade generation should be limited to a single user param: \core\progress\base|null $progress Optional progress indicator |
| aggregate_grades($userid,$items,$grade_values,$oldgrade,$excluded,$grademinoverrides,$grademaxoverrides) X-Ref |
| Internal function for grade category grade aggregation param: int $userid The User ID param: array $items Grade items param: array $grade_values Array of grade values param: object $oldgrade Old grade param: array $excluded Excluded param: array $grademinoverrides User specific grademin values if different to the grade_item grademin (key is itemid) param: array $grademaxoverrides User specific grademax values if different to the grade_item grademax (key is itemid) |
| set_usedinaggregation($userid, $usedweights, $novalue, $dropped, $extracredit) X-Ref |
| Set the flags on the grade_grade items to indicate how individual grades are used in the aggregation. WARNING: This function is called a lot during gradebook recalculation, be very performance considerate. param: int $userid The user we have aggregated the grades for. param: array $usedweights An array with keys for each of the grade_item columns included in the aggregation. The value are the relative weight. param: array $novalue An array with keys for each of the grade_item columns skipped because param: array $dropped An array with keys for each of the grade_item columns dropped param: array $extracredit An array with keys for each of the grade_item columns |
| aggregate_values_and_adjust_bounds($grade_values,$items,& $weights = null,$grademinoverrides = array() X-Ref |
| Internal function that calculates the aggregated grade and new min/max for this grade category Must be public as it is used by grade_grade::get_hiding_affected() return: array containing values for: param: array $grade_values An array of values to be aggregated param: array $items The array of grade_items param: array & $weights If provided, will be filled with the normalized weights param: array $grademinoverrides User specific grademin values if different to the grade_item grademin (key is itemid) param: array $grademaxoverrides User specific grademax values if different to the grade_item grademax (key is itemid) |
| aggregate_values($grade_values, $items) X-Ref |
| Internal function that calculates the aggregated grade for this grade category Must be public as it is used by grade_grade::get_hiding_affected() return: float The aggregate grade for this grade category param: array $grade_values An array of values to be aggregated param: array $items The array of grade_items |
| auto_update_max() X-Ref |
| Some aggregation types may need to update their max grade. This must be executed after updating the weights as it relies on them. return: void |
| auto_update_weights() X-Ref |
| Recalculate the weights of the grade items in this category. The category total is not updated here, a further call to {@link self::auto_update_max()} is required. return: void |
| apply_limit_rules(&$grade_values, $items) X-Ref |
| Given an array of grade values (numerical indices) applies droplow or keephigh rules to limit the final array. return: array Limited grades. param: array $grade_values itemid=>$grade_value float param: array $items grade item objects |
| can_apply_limit_rules() X-Ref |
| Returns whether or not we can apply the limit rules. There are cases where drop lowest or keep highest should not be used at all. This method will determine whether or not this logic can be applied considering the current setup of the category. return: bool |
| is_extracredit_used() X-Ref |
| Returns true if category uses extra credit of any kind return: bool True if extra credit used |
| aggregation_uses_extracredit($aggregation) X-Ref |
| Returns true if aggregation passed is using extracredit. return: bool True if extra credit used param: int $aggregation Aggregation const. |
| is_aggregationcoef_used() X-Ref |
| Returns true if category uses special aggregation coefficient return: bool True if an aggregation coefficient is being used |
| aggregation_uses_aggregationcoef($aggregation) X-Ref |
| Returns true if aggregation uses aggregationcoef return: bool True if an aggregation coefficient is being used param: int $aggregation Aggregation const. |
| get_coefstring($first=true) X-Ref |
| Recursive function to find which weight/extra credit field to use in the grade item form. return: string param: string $first Whether or not this is the first item in the recursion |
| fetch_course_tree($courseid, $include_category_items=false) X-Ref |
| Returns tree with all grade_items and categories as elements return: array param: int $courseid The course ID param: bool $include_category_items as category children |
| _fetch_course_tree_recursion($category_array, &$sortorder) X-Ref |
| An internal function that recursively sorts grade categories within a course return: array An array containing 'object', 'type', 'depth' and optionally 'children' param: array $category_array The seed of the recursion param: int $sortorder The current sortorder |
| get_children($include_category_items=false) X-Ref |
| Fetches and returns all the children categories and/or grade_items belonging to this category. By default only returns the immediate children (depth=1), but deeper levels can be requested, as well as all levels (0). The elements are indexed by sort order. return: array Array of child objects (grade_category and grade_item). param: bool $include_category_items Whether or not to include category grade_items in the children array |
| _get_children_recursion($category) X-Ref |
| Private method used to retrieve all children of this category recursively return: array An array of child grade categories param: grade_category $category Source of current recursion |
| load_grade_item() X-Ref |
| Uses {@link get_grade_item()} to load or create a grade_item, then saves it as $this->grade_item. return: grade_item |
| get_grade_item() X-Ref |
| Retrieves this grade categories' associated grade_item from the database If no grade_item exists yet, creates one. return: grade_item |
| load_parent_category() X-Ref |
| Uses $this->parent to instantiate $this->parent_category based on the referenced record in the DB return: grade_category The parent category |
| get_parent_category() X-Ref |
| Uses $this->parent to instantiate and return a grade_category object return: grade_category Returns the parent category or null if this category has no parent |
| get_name($escape = true) X-Ref |
| Returns the most descriptive field for this grade category return: string name param: bool $escape Whether the returned category name is to be HTML escaped or not. |
| get_description() X-Ref |
| Describe the aggregation settings for this category so the reports make more sense. return: string description |
| set_parent($parentid, $source=null) X-Ref |
| Sets this category's parent id return: bool success param: int $parentid The ID of the category that is the new parent to $this param: string $source From where was the object updated (mod/forum, manual, etc.) |
| get_final($userid=null) X-Ref |
| Returns the final grade values for this grade category. return: mixed An array of all final_grades (stdClass objects) for this grade_item, or a single final_grade. param: int $userid Optional user ID to retrieve a single user's final grade |
| get_sortorder() X-Ref |
| Returns the sortorder of the grade categories' associated grade_item This method is also available in grade_item for cases where the object type is not known. return: int Sort order |
| get_idnumber() X-Ref |
| Returns the idnumber of the grade categories' associated grade_item. This method is also available in grade_item for cases where the object type is not known. return: string idnumber |
| set_sortorder($sortorder) X-Ref |
| Sets the sortorder variable for this category. This method is also available in grade_item, for cases where the object type is not know. param: int $sortorder The sortorder to assign to this category |
| move_after_sortorder($sortorder) X-Ref |
| Move this category after the given sortorder Does not change the parent return: void param: int $sortorder to place after. |
| is_course_category() X-Ref |
| Return true if this is the top most category that represents the total course grade. return: bool |
| fetch_course_category($courseid) X-Ref |
| Return the course level grade_category object return: grade_category Returns the course level grade_category instance param: int $courseid The Course ID |
| is_editable() X-Ref |
| Is grading object editable? return: bool |
| is_locked() X-Ref |
| Returns the locked state/date of the grade categories' associated grade_item. This method is also available in grade_item, for cases where the object type is not known. return: bool |
| set_locked($lockedstate, $cascade=false, $refresh=true) X-Ref |
| Sets the grade_item's locked variable and updates the grade_item. Calls set_locked() on the categories' grade_item return: bool success if category locked (not all children mayb be locked though) param: int $lockedstate 0, 1 or a timestamp int(10) after which date the item will be locked. param: bool $cascade lock/unlock child objects too param: bool $refresh refresh grades when unlocking |
| set_properties(&$instance, $params) X-Ref |
| Overrides grade_object::set_properties() to add special handling for changes to category aggregation types param: stdClass $instance the object to set the properties on param: array|stdClass $params Either an associative array or an object containing property name, property value pairs |
| set_hidden($hidden, $cascade=false) X-Ref |
| Sets the grade_item's hidden variable and updates the grade_item. Overrides grade_item::set_hidden() to add cascading of the hidden value to grade items in this grade category param: int $hidden 0 mean always visible, 1 means always hidden and a number > 1 is a timestamp to hide until param: bool $cascade apply to child objects too |
| apply_default_settings() X-Ref |
| Applies default settings on this category return: bool True if anything changed |
| apply_forced_settings() X-Ref |
| Applies forced settings on this category return: bool True if anything changed |
| updated_forced_settings() X-Ref |
| Notification of change in forced category settings. Causes all course and category grade items to be marked as needing to be updated |
| get_default_aggregation_coefficient_values($aggregationmethod) X-Ref |
| Determine the default aggregation values for a given aggregation method. return: array Containing the keys 'aggregationcoef', 'aggregationcoef2' and 'weightoverride'. param: int $aggregationmethod The aggregation method constant value. |
| notify_changed($deleted) X-Ref |
| Cleans the cache. We invalidate them all so it can be completely reloaded. Being conservative here, if there is a new grade_category we purge them, the important part is that this is not purged when there are no changes in grade_categories. return: void param: bool $deleted |
| generate_record_set_key($params) X-Ref |
| Generates a unique key per query. Not unique between grade_object children. self::retrieve_record_set and self::set_record_set will be in charge of selecting the appropriate cache. return: string param: array $params An array of conditions like $fieldname => $fieldvalue |
| retrieve_record_set($params) X-Ref |
| Tries to retrieve a record set from the cache. return: grade_object[]|bool An array of grade_objects or false if not found. param: array $params The query params |
| set_record_set($params, $records) X-Ref |
| Sets a result to the records cache, even if there were no results. return: void param: string $params The query params param: grade_object[]|bool $records An array of grade_objects or false if there are no records matching the $key filters |
| clean_record_set() X-Ref |
| Cleans the cache. Aggressive deletion to be conservative given the gradebook design. The key is based on the requested params, not easy nor worth to purge selectively. return: void |
