Moodle PHP Documentation 4.2
Moodle 4.2.8 (Build: 20240610) (2d41ac46f45)
grade_report_grader Class Reference

Class providing an API for the grader report building and displaying. More...

Inheritance diagram for grade_report_grader:
grade_report

Public Member Functions

 __construct ($courseid, $gpr, $context, $page=null, $sortitemid=null, string $sort='')
 Constructor.
 
 get_category_view_mode_link (moodle_url $url, string $title, string $action, bool $active=false)
 Returns link to change category view mode.
 
 get_cell_display_class (grade_item $item)
 Return class used for text alignment.
 
 get_default_sortable ()
 Return the base report link with some default sorting applied.
 
 get_grade_table ($displayaverages=false)
 Depending on the style of report (fixedstudents vs traditional one-table), arranges the rows of data in one or two tables, and returns the output of these tables in HTML.
 
 get_hide_show_link ()
 Return the link to allow the field to collapse from the users view.
 
 get_lang_string ($strcode, $section=null)
 First checks the cached language strings, then returns match if found, or uses get_string() to get it from the DB, caches it then returns it.
 
 get_left_avg_row ($rows=array(), $colspan=1, $groupavg=false)
 Builds and return the headers for the rows of averages, for the left part of the grader report.
 
 get_left_icons_row ($rows=array(), $colspan=1)
 Builds and return the row of icons for the left side of the report.
 
 get_left_range_row ($rows=array(), $colspan=1)
 Builds and return the header for the row of ranges, for the left part of the grader report.
 
 get_left_rows ($displayaverages)
 Builds and returns the rows that will make up the left part of the grader report This consists of student names and icons, links to user reports and id numbers, as well as header cells for these columns.
 
 get_numusers ($groups=true, $users=false)
 Fetches and returns a count of all the users that will be shown on this page.
 
 get_pref ($pref, $objectid=null)
 Given the name of a user preference (without grade_report_ prefix), locally saves then returns the value of that preference.
 
 get_right_avg_row ($rows=array(), $grouponly=false)
 Builds and return the row of averages for the right part of the grader report.
 
 get_right_icons_row ($rows=array())
 Builds and return the row of icons when editing is on, for the right part of the grader report.
 
 get_right_range_row ($rows=array())
 Builds and return the row of ranges for the right part of the grader report.
 
 get_right_rows (bool $displayaverages)
 Builds and returns the rows that will make up the right part of the grader report.
 
 get_sort_arrows (array $extrafields=[])
 Refactored function for generating HTML of sorting links with matching arrows.
 
 get_students_per_page ()
 Returns the maximum number of students to be displayed on each page.
 
 get_toggles_html ()
 Gets html toggle.
 
 item_types ()
 Get grade item type names in a course to use in filter dropdown.
 
 load_final_grades ()
 we supply the userids in this query, and get all the grades pulls out all the grades, this does not need to worry about paging
 
 load_users (bool $allusers=false)
 pulls out the userids of the users to be display, and sorts them
 
 print_toggle ($type)
 Prints html toggle.
 
 process_action ($target, $action)
 Processes a single action against a category, grade_item or grade.
 
 process_data ($data)
 Processes the data sent by the form (grades).
 
 set_pref ($pref, $pref_value='default', $itemid=null)
 Uses set_user_preferences() to update the value of a user preference.
 
 setup_users ()
 Sets up this report's user criteria to restrict the selection of users to display.
 
 ungraded_counts ()
 Get ungraded grade items info and sum of all grade items in a course.
 

Static Public Member Functions

static calculate_average (grade_item $gradeitem, array $info)
 Calculate average grade for a given grade item.
 
static do_process_action ($target, $action, $courseid=null)
 Processes a single action against a category, grade_item or grade.
 
static get_additional_context (context_course $context, int $courseid, array $element, grade_plugin_return $gpr, string $mode, stdClass $templatecontext, bool $otherplugins=false)
 Add additional links specific to plugin.
 
static get_gradable_users (int $courseid, ?int $groupid=null)
 Load a valid list of gradable users in a course.
 
static supports_mygrades ()
 Shows support for being used as a 'Grades' report.
 

Public Attributes

string $baseurl
 base url for sorting by first/last name.
 
boolean $canviewhidden
 Capability check caching $canviewhidden.
 
array $collapsed
 List of collapsed categories from user preference $collapsed.
 
context $context
 The context.
 
object $course
 The course.
 
int $courseid
 The courseid.
 
int $currentgroup
 The current group being displayed.
 
string $currentgroupname
 The current groupname being displayed.
 
object $gpr
 Grade plugin return tracking object.
 
string $gradebookroles
 The roles for this report.
 
array $grades
 The final grades.
 
array $gradeserror = array()
 Array of errors for bulk grades updating.
 
string $group_selector
 A HTML select element used to select the current group.
 
int $groupmode
 Current course group mode $groupmode.
 
grade_tree $gtree
 The grade_tree object.
 
int $page
 Current page (for paging).
 
string $pbarurl
 base url for paging.
 
array $prefs = array()
 User preferences related to this report.
 
int $rowcount = 0
 A count of the rows, used for css classes.
 
array $showtotalsifcontainhidden = []
 show course/category totals if they contain hidden items $showtotalsifcontainhidden
 
int $sortitemid
 The id of the grade_item by which this report will be sorted.
 
int $sortorder
 Sortorder used in the SQL selections.
 
stdClass $user
 To store user data $user.
 
string $userselect
 An SQL fragment affecting the search for users.
 
array $userselectparams = array()
 The bound params for $userselect $userselectparams.
 
int const MAX_STUDENTS_PER_PAGE = 5000
 Maximum number of students that can be shown on one page.
 
int[] const PAGINATION_OPTIONS = [20, 100]
 List of available options on the pagination dropdown.
 

Protected Member Functions

 blank_hidden_total ($courseid, $course_item, $finalgrade)
 Optionally blank out course/category totals if they contain any hidden items.
 
 blank_hidden_total_and_adjust_bounds ($courseid, $course_item, $finalgrade)
 Optionally blank out course/category totals if they contain any hidden items.
 
 get_allgradeitems ()
 Load all grade items.
 
 get_collapsing_icon ($element)
 Given a category element returns collapsing +/- icon if available.
 
 get_course_header ($element)
 Given element category, create a collapsible icon and course header.
 
 get_icons ($element)
 Given a grade_category, grade_item or grade_grade, this function figures out the state of the object and builds then returns a div with the icons needed for the grader report.
 
 get_sort_arrow (string $direction='down', ?moodle_url $sortlink=null)
 Returns an arrow icon inside an tag, for the purpose of sorting a column.
 
 get_users_search_sql (array $mappings, array $userfields)
 Prepare SQL where clause and associated parameters for any user searching being performed.
 
 setup_groups ()
 Sets up this object's group variables, mainly to restrict the selection of users to display.
 

Static Protected Member Functions

static filter_collapsed_categories ($courseid, $collapsed)
 From the list of categories that this user prefers to collapse choose ones that belong to the current course.
 
static get_collapsed_preferences ($courseid)
 Returns the list of categories that this user wants to collapse or display aggregatesonly.
 
static set_collapsed_preferences ($courseid, $collapsed)
 Sets the list of categories that user wants to see collapsed in user preferences.
 

Protected Attributes

string $groupsql
 An SQL fragment used to add linking information to the group tables.
 
string $groupwheresql
 An SQL constraint to append to the queries used by this object to build the report.
 
array $groupwheresql_params = array()
 The ordered params for $groupwheresql $groupwheresql_params.
 
bool $overridecat
 Allow category grade overriding $overridecat.
 
string $preferences_page
 To store a link to preferences page $preferences_page.
 
int int $userid = -1
 If the user is wanting to show only one particular user their id will be placed here.
 
array $users = []
 of objects, or empty array if no records were found.
 
string string $usersearch = ''
 If the user is wanting to search for a particular user within searchable fields their needle will be placed here.
 
string $userwheresql
 An SQL constraint to append to the queries used by this object to build the report.
 
array $userwheresql_params = array()
 The ordered params for $userwheresql $userwheresql_params.
 

Detailed Description

Class providing an API for the grader report building and displaying.

@uses grade_report

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

Constructor & Destructor Documentation

◆ __construct()

grade_report_grader::__construct ( $courseid,
$gpr,
$context,
$page = null,
$sortitemid = null,
string $sort = '' )

Constructor.

Sets local copies of user preferences and initialises grade_tree.

Parameters
int$courseid
object$gprgrade plugin return tracking object
string$context
int$pageThe current page being viewed (when report is paged)
int$sortitemidThe id of the grade_item by which to sort the table
string$sortSorting direction

Member Function Documentation

◆ blank_hidden_total()

grade_report::blank_hidden_total ( $courseid,
$course_item,
$finalgrade )
protectedinherited

Optionally blank out course/category totals if they contain any hidden items.

Deprecated
since Moodle 2.8 - Call blank_hidden_total_and_adjust_bounds instead.
Parameters
string$courseidthe course id
string$course_iteman instance of grade_item
string$finalgradethe grade for the course_item
Return values
stringThe new final grade

◆ blank_hidden_total_and_adjust_bounds()

grade_report::blank_hidden_total_and_adjust_bounds ( $courseid,
$course_item,
$finalgrade )
protectedinherited

Optionally blank out course/category totals if they contain any hidden items.

Parameters
string$courseidthe course id
string$course_iteman instance of grade_item
string$finalgradethe grade for the course_item
Return values
array[]containing values for 'grade', 'grademax', 'grademin', 'aggregationstatus' and 'aggregationweight'

◆ calculate_average()

static grade_report::calculate_average ( grade_item $gradeitem,
array $info )
staticinherited

Calculate average grade for a given grade item.

Based on calculate_averages function from grade/report/user/lib.php

Parameters
grade_item$gradeitemGrade item
array$infoUngraded grade items counts and report preferences.
Return values
arrayAverage grade and meancount.

◆ do_process_action()

static grade_report_grader::do_process_action ( $target,
$action,
$courseid = null )
static

Processes a single action against a category, grade_item or grade.

Parameters
string$targeteid ({type}{id}, e.g. c4 for category4)
string$actionWhich action to take (edit, delete etc...)
int$courseidaffected course.
Return values

◆ filter_collapsed_categories()

static grade_report_grader::filter_collapsed_categories ( $courseid,
$collapsed )
staticprotected

From the list of categories that this user prefers to collapse choose ones that belong to the current course.

This function serves two purposes. Mainly it helps migrating from user preference style when all courses were stored in one preference. Also it helps to remove the settings for categories that were removed if the array for one course grows too big.

Parameters
int$courseid
array$collapsed
Return values
array

◆ get_additional_context()

static grade_report::get_additional_context ( context_course $context,
int $courseid,
array $element,
grade_plugin_return $gpr,
string $mode,
stdClass $templatecontext,
bool $otherplugins = false )
staticinherited

Add additional links specific to plugin.

Parameters
context_course$contextCourse context
int$courseidCourse ID
array$elementAn array representing an element in the grade_tree
grade_plugin_return$gprA grade_plugin_return object
string$modeMode (user or grade item)
stdClass$templatecontextTemplate context
bool$otherpluginsIf we need to insert links to other plugins
Return values
?stdClassUpdated template context

◆ get_category_view_mode_link()

grade_report_grader::get_category_view_mode_link ( moodle_url $url,
string $title,
string $action,
bool $active = false )

Returns link to change category view mode.

Parameters
moodle_url$urlUrl to grader report page
string$titleMenu item title
string$actionView mode to change to
bool$activeWhether link is active in dropdown
Return values
string|null

◆ get_cell_display_class()

grade_report_grader::get_cell_display_class ( grade_item $item)

Return class used for text alignment.

Parameters
grade_item$itemCan be grade item or grade
Return values
stringclass name used for text alignment

◆ get_collapsed_preferences()

static grade_report_grader::get_collapsed_preferences ( $courseid)
staticprotected

Returns the list of categories that this user wants to collapse or display aggregatesonly.

This method also migrates on request from the old format of storing user preferences when they were stored in one preference for all courses causing DB error when trying to insert very big value.

Parameters
int$courseid
Return values
array

◆ get_collapsing_icon()

grade_report_grader::get_collapsing_icon ( $element)
protected

Given a category element returns collapsing +/- icon if available.

Deprecated
since Moodle 2.9 MDL-46662 - please do not use this function any more.

◆ get_course_header()

grade_report_grader::get_course_header ( $element)
protected

Given element category, create a collapsible icon and course header.

Parameters
array$element
Return values
stringHTML

◆ get_default_sortable()

grade_report_grader::get_default_sortable ( )

Return the base report link with some default sorting applied.

Return values
string
Exceptions
moodle_exception

◆ get_gradable_users()

static grade_report::get_gradable_users ( int $courseid,
?int $groupid = null )
staticinherited

Load a valid list of gradable users in a course.

Parameters
int$courseidThe course ID.
int | null$groupidThe group ID (optional).
Return values
arrayA list of enrolled gradable users.

◆ get_grade_table()

grade_report_grader::get_grade_table ( $displayaverages = false)

Depending on the style of report (fixedstudents vs traditional one-table), arranges the rows of data in one or two tables, and returns the output of these tables in HTML.

Parameters
boolean$displayaverageswhether to display average rows in the table
Return values
stringHTML

◆ get_hide_show_link()

grade_report_grader::get_hide_show_link ( )

Return the link to allow the field to collapse from the users view.

Return values
stringDropdown menu link that'll trigger the collapsing functionality.
Exceptions
coding_exception
moodle_exception

◆ get_icons()

grade_report_grader::get_icons ( $element)
protected

Given a grade_category, grade_item or grade_grade, this function figures out the state of the object and builds then returns a div with the icons needed for the grader report.

Parameters
array$element
Return values
stringHTML
Deprecated
since Moodle 4.2 - The row is not shown anymore - we have actions menu.
Todo
MDL-77307 This will be deleted in Moodle 4.6.

◆ get_lang_string()

grade_report::get_lang_string ( $strcode,
$section = null )
inherited

First checks the cached language strings, then returns match if found, or uses get_string() to get it from the DB, caches it then returns it.

Deprecated
since 4.2
Todo
MDL-77307 This will be deleted in Moodle 4.6.
Parameters
string$strcode
string$sectionOptional language section
Return values
string

◆ get_left_avg_row()

grade_report_grader::get_left_avg_row ( $rows = array(),
$colspan = 1,
$groupavg = false )

Builds and return the headers for the rows of averages, for the left part of the grader report.

Parameters
array$rowsThe Array of rows for the left part of the report
int$colspanThe number of columns this cell has to span
bool$groupavgIf true, returns the row for group averages, otherwise for overall averages
Return values
arrayArray of rows for the left part of the report

◆ get_left_icons_row()

grade_report_grader::get_left_icons_row ( $rows = array(),
$colspan = 1 )

Builds and return the row of icons for the left side of the report.

It only has one cell that says "Controls"

Parameters
array$rowsThe Array of rows for the left part of the report
int$colspanThe number of columns this cell has to span
Return values
arrayArray of rows for the left part of the report
Deprecated
since Moodle 4.2 - The row is not shown anymore - we have actions menu.
Todo
MDL-77307 This will be deleted in Moodle 4.6.

◆ get_left_range_row()

grade_report_grader::get_left_range_row ( $rows = array(),
$colspan = 1 )

Builds and return the header for the row of ranges, for the left part of the grader report.

Parameters
array$rowsThe Array of rows for the left part of the report
int$colspanThe number of columns this cell has to span
Return values
arrayArray of rows for the left part of the report

◆ get_left_rows()

grade_report_grader::get_left_rows ( $displayaverages)

Builds and returns the rows that will make up the left part of the grader report This consists of student names and icons, links to user reports and id numbers, as well as header cells for these columns.

It also includes the fillers required for the categories displayed on the right side of the report.

Parameters
boolean$displayaverageswhether to display average rows in the table
Return values
arrayArray of html_table_row objects

◆ get_numusers()

grade_report::get_numusers ( $groups = true,
$users = false )
inherited

Fetches and returns a count of all the users that will be shown on this page.

Parameters
boolean$groupsinclude groups limit
boolean$usersinclude users limit - default false, used for searching purposes
Return values
intCount of users

◆ get_pref()

grade_report::get_pref ( $pref,
$objectid = null )
inherited

Given the name of a user preference (without grade_report_ prefix), locally saves then returns the value of that preference.

If the preference has already been fetched before, the saved value is returned. If the preference is not set at the User level, the $CFG equivalent is given (site default). Can be called statically, but then doesn't benefit from caching

Parameters
string$prefThe name of the preference (do not include the grade_report_ prefix)
int$objectidAn optional itemid or categoryid to check for a more fine-grained preference
Return values
mixedThe value of the preference

◆ get_right_avg_row()

grade_report_grader::get_right_avg_row ( $rows = array(),
$grouponly = false )

Builds and return the row of averages for the right part of the grader report.

Parameters
array$rowsWhether to return only group averages or all averages.
bool$grouponlyWhether to return only group averages or all averages.
Return values
arrayArray of rows for the right part of the report

◆ get_right_icons_row()

grade_report_grader::get_right_icons_row ( $rows = array())

Builds and return the row of icons when editing is on, for the right part of the grader report.

Parameters
array$rowsThe Array of rows for the right part of the report
Return values
arrayArray of rows for the right part of the report
Deprecated
since Moodle 4.2 - The row is not shown anymore - we have actions menu.
Todo
MDL-77307 This will be deleted in Moodle 4.6.

◆ get_right_range_row()

grade_report_grader::get_right_range_row ( $rows = array())

Builds and return the row of ranges for the right part of the grader report.

Parameters
array$rowsThe Array of rows for the right part of the report
Return values
arrayArray of rows for the right part of the report

◆ get_right_rows()

grade_report_grader::get_right_rows ( bool $displayaverages)

Builds and returns the rows that will make up the right part of the grader report.

Parameters
boolean$displayaverageswhether to display average rows in the table
Return values
arrayArray of html_table_row objects

◆ get_sort_arrow()

grade_report::get_sort_arrow ( string $direction = 'down',
?moodle_url $sortlink = null )
protectedinherited

Returns an arrow icon inside an tag, for the purpose of sorting a column.

Parameters
string$direction
moodle_url | null$sortlink

◆ get_sort_arrows()

grade_report_grader::get_sort_arrows ( array $extrafields = [])

Refactored function for generating HTML of sorting links with matching arrows.

Returns an array with 'studentname' and 'idnumber' as keys, with HTML ready to inject into a table header cell.

Parameters
array$extrafieldsArray of extra fields being displayed, such as user idnumber
Return values
arrayAn associative array of HTML sorting links+arrows

◆ get_students_per_page()

grade_report_grader::get_students_per_page ( )

Returns the maximum number of students to be displayed on each page.

Return values
intThe maximum number of students to display per page

◆ get_toggles_html()

grade_report_grader::get_toggles_html ( )

Gets html toggle.

Deprecated
since Moodle 2.4 as it appears not to be used any more.

◆ get_users_search_sql()

grade_report::get_users_search_sql ( array $mappings,
array $userfields )
protectedinherited

Prepare SQL where clause and associated parameters for any user searching being performed.

This mostly came from core_user\table\participants_search with some slight modifications four our use case.

Parameters
array$mappingsArray of field mappings (fieldname => SQL code for the value)
array$userfieldsAn array that we cast from user profile fields to search within.
Return values
arraySQL query data in the format ['where' => '', 'params' => []].

◆ item_types()

grade_report::item_types ( )
inherited

Get grade item type names in a course to use in filter dropdown.

Return values
arrayItem types.

◆ load_users()

grade_report_grader::load_users ( bool $allusers = false)

pulls out the userids of the users to be display, and sorts them

Parameters
bool$allusersIf we are getting the users within the report, we want them all irrespective of paging.

◆ print_toggle()

grade_report_grader::print_toggle ( $type)

Prints html toggle.

Deprecated
since 2.4 as it appears not to be used any more.
Parameters
unknown$type

◆ process_action()

grade_report_grader::process_action ( $target,
$action )

Processes a single action against a category, grade_item or grade.

Parameters
string$targeteid ({type}{id}, e.g. c4 for category4)
string$actionWhich action to take (edit, delete etc...)
Return values

Reimplemented from grade_report.

◆ process_data()

grade_report_grader::process_data ( $data)

Processes the data sent by the form (grades).

Caller is responsible for all access control checks

Parameters
array$dataform submission (with magic quotes)
Return values
arrayempty array if success, array of warnings if something fails.

Reimplemented from grade_report.

◆ set_collapsed_preferences()

static grade_report_grader::set_collapsed_preferences ( $courseid,
$collapsed )
staticprotected

Sets the list of categories that user wants to see collapsed in user preferences.

This method may filter or even trim the list if it does not fit in DB field.

Parameters
int$courseid
array$collapsed

◆ set_pref()

grade_report::set_pref ( $pref,
$pref_value = 'default',
$itemid = null )
inherited

Uses set_user_preferences() to update the value of a user preference.

If 'default' is given as the value, the preference will be removed in favour of a higher-level preference.

Parameters
string$prefThe name of the preference.
mixed$pref_valueThe value of the preference.
int$itemidAn optional itemid to which the preference will be assigned
Return values
boolSuccess or failure.

◆ setup_groups()

grade_report::setup_groups ( )
protectedinherited

Sets up this object's group variables, mainly to restrict the selection of users to display.

Reimplemented in gradereport_singleview\report\singleview.

◆ supports_mygrades()

static grade_report::supports_mygrades ( )
staticinherited

Shows support for being used as a 'Grades' report.

Reimplemented in grade_report_overview.

◆ ungraded_counts()

grade_report::ungraded_counts ( )
inherited

Get ungraded grade items info and sum of all grade items in a course.

Based on calculate_averages function from grade/report/user/lib.php

Return values
arrayUngraded grade items counts with report preferences.

Member Data Documentation

◆ $baseurl

string grade_report::$baseurl
inherited

base url for sorting by first/last name.

$baseurl

◆ $context

context grade_report::$context
inherited

The context.

$context

◆ $course

object grade_report::$course
inherited

The course.

$course

◆ $courseid

int grade_report::$courseid
inherited

The courseid.

$courseid

◆ $currentgroup

int grade_report::$currentgroup
inherited

The current group being displayed.

$currentgroup

◆ $currentgroupname

string grade_report::$currentgroupname
inherited

The current groupname being displayed.

$currentgroupname

◆ $gpr

object grade_report::$gpr
inherited

Grade plugin return tracking object.

$gpr

◆ $gradebookroles

string grade_report::$gradebookroles
inherited

The roles for this report.

$gradebookroles

◆ $grades

array grade_report_grader::$grades

The final grades.

$grades

◆ $gradeserror

array grade_report_grader::$gradeserror = array()

Array of errors for bulk grades updating.

$gradeserror

◆ $group_selector

string grade_report::$group_selector
inherited

A HTML select element used to select the current group.

$group_selector

◆ $groupsql

string grade_report::$groupsql
protectedinherited

An SQL fragment used to add linking information to the group tables.

$groupsql

◆ $groupwheresql

string grade_report::$groupwheresql
protectedinherited

An SQL constraint to append to the queries used by this object to build the report.

$groupwheresql

◆ $gtree

grade_tree grade_report::$gtree
inherited

The grade_tree object.

$gtree

◆ $page

int grade_report::$page
inherited

Current page (for paging).

$page

◆ $pbarurl

string grade_report::$pbarurl
inherited

base url for paging.

$pbarurl

◆ $prefs

array grade_report::$prefs = array()
inherited

User preferences related to this report.

$prefs

◆ $rowcount

int grade_report_grader::$rowcount = 0

A count of the rows, used for css classes.

$rowcount

◆ $sortitemid

int grade_report_grader::$sortitemid

The id of the grade_item by which this report will be sorted.

$sortitemid

◆ $sortorder

int grade_report_grader::$sortorder

Sortorder used in the SQL selections.

$sortorder

◆ $userid

int int grade_report::$userid = -1
protectedinherited

If the user is wanting to show only one particular user their id will be placed here.

$userid

◆ $usersearch

string string grade_report::$usersearch = ''
protectedinherited

If the user is wanting to search for a particular user within searchable fields their needle will be placed here.

$usersearch

◆ $userselect

string grade_report_grader::$userselect

An SQL fragment affecting the search for users.

$userselect

◆ $userwheresql

string grade_report::$userwheresql
protectedinherited

An SQL constraint to append to the queries used by this object to build the report.

$userwheresql


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