Moodle PHP Documentation 4.5
Moodle 4.5dev (Build: 20240606) (d3ae1391abe)
grade_item Class Reference

Class representing a grade item. More...

Inheritance diagram for grade_item:
grade_object

Public Member Functions

 __construct ($params=null, $fetch=true)
 Constructor.
 
 add_idnumber ($idnumber)
 Set idnumber of grade item, updates also course_modules table.
 
 adjust_raw_grade ($rawgrade, $rawmin, $rawmax)
 Given a float grade value or integer grade scale, applies a number of adjustment based on grade_item variables and returns the result.
 
 bounded_grade ($gradevalue)
 Makes sure value is a valid grade value.
 
 can_control_visibility ()
 Returns whether the grade item can control the visibility of the grades.
 
 check_locktime ()
 Lock the grade if needed.
 
 compute ($userid=null)
 Calculates final grade values using the formula in the calculation property.
 
 delete ($source=null)
 Delete all grades and force_regrading of parent category.
 
 delete_all_grades ($source=null)
 Delete all grades.
 
 depends_on ($reset_cache=false)
 Finds out on which other items does this depend directly when doing calculation or category aggregation.
 
 duplicate ()
 Duplicate grade item.
 
 force_regrading ()
 Sets this grade_item's needsupdate to true.
 
 get_calculation ()
 Returns calculation string if grade calculated.
 
 get_coefstring ()
 Queries parent categories recursively to find the aggregationcoef type that applies to this grade item.
 
 get_context ()
 Helper function to get the accurate context for this grade column.
 
 get_decimals ()
 Returns the value of the decimals field.
 
 get_description ()
 A grade item can return a more detailed description which will be added to the header of the column/row in some reports.
 
 get_displaytype ()
 Returns the value of the display type.
 
 get_final ($userid=NULL)
 Returns the final values for this grade item (as imported by module or other source).
 
 get_formatted_range ($rangesdisplaytype=null, $rangesdecimalpoints=null)
 Returns a string representing the range of grademin - grademax for this grade item.
 
 get_grade ($userid, $create=true)
 Get (or create if not exist yet) grade for this user.
 
 get_grade_item ()
 Returns this grade_item.
 
 get_hidden ()
 Check a grade item hidden status.
 
 get_idnumber ()
 Returns the idnumber of this grade_item.
 
 get_item_category ()
 Returns the grade_category for a grade category grade item.
 
 get_locktime ()
 Set the locktime for this grade item.
 
 get_name ($fulltotal=false, $escape=true)
 Returns the most descriptive field for this object.
 
 get_parent_category ()
 Returns the grade_category object this grade_item belongs to (referenced by categoryid) or category attached to category item.
 
 get_record_data ()
 Returns object with fields and values that are defined in database.
 
 get_sortorder ()
 Returns the sortorder of this grade_item.
 
 has_grades ()
 Check to see if there are any existing grades for this grade_item.
 
 has_hidden_grades ($groupsql="", array $params=null, $groupwheresql="")
 Returns the number of grades that are hidden.
 
 has_overridden_grades ()
 Check to see if there are existing overridden grades for this grade_item.
 
 insert ($source=null, $isbulkupdate=false)
 In addition to perform parent\insert(), calls force_regrading() method too.
 
 is_aggregate_item ()
 Returns true if the grade item is an aggreggated type grade.
 
 is_calculated ()
 Checks if grade calculated.
 
 is_category_item ()
 Is the grade item associated with category?
 
 is_course_item ()
 Is the grade item associated with course?
 
 is_editable ()
 Is grading object editable?
 
 is_external_item ()
 Is the grade item external - associated with module, plugin or something else?
 
 is_hidden ()
 Returns the current hidden state of this grade_item.
 
 is_hiddenuntil ()
 Check grade object hidden status.
 
 is_locked ($userid=NULL)
 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.
 
 is_manual_item ()
 Is this a manually graded item?
 
 is_outcome_item ()
 Is this an outcome item?
 
 is_overridable_item ()
 Is the grade item overridable.
 
 is_overridable_item_feedback ()
 Is the grade item feedback overridable.
 
 is_raw_used ()
 Returns true if grade items uses raw grades.
 
 load_item_category ()
 Calls upon the get_item_category method to retrieve the grade_category object from the DB and assigns it to $this->item_category.
 
 load_optional_fields ()
 Makes sure all the optional fields are loaded.
 
 load_outcome ()
 Instantiates a grade_outcome object from the DB if this item's outcomeid variable is set.
 
 load_parent_category ()
 Calls upon the get_parent_category method to retrieve the grade_category object from the DB and assigns it to $this->parent_category.
 
 load_scale ()
 Instantiates a grade_scale object from the DB if this item's scaleid variable is set.
 
 move_after_sortorder ($sortorder)
 Update this grade item's sortorder so that it will appear after $sortorder.
 
 qualifies_for_regrading ()
 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.
 
 refresh_grades ($userid=0)
 Refetch grades from modules, plugins.
 
 regrade_final_grades ($userid=null, ?\core\progress\base $progress=null)
 Performs the necessary calculations on the grades_final referenced by this grade_item.
 
 regrading_finished ()
 Mark regrading as finished successfully.
 
 rescale_grades_keep_percentage ($oldgrademin, $oldgrademax, $newgrademin, $newgrademax, $source=null)
 Update the rawgrademax and rawgrademin for all grade_grades records for this item.
 
 set_aggregation_fields_for_aggregation ($from, $to)
 Update the aggregation fields when the aggregation changed.
 
 set_calculation ($formula)
 Sets this item's calculation (creates it) if not yet set, or updates it if already set (in the DB).
 
 set_hidden ($hidden, $cascade=false)
 Set the hidden status of grade_item and all grades.
 
 set_locked ($lockedstate, $cascade=false, $refresh=true)
 Locks or unlocks this grade_item and (optionally) all its associated final grades.
 
 set_locktime ($locktime)
 Set the locktime for this grade item.
 
 set_parent ($parentid, $updateaggregationfields=true)
 Sets this item's categoryid.
 
 set_sortorder ($sortorder)
 Sets the sortorder of this grade_item.
 
 update ($source=null, $isbulkupdate=false)
 In addition to update() as defined in grade_object, handle the grade_outcome and grade_scale objects.
 
 update_final_grade ($userid, $finalgrade=false, $source=null, $feedback=false, $feedbackformat=FORMAT_MOODLE, $usermodified=null, $timemodified=null, $isbulkupdate=false)
 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.
 
 update_from_db ()
 Using this object's id field, fetches the matching record in the DB, and looks at each variable in turn.
 
 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)
 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.
 
 use_formula ($userid, $params, $useditems, $oldgrade)
 Internal function that does the final grade calculation.
 
 validate_formula ($formulastr)
 Validate the formula.
 

Static Public Member Functions

static denormalize_formula ($formula, $courseid)
 Denormalizes the calculation formula to [idnumber] form.
 
static fetch ($params)
 Finds and returns a grade_item instance based on params.
 
static fetch_all ($params)
 Finds and returns all grade_item instances based on params.
 
static fetch_all_helper ($table, $classname, $params)
 Factory method which uses the parameters to retrieve all matching instances from the database.
 
static fetch_course_item ($courseid)
 Returns the grade item associated with the course.
 
static fix_duplicate_sortorder ($courseid)
 Detect duplicate grade item's sortorder and re-sort them.
 
static normalize_formula ($formula, $courseid)
 Normalizes the calculation formula to [#giXX#] form.
 
static set_properties (&$instance, $params)
 Given an associated array or object, cycles through each key/variable and assigns the value to the corresponding variable in this object.
 

Public Attributes

float $aggregationcoef = 0
 Aggregation coeficient used for weighted averages or extra credit $aggregationcoef.
 
float $aggregationcoef2 = 0
 Aggregation coeficient used for weighted averages only $aggregationcoef2.
 
string $avg
 average information.
 
string $calculation
 Calculation string used for this item.
 
bool $calculation_normalized
 Indicates if we already tried to normalize the grade calculation formula.
 
string $category
 Category name.
 
int $categoryid
 The category this grade_item belongs to (optional).
 
int $cmid
 course module ID
 
int $courseid
 The course this grade_item belongs to.
 
int $decimals = null
 The number of digits after the decimal point symbol.
 
array $dependson_cache = null
 Cached dependson array An array of cached grade item dependencies.
 
int $display = GRADE_DISPLAY_TYPE_DEFAULT
 Display type of the grades (Real, Percentage, Letter, or default).
 
calc_formula $formula
 Math evaluation object A formula object.
 
float $grademax = 100
 Maximum allowable grade.
 
float $grademin = 0
 Minimum allowable grade.
 
float $gradepass = 0
 grade required to pass.
 
int $gradetype = GRADE_TYPE_VALUE
 The type of grade (0 = none, 1 = value, 2 = scale, 3 = text) $gradetype.
 
int $hidden = 0
 0 if visible, 1 always hidden or date not visible until $hidden
 
int $id
 The PK.
 
string $idnumber
 Arbitrary idnumber provided by the module responsible.
 
grade_category $item_category
 The grade_category object referenced $this->iteminstance if itemtype == 'category' or == 'course'.
 
string $iteminfo
 Info and notes about this item.
 
int $iteminstance
 ID of the item module $iteminstance.
 
string $itemmodule
 The module pushing this grade (e.g.
 
string $itemname
 The name of this grade_item (pushed by the module).
 
int $itemnumber
 Number of the item in a series of multiple grades pushed by an activity.
 
string $itemtype
 e.g.
 
int $locked = 0
 Grade item lock flag.
 
int $locktime = 0
 Date after which the grade will be locked.
 
bool $markasoverriddenwhengraded = true
 If we regrade this item should we mark it as overridden?
 
float $multfactor = 1.0
 Multiply all grades by this number.
 
bool $needsupdate = 1
 If set, the whole column will be recalculated, then this flag will be switched off.
 
array $optional_fields = array()
 Array of optional fields with default values - usually long text information that is not always needed.
 
grade_outcome $outcome
 The grade_outcome this grade is associated with, if applicable.
 
int $outcomeid
 The id of the optional grade_outcome associated with this grade_item.
 
grade_category $parent_category
 The grade_category object referenced by $this->categoryid.
 
float $plusfactor = 0
 Add this to all grades.
 
array $required_fields
 Array of required table fields, must start with 'id'.
 
grade_scale $scale
 The grade_scale object referenced by $this->scaleid.
 
int $scaleid
 id of the scale, if this grade is based on a scale.
 
int $sortorder = 0
 Sorting order of the columns.
 
string $table = 'grade_items'
 DB Table (used by grade_object).
 
int $timecreated
 The first time this grade_object was created.
 
int $timemodified
 The last time this grade_object was modified.
 
 $weightoverride = 0
 If set, the grade item's weight has been overridden by a user and should not be automatically adjusted.
 

Protected Member Functions

 add_feedback_files (int $historyid=null)
 Handles adding feedback files in the gradebook.
 
 delete_feedback_files ()
 Handles deleting feedback files in the gradebook.
 
 notify_changed ($deleted)
 Used to notify the completion system (if necessary) that a user's grade has changed, and clear up a possible score cache.
 
 update_feedback_files (int $historyid=null)
 Handles updating feedback files in the gradebook.
 

Static Protected Member Functions

static fetch_helper ($table, $classname, $params)
 Factory method which uses the parameters to retrieve matching instances from the database.
 

Detailed Description

Class representing a grade item.

It is responsible for handling its DB representation, modifying and returning its metadata.

License
http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later

Constructor & Destructor Documentation

◆ __construct()

grade_item::__construct ( $params = null,
$fetch = true )

Constructor.

Optionally (and by default) attempts to fetch corresponding row from the database

Parameters
array$paramsAn array with required parameters for this grade object.
bool$fetchWhether to fetch corresponding row from the database or not, optional fields might not be defined if false used

Reimplemented from grade_object.

Member Function Documentation

◆ add_feedback_files()

grade_object::add_feedback_files ( int $historyid = null)
protectedinherited

Handles adding feedback files in the gradebook.

Parameters
int | null$historyid

Reimplemented in grade_grade.

◆ add_idnumber()

grade_item::add_idnumber ( $idnumber)

Set idnumber of grade item, updates also course_modules table.

Parameters
string$idnumber(without magic quotes)
Return values
boolsuccess

◆ adjust_raw_grade()

grade_item::adjust_raw_grade ( $rawgrade,
$rawmin,
$rawmax )

Given a float grade value or integer grade scale, applies a number of adjustment based on grade_item variables and returns the result.

Parameters
float$rawgradeThe raw grade value
float$rawminoriginal rawmin
float$rawmaxoriginal rawmax
Return values
mixed

◆ bounded_grade()

grade_item::bounded_grade ( $gradevalue)

Makes sure value is a valid grade value.

Parameters
float$gradevalue
Return values
mixedfloat or int fixed grade value

◆ can_control_visibility()

grade_item::can_control_visibility ( )

Returns whether the grade item can control the visibility of the grades.

Return values
bool

Reimplemented from grade_object.

◆ check_locktime()

grade_item::check_locktime ( )

Lock the grade if needed.

Make sure this is called only when final grades are valid

◆ compute()

grade_item::compute ( $userid = null)

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.

Parameters
int$useridSupply a user ID to limit the calculations to the grades of a single user
Return values
boolfalse if error

◆ delete()

grade_item::delete ( $source = null)

Delete all grades and force_regrading of parent category.

Parameters
string$sourcefrom where was the object deleted (mod/forum, manual, etc.)
Return values
boolsuccess

Reimplemented from grade_object.

◆ delete_all_grades()

grade_item::delete_all_grades ( $source = null)

Delete all grades.

Parameters
string$sourcefrom where was the object deleted (mod/forum, manual, etc.)
Return values
bool

◆ delete_feedback_files()

grade_object::delete_feedback_files ( )
protectedinherited

Handles deleting feedback files in the gradebook.

Reimplemented in grade_grade.

◆ denormalize_formula()

static grade_item::denormalize_formula ( $formula,
$courseid )
static

Denormalizes the calculation formula to [idnumber] form.

Parameters
string$formulaA string representation of the formula
int$courseidThe course ID
Return values
stringThe denormalized formula as a string

◆ depends_on()

grade_item::depends_on ( $reset_cache = false)

Finds out on which other items does this depend directly when doing calculation or category aggregation.

Parameters
bool$reset_cache
Return values
arrayof grade_item IDs this one depends on

◆ duplicate()

grade_item::duplicate ( )

Duplicate grade item.

Return values
grade_itemThe duplicate grade item

◆ fetch()

static grade_item::fetch ( $params)
static

Finds and returns a grade_item instance based on params.

Parameters
array$paramsassociative arrays varname=>value
Return values
grade_item|boolReturns a grade_item instance or false if none found

Reimplemented from grade_object.

◆ fetch_all()

static grade_item::fetch_all ( $params)
static

Finds and returns all grade_item instances based on params.

Parameters
array$paramsassociative arrays varname=>value
Return values
arrayarray of grade_item instances or false if none found.

Reimplemented from grade_object.

◆ fetch_all_helper()

static grade_object::fetch_all_helper ( $table,
$classname,
$params )
staticinherited

Factory method which uses the parameters to retrieve all matching instances from the database.

Parameters
string$tableThe table to retrieve from
string$classnameThe name of the class to instantiate
array$paramsAn array of conditions like $fieldname => $fieldvalue
Return values
array|boolArray of object instances or false if not found

◆ fetch_course_item()

static grade_item::fetch_course_item ( $courseid)
static

Returns the grade item associated with the course.

Parameters
int$courseid
Return values
grade_itemCourse level grade item object

◆ fetch_helper()

static grade_object::fetch_helper ( $table,
$classname,
$params )
staticprotectedinherited

Factory method which uses the parameters to retrieve matching instances from the database.

Parameters
string$tableThe table to retrieve from
string$classnameThe name of the class to instantiate
array$paramsAn array of conditions like $fieldname => $fieldvalue
Return values
mixedAn object instance or false if not found

◆ fix_duplicate_sortorder()

static grade_item::fix_duplicate_sortorder ( $courseid)
static

Detect duplicate grade item's sortorder and re-sort them.

Note: Duplicate sortorder will be introduced while duplicating activities or merging two courses.

Parameters
int$courseidid of the course for which grade_items sortorder need to be fixed.

◆ force_regrading()

grade_item::force_regrading ( )

Sets this grade_item's needsupdate to true.

Also marks the course item as needing update.

Return values
void

◆ get_calculation()

grade_item::get_calculation ( )

Returns calculation string if grade calculated.

Return values
stringReturns the grade item's calculation if calculation is used, null if not

◆ get_coefstring()

grade_item::get_coefstring ( )

Queries parent categories recursively to find the aggregationcoef type that applies to this grade item.

Return values
string|falseReturns the coefficient string of false is no coefficient is being used

◆ get_context()

grade_item::get_context ( )

Helper function to get the accurate context for this grade column.

Return values
context

◆ get_decimals()

grade_item::get_decimals ( )

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 values
intDecimals (0 - 5)

◆ get_description()

grade_item::get_description ( )

A grade item can return a more detailed description which will be added to the header of the column/row in some reports.

Return values
stringdescription

◆ get_displaytype()

grade_item::get_displaytype ( )

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 values
intDisplay type

◆ get_final()

grade_item::get_final ( $userid = NULL)

Returns the final values for this grade item (as imported by module or other source).

Parameters
int$useridOptional: to retrieve a single user's final grade
Return values
array|grade_gradeAn array of all grade_grade instances for this grade_item, or a single grade_grade instance.

◆ get_formatted_range()

grade_item::get_formatted_range ( $rangesdisplaytype = null,
$rangesdecimalpoints = null )

Returns a string representing the range of grademin - grademax for this grade item.

Parameters
int$rangesdisplaytype
int$rangesdecimalpoints
Return values
string

◆ get_grade()

grade_item::get_grade ( $userid,
$create = true )

Get (or create if not exist yet) grade for this user.

Parameters
int$useridThe user ID
bool$createIf true and the user has no grade for this grade item a new grade_grade instance will be inserted
Return values
grade_gradeThe grade_grade instance for the user for this grade item

◆ get_grade_item()

grade_item::get_grade_item ( )

Returns this grade_item.

This method is also available in grade_category, for cases where the object type is not know.

Return values
grade_item

◆ get_hidden()

grade_object::get_hidden ( )
inherited

Check a grade item hidden status.

Return values
int0 means visible, 1 hidden always, a timestamp means "hidden until"

Reimplemented in grade_grade.

◆ get_idnumber()

grade_item::get_idnumber ( )

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 values
stringThe grade item idnumber

◆ get_item_category()

grade_item::get_item_category ( )

Returns the grade_category for a grade category grade item.

Return values
grade_category|boolReturns a grade_category instance if applicable or false otherwise

◆ get_locktime()

grade_item::get_locktime ( )

Set the locktime for this grade item.

Return values
int\$locktimetimestamp for lock to activate

◆ get_name()

grade_item::get_name ( $fulltotal = false,
$escape = true )

Returns the most descriptive field for this object.

Determines what type of grade item it is then returns the appropriate string

Parameters
bool$fulltotalIf the item is a category total, returns $categoryname."total" instead of "Category total" or "Course total"
bool$escapeWhether the returned category name is to be HTML escaped or not.
Return values
stringname

◆ get_parent_category()

grade_item::get_parent_category ( )

Returns the grade_category object this grade_item belongs to (referenced by categoryid) or category attached to category item.

Return values
grade_category|boolReturns a grade_category object if applicable or false if this is a course item

◆ get_record_data()

grade_object::get_record_data ( )
inherited

Returns object with fields and values that are defined in database.

Return values
stdClass

◆ get_sortorder()

grade_item::get_sortorder ( )

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 values
intSort order

◆ has_grades()

grade_item::has_grades ( )

Check to see if there are any existing grades for this grade_item.

Return values
boolean- true if there are valid grades for this grade_item.

◆ has_hidden_grades()

grade_item::has_hidden_grades ( $groupsql = "",
array $params = null,
$groupwheresql = "" )

Returns the number of grades that are hidden.

Parameters
string$groupsqlSQL to limit the query by group
array$paramsSQL params for $groupsql
string$groupwheresqlWhere conditions for $groupsql
Return values
intThe number of hidden grades

◆ has_overridden_grades()

grade_item::has_overridden_grades ( )

Check to see if there are existing overridden grades for this grade_item.

Return values
boolean- true if there are overridden grades for this grade_item.

◆ insert()

grade_item::insert ( $source = null,
$isbulkupdate = false )

In addition to perform parent\insert(), calls force_regrading() method too.

Parameters
string$sourceFrom where was the object inserted (mod/forum, manual, etc.)
string$isbulkupdateIf bulk grade update is happening.
Return values
intPK ID if successful, false otherwise

Reimplemented from grade_object.

◆ is_aggregate_item()

grade_item::is_aggregate_item ( )

Returns true if the grade item is an aggreggated type grade.

Since
Moodle 2.8.7, 2.9.1
Return values
bool

◆ is_calculated()

grade_item::is_calculated ( )

Checks if grade calculated.

Returns this object's calculation.

Return values
booltrue if grade item calculated.

◆ is_category_item()

grade_item::is_category_item ( )

Is the grade item associated with category?

Return values
bool

◆ is_course_item()

grade_item::is_course_item ( )

Is the grade item associated with course?

Return values
bool

◆ is_editable()

grade_item::is_editable ( )

Is grading object editable?

Return values
bool

◆ is_external_item()

grade_item::is_external_item ( )

Is the grade item external - associated with module, plugin or something else?

Return values
bool

◆ is_hidden()

grade_object::is_hidden ( )
inherited

Returns the current hidden state of this grade_item.

This depends on the grade object hidden setting and the current time if hidden is set to a "hidden until" timestamp

Return values
boolCurrent hidden state

Reimplemented in grade_grade.

◆ is_hiddenuntil()

grade_object::is_hiddenuntil ( )
inherited

Check grade object hidden status.

Return values
boolTrue if a "hidden until" timestamp is set, false if grade object is set to always visible or always hidden.

Reimplemented in grade_grade.

◆ is_locked()

grade_item::is_locked ( $userid = NULL)

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.

Parameters
int$useridThe user's ID
Return values
boolLocked state

◆ is_manual_item()

grade_item::is_manual_item ( )

Is this a manually graded item?

Return values
bool

◆ is_outcome_item()

grade_item::is_outcome_item ( )

Is this an outcome item?

Return values
bool

◆ is_overridable_item()

grade_item::is_overridable_item ( )

Is the grade item overridable.

Return values
bool

◆ is_overridable_item_feedback()

grade_item::is_overridable_item_feedback ( )

Is the grade item feedback overridable.

Return values
bool

◆ is_raw_used()

grade_item::is_raw_used ( )

Returns true if grade items uses raw grades.

Return values
bool

◆ load_item_category()

grade_item::load_item_category ( )

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 values
grade_category

◆ load_optional_fields()

grade_object::load_optional_fields ( )
inherited

Makes sure all the optional fields are loaded.

If id present, meaning the instance exists in the database, then data will be fetched from the database. Defaults are used for new instances.

◆ load_outcome()

grade_item::load_outcome ( )

Instantiates a grade_outcome object from the DB if this item's outcomeid variable is set.

Return values
grade_outcomeThis grade item's associated grade_outcome or null

◆ load_parent_category()

grade_item::load_parent_category ( )

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 values
grade_categoryThis grade item's parent grade_category.

◆ load_scale()

grade_item::load_scale ( )

Instantiates a grade_scale object from the DB if this item's scaleid variable is set.

Return values
grade_scaleReturns a grade_scale object or null if no scale used

◆ move_after_sortorder()

grade_item::move_after_sortorder ( $sortorder)

Update this grade item's sortorder so that it will appear after $sortorder.

Parameters
int$sortorderThe sort order to place this grade item after

◆ normalize_formula()

static grade_item::normalize_formula ( $formula,
$courseid )
static

Normalizes the calculation formula to [#giXX#] form.

Parameters
string$formulaThe formula
int$courseidThe course ID
Return values
stringThe normalized formula as a string

◆ notify_changed()

grade_item::notify_changed ( $deleted)
protected

Used to notify the completion system (if necessary) that a user's grade has changed, and clear up a possible score cache.

Parameters
bool$deletedTrue if grade was actually deleted

Reimplemented from grade_object.

◆ qualifies_for_regrading()

grade_item::qualifies_for_regrading ( )

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 values
bool

◆ refresh_grades()

grade_item::refresh_grades ( $userid = 0)

Refetch grades from modules, plugins.

Parameters
int$useridoptional, limit the refetch to a single user
Return values
boolReturns true on success or if there is nothing to do

◆ regrade_final_grades()

grade_item::regrade_final_grades ( $userid = null,
?\core\progress\base $progress = null )

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!!

Parameters
int$useridSupply a user ID to limit the regrading to a single user
core\progress\base | null$progressOptional progress object, will be updated per user
Return values
booltrue if ok, error string otherwise

◆ regrading_finished()

grade_item::regrading_finished ( )

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.

◆ rescale_grades_keep_percentage()

grade_item::rescale_grades_keep_percentage ( $oldgrademin,
$oldgrademax,
$newgrademin,
$newgrademax,
$source = null )

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.

Parameters
float$oldgrademinThe previous grade min value
float$oldgrademaxThe previous grade max value
float$newgrademinThe new grade min value
float$newgrademaxThe new grade max value
string$sourcefrom where was the object inserted (mod/forum, manual, etc.)
Return values
boolTrue on success

◆ set_aggregation_fields_for_aggregation()

grade_item::set_aggregation_fields_for_aggregation ( $from,
$to )

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. grade_item::update() has to be called manually after using this method.

Parameters
int$fromAggregation method constant value.
int$toAggregation method constant value.
Return values
booleanTrue when at least one field was changed, false otherwise

◆ set_calculation()

grade_item::set_calculation ( $formula)

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.

Parameters
string$formulastring representation of formula used for calculation
Return values
boolsuccess

◆ set_hidden()

grade_item::set_hidden ( $hidden,
$cascade = false )

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

Parameters
int$hiddennew hidden status
bool$cascadeapply to child objects too

Reimplemented from grade_object.

◆ set_locked()

grade_item::set_locked ( $lockedstate,
$cascade = false,
$refresh = true )

Locks or unlocks this grade_item and (optionally) all its associated final grades.

Parameters
int$lockedstate0, 1 or a timestamp int(10) after which date the item will be locked.
bool$cascadeLock/unlock child objects too
bool$refreshRefresh grades when unlocking
Return values
boolTrue if grade_item all grades updated, false if at least one update fails

◆ set_locktime()

grade_item::set_locktime ( $locktime)

Set the locktime for this grade item.

Parameters
int$locktimetimestamp for lock to activate
Return values
void

◆ set_parent()

grade_item::set_parent ( $parentid,
$updateaggregationfields = true )

Sets this item's categoryid.

A generic method shared by objects that have a parent id of some kind.

Parameters
int$parentidThe ID of the new parent
bool$updateaggregationfieldsWhether or not to convert the aggregation fields when switching between category. Set this to false when the aggregation fields have been updated in prevision of the new category, typically when the item is freshly created.
Return values
boolTrue if success

◆ set_properties()

static grade_object::set_properties ( & $instance,
$params )
staticinherited

Given an associated array or object, cycles through each key/variable and assigns the value to the corresponding variable in this object.

Parameters
grade_object$instanceThe object to set the properties on
array$paramsAn array of properties to set like $propertyname => $propertyvalue
Return values
array|stdClassEither an associative array or an object containing property name, property value pairs

Reimplemented in grade_category.

◆ set_sortorder()

grade_item::set_sortorder ( $sortorder)

Sets the sortorder of this grade_item.

This method is also available in grade_category, for cases where the object type is not know.

Parameters
int$sortorder

◆ update()

grade_item::update ( $source = null,
$isbulkupdate = false )

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.

Parameters
string$sourcefrom where was the object inserted (mod/forum, manual, etc.)
bool$isbulkupdateIf bulk grade update is happening.
Return values
boolsuccess

Reimplemented from grade_object.

◆ update_feedback_files()

grade_object::update_feedback_files ( int $historyid = null)
protectedinherited

Handles updating feedback files in the gradebook.

Parameters
int | null$historyid

Reimplemented in grade_grade.

◆ update_final_grade()

grade_item::update_final_grade ( $userid,
$finalgrade = false,
$source = null,
$feedback = false,
$feedbackformat = FORMAT_MOODLE,
$usermodified = null,
$timemodified = null,
$isbulkupdate = false )

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.

Parameters
int$useridThe graded user
float | false$finalgradeThe float value of final grade, false means do not change
string$sourceThe modification source
string$feedbackOptional teacher feedback
int$feedbackformatA format like FORMAT_PLAIN or FORMAT_HTML
int$usermodifiedThe ID of the user making the modification
int$timemodifiedOptional parameter to set the time modified, if not present current time.
bool$isbulkupdateIf bulk grade update is happening.
Return values
boolsuccess

◆ update_from_db()

grade_object::update_from_db ( )
inherited

Using this object's id field, fetches the matching record in the DB, and looks at each variable in turn.

If the DB has different data, the db's data is used to update the object. This is different from the update() function, which acts on the DB record based on the object.

Return values
boolTrue if successful

◆ update_raw_grade()

grade_item::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 )

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.

Parameters
int$useridthe graded user
mixed$rawgradefloat value of raw grade - false means do not change
string$sourcemodification source
string$feedbackoptional teacher feedback
int$feedbackformatA format like FORMAT_PLAIN or FORMAT_HTML
int$usermodifiedthe ID of the user who did the grading
int$dategradedA timestamp of when the student's work was graded
int$datesubmittedA timestamp of when the student's work was submitted
grade_grade$gradeA grade object, useful for bulk upgrades
array$feedbackfilesAn array identifying the location of files we want to copy to the gradebook feedback area. Example - [ 'contextid' => 1, 'component' => 'mod_xyz', 'filearea' => 'mod_xyz_feedback', 'itemid' => 2 ];
bool$isbulkupdateIf bulk grade update is happening.
Return values
boolsuccess

◆ use_formula()

grade_item::use_formula ( $userid,
$params,
$useditems,
$oldgrade )

Internal function that does the final grade calculation.

Parameters
int$useridThe user ID
array$paramsAn array of grade items of the form {'gi'.$itemid]} => $finalgrade
array$useditemsAn array of grade item IDs that this grade item depends on plus its own ID
grade_grade$oldgradeA grade_grade instance containing the old values from the database
Return values
boolFalse if an error occurred

◆ validate_formula()

grade_item::validate_formula ( $formulastr)

Validate the formula.

Parameters
string$formulastr
Return values
booltrue if calculation possible, false otherwise

Member Data Documentation

◆ $calculation

string grade_item::$calculation

Calculation string used for this item.

$calculation

◆ $calculation_normalized

bool grade_item::$calculation_normalized

Indicates if we already tried to normalize the grade calculation formula.

This flag helps to minimize db access when broken formulas used in calculation.

◆ $categoryid

int grade_item::$categoryid

The category this grade_item belongs to (optional).

$categoryid

◆ $courseid

int grade_item::$courseid

The course this grade_item belongs to.

$courseid

◆ $decimals

int grade_item::$decimals = null

The number of digits after the decimal point symbol.

Applies only to REAL and PERCENTAGE grade display types. $decimals

◆ $display

int grade_item::$display = GRADE_DISPLAY_TYPE_DEFAULT

Display type of the grades (Real, Percentage, Letter, or default).

$display

◆ $grademax

float grade_item::$grademax = 100

Maximum allowable grade.

$grademax

◆ $grademin

float grade_item::$grademin = 0

Minimum allowable grade.

$grademin

◆ $gradepass

float grade_item::$gradepass = 0

grade required to pass.

(grademin <= gradepass <= grademax) $gradepass

◆ $id

int grade_object::$id
inherited

The PK.

$id

◆ $idnumber

string grade_item::$idnumber

Arbitrary idnumber provided by the module responsible.

$idnumber

◆ $item_category

grade_category grade_item::$item_category

The grade_category object referenced $this->iteminstance if itemtype == 'category' or == 'course'.

$item_category

◆ $iteminfo

string grade_item::$iteminfo

Info and notes about this item.

$iteminfo

◆ $itemmodule

string grade_item::$itemmodule

The module pushing this grade (e.g.

'forum', 'quiz', 'assignment' etc). $itemmodule

◆ $itemname

string grade_item::$itemname

The name of this grade_item (pushed by the module).

$itemname

◆ $itemnumber

int grade_item::$itemnumber

Number of the item in a series of multiple grades pushed by an activity.

$itemnumber

◆ $itemtype

string grade_item::$itemtype

e.g.

'category', 'course' and 'mod', 'blocks', 'import', etc... $itemtype

◆ $locked

int grade_item::$locked = 0

Grade item lock flag.

Empty if not locked, locked if any value present, usually date when item was locked. Locking prevents updating. $locked

◆ $locktime

int grade_item::$locktime = 0

Date after which the grade will be locked.

Empty means no automatic locking. $locktime

◆ $multfactor

float grade_item::$multfactor = 1.0

Multiply all grades by this number.

$multfactor

◆ $needsupdate

bool grade_item::$needsupdate = 1

If set, the whole column will be recalculated, then this flag will be switched off.

$needsupdate

◆ $optional_fields

array grade_object::$optional_fields = array()
inherited

Array of optional fields with default values - usually long text information that is not always needed.

If you want to create an instance without optional fields use: new grade_object($only_required_fields, false); $optional_fields

◆ $outcome

grade_outcome grade_item::$outcome

The grade_outcome this grade is associated with, if applicable.

$outcome

◆ $outcomeid

int grade_item::$outcomeid

The id of the optional grade_outcome associated with this grade_item.

$outcomeid

◆ $parent_category

grade_category grade_item::$parent_category

The grade_category object referenced by $this->categoryid.

$parent_category

◆ $plusfactor

float grade_item::$plusfactor = 0

Add this to all grades.

$plusfactor

◆ $required_fields

array grade_item::$required_fields
Initial value:
= array('id', 'courseid', 'categoryid', 'itemname', 'itemtype', 'itemmodule', 'iteminstance',
'itemnumber', 'iteminfo', 'idnumber', 'calculation', 'gradetype', 'grademax', 'grademin',
'scaleid', 'outcomeid', 'gradepass', 'multfactor', 'plusfactor', 'aggregationcoef',
'aggregationcoef2', 'sortorder', 'display', 'decimals', 'hidden', 'locked', 'locktime',
'needsupdate', 'weightoverride', 'timecreated', 'timemodified')

Array of required table fields, must start with 'id'.

$required_fields

◆ $scale

grade_scale grade_item::$scale

The grade_scale object referenced by $this->scaleid.

$scale

◆ $scaleid

int grade_item::$scaleid

id of the scale, if this grade is based on a scale.

$scaleid

◆ $sortorder

int grade_item::$sortorder = 0

Sorting order of the columns.

$sortorder

◆ $table

string grade_item::$table = 'grade_items'

DB Table (used by grade_object).

$table

◆ $timecreated

int grade_object::$timecreated
inherited

The first time this grade_object was created.

$timecreated

◆ $timemodified

int grade_object::$timemodified
inherited

The last time this grade_object was modified.

$timemodified


The documentation for this class was generated from the following file: