Search moodle.org's
Developer Documentation
Developer Documentation
See Release Notes
Long Term Support Release
- Bug fixes for general core bugs in 4.1.x will end 13 November 2023 (12 months).
- Bug fixes for security issues in 4.1.x will end 10 November 2025 (36 months).
- PHP version: minimum PHP 7.4.0 Note: minimum PHP version has increased since Moodle 4.0. PHP 8.0.x is supported too.
/lib/grade/ -> grade_category.php (source)
Differences Between: [Versions 310 and 401] [Versions 311 and 401] [Versions 39 and 401] [Versions 400 and 401] [Versions 401 and 402] [Versions 401 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: | 2805 lines (113 kb) |
| Included or required: | 0 times |
| Referenced: | 0 times |
| 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. param: grade_category $grade_category A Grade_Category object return: string The category's path string |
| fetch($params) X-Ref |
| Finds and returns a grade_category instance based on params. param: array $params associative arrays varname=>value return: grade_category The retrieved grade_category instance or false if none found. |
| fetch_all($params) X-Ref |
| Finds and returns all grade_category instances based on params. param: array $params associative arrays varname=>value return: array array of grade_category insatnces or false if none found. |
| update($source = null, $isbulkupdate = false) X-Ref |
| In addition to update() as defined in grade_object, call force_regrading of parent categories, if applicable. param: string $source from where was the object updated (mod/forum, manual, etc.) param: bool $isbulkupdate If bulk grade update is happening. return: bool success |
| delete($source=null) X-Ref |
| If parent::delete() is successful, send force_regrading message to parent category. param: string $source from where was the object deleted (mod/forum, manual, etc.) return: bool success |
| 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. param: string $source from where was the object inserted (mod/forum, manual, etc.) param: bool $isbulkupdate If bulk grade update is happening. return: int PK ID if successful, false otherwise |
| insert_course_category($courseid) X-Ref |
| Internal function - used only from fetch_course_category() Normal insert() can not be used for course category param: int $courseid The course ID return: int The ID of the new course category |
| 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 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 return: bool |
| 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() 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) return: array containing values for: |
| 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() param: array $grade_values An array of values to be aggregated param: array $items The array of grade_items return: float The aggregate grade for this grade category |
| 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. param: array $grade_values itemid=>$grade_value float param: array $items grade item objects return: array Limited grades. |
| 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. param: int $aggregation Aggregation const. return: bool True if extra credit used |
| 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 param: int $aggregation Aggregation const. return: bool True if an aggregation coefficient is being used |
| get_coefstring($first=true) X-Ref |
| Recursive function to find which weight/extra credit field to use in the grade item form. param: string $first Whether or not this is the first item in the recursion return: string |
| fetch_course_tree($courseid, $include_category_items=false) X-Ref |
| Returns tree with all grade_items and categories as elements param: int $courseid The course ID param: bool $include_category_items as category children return: array |
| _fetch_course_tree_recursion($category_array, &$sortorder) X-Ref |
| An internal function that recursively sorts grade categories within a course param: array $category_array The seed of the recursion param: int $sortorder The current sortorder return: array An array containing 'object', 'type', 'depth' and optionally 'children' |
| 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. param: bool $include_category_items Whether or not to include category grade_items in the children array return: array Array of child objects (grade_category and grade_item). |
| _get_children_recursion($category) X-Ref |
| Private method used to retrieve all children of this category recursively param: grade_category $category Source of current recursion return: array An array of child grade categories |
| 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 param: bool $escape Whether the returned category name is to be HTML escaped or not. return: string name |
| 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 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.) return: bool success |
| get_final($userid=null) X-Ref |
| Returns the final grade values for this grade category. param: int $userid Optional user ID to retrieve a single user's final grade return: mixed An array of all final_grades (stdClass objects) for this grade_item, or a single 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 param: int $sortorder to place after. return: void |
| 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 param: int $courseid The Course ID return: grade_category Returns the course level grade_category instance |
| 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 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 return: bool success if category locked (not all children mayb be locked though) |
| 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. param: int $aggregationmethod The aggregation method constant value. return: array Containing the keys 'aggregationcoef', 'aggregationcoef2' and 'weightoverride'. |
| 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. param: bool $deleted return: void |
| 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. param: array $params An array of conditions like $fieldname => $fieldvalue return: string |
| retrieve_record_set($params) X-Ref |
| Tries to retrieve a record set from the cache. param: array $params The query params return: grade_object[]|bool An array of grade_objects or false if not found. |
| set_record_set($params, $records) X-Ref |
| Sets a result to the records cache, even if there were no results. 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 return: void |
| 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 |
