Moodle PHP Documentation 4.3
Moodle 4.3.5 (Build: 20240610) (7dcfaa79f78)
core_grades

Namespaces

namespace  core_grades
  
 
namespace  core_grades\external
  
 
namespace  core_grades\form
  
 
namespace  core_grades\grades\grader\gradingpanel\point\external
  
 
namespace  core_grades\grades\grader\gradingpanel\scale\external
  
 
namespace  core_grades\local\gradeitem
  
 
namespace  core_grades\output
  
 
namespace  core_grades\privacy
  
 

Classes

class  behat_grade
 
class  behat_grade_deprecated
 
class  behat_grades
 
class  core_grades\component_gradeitem
 Compontent definition of a gradeitem. More...
 
class  core_grades\component_gradeitems
 Helper class to fetch information about component grade items. More...
 
class  core_grades\external\create_gradecategories
 
class  core_grades\external\get_enrolled_users_for_search_widget
 
class  core_grades\external\get_enrolled_users_for_selector
 
class  core_grades\external\get_feedback
 
class  core_grades\external\get_gradable_users
 
class  core_grades\external\get_grade_tree
 
class  core_grades\external\get_gradeitems
 
class  core_grades\external\get_groups_for_search_widget
 
class  core_grades\form\add_category
 
class  core_grades\form\add_item
 
class  core_grades\form\add_outcome
 
class  core_grades\grades\grader\gradingpanel\point\external\fetch
 External grading panel point API. More...
 
class  core_grades\grades\grader\gradingpanel\point\external\store
 External grading panel point API. More...
 
class  core_grades\grades\grader\gradingpanel\scale\external\fetch
 External grading panel scale API. More...
 
class  core_grades\grades\grader\gradingpanel\scale\external\store
 External grading panel scale API. More...
 
interface  core_grades\local\gradeitem\advancedgrading_mapping
 Grade item, itemnumber mapping. More...
 
interface  core_grades\local\gradeitem\fieldname_mapping
 Grade item, fieldname mapping. More...
 
interface  core_grades\local\gradeitem\itemnumber_mapping
 Grade item, itemnumber mapping. More...
 
class  core_grades\output\action_bar
 
class  core_grades\output\course_outcomes_action_bar
 
class  core_grades\output\export_action_bar
 
class  core_grades\output\export_key_manager_action_bar
 
class  core_grades\output\export_publish_action_bar
 
class  core_grades\output\general_action_bar
 
class  core_grades\output\grade_letters_action_bar
 
class  core_grades\output\gradebook_setup_action_bar
 
class  core_grades\output\import_action_bar
 
class  core_grades\output\import_key_manager_action_bar
 
class  core_grades\output\manage_outcomes_action_bar
 
class  core_grades\output\scales_action_bar
 
class  core_grades\privacy\grade_grade_with_history
 
class  core_grades\privacy\provider
 Data provider class. More...
 
class  core_grades_external
 core grades functions More...
 
class  core_grades_renderer
 
class  course_settings_form
 First implementation of the preferences in the form of a moodleform. More...
 
class  edit_calculation_form
 
class  edit_category_form
 
class  edit_grade_form
 
class  edit_item_form
 
class  edit_letter_form
 
class  edit_outcome_form
 
class  edit_outcomeitem_form
 
class  edit_scale_form
 
class  grade_category
 grade_category is an object mapped to DB table {prefix}grade_categories More...
 
class  grade_edit_tree
 
class  grade_edit_tree_column
 Class grade_edit_tree_column. More...
 
class  grade_edit_tree_column_actions
 Class grade_edit_tree_column_actions. More...
 
class  grade_edit_tree_column_name
 Class grade_edit_tree_column_name. More...
 
class  grade_edit_tree_column_range
 Class grade_edit_tree_column_range. More...
 
class  grade_edit_tree_column_select
 Class grade_edit_tree_column_select. More...
 
class  grade_edit_tree_column_status
 Class grade_edit_tree_column_status. More...
 
class  grade_edit_tree_column_weight
 Class grade_edit_tree_column_weight. More...
 
class  grade_grade
 grade_grades is an object mapped to DB table {prefix}grade_grades More...
 
class  grade_helper
 Grade helper class. More...
 
class  grade_item
 Class representing a grade item. More...
 
class  grade_object
 An abstract object that holds methods and attributes common to all grade_* objects defined here. More...
 
class  grade_outcome
 Class representing a grade outcome. More...
 
class  grade_plugin_info
 A simple class containing info about grade plugins. More...
 
class  grade_plugin_return
 Utility class used for return tracking when using edit and other forms in grade plugins. More...
 
class  grade_report
 An abstract class containing variables and methods used by all or most reports. More...
 
class  grade_scale
 Class representing a grade scale. More...
 
class  grade_seq
 Flat structure similar to grade tree. More...
 
class  grade_structure
 General structure representing grade items in course. More...
 
class  grade_tree
 This class represents a complete tree of categories, grade_items and final grades, organises as an array primarily, but which can also be converted to other formats. More...
 
class  graded_users_iterator
 This class iterates over all users that are graded in a course. More...
 
class  import_outcomes_form
 

Functions

 get_gradable_users (int $courseid, ?int $groupid=null, bool $onlyactiveenrol=false)
 Load a valid list of gradable users in a course.
 
 grade_build_nav ($path, $pagename=null, $id=null)
 Function central to gradebook for building and printing the navigation (breadcrumb trail).
 
 grade_button ($type, $courseid, $object)
 Local shortcut function for creating an edit/delete button for a grade_* object.
 
 grade_course_category_delete ($categoryid, $newparentid, $showfeedback)
 Called when course category is deleted Cleans the gradebook of associated data.
 
 grade_course_reset ($courseid)
 Reset all course grades, refetch from the activities and recalculate.
 
moodle_page grade_extend_settings ($plugininfo, $courseid)
 This method adds settings to the settings block for the grade system and its plugins.
 
 grade_floats_different (?float $f1, ?float $f2)
 Compare two float numbers safely.
 
 grade_floats_equal (?float $f1, ?float $f2)
 Compare two float numbers safely.
 
 grade_floatval (?float $number)
 Convert a number to 5 decimal point float, null db compatible format (we need this to decide if db value changed)
 
 grade_force_full_regrading ($courseid)
 Force final grade recalculation in all course items.
 
 grade_force_site_regrading ()
 Forces regrading of all site grades.
 
 grade_format_gradevalue (?float $value, &$grade_item, $localized=true, $displaytype=null, $decimals=null)
 Returns string representation of grade value.
 
 grade_format_gradevalue_letter (?float $value, $grade_item)
 Returns a letter grade representation of a grade value The array of grade letters used is produced by grade_get_letters() using the course context.
 
 grade_format_gradevalue_percentage (?float $value, $grade_item, $decimals, $localized)
 Returns a percentage representation of a grade value.
 
 grade_format_gradevalue_real (?float $value, $grade_item, $decimals, $localized)
 Returns a float representation of a grade value.
 
 grade_get_categories_menu ($courseid, $includenew=false)
 Returns grade options for gradebook grade category menu.
 
 grade_get_course_grade ($userid, $courseid_or_ids=null)
 Returns the aggregated or calculated course grade for a single user for one or more courses.
 
 grade_get_course_grades ($courseid, $userid_or_ids=null)
 Returns the aggregated or calculated course grade(s) for a single course for one or more users.
 
 grade_get_date_for_user_grade (\stdClass $grade, stdClass $user)
 Get the most appropriate grade date for a grade item given the user that the grade relates to.
 
 grade_get_gradable_activities ($courseid, $modulename='')
 Returns an array of activities (defined as $cm objects) which are gradeable from gradebook, outcomes are ignored.
 
 grade_get_grade_items_for_activity ($cm, $only_main_item=false)
 Returns all grade items (including outcomes) or main item for a given activity identified by $cm object.
 
 grade_get_graded_users_select ($report, $course, $userid, $groupid, $includeall)
 
 grade_get_grades ($courseid, $itemtype, $itemmodule, $iteminstance, $userid_or_ids=null)
 Returns grading information for given activity, optionally with user grades.
 
 grade_get_letters ($context=null)
 Returns the array of grade letters to be used in the supplied context.
 
 grade_get_plugin_info ($courseid, $active_type, $active_plugin)
 grade_get_plugin_info
 
 grade_get_setting ($courseid, $name, $default=null, $resetcache=false)
 Returns a course gradebook setting.
 
 grade_get_settings ($courseid)
 Returns all course gradebook settings as object properties.
 
 grade_grab_course_grades ($courseid, $modname=null, $userid=0)
 Refetches grade data from course activities.
 
 grade_hide_min_max_grade_upgrade_notice ($courseid)
 Hide warning about changed grades during upgrade from 2.8.0-2.8.6 and 2.9.0.
 
 grade_is_user_graded_in_activity ($cm, $userid)
 Returns whether or not a user received grades in main grade item for given activity.
 
 grade_needs_regrade_final_grades ($courseid)
 Return true if the course needs regrading.
 
 grade_needs_regrade_progress_bar ($courseid)
 Return true if the regrade process is likely to be time consuming and will therefore require the progress bar.
 
 grade_recover_history_grades ($userid, $courseid)
 Recover a user's grades from grade_grades_history.
 
 grade_regrade_final_grades ($courseid, $userid=null, $updated_item=null, $progress=null)
 Updates all final grades in course.
 
 grade_regrade_final_grades_if_required ($course, callable $callback=null)
 Check whether regarding of final grades is required and, if so, perform the regrade.
 
 grade_set_setting ($courseid, $name, $value)
 Add, update or delete a course gradebook setting.
 
 grade_uninstalled_module ($modname)
 Does gradebook cleanup when a module is uninstalled Deletes all associated grade items.
 
 grade_update ($source, $courseid, $itemtype, $itemmodule, $iteminstance, $itemnumber, $grades=null, $itemdetails=null, $isbulkupdate=false)
 Include essential files.
 
 grade_update_mod_grades ($modinstance, $userid=0)
 Force full update of module grades in central gradebook.
 
 grade_update_outcomes ($source, $courseid, $itemtype, $itemmodule, $iteminstance, $userid, $data)
 Updates a user's outcomes.
 
 grade_upgrade_use_min_max_from_grade_grade ($courseid)
 Use the grade min and max from the grade_grade.
 
 grade_upgrade_use_min_max_from_grade_item ($courseid)
 Use the grade min and max from the grade_item.
 
 grade_user_delete ($userid)
 Deletes all of a user's grade data from gradebook.
 
 grade_user_unenrol ($courseid, $userid)
 Purge course data when user unenrolls from a course.
 
 grade_verify_idnumber ($idnumber, $courseid, $grade_item=null, $cm=null)
 Verify new value of grade item idnumber.
 
 hide_aggregatesubcats_upgrade_notice ($courseid)
 Hide warning about changed grades during upgrade to 2.8.
 
 hide_gradebook_calculations_freeze_notice ($courseid)
 Hide warning about changed grades due to bug fixes.
 
 hide_natural_aggregation_upgrade_notice ($courseid)
 Hide warning about changed grades during upgrade to 2.8.
 
 print_grade_page_head (int $courseid, string $active_type, ?string $active_plugin=null, string|bool $heading=false, bool $return=false, $buttons=false, bool $shownavigation=true, ?string $headerhelpidentifier=null, ?string $headerhelpcomponent=null, ?stdClass $user=null, ?action_bar $actionbar=null, $unused=null)
 Prints the page headers, breadcrumb trail, page heading, (optional) navigation and for any gradebook page.
 
 print_graded_users_selector ($course, $actionpage, $userid=0, $groupid=0, $includeall=true, $return=false)
 Print a selection popup form of the graded users in a course.
 
 print_natural_aggregation_upgrade_notice ($courseid, $context, $thispage, $return=false)
 Print warning about changed grades during upgrade to 2.8.
 
 remove_course_grades ($courseid, $showfeedback)
 Remove all grade related course data Grade history is kept.
 
 remove_grade_letters ($context, $showfeedback)
 Remove grade letters for given context.
 

Variables

global $CFG
 
 $context = context_course::instance($courseid)
 
 $row = $tabs = array()
 
 $row []
 
 $row = $tabs = array()
 
 $row []
 
if(has_capability('moodle/grade:manageletters', $context)) $tabs [] = $row
 
if(has_capability('moodle/grade:manage', $context)) $tabs [] = $row
 
const GRADE_AGGREGATE_EXTRACREDIT_MEAN 12
 GRADE_AGGREGATE_EXTRACREDIT_MEAN - Use the category mean for grade aggregation and include support for extra credit.
 
const GRADE_AGGREGATE_MAX 6
 GRADE_AGGREGATE_MAX - Use the category maximum grade for grade aggregation.
 
const GRADE_AGGREGATE_MEAN 0
 GRADE_AGGREGATE_MEAN - Use the category mean for grade aggregation.
 
const GRADE_AGGREGATE_MEDIAN 2
 GRADE_AGGREGATE_MEDIAN - Use the category median for grade aggregation.
 
const GRADE_AGGREGATE_MIN 4
 GRADE_AGGREGATE_MIN - Use the category minimum grade for grade aggregation.
 
const GRADE_AGGREGATE_MODE 8
 GRADE_AGGREGATE_MEDIAN - Use the category mode for grade aggregation.
 
const GRADE_AGGREGATE_SUM 13
 GRADE_AGGREGATE_SUM - Use Natural in the category for grade aggregation.
 
const GRADE_AGGREGATE_WEIGHTED_MEAN 10
 GRADE_AGGREGATE_WEIGHTED_MEAN - Use a weighted mean of grades in the category for grade aggregation.
 
const GRADE_AGGREGATE_WEIGHTED_MEAN2 11
 GRADE_AGGREGATE_WEIGHTED_MEAN2 - Use a simple weighted mean of grades in the category for grade aggregation.
 
const GRADE_DISPLAY_TYPE_DEFAULT 0
 GRADE_DISPLAY_TYPE_DEFAULT - Grade display type can be set at 3 levels: grade_item, course setting and site.
 
const GRADE_DISPLAY_TYPE_LETTER 3
 GRADE_DISPLAY_TYPE_LETTER - Display the grade as a letter grade.
 
const GRADE_DISPLAY_TYPE_LETTER_PERCENTAGE 32
 GRADE_DISPLAY_TYPE_LETTER_PERCENTAGE - Display the grade as a letter grade and a percentage.
 
const GRADE_DISPLAY_TYPE_LETTER_REAL 31
 GRADE_DISPLAY_TYPE_LETTER_REAL - Display the grade as a letter grade and a decimal number.
 
const GRADE_DISPLAY_TYPE_PERCENTAGE 2
 GRADE_DISPLAY_TYPE_PERCENTAGE - Display the grade as a percentage.
 
const GRADE_DISPLAY_TYPE_PERCENTAGE_LETTER 23
 GRADE_DISPLAY_TYPE_PERCENTAGE_LETTER - Display the grade as a percentage and a letter grade.
 
const GRADE_DISPLAY_TYPE_PERCENTAGE_REAL 21
 GRADE_DISPLAY_TYPE_PERCENTAGE_REAL - Display the grade as a percentage and a decimal number.
 
const GRADE_DISPLAY_TYPE_REAL 1
 GRADE_DISPLAY_TYPE_REAL - Display the grade as a decimal number.
 
const GRADE_DISPLAY_TYPE_REAL_LETTER 13
 GRADE_DISPLAY_TYPE_REAL_LETTER - Display the grade as a decimal number and a letter grade.
 
const GRADE_DISPLAY_TYPE_REAL_PERCENTAGE 12
 GRADE_DISPLAY_TYPE_REAL_PERCENTAGE - Display the grade as a decimal number and a percentage.
 
const GRADE_FEEDBACK_FILEAREA 'feedback'
 The file area to store the associated grade_grades feedback files.
 
const GRADE_FILE_COMPONENT 'grade'
 The component to store grade files.
 
const GRADE_HISTORY_DELETE 3
 GRADE_HISTORY_INSERT - A grade item was deleted.
 
const GRADE_HISTORY_FEEDBACK_FILEAREA 'historyfeedback'
 The file area to store the associated grade_grades_history feedback files.
 
const GRADE_HISTORY_INSERT 1
 GRADE_HISTORY_INSERT - A grade item was inserted.
 
const GRADE_HISTORY_UPDATE 2
 GRADE_HISTORY_UPDATE - A grade item was updated.
 
const GRADE_MIN_MAX_FROM_GRADE_GRADE 2
 GRADE_MIN_MAX_FROM_GRADE_GRADE - Get the grade min/max from the grade grade.
 
const GRADE_MIN_MAX_FROM_GRADE_ITEM 1
 GRADE_MIN_MAX_FROM_GRADE_ITEM - Get the grade min/max from the grade item.
 
const GRADE_REPORT_AGGREGATION_POSITION_FIRST 0
 GRADE_REPORT_AGGREGATION_POSITION_FIRST - Display the course totals before the individual activity grades.
 
const GRADE_REPORT_AGGREGATION_POSITION_LAST 1
 GRADE_REPORT_AGGREGATION_POSITION_LAST - Display the course totals after the individual activity grades.
 
const GRADE_REPORT_HIDE_TOTAL_IF_CONTAINS_HIDDEN 0
 GRADE_REPORT_HIDE_TOTAL_IF_CONTAINS_HIDDEN - If the category or course total contains a hidden item hide the total from students.
 
const GRADE_REPORT_MEAN_ALL 0
 GRADE_REPORT_MEAN_ALL - Include all grade items including those where the student hasn't received a grade when calculating the mean.
 
const GRADE_REPORT_MEAN_GRADED 1
 GRADE_REPORT_MEAN_GRADED - Only include grade items where the student has a grade when calculating the mean.
 
const GRADE_REPORT_PREFERENCE_DEFAULT 'default'
 GRADE_REPORT_PREFERENCE_DEFAULT - Use the setting from site preferences.
 
const GRADE_REPORT_PREFERENCE_INHERIT 'inherit'
 GRADE_REPORT_PREFERENCE_INHERIT - Inherit the setting value from the parent.
 
const GRADE_REPORT_PREFERENCE_UNUSED -1
 GRADE_REPORT_PREFERENCE_UNUSED - Unused constant.
 
const GRADE_REPORT_SHOW_REAL_TOTAL_IF_CONTAINS_HIDDEN 2
 GRADE_REPORT_SHOW_REAL_TOTAL_IF_CONTAINS_HIDDEN - If the category or course total contains a hidden item show students the real total including marks from hidden items.
 
const GRADE_REPORT_SHOW_TOTAL_IF_CONTAINS_HIDDEN 1
 GRADE_REPORT_SHOW_TOTAL_IF_CONTAINS_HIDDEN - If the category or course total contains a hidden item show the total to students minus grades from the hidden items.
 
const GRADE_TYPE_NONE 0
 GRADE_TYPE_NONE - Ungraded.
 
const GRADE_TYPE_SCALE 2
 GRADE_TYPE_NONE - The grade is a value from the set of values available in a grade scale.
 
const GRADE_TYPE_TEXT 3
 GRADE_TYPE_NONE - Feedback only.
 
const GRADE_TYPE_VALUE 1
 GRADE_TYPE_NONE - The grade is a numeric value.
 
const GRADE_UPDATE_FAILED 1
 GRADE_UPDATE_FAILED - Grade updated failed.
 
const GRADE_UPDATE_ITEM_LOCKED 4
 GRADE_UPDATE_DELETED - Grade item cannot be updated as it is locked.
 
const GRADE_UPDATE_MULTIPLE 2
 GRADE_UPDATE_MULTIPLE - Grade update failed because there are multiple grade items with the same itemnumber for this activity.
 
const GRADE_UPDATE_OK 0
 GRADE_UPDATE_OK - Grade updated completed successfully.
 
 if (!defined( 'MOODLE_INTERNAL'))
 
 if (!defined( 'MOODLE_INTERNAL'))
 
 if (!defined( 'MOODLE_INTERNAL'))
 
 if (!defined( 'MOODLE_INTERNAL'))
 
 if (!defined( 'MOODLE_INTERNAL'))
 
 if (!defined( 'MOODLE_INTERNAL'))
 
 if (!defined( 'MOODLE_INTERNAL'))
 
 if (!defined( 'MOODLE_INTERNAL'))
 
 if (!defined( 'MOODLE_INTERNAL'))
 
 if (!defined( 'MOODLE_INTERNAL'))
 

Detailed Description

Function Documentation

◆ get_gradable_users()

get_gradable_users ( int $courseid,
?int $groupid = null,
bool $onlyactiveenrol = false )

Load a valid list of gradable users in a course.

Parameters
int$courseidThe course ID.
int | null$groupidThe group ID (optional).
bool$onlyactiveenrolInclude only active enrolments.
Return values
array\$usersA list of enrolled gradable users.

◆ grade_build_nav()

grade_build_nav ( $path,
$pagename = null,
$id = null )

Function central to gradebook for building and printing the navigation (breadcrumb trail).

Parameters
string$pathThe path of the calling script (using FILE?)
string$pagenameThe language string to use as the last part of the navigation (non-link)
mixed$idEither a plain integer (assuming the key is 'id') or an array of keys and values (e.g courseid => $courseid, itemid...)
Return values
string

◆ grade_button()

grade_button ( $type,
$courseid,
$object )

Local shortcut function for creating an edit/delete button for a grade_* object.

Parameters
string$type'edit' or 'delete'
int$courseidThe Course ID
grade_*$object The grade_* object
Return values
stringhtml

◆ grade_course_category_delete()

grade_course_category_delete ( $categoryid,
$newparentid,
$showfeedback )

Called when course category is deleted Cleans the gradebook of associated data.

Parameters
int$categoryidThe course category id
int$newparentidIf empty everything is deleted. Otherwise the ID of the category where content moved
bool$showfeedbackprint feedback

◆ grade_course_reset()

grade_course_reset ( $courseid)

Reset all course grades, refetch from the activities and recalculate.

Parameters
int$courseidThe course to reset
Return values
boolsuccess

◆ grade_extend_settings()

moodle_page grade_extend_settings ( $plugininfo,
$courseid )

This method adds settings to the settings block for the grade system and its plugins.

$PAGE

◆ grade_floats_different()

grade_floats_different ( ?float $f1,
?float $f2 )

Compare two float numbers safely.

Uses 5 decimals php precision using grade_floatval(). Nulls accepted too. Used for determining if a database update is required

Parameters
float | null$f1Float one to compare
float | null$f2Float two to compare
Return values
boolTrue if the supplied values are different

◆ grade_floats_equal()

grade_floats_equal ( ?float $f1,
?float $f2 )

Compare two float numbers safely.

Uses 5 decimals php precision using grade_floatval()

Do not use rounding for 10,5 at the database level as the results may be different from php round() function.

Since
Moodle 2.0
Parameters
float | null$f1Float one to compare
float | null$f2Float two to compare
Return values
boolTrue if the values should be considered as the same grades

◆ grade_floatval()

grade_floatval ( ?float $number)

Convert a number to 5 decimal point float, null db compatible format (we need this to decide if db value changed)

Parameters
float | null$numberThe number to convert
Return values
float|nullfloat or null

◆ grade_force_full_regrading()

grade_force_full_regrading ( $courseid)

Force final grade recalculation in all course items.

Parameters
int$courseidThe course ID to recalculate

◆ grade_force_site_regrading()

grade_force_site_regrading ( )

Forces regrading of all site grades.

Used when changing site setings

◆ grade_format_gradevalue()

grade_format_gradevalue ( ?float $value,
& $grade_item,
$localized = true,
$displaytype = null,
$decimals = null )

Returns string representation of grade value.

Parameters
float | null$valueThe grade value
object$grade_itemGrade item object passed by reference to prevent scale reloading
bool$localizeduse localised decimal separator
int$displaytypetype of display. For example GRADE_DISPLAY_TYPE_REAL, GRADE_DISPLAY_TYPE_PERCENTAGE, GRADE_DISPLAY_TYPE_LETTER
int$decimalsThe number of decimal places when displaying float values
Return values
string

◆ grade_format_gradevalue_letter()

grade_format_gradevalue_letter ( ?float $value,
$grade_item )

Returns a letter grade representation of a grade value The array of grade letters used is produced by grade_get_letters() using the course context.

Parameters
float | null$valueThe grade value
object$grade_itemGrade item object
Return values
string

◆ grade_format_gradevalue_percentage()

grade_format_gradevalue_percentage ( ?float $value,
$grade_item,
$decimals,
$localized )

Returns a percentage representation of a grade value.

Parameters
float | null$valueThe grade value
object$grade_itemGrade item object
int$decimalsThe number of decimal places
bool$localizeduse localised decimal separator
Return values
string

◆ grade_format_gradevalue_real()

grade_format_gradevalue_real ( ?float $value,
$grade_item,
$decimals,
$localized )

Returns a float representation of a grade value.

Parameters
float | null$valueThe grade value
object$grade_itemGrade item object
int$decimalsThe number of decimal places
bool$localizeduse localised decimal separator
Return values
string

◆ grade_get_categories_menu()

grade_get_categories_menu ( $courseid,
$includenew = false )

Returns grade options for gradebook grade category menu.

Parameters
int$courseidThe course ID
bool$includenewInclude option for new category at array index -1
Return values
arrayof grade categories in course

◆ grade_get_course_grade()

grade_get_course_grade ( $userid,
$courseid_or_ids = null )

Returns the aggregated or calculated course grade for a single user for one or more courses.

Parameters
int$useridThe ID of the single user
int | array$courseid_or_idsOptional ID of course or array of IDs, empty means all of the user's courses
Return values
mixedgrade info or grades array including item info, false if error

◆ grade_get_course_grades()

grade_get_course_grades ( $courseid,
$userid_or_ids = null )

Returns the aggregated or calculated course grade(s) for a single course for one or more users.

License
http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
Parameters
int$courseidThe ID of course
int | array$userid_or_idsOptional ID of the graded user or array of user IDs; if userid not used, returns only information about grade_item
Return values
stdClassReturns an object containing information about course grade item. scaleid, name, grade and locked status etc and user course grades: $item->grades[$userid] => $usercoursegrade

◆ grade_get_date_for_user_grade()

grade_get_date_for_user_grade ( \stdClass $grade,
stdClass $user )

Get the most appropriate grade date for a grade item given the user that the grade relates to.

Parameters
stdClass$grade
stdClass$user
Return values
int|null

◆ grade_get_gradable_activities()

grade_get_gradable_activities ( $courseid,
$modulename = '' )

Returns an array of activities (defined as $cm objects) which are gradeable from gradebook, outcomes are ignored.

Parameters
int$courseidIf provided then restrict to one course.
string$modulenameIf defined (could be 'forum', 'assignment' etc) then only that type are returned.
Return values
array\$cmobjects

◆ grade_get_grade_items_for_activity()

grade_get_grade_items_for_activity ( $cm,
$only_main_item = false )

Returns all grade items (including outcomes) or main item for a given activity identified by $cm object.

Parameters
cm_info$cmA course module object (preferably with modname property)
bool$only_main_itemLimit the search to the primary grade item for the activity, 'itemnumber'==0
Return values
mixedAn array of grade item instances, one grade item if $only_main_item == true, false if error or not found

◆ grade_get_grades()

grade_get_grades ( $courseid,
$itemtype,
$itemmodule,
$iteminstance,
$userid_or_ids = null )

Returns grading information for given activity, optionally with user grades.

Manual, course or category items can not be queried.

This function can be VERY costly - it is doing full course grades recalculation if needsupdate = 1 for course grade item. So be sure you really need it. If you need just certain grades consider using grade_item\refresh_grades() together with grade_item\get_grade() instead.

Parameters
int$courseidID of course
string$itemtypeType of grade item. For example, 'mod' or 'block'
string$itemmoduleMore specific then $itemtype. For example, 'forum' or 'quiz'. May be NULL for some item types
int$iteminstanceID of the item module
mixed$userid_or_idsEither a single user ID, an array of user IDs or null. If user ID or IDs are not supplied returns information about grade_item
Return values
stdClassObject with keys {items, outcomes, errors}, where 'items' is an array of grade information objects (scaleid, name, grade and locked status, etc.) indexed with itemnumbers

◆ grade_get_letters()

grade_get_letters ( $context = null)

Returns the array of grade letters to be used in the supplied context.

Parameters
object$contextContext object or null for defaults
Return values
arrayof grade_boundary (minimum) => letter_string

◆ grade_get_plugin_info()

grade_get_plugin_info ( $courseid,
$active_type,
$active_plugin )

grade_get_plugin_info

Parameters
int$courseidThe course id
string$active_typetype of plugin on current page - import, export, report or edit
string$active_pluginactive plugin type - grader, user, cvs, ...
Return values
array

◆ grade_get_setting()

grade_get_setting ( $courseid,
$name,
$default = null,
$resetcache = false )

Returns a course gradebook setting.

Parameters
int$courseid
string$nameof setting, maybe null if reset only
string$defaultvalue to return if setting is not found
bool$resetcacheforce reset of internal static cache
Return values
stringvalue of the setting, $default if setting not found, NULL if supplied $name is null

◆ grade_get_settings()

grade_get_settings ( $courseid)

Returns all course gradebook settings as object properties.

Parameters
int$courseid
Return values
object

◆ grade_grab_course_grades()

grade_grab_course_grades ( $courseid,
$modname = null,
$userid = 0 )

Refetches grade data from course activities.

Parameters
int$courseidThe course ID
string$modnameLimit the grade fetch to a single module type. For example 'forum'
int$useridlimit the grade fetch to a single user

◆ grade_hide_min_max_grade_upgrade_notice()

grade_hide_min_max_grade_upgrade_notice ( $courseid)

Hide warning about changed grades during upgrade from 2.8.0-2.8.6 and 2.9.0.

Parameters
int$courseidThe current course id.

◆ grade_is_user_graded_in_activity()

grade_is_user_graded_in_activity ( $cm,
$userid )

Returns whether or not a user received grades in main grade item for given activity.

Parameters
cm_info$cmThe activity context module
int$useridThe user ID
Return values
boolTrue if graded, false if user not graded yet

◆ grade_needs_regrade_final_grades()

grade_needs_regrade_final_grades ( $courseid)

Return true if the course needs regrading.

Parameters
int$courseidThe course ID
Return values
booltrue if course grades need updating.

◆ grade_needs_regrade_progress_bar()

grade_needs_regrade_progress_bar ( $courseid)

Return true if the regrade process is likely to be time consuming and will therefore require the progress bar.

Parameters
int$courseidThe course ID
Return values
boolWhether the regrade process is likely to be time consuming

◆ grade_recover_history_grades()

grade_recover_history_grades ( $userid,
$courseid )

Recover a user's grades from grade_grades_history.

Parameters
int$useridthe user ID whose grades we want to recover
int$courseidthe relevant course
Return values
booltrue if successful or false if there was an error or no grades could be recovered

◆ grade_regrade_final_grades()

grade_regrade_final_grades ( $courseid,
$userid = null,
$updated_item = null,
$progress = null )

Updates all final grades in course.

Parameters
int$courseidThe course ID
int$useridIf specified try to do a quick regrading of the grades of this user only
object$updated_itemOptional grade item to be marked for regrading. It is required if $userid is set.
core\progress\base$progressIf provided, will be used to update progress on this long operation.
Return values
array|truetrue if ok, array of errors if problems found. Grade item id => error message

◆ grade_regrade_final_grades_if_required()

grade_regrade_final_grades_if_required ( $course,
callable $callback = null )

Check whether regarding of final grades is required and, if so, perform the regrade.

If the regrade is expected to be time consuming (see grade_needs_regrade_progress_bar), then this function will output the progress bar, and redirect to the current PAGE->url after regrading completes. Otherwise the regrading will happen immediately and the page will be loaded as per normal.

A callback may be specified, which is called if regrading has taken place. The callback may optionally return a URL which will be redirected to when the progress bar is present.

Parameters
stdClass$courseThe course to regrade
callable$callbackA function to call if regrading took place
Return values
moodle_urlThe URL to redirect to if redirecting

◆ grade_set_setting()

grade_set_setting ( $courseid,
$name,
$value )

Add, update or delete a course gradebook setting.

Parameters
int$courseidThe course ID
string$nameName of the setting
string$valueValue of the setting. NULL means delete the setting.

◆ grade_uninstalled_module()

grade_uninstalled_module ( $modname)

Does gradebook cleanup when a module is uninstalled Deletes all associated grade items.

Parameters
string$modnameThe grade item module name to remove. For example 'forum'

◆ grade_update()

grade_update ( $source,
$courseid,
$itemtype,
$itemmodule,
$iteminstance,
$itemnumber,
$grades = null,
$itemdetails = null,
$isbulkupdate = false )

Include essential files.

Submit new or update grade; update/create grade_item definition. Grade must have userid specified, rawgrade and feedback with format are optional. rawgrade NULL means 'Not graded'. Missing property or key means does not change the existing value.

Only following grade item properties can be changed 'itemname', 'idnumber', 'gradetype', 'grademax', 'grademin', 'scaleid', 'multfactor', 'plusfactor', 'deleted' and 'hidden'. 'reset' means delete all current grades including locked ones.

Manual, course or category items can not be updated by this function.

Parameters
string$sourceSource of the grade such as 'mod/assignment'
int$courseidID of course
string$itemtypeType of grade item. For example, mod or block
string$itemmoduleMore specific then $itemtype. For example, assignment or forum. May be NULL for some item types
int$iteminstanceInstance ID of graded item
int$itemnumberMost probably 0. Modules can use other numbers when having more than one grade for each user
mixed$gradesGrade (object, array) or several grades (arrays of arrays or objects), NULL if updating grade_item definition only
mixed$itemdetailsObject or array describing the grading item, NULL if no change
bool$isbulkupdateIf bulk grade update is happening.
Return values
intReturns GRADE_UPDATE_OK, GRADE_UPDATE_FAILED, GRADE_UPDATE_MULTIPLE or GRADE_UPDATE_ITEM_LOCKED

◆ grade_update_mod_grades()

grade_update_mod_grades ( $modinstance,
$userid = 0 )

Force full update of module grades in central gradebook.

Parameters
object$modinstanceModule object with extra cmidnumber and modname property
int$useridOptional user ID if limiting the update to a single user
Return values
boolTrue if success

◆ grade_update_outcomes()

grade_update_outcomes ( $source,
$courseid,
$itemtype,
$itemmodule,
$iteminstance,
$userid,
$data )

Updates a user's outcomes.

Manual outcomes can not be updated.

Parameters
string$sourceSource of the grade such as 'mod/assignment'
int$courseidID of course
string$itemtypeType of grade item. For example, 'mod' or 'block'
string$itemmoduleMore specific then $itemtype. For example, 'forum' or 'quiz'. May be NULL for some item types
int$iteminstanceInstance ID of graded item. For example the forum ID.
int$useridID of the graded user
array$dataArray consisting of grade item itemnumber (grade_update()) => outcomegrade
Return values
boolreturns true if grade items were found and updated successfully

◆ grade_upgrade_use_min_max_from_grade_grade()

grade_upgrade_use_min_max_from_grade_grade ( $courseid)

Use the grade min and max from the grade_grade.

This is reserved for core use after an upgrade.

Parameters
int$courseidThe current course id.

◆ grade_upgrade_use_min_max_from_grade_item()

grade_upgrade_use_min_max_from_grade_item ( $courseid)

Use the grade min and max from the grade_item.

This is reserved for core use after an upgrade.

Parameters
int$courseidThe current course id.

◆ grade_user_delete()

grade_user_delete ( $userid)

Deletes all of a user's grade data from gradebook.

Parameters
int$useridThe user whose grade data should be deleted

◆ grade_user_unenrol()

grade_user_unenrol ( $courseid,
$userid )

Purge course data when user unenrolls from a course.

Parameters
int$courseidThe ID of the course the user has unenrolled from
int$useridThe ID of the user unenrolling

◆ grade_verify_idnumber()

grade_verify_idnumber ( $idnumber,
$courseid,
$grade_item = null,
$cm = null )

Verify new value of grade item idnumber.

Checks for uniqueness of new ID numbers. Old ID numbers are kept intact.

Parameters
string$idnumberstring (with magic quotes)
int$courseidID numbers are course unique only
grade_item$grade_itemThe grade item this idnumber is associated with
stdClass$cmused for course module idnumbers and items attached to modules
Return values
booltrue means idnumber ok

◆ hide_aggregatesubcats_upgrade_notice()

hide_aggregatesubcats_upgrade_notice ( $courseid)

Hide warning about changed grades during upgrade to 2.8.

Parameters
int$courseidThe current course id.

◆ hide_gradebook_calculations_freeze_notice()

hide_gradebook_calculations_freeze_notice ( $courseid)

Hide warning about changed grades due to bug fixes.

Parameters
int$courseidThe current course id.

◆ hide_natural_aggregation_upgrade_notice()

hide_natural_aggregation_upgrade_notice ( $courseid)

Hide warning about changed grades during upgrade to 2.8.

Parameters
int$courseidThe current course id.

◆ print_grade_page_head()

print_grade_page_head ( int $courseid,
string $active_type,
?string $active_plugin = null,
string|bool $heading = false,
bool $return = false,
$buttons = false,
bool $shownavigation = true,
?string $headerhelpidentifier = null,
?string $headerhelpcomponent = null,
?stdClass $user = null,
?action_bar $actionbar = null,
$unused = null )

Prints the page headers, breadcrumb trail, page heading, (optional) navigation and for any gradebook page.

All gradebook pages MUST use these functions in favour of the usual print_header(), print_header_simple(), print_heading() etc.

Parameters
int$courseidCourse id
string$active_typeThe type of the current page (report, settings, import, export, scales, outcomes, letters)
string | null$active_pluginThe plugin of the current page (grader, fullview etc...)
string | bool$headingThe heading of the page.
boolean$returnWhether to return (true) or echo (false) the HTML generated by this function
string | bool$buttonsAdditional buttons to display on the page
boolean$shownavigationshould the gradebook navigation be shown?
string | null$headerhelpidentifierThe help string identifier if required.
string | null$headerhelpcomponentThe component for the help string.
stdClass | null$userThe user object for use with the user context header.
action_bar | null$actionbarThe actions bar which will be displayed on the page if $shownavigation is set to true. If $actionbar is not explicitly defined, the general action bar (core_grades\output\general_action_bar) will be used by default.
null$unusedThis parameter has been deprecated since 4.3 and should not be used anymore.
Return values
stringHTML code or nothing if $return == false

◆ print_graded_users_selector()

print_graded_users_selector ( $course,
$actionpage,
$userid = 0,
$groupid = 0,
$includeall = true,
$return = false )

Print a selection popup form of the graded users in a course.

Deprecated
since 2.0
Parameters
int$courseid of the course
string$actionpageThe page receiving the data from the popoup form
int$useridid of the currently selected user (or 'all' if they are all selected)
int$groupidid of requested group, 0 means all
int$includeallbool include all option
bool$returnIf true, will return the HTML, otherwise, will print directly
Return values
null

◆ print_natural_aggregation_upgrade_notice()

print_natural_aggregation_upgrade_notice ( $courseid,
$context,
$thispage,
$return = false )

Print warning about changed grades during upgrade to 2.8.

Parameters
int$courseidThe current course id.
context$contextThe course context.
string$thispageThe relative path for the current page. E.g. /grade/report/user/index.php
boolean$returnreturn as string
Return values
nothingor string if $return true

◆ remove_course_grades()

remove_course_grades ( $courseid,
$showfeedback )

Remove all grade related course data Grade history is kept.

Parameters
int$courseidThe course ID
bool$showfeedbackIf true success notifications will be displayed

◆ remove_grade_letters()

remove_grade_letters ( $context,
$showfeedback )

Remove grade letters for given context.

Parameters
context$contextThe context
bool$showfeedbackIf true a success notification will be displayed

Variable Documentation

◆ $row [1/2]

$row[]
Initial value:
= new tabobject('lettersview',
$CFG->wwwroot.'/grade/edit/letter/index.php?id='.$COURSE->id,
get_string('letters', 'grades'))
Stores one tab.
Definition outputcomponents.php:3984

◆ $row [2/2]

$row[]
Initial value:
= new tabobject('courseoutcomes',
$CFG->wwwroot.'/grade/edit/outcome/course.php?id='.$courseid,
get_string('outcomescourse', 'grades'))

◆ GRADE_AGGREGATE_WEIGHTED_MEAN

const GRADE_AGGREGATE_WEIGHTED_MEAN 10

GRADE_AGGREGATE_WEIGHTED_MEAN - Use a weighted mean of grades in the category for grade aggregation.

Weights can be manually set.

◆ GRADE_DISPLAY_TYPE_DEFAULT

const GRADE_DISPLAY_TYPE_DEFAULT 0

GRADE_DISPLAY_TYPE_DEFAULT - Grade display type can be set at 3 levels: grade_item, course setting and site.

Use the display type from the higher level.

◆ GRADE_DISPLAY_TYPE_LETTER

const GRADE_DISPLAY_TYPE_LETTER 3

GRADE_DISPLAY_TYPE_LETTER - Display the grade as a letter grade.

For example, A, B, C, D or F.