Class representing a grade item. More...

Inheritance diagram for grade_item:

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.

Copyright: 2006 Nicolas Connault

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	$params	An array with required parameters for this grade object.
bool	$fetch	Whether 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

bool success

◆ 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	$rawgrade	The raw grade value
float	$rawmin	original rawmin
float	$rawmax	original rawmax

Return values

mixed

◆ bounded_grade()

grade_item::bounded_grade ( $gradevalue )

Makes sure value is a valid grade value.

Parameters

float $gradevalue

Return values

mixed float 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 $userid Supply a user ID to limit the calculations to the grades of a single user

Return values

bool	false if error

◆ delete()

grade_item::delete ( $source = null )

Delete all grades and force_regrading of parent category.

Parameters

string $source from where was the object deleted (mod/forum, manual, etc.)

Return values

bool success

Reimplemented from grade_object.

◆ delete_all_grades()

grade_item::delete_all_grades ( $source = null )

Delete all grades.

Parameters

string $source from 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	$formula	A string representation of the formula
int	$courseid	The course ID

Return values

string The 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

array of grade_item IDs this one depends on

◆ duplicate()

grade_item::duplicate ( )

Duplicate grade item.

Return values

grade_item The duplicate grade item

◆ fetch()

static grade_item::fetch ( $params )

static

Finds and returns a grade_item instance based on params.

Parameters

array $params associative arrays varname=>value

Return values

grade_item|bool Returns 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 $params associative arrays varname=>value

Return values

array array 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	$table	The table to retrieve from
string	$classname	The name of the class to instantiate
array	$params	An array of conditions like $fieldname => $fieldvalue

Return values

array|bool Array 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_item Course 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	$table	The table to retrieve from
string	$classname	The name of the class to instantiate
array	$params	An array of conditions like $fieldname => $fieldvalue

Return values

mixed An 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 $courseid id 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

string Returns 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|false Returns 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

int	Decimals (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

string description

◆ 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

int	Display 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 $userid Optional: to retrieve a single user's final grade

Return values

array|grade_grade An 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	$userid	The user ID
bool	$create	If true and the user has no grade for this grade item a new grade_grade instance will be inserted

Return values

grade_grade The 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

int	0 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

string The 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|bool Returns 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\$locktime timestamp 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	$fulltotal	If the item is a category total, returns $categoryname."total" instead of "Category total" or "Course total"
bool	$escape	Whether the returned category name is to be HTML escaped or not.

Return values

string name

◆ 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|bool Returns 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

int	Sort 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	$groupsql	SQL to limit the query by group
array	$params	SQL params for $groupsql
string	$groupwheresql	Where conditions for $groupsql

Return values

int	The 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	$source	From where was the object inserted (mod/forum, manual, etc.)
string	$isbulkupdate	If bulk grade update is happening.

Return values

int	PK 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

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

bool	Current hidden state

Reimplemented in grade_grade.

◆ is_hiddenuntil()

grade_object::is_hiddenuntil ( )

inherited

Check grade object hidden status.

Return values

bool	True 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 $userid The user's ID

Return values

bool	Locked 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_outcome This 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_category This 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_scale Returns 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 $sortorder The 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	$formula	The formula
int	$courseid	The course ID

Return values

string The 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 $deleted True 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 $userid optional, limit the refetch to a single user

Return values

bool	Returns 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	$userid	Supply a user ID to limit the regrading to a single user
core\progress\base \| null	$progress	Optional progress object, will be updated per user

Return values

bool	true 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	$oldgrademin	The previous grade min value
float	$oldgrademax	The previous grade max value
float	$newgrademin	The new grade min value
float	$newgrademax	The new grade max value
string	$source	from where was the object inserted (mod/forum, manual, etc.)

Return values

bool	True 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	$from	Aggregation method constant value.
int	$to	Aggregation method constant value.

Return values

boolean True 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 $formula string representation of formula used for calculation

Return values

bool success

◆ 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	$hidden	new hidden status
bool	$cascade	apply 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	$lockedstate	0, 1 or a timestamp int(10) after which date the item will be locked.
bool	$cascade	Lock/unlock child objects too
bool	$refresh	Refresh grades when unlocking

Return values

bool	True 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 $locktime timestamp 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	$parentid	The ID of the new parent
bool	$updateaggregationfields	Whether 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

bool	True 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	$instance	The object to set the properties on
array	$params	An array of properties to set like $propertyname => $propertyvalue

Return values

array|stdClass Either 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	$source	from where was the object inserted (mod/forum, manual, etc.)
bool	$isbulkupdate	If bulk grade update is happening.

Return values

bool success

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	$userid	The graded user
float \| false	$finalgrade	The float value of final grade, false means do not change
string	$source	The modification source
string	$feedback	Optional teacher feedback
int	$feedbackformat	A format like FORMAT_PLAIN or FORMAT_HTML
int	$usermodified	The ID of the user making the modification
int	$timemodified	Optional parameter to set the time modified, if not present current time.
bool	$isbulkupdate	If bulk grade update is happening.

Return values

bool success

◆ 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

bool	True 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	$userid	the graded user
mixed	$rawgrade	float value of raw grade - false means do not change
string	$source	modification source
string	$feedback	optional teacher feedback
int	$feedbackformat	A format like FORMAT_PLAIN or FORMAT_HTML
int	$usermodified	the ID of the user who did the grading
int	$dategraded	A timestamp of when the student's work was graded
int	$datesubmitted	A timestamp of when the student's work was submitted
grade_grade	$grade	A grade object, useful for bulk upgrades
array	$feedbackfiles	An 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	$isbulkupdate	If bulk grade update is happening.

Return values

bool success

◆ use_formula()

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

Internal function that does the final grade calculation.

Parameters

int	$userid	The user ID
array	$params	An array of grade items of the form {'gi'.$itemid]} => $finalgrade
array	$useditems	An array of grade item IDs that this grade item depends on plus its own ID
grade_grade	$oldgrade	A grade_grade instance containing the old values from the database

Return values

bool	False if an error occurred

◆ validate_formula()

grade_item::validate_formula ( $formulastr )

Validate the formula.

Parameters

string $formulastr

Return values

bool	true 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:

lib/grade/grade_item.php

Public Member Functions

Static Public Member Functions

Public Attributes

Protected Member Functions

Static Protected Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ __construct()

Member Function Documentation

◆ add_feedback_files()

◆ add_idnumber()

◆ adjust_raw_grade()

◆ bounded_grade()

◆ can_control_visibility()

◆ check_locktime()

◆ compute()

◆ delete()

◆ delete_all_grades()

◆ delete_feedback_files()

◆ denormalize_formula()

◆ depends_on()

◆ duplicate()

◆ fetch()

◆ fetch_all()

◆ fetch_all_helper()

◆ fetch_course_item()

◆ fetch_helper()

◆ fix_duplicate_sortorder()

◆ force_regrading()

◆ get_calculation()

◆ get_coefstring()

◆ get_context()

◆ get_decimals()

◆ get_description()

◆ get_displaytype()

◆ get_final()

◆ get_formatted_range()

◆ get_grade()

◆ get_grade_item()

◆ get_hidden()

◆ get_idnumber()

◆ get_item_category()

◆ get_locktime()

◆ get_name()

◆ get_parent_category()

◆ get_record_data()

◆ get_sortorder()

◆ has_grades()

◆ has_hidden_grades()

◆ has_overridden_grades()

◆ insert()

◆ is_aggregate_item()

◆ is_calculated()

◆ is_category_item()

◆ is_course_item()

◆ is_editable()

◆ is_external_item()

◆ is_hidden()

◆ is_hiddenuntil()

◆ is_locked()

◆ is_manual_item()

◆ is_outcome_item()

◆ is_overridable_item()

◆ is_overridable_item_feedback()

◆ is_raw_used()

◆ load_item_category()

◆ load_optional_fields()

◆ load_outcome()

◆ load_parent_category()

◆ load_scale()

◆ move_after_sortorder()

◆ normalize_formula()

◆ notify_changed()

◆ qualifies_for_regrading()

◆ refresh_grades()

◆ regrade_final_grades()

◆ regrading_finished()

◆ rescale_grades_keep_percentage()

◆ set_aggregation_fields_for_aggregation()

◆ set_calculation()