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_item.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 item
| Copyright: | 2006 Nicolas Connault |
| License: | http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later |
| File Size: | 2599 lines (94 kb) |
| Included or required: | 0 times |
| Referenced: | 0 times |
| Includes or requires: | 1 file lib/grade/grade_object.php |
Defines 1 class
grade_item:: (73 methods):
__construct()
update()
qualifies_for_regrading()
fetch()
has_grades()
has_overridden_grades()
fetch_all()
delete()
delete_all_grades()
duplicate()
insert()
add_idnumber()
is_locked()
set_locked()
check_locktime()
set_locktime()
get_locktime()
set_hidden()
has_hidden_grades()
regrading_finished()
regrade_final_grades()
adjust_raw_grade()
rescale_grades_keep_percentage()
force_regrading()
load_scale()
load_outcome()
get_parent_category()
load_parent_category()
get_item_category()
load_item_category()
is_category_item()
is_course_item()
is_manual_item()
is_outcome_item()
is_external_item()
is_overridable_item()
is_overridable_item_feedback()
is_raw_used()
is_aggregate_item()
fetch_course_item()
is_editable()
is_calculated()
get_calculation()
set_calculation()
denormalize_formula()
normalize_formula()
get_final()
get_grade()
get_sortorder()
get_idnumber()
get_grade_item()
set_sortorder()
move_after_sortorder()
fix_duplicate_sortorder()
get_name()
get_description()
set_parent()
set_aggregation_fields_for_aggregation()
bounded_grade()
depends_on()
refresh_grades()
update_final_grade()
update_raw_grade()
compute()
use_formula()
validate_formula()
get_displaytype()
get_decimals()
get_formatted_range()
get_coefstring()
can_control_visibility()
notify_changed()
get_context()
Class: grade_item - X-Ref
Class representing a grade item.It is responsible for handling its DB representation, modifying and returning its metadata.
| __construct($params = null, $fetch = true) X-Ref |
| Constructor. Optionally (and by default) attempts to fetch corresponding row from the database param: array $params An array with required parameters for this grade object. param: bool $fetch Whether to fetch corresponding row from the database or not, |
| update($source = null, $isbulkupdate = false) X-Ref |
| In addition to update() as defined in grade_object, handle the grade_outcome and grade_scale objects. Force regrading if necessary, rounds the float numbers using php function, the reason is we need to compare the db value with computed number to skip regrading if possible. param: string $source from where was the object inserted (mod/forum, manual, etc.) param: bool $isbulkupdate If bulk grade update is happening. return: bool success |
| 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 |
| fetch($params) X-Ref |
| Finds and returns a grade_item instance based on params. param: array $params associative arrays varname=>value return: grade_item|bool Returns a grade_item instance or false if none found |
| has_grades() X-Ref |
| Check to see if there are any existing grades for this grade_item. return: boolean - true if there are valid grades for this grade_item. |
| has_overridden_grades() X-Ref |
| Check to see if there are existing overridden grades for this grade_item. return: boolean - true if there are overridden grades for this grade_item. |
| fetch_all($params) X-Ref |
| Finds and returns all grade_item instances based on params. param: array $params associative arrays varname=>value return: array array of grade_item instances or false if none found. |
| delete($source=null) X-Ref |
| Delete all grades and force_regrading of parent category. param: string $source from where was the object deleted (mod/forum, manual, etc.) return: bool success |
| delete_all_grades($source=null) X-Ref |
| Delete all grades param: string $source from where was the object deleted (mod/forum, manual, etc.) return: bool |
| duplicate() X-Ref |
| Duplicate grade item. return: grade_item The duplicate grade item |
| insert($source = null, $isbulkupdate = false) X-Ref |
| In addition to perform parent::insert(), calls force_regrading() method too. param: string $source From where was the object inserted (mod/forum, manual, etc.) param: string $isbulkupdate If bulk grade update is happening. return: int PK ID if successful, false otherwise |
| add_idnumber($idnumber) X-Ref |
| Set idnumber of grade item, updates also course_modules table param: string $idnumber (without magic quotes) return: bool success |
| is_locked($userid=NULL) X-Ref |
| Returns the locked state of this grade_item (if the grade_item is locked OR no specific $userid is given) or the locked state of a specific grade within this item if a specific $userid is given and the grade_item is unlocked. param: int $userid The user's ID return: bool Locked state |
| set_locked($lockedstate, $cascade=false, $refresh=true) X-Ref |
| Locks or unlocks this grade_item and (optionally) all its associated final grades. 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 True if grade_item all grades updated, false if at least one update fails |
| check_locktime() X-Ref |
| Lock the grade if needed. Make sure this is called only when final grades are valid |
| set_locktime($locktime) X-Ref |
| Set the locktime for this grade item. param: int $locktime timestamp for lock to activate return: void |
| get_locktime() X-Ref |
| Set the locktime for this grade item. return: int $locktime timestamp for lock to activate |
| set_hidden($hidden, $cascade=false) X-Ref |
| Set the hidden status of grade_item and all grades. 0 mean always visible, 1 means always hidden and a number > 1 is a timestamp to hide until param: int $hidden new hidden status param: bool $cascade apply to child objects too |
| has_hidden_grades($groupsql="", array $params=null, $groupwheresql="") X-Ref |
| Returns the number of grades that are hidden param: string $groupsql SQL to limit the query by group param: array $params SQL params for $groupsql param: string $groupwheresql Where conditions for $groupsql return: int The number of hidden grades |
| regrading_finished() X-Ref |
| Mark regrading as finished successfully. This will also be called when subsequent regrading will not change any grades. Situations such as an error being found will still result in the regrading being finished. |
| regrade_final_grades($userid=null, ?\core\progress\base $progress = null) X-Ref |
| Performs the necessary calculations on the grades_final referenced by this grade_item. Also resets the needsupdate flag once successfully performed. This function must be used ONLY from lib/gradeslib.php/grade_regrade_final_grades(), because the regrading must be done in correct order!! param: int $userid Supply a user ID to limit the regrading to a single user param: \core\progress\base|null $progress Optional progress object, will be updated per user return: bool true if ok, error string otherwise |
| adjust_raw_grade($rawgrade, $rawmin, $rawmax) X-Ref |
| Given a float grade value or integer grade scale, applies a number of adjustment based on grade_item variables and returns the result. param: float $rawgrade The raw grade value param: float $rawmin original rawmin param: float $rawmax original rawmax return: mixed |
| rescale_grades_keep_percentage($oldgrademin, $oldgrademax, $newgrademin, $newgrademax, $source = null) X-Ref |
| Update the rawgrademax and rawgrademin for all grade_grades records for this item. Scale every rawgrade to maintain the percentage. This function should be called after the gradeitem has been updated to the new min and max values. param: float $oldgrademin The previous grade min value param: float $oldgrademax The previous grade max value param: float $newgrademin The new grade min value param: float $newgrademax The new grade max value param: string $source from where was the object inserted (mod/forum, manual, etc.) return: bool True on success |
| force_regrading() X-Ref |
| Sets this grade_item's needsupdate to true. Also marks the course item as needing update. return: void |
| load_scale() X-Ref |
| Instantiates a grade_scale object from the DB if this item's scaleid variable is set return: grade_scale Returns a grade_scale object or null if no scale used |
| load_outcome() X-Ref |
| Instantiates a grade_outcome object from the DB if this item's outcomeid variable is set return: grade_outcome This grade item's associated grade_outcome or null |
| get_parent_category() X-Ref |
| Returns the grade_category object this grade_item belongs to (referenced by categoryid) or category attached to category item. return: grade_category|bool Returns a grade_category object if applicable or false if this is a course item |
| load_parent_category() X-Ref |
| Calls upon the get_parent_category method to retrieve the grade_category object from the DB and assigns it to $this->parent_category. It also returns the object. return: grade_category This grade item's parent grade_category. |
| get_item_category() X-Ref |
| Returns the grade_category for a grade category grade item return: grade_category|bool Returns a grade_category instance if applicable or false otherwise |
| load_item_category() X-Ref |
| Calls upon the get_item_category method to retrieve the grade_category object from the DB and assigns it to $this->item_category. It also returns the object. return: grade_category |
| is_category_item() X-Ref |
| Is the grade item associated with category? return: bool |
| is_course_item() X-Ref |
| Is the grade item associated with course? return: bool |
| is_manual_item() X-Ref |
| Is this a manually graded item? return: bool |
| is_outcome_item() X-Ref |
| Is this an outcome item? return: bool |
| is_external_item() X-Ref |
| Is the grade item external - associated with module, plugin or something else? return: bool |
| is_overridable_item() X-Ref |
| Is the grade item overridable return: bool |
| is_overridable_item_feedback() X-Ref |
| Is the grade item feedback overridable return: bool |
| is_raw_used() X-Ref |
| Returns true if grade items uses raw grades return: bool |
| is_aggregate_item() X-Ref |
| Returns true if the grade item is an aggreggated type grade. return: bool |
| fetch_course_item($courseid) X-Ref |
| Returns the grade item associated with the course param: int $courseid return: grade_item Course level grade item object |
| is_editable() X-Ref |
| Is grading object editable? return: bool |
| is_calculated() X-Ref |
| Checks if grade calculated. Returns this object's calculation. return: bool true if grade item calculated. |
| get_calculation() X-Ref |
| Returns calculation string if grade calculated. return: string Returns the grade item's calculation if calculation is used, null if not |
| set_calculation($formula) X-Ref |
| Sets this item's calculation (creates it) if not yet set, or updates it if already set (in the DB). If no calculation is given, the calculation is removed. param: string $formula string representation of formula used for calculation return: bool success |
| denormalize_formula($formula, $courseid) X-Ref |
| Denormalizes the calculation formula to [idnumber] form param: string $formula A string representation of the formula param: int $courseid The course ID return: string The denormalized formula as a string |
| normalize_formula($formula, $courseid) X-Ref |
| Normalizes the calculation formula to [#giXX#] form param: string $formula The formula param: int $courseid The course ID return: string The normalized formula as a string |
| get_final($userid=NULL) X-Ref |
| Returns the final values for this grade item (as imported by module or other source). param: int $userid Optional: to retrieve a single user's final grade return: array|grade_grade An array of all grade_grade instances for this grade_item, or a single grade_grade instance. |
| get_grade($userid, $create=true) X-Ref |
| Get (or create if not exist yet) grade for this user param: int $userid The user ID param: bool $create If true and the user has no grade for this grade item a new grade_grade instance will be inserted return: grade_grade The grade_grade instance for the user for this grade item |
| get_sortorder() X-Ref |
| Returns the sortorder of this grade_item. This method is also available in grade_category, for cases where the object type is not know. return: int Sort order |
| get_idnumber() X-Ref |
| Returns the idnumber of this grade_item. This method is also available in grade_category, for cases where the object type is not know. return: string The grade item idnumber |
| get_grade_item() X-Ref |
| Returns this grade_item. This method is also available in grade_category, for cases where the object type is not know. return: grade_item |
| set_sortorder($sortorder) X-Ref |
| Sets the sortorder of this grade_item. This method is also available in grade_category, for cases where the object type is not know. param: int $sortorder |
| move_after_sortorder($sortorder) X-Ref |
| Update this grade item's sortorder so that it will appear after $sortorder param: int $sortorder The sort order to place this grade item after |
| fix_duplicate_sortorder($courseid) X-Ref |
| Detect duplicate grade item's sortorder and re-sort them. Note: Duplicate sortorder will be introduced while duplicating activities or merging two courses. param: int $courseid id of the course for which grade_items sortorder need to be fixed. |
| get_name($fulltotal=false, $escape = true) X-Ref |
| Returns the most descriptive field for this object. Determines what type of grade item it is then returns the appropriate string param: bool $fulltotal If the item is a category total, returns $categoryname."total" instead of "Category total" or "Course total" param: bool $escape Whether the returned category name is to be HTML escaped or not. return: string name |
| get_description() X-Ref |
| A grade item can return a more detailed description which will be added to the header of the column/row in some reports. return: string description |
| set_parent($parentid, $updateaggregationfields = true) X-Ref |
| Sets this item's categoryid. A generic method shared by objects that have a parent id of some kind. param: int $parentid The ID of the new parent param: bool $updateaggregationfields Whether or not to convert the aggregation fields when switching between category. return: bool True if success |
| set_aggregation_fields_for_aggregation($from, $to) X-Ref |
| Update the aggregation fields when the aggregation changed. This method should always be called when the aggregation has changed, but also when the item was moved to another category, even it if uses the same aggregation method. Some values such as the weight only make sense within a category, once moved the values should be reset to let the user adapt them accordingly. Note that this method does not save the grade item. {@link grade_item::update()} has to be called manually after using this method. param: int $from Aggregation method constant value. param: int $to Aggregation method constant value. return: boolean True when at least one field was changed, false otherwise |
| bounded_grade($gradevalue) X-Ref |
| Makes sure value is a valid grade value. param: float $gradevalue return: mixed float or int fixed grade value |
| depends_on($reset_cache=false) X-Ref |
| Finds out on which other items does this depend directly when doing calculation or category aggregation param: bool $reset_cache return: array of grade_item IDs this one depends on |
| refresh_grades($userid=0) X-Ref |
| Refetch grades from modules, plugins. param: int $userid optional, limit the refetch to a single user return: bool Returns true on success or if there is nothing to do |
| update_final_grade($userid, $finalgrade = false, $source = null, $feedback = false,$feedbackformat = FORMAT_MOODLE, $usermodified = null, $timemodified = null, $isbulkupdate = false) X-Ref |
| Updates final grade value for given user, this is a only way to update final grades from gradebook and import because it logs the change in history table and deals with overridden flag. This flag is set to prevent later overriding from raw grades submitted from modules. param: int $userid The graded user param: float|false $finalgrade The float value of final grade, false means do not change param: string $source The modification source param: string $feedback Optional teacher feedback param: int $feedbackformat A format like FORMAT_PLAIN or FORMAT_HTML param: int $usermodified The ID of the user making the modification param: int $timemodified Optional parameter to set the time modified, if not present current time. param: bool $isbulkupdate If bulk grade update is happening. return: bool success |
| update_raw_grade($userid, $rawgrade = false, $source = null, $feedback = false,$feedbackformat = FORMAT_MOODLE, $usermodified = null, $dategraded = null, $datesubmitted=null,$grade = null, array $feedbackfiles = [], $isbulkupdate = false) X-Ref |
| Updates raw grade value for given user, this is a only way to update raw grades from external source (modules, etc.), because it logs the change in history table and deals with final grade recalculation. param: int $userid the graded user param: mixed $rawgrade float value of raw grade - false means do not change param: string $source modification source param: string $feedback optional teacher feedback param: int $feedbackformat A format like FORMAT_PLAIN or FORMAT_HTML param: int $usermodified the ID of the user who did the grading param: int $dategraded A timestamp of when the student's work was graded param: int $datesubmitted A timestamp of when the student's work was submitted param: grade_grade $grade A grade object, useful for bulk upgrades param: array $feedbackfiles An array identifying the location of files we want to copy to the gradebook feedback area. param: bool $isbulkupdate If bulk grade update is happening. return: bool success |
| compute($userid=null) X-Ref |
| Calculates final grade values using the formula in the calculation property. The parameters are taken from final grades of grade items in current course only. param: int $userid Supply a user ID to limit the calculations to the grades of a single user return: bool false if error |
| use_formula($userid, $params, $useditems, $oldgrade) X-Ref |
| Internal function that does the final grade calculation param: int $userid The user ID param: array $params An array of grade items of the form {'gi'.$itemid]} => $finalgrade param: array $useditems An array of grade item IDs that this grade item depends on plus its own ID param: grade_grade $oldgrade A grade_grade instance containing the old values from the database return: bool False if an error occurred |
| validate_formula($formulastr) X-Ref |
| Validate the formula. param: string $formulastr return: bool true if calculation possible, false otherwise |
| get_displaytype() X-Ref |
| Returns the value of the display type It can be set at 3 levels: grade_item, course setting and site. The lowest level overrides the higher ones. return: int Display type |
| get_decimals() X-Ref |
| Returns the value of the decimals field It can be set at 3 levels: grade_item, course setting and site. The lowest level overrides the higher ones. return: int Decimals (0 - 5) |
| get_formatted_range($rangesdisplaytype=null, $rangesdecimalpoints=null) X-Ref |
| Returns a string representing the range of grademin - grademax for this grade item. param: int $rangesdisplaytype param: int $rangesdecimalpoints return: string |
| get_coefstring() X-Ref |
| Queries parent categories recursively to find the aggregationcoef type that applies to this grade item. return: string|false Returns the coefficient string of false is no coefficient is being used |
| can_control_visibility() X-Ref |
| Returns whether the grade item can control the visibility of the grades return: bool |
| notify_changed($deleted) X-Ref |
| Used to notify the completion system (if necessary) that a user's grade has changed, and clear up a possible score cache. param: bool $deleted True if grade was actually deleted |
| get_context() X-Ref |
| Helper function to get the accurate context for this grade column. return: context |
