 |
Moodle PHP Documentation 4.3
Moodle 4.3.5 (Build: 20240610) (7dcfaa79f78)
|
|
Moodle PHP Documentation 4.3
Moodle 4.3.5 (Build: 20240610) (7dcfaa79f78)
|
Class representing a grade item. More...
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. | |
Class representing a grade item.
It is responsible for handling its DB representation, modifying and returning its metadata.
| grade_item::__construct | ( | $params = null, | |
| $fetch = true ) |
Constructor.
Optionally (and by default) attempts to fetch corresponding row from the database
| 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.
|
protectedinherited |
Handles adding feedback files in the gradebook.
| int | null | $historyid |
Reimplemented in grade_grade.
| grade_item::add_idnumber | ( | $idnumber | ) |
Set idnumber of grade item, updates also course_modules table.
| string | $idnumber | (without magic quotes) |
| bool | success |
| 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.
| float | $rawgrade | The raw grade value |
| float | $rawmin | original rawmin |
| float | $rawmax | original rawmax |
| mixed |
| grade_item::bounded_grade | ( | $gradevalue | ) |
Makes sure value is a valid grade value.
| float | $gradevalue |
| mixed | float or int fixed grade value |
| grade_item::can_control_visibility | ( | ) |
Returns whether the grade item can control the visibility of the grades.
| bool |
Reimplemented from grade_object.
| grade_item::check_locktime | ( | ) |
Lock the grade if needed.
Make sure this is called only when final grades are valid
| 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.
| int | $userid | Supply a user ID to limit the calculations to the grades of a single user |
| bool | false if error |
| grade_item::delete | ( | $source = null | ) |
Delete all grades and force_regrading of parent category.
| string | $source | from where was the object deleted (mod/forum, manual, etc.) |
| bool | success |
Reimplemented from grade_object.
| grade_item::delete_all_grades | ( | $source = null | ) |
Delete all grades.
| string | $source | from where was the object deleted (mod/forum, manual, etc.) |
| bool |
|
protectedinherited |
Handles deleting feedback files in the gradebook.
Reimplemented in grade_grade.
|
static |
Denormalizes the calculation formula to [idnumber] form.
| string | $formula | A string representation of the formula |
| int | $courseid | The course ID |
| string | The denormalized formula as a string |
| grade_item::depends_on | ( | $reset_cache = false | ) |
Finds out on which other items does this depend directly when doing calculation or category aggregation.
| bool | $reset_cache |
| array | of grade_item IDs this one depends on |
| grade_item::duplicate | ( | ) |
Duplicate grade item.
| grade_item | The duplicate grade item |
|
static |
Finds and returns a grade_item instance based on params.
| array | $params | associative arrays varname=>value |
| grade_item|bool | Returns a grade_item instance or false if none found |
Reimplemented from grade_object.
|
static |
Finds and returns all grade_item instances based on params.
| array | $params | associative arrays varname=>value |
| array | array of grade_item instances or false if none found. |
Reimplemented from grade_object.
|
staticinherited |
Factory method which uses the parameters to retrieve all matching instances from the database.
| 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 |
| array|bool | Array of object instances or false if not found |
|
static |
Returns the grade item associated with the course.
| int | $courseid |
| grade_item | Course level grade item object |
|
staticprotectedinherited |
Factory method which uses the parameters to retrieve matching instances from the database.
| 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 |
| mixed | An object instance or false if not found |
|
static |
Detect duplicate grade item's sortorder and re-sort them.
Note: Duplicate sortorder will be introduced while duplicating activities or merging two courses.
| int | $courseid | id of the course for which grade_items sortorder need to be fixed. |
| grade_item::force_regrading | ( | ) |
Sets this grade_item's needsupdate to true.
Also marks the course item as needing update.
| void |
| grade_item::get_calculation | ( | ) |
Returns calculation string if grade calculated.
| string | Returns the grade item's calculation if calculation is used, null if not |
| grade_item::get_coefstring | ( | ) |
Queries parent categories recursively to find the aggregationcoef type that applies to this grade item.
| string|false | Returns the coefficient string of false is no coefficient is being used |
| grade_item::get_context | ( | ) |
Helper function to get the accurate context for this grade column.
| context |
| 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.
| int | Decimals (0 - 5) |
| 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.
| string | description |
| 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.
| int | Display type |
| grade_item::get_final | ( | $userid = NULL | ) |
Returns the final values for this grade item (as imported by module or other source).
| int | $userid | Optional: to retrieve a single user's final grade |
| array|grade_grade | An array of all grade_grade instances for this grade_item, or a single grade_grade instance. |
| grade_item::get_formatted_range | ( | $rangesdisplaytype = null, | |
| $rangesdecimalpoints = null ) |
Returns a string representing the range of grademin - grademax for this grade item.
| int | $rangesdisplaytype | |
| int | $rangesdecimalpoints |
| string |
| grade_item::get_grade | ( | $userid, | |
| $create = true ) |
Get (or create if not exist yet) grade for this user.
| 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 |
| grade_grade | The grade_grade instance for the user for this 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.
| grade_item |
|
inherited |
Check a grade item hidden status.
| int | 0 means visible, 1 hidden always, a timestamp means "hidden until" |
Reimplemented in grade_grade.
| 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.
| string | The grade item idnumber |
| grade_item::get_item_category | ( | ) |
Returns the grade_category for a grade category grade item.
| grade_category|bool | Returns a grade_category instance if applicable or false otherwise |
| grade_item::get_locktime | ( | ) |
Set the locktime for this grade item.
| int\$locktime | timestamp for lock to activate |
| 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
| 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. |
| string | name |
| grade_item::get_parent_category | ( | ) |
Returns the grade_category object this grade_item belongs to (referenced by categoryid) or category attached to category item.
| grade_category|bool | Returns a grade_category object if applicable or false if this is a course item |
|
inherited |
Returns object with fields and values that are defined in database.
| stdClass |
| 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.
| int | Sort order |
| grade_item::has_grades | ( | ) |
Check to see if there are any existing grades for this grade_item.
| boolean | - true if there are valid grades for this grade_item. |
| grade_item::has_hidden_grades | ( | $groupsql = "", | |
| array | $params = null, | ||
| $groupwheresql = "" ) |
Returns the number of grades that are hidden.
| string | $groupsql | SQL to limit the query by group |
| array | $params | SQL params for $groupsql |
| string | $groupwheresql | Where conditions for $groupsql |
| int | The number of hidden grades |
| grade_item::has_overridden_grades | ( | ) |
Check to see if there are existing overridden grades for this grade_item.
| boolean | - true if there are overridden grades for this grade_item. |
| grade_item::insert | ( | $source = null, | |
| $isbulkupdate = false ) |
In addition to perform parent\insert(), calls force_regrading() method too.
| string | $source | From where was the object inserted (mod/forum, manual, etc.) |
| string | $isbulkupdate | If bulk grade update is happening. |
| int | PK ID if successful, false otherwise |
Reimplemented from grade_object.
| grade_item::is_aggregate_item | ( | ) |
Returns true if the grade item is an aggreggated type grade.
| bool |
| grade_item::is_calculated | ( | ) |
Checks if grade calculated.
Returns this object's calculation.
| bool | true if grade item calculated. |
| grade_item::is_category_item | ( | ) |
Is the grade item associated with category?
| bool |
| grade_item::is_course_item | ( | ) |
Is the grade item associated with course?
| bool |
| grade_item::is_editable | ( | ) |
Is grading object editable?
| bool |
| grade_item::is_external_item | ( | ) |
Is the grade item external - associated with module, plugin or something else?
| bool |
|
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
| bool | Current hidden state |
Reimplemented in grade_grade.
|
inherited |
Check grade object hidden status.
| 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.
| 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.
| int | $userid | The user's ID |
| bool | Locked state |
| grade_item::is_manual_item | ( | ) |
Is this a manually graded item?
| bool |
| grade_item::is_outcome_item | ( | ) |
Is this an outcome item?
| bool |
| grade_item::is_overridable_item | ( | ) |
Is the grade item overridable.
| bool |
| grade_item::is_overridable_item_feedback | ( | ) |
Is the grade item feedback overridable.
| bool |
| grade_item::is_raw_used | ( | ) |
Returns true if grade items uses raw grades.
| bool |
| 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.
| grade_category |
|
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.
| grade_item::load_outcome | ( | ) |
Instantiates a grade_outcome object from the DB if this item's outcomeid variable is set.
| grade_outcome | This grade item's associated grade_outcome or null |
| 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.
| grade_category | This grade item's parent grade_category. |
| grade_item::load_scale | ( | ) |
Instantiates a grade_scale object from the DB if this item's scaleid variable is set.
| grade_scale | Returns a grade_scale object or null if no scale used |
| grade_item::move_after_sortorder | ( | $sortorder | ) |
Update this grade item's sortorder so that it will appear after $sortorder.
| int | $sortorder | The sort order to place this grade item after |
|
static |
Normalizes the calculation formula to [#giXX#] form.
| string | $formula | The formula |
| int | $courseid | The course ID |
| string | The normalized formula as a string |
|
protected |
Used to notify the completion system (if necessary) that a user's grade has changed, and clear up a possible score cache.
| bool | $deleted | True if grade was actually deleted |
Reimplemented from grade_object.
| 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.
| bool |
| grade_item::refresh_grades | ( | $userid = 0 | ) |
Refetch grades from modules, plugins.
| int | $userid | optional, limit the refetch to a single user |
| bool | Returns true on success or if there is nothing to do |
| 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!!
| 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 |
| bool | true if ok, error string otherwise |
| 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.
| 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.
| 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.) |
| bool | True on success |
| 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.
| int | $from | Aggregation method constant value. |
| int | $to | Aggregation method constant value. |
| boolean | True when at least one field was changed, false otherwise |
| 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.
| string | $formula | string representation of formula used for calculation |
| bool | success |
| 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
| int | $hidden | new hidden status |
| bool | $cascade | apply to child objects too |
Reimplemented from grade_object.
| grade_item::set_locked | ( | $lockedstate, | |
| $cascade = false, | |||
| $refresh = true ) |
Locks or unlocks this grade_item and (optionally) all its associated final grades.
| 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 |
| bool | True if grade_item all grades updated, false if at least one update fails |
| grade_item::set_locktime | ( | $locktime | ) |
Set the locktime for this grade item.
| int | $locktime | timestamp for lock to activate |
| void |
| 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.
| 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. |
| bool | True if success |
|
staticinherited |
Given an associated array or object, cycles through each key/variable and assigns the value to the corresponding variable in this object.
| grade_object | $instance | The object to set the properties on |
| array | $params | An array of properties to set like $propertyname => $propertyvalue |
| array|stdClass | Either an associative array or an object containing property name, property value pairs |
Reimplemented in grade_category.
| 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.
| int | $sortorder |
| 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.
| string | $source | from where was the object inserted (mod/forum, manual, etc.) |
| bool | $isbulkupdate | If bulk grade update is happening. |
| bool | success |
Reimplemented from grade_object.
|
protectedinherited |
Handles updating feedback files in the gradebook.
| int | null | $historyid |
Reimplemented in grade_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.
| 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. |
| bool | success |
|
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.
| bool | True if successful |
| 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.
| 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. |
| bool | success |
| grade_item::use_formula | ( | $userid, | |
| $params, | |||
| $useditems, | |||
| $oldgrade ) |
Internal function that does the final grade calculation.
| 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 |
| bool | False if an error occurred |
| grade_item::validate_formula | ( | $formulastr | ) |
Validate the formula.
| string | $formulastr |
| bool | true if calculation possible, false otherwise |
| string grade_item::$calculation |
Calculation string used for this item.
$calculation
| 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.
| int grade_item::$categoryid |
The category this grade_item belongs to (optional).
$categoryid
| int grade_item::$courseid |
The course this grade_item belongs to.
$courseid
| int grade_item::$decimals = null |
The number of digits after the decimal point symbol.
Applies only to REAL and PERCENTAGE grade display types. $decimals
| int grade_item::$display = GRADE_DISPLAY_TYPE_DEFAULT |
Display type of the grades (Real, Percentage, Letter, or default).
$display
| float grade_item::$grademax = 100 |
Maximum allowable grade.
$grademax
| float grade_item::$grademin = 0 |
Minimum allowable grade.
$grademin
| float grade_item::$gradepass = 0 |
grade required to pass.
(grademin <= gradepass <= grademax) $gradepass
|
inherited |
The PK.
$id
| string grade_item::$idnumber |
Arbitrary idnumber provided by the module responsible.
$idnumber
| grade_category grade_item::$item_category |
The grade_category object referenced $this->iteminstance if itemtype == 'category' or == 'course'.
$item_category
| string grade_item::$iteminfo |
Info and notes about this item.
$iteminfo
| string grade_item::$itemmodule |
The module pushing this grade (e.g.
'forum', 'quiz', 'assignment' etc). $itemmodule
| string grade_item::$itemname |
The name of this grade_item (pushed by the module).
$itemname
| int grade_item::$itemnumber |
Number of the item in a series of multiple grades pushed by an activity.
$itemnumber
| string grade_item::$itemtype |
e.g.
'category', 'course' and 'mod', 'blocks', 'import', etc... $itemtype
| 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
| int grade_item::$locktime = 0 |
Date after which the grade will be locked.
Empty means no automatic locking. $locktime
| float grade_item::$multfactor = 1.0 |
Multiply all grades by this number.
$multfactor
| bool grade_item::$needsupdate = 1 |
If set, the whole column will be recalculated, then this flag will be switched off.
$needsupdate
|
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
| grade_outcome grade_item::$outcome |
The grade_outcome this grade is associated with, if applicable.
$outcome
| int grade_item::$outcomeid |
The id of the optional grade_outcome associated with this grade_item.
$outcomeid
| grade_category grade_item::$parent_category |
The grade_category object referenced by $this->categoryid.
$parent_category
| float grade_item::$plusfactor = 0 |
Add this to all grades.
$plusfactor
| array grade_item::$required_fields |
Array of required table fields, must start with 'id'.
$required_fields
| grade_scale grade_item::$scale |
The grade_scale object referenced by $this->scaleid.
$scale
| int grade_item::$scaleid |
id of the scale, if this grade is based on a scale.
$scaleid
| int grade_item::$sortorder = 0 |
Sorting order of the columns.
$sortorder
| string grade_item::$table = 'grade_items' |
DB Table (used by grade_object).
$table
|
inherited |
The first time this grade_object was created.
$timecreated
|
inherited |
The last time this grade_object was modified.
$timemodified
1.11.0