Moodle PHP Documentation 4.4
Moodle 4.4.1 (Build: 20240610) (db07c09afc5)
|
Class providing an API for the grader report building and displaying. More...
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) | |
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. | |
show_only_active () | |
To check if we only need to include active enrolments. | |
ungraded_counts (bool $grouponly=false, bool $includehiddengrades=false, $showonlyactiveenrol=true) | |
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. | |
format_average_cell (grade_item $gradeitem, ?array $aggr=null, ?bool $shownumberofgrades=null) | |
Returns a row of grade items averages. | |
format_averages (array $ungradedcounts) | |
Returns a row of grade items averages. | |
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. | |
Class providing an API for the grader report building and displaying.
@uses grade_report
grade_report_grader::__construct | ( | $courseid, | |
$gpr, | |||
$context, | |||
$page = null, | |||
$sortitemid = null, | |||
string | $sort = '' ) |
Constructor.
Sets local copies of user preferences and initialises grade_tree.
int | $courseid | |
object | $gpr | grade plugin return tracking object |
string | $context | |
int | $page | The current page being viewed (when report is paged) |
int | $sortitemid | The id of the grade_item by which to sort the table |
string | $sort | Sorting direction |
|
protectedinherited |
Optionally blank out course/category totals if they contain any hidden items.
string | $courseid | the course id |
string | $course_item | an instance of grade_item |
string | $finalgrade | the grade for the course_item |
string | The new final grade |
|
protectedinherited |
Optionally blank out course/category totals if they contain any hidden items.
string | $courseid | the course id |
string | $course_item | an instance of grade_item |
string | $finalgrade | the grade for the course_item |
array[] | containing values for 'grade', 'grademax', 'grademin', 'aggregationstatus' and 'aggregationweight' |
|
staticinherited |
Calculate average grade for a given grade item.
grade_item | $gradeitem | Grade item |
array | $info | Ungraded grade items counts and report preferences. |
array | Average grade and meancount. |
|
static |
Processes a single action against a category, grade_item or grade.
string | $target | eid ({type}{id}, e.g. c4 for category4) |
string | $action | Which action to take (edit, delete etc...) |
int | $courseid | affected course. |
|
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.
int | $courseid | |
array | $collapsed |
array |
|
protected |
Returns a row of grade items averages.
grade_item | $gradeitem | Grade item. |
array | null | $aggr | Average value and meancount information. |
bool | null | $shownumberofgrades | Whether to show number of grades. |
html_table_cell | Formatted average cell. |
Reimplemented from grade_report.
|
protectedinherited |
Returns a row of grade items averages.
array | $ungradedcounts | Ungraded grade items counts with report preferences. |
html_table_row | Row with averages |
|
staticinherited |
Add additional links specific to plugin.
context_course | $context | Course context |
int | $courseid | Course ID |
array | $element | An array representing an element in the grade_tree |
grade_plugin_return | $gpr | A grade_plugin_return object |
string | $mode | Mode (user or grade item) |
stdClass | $templatecontext | Template context |
bool | $otherplugins | If we need to insert links to other plugins |
?stdClass | Updated template context |
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.
moodle_url | $url | Url to grader report page |
string | $title | Menu item title |
string | $action | View mode to change to |
bool | $active | Whether link is active in dropdown |
string|null |
grade_report_grader::get_cell_display_class | ( | grade_item | $item | ) |
Return class used for text alignment.
grade_item | $item | Can be grade item or grade |
string | class name used for text alignment |
|
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.
int | $courseid |
array |
|
protected |
Given a category element returns collapsing +/- icon if available.
|
protected |
Given element category, create a collapsible icon and course header.
array | $element |
string | HTML |
grade_report_grader::get_default_sortable | ( | ) |
Return the base report link with some default sorting applied.
string |
moodle_exception |
|
staticinherited |
Load a valid list of gradable users in a course.
int | $courseid | The course ID. |
int | null | $groupid | The group ID (optional). |
array | A list of enrolled gradable users. |
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.
boolean | $displayaverages | whether to display average rows in the table |
string | HTML |
grade_report_grader::get_hide_show_link | ( | ) |
Return the link to allow the field to collapse from the users view.
string | Dropdown menu link that'll trigger the collapsing functionality. |
coding_exception | |
moodle_exception |
|
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.
array | $element |
string | HTML |
|
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.
string | $strcode | |
string | $section | Optional language section |
string |
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.
array | $rows | The Array of rows for the left part of the report |
int | $colspan | The number of columns this cell has to span |
bool | $groupavg | If true, returns the row for group averages, otherwise for overall averages |
array | Array of rows for the left part of the report |
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"
array | $rows | The Array of rows for the left part of the report |
int | $colspan | The number of columns this cell has to span |
array | Array of rows for the left part of the report |
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.
array | $rows | The Array of rows for the left part of the report |
int | $colspan | The number of columns this cell has to span |
array | Array of rows for the left part of the report |
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.
boolean | $displayaverages | whether to display average rows in the table |
array | Array of html_table_row objects |
|
inherited |
Fetches and returns a count of all the users that will be shown on this page.
boolean | $groups | include groups limit |
boolean | $users | include users limit - default false, used for searching purposes |
int | Count of users |
|
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
string | $pref | The name of the preference (do not include the grade_report_ prefix) |
int | $objectid | An optional itemid or categoryid to check for a more fine-grained preference |
mixed | The value of the preference |
grade_report_grader::get_right_avg_row | ( | $rows = array(), | |
$grouponly = false ) |
array | $rows | Whether to return only group averages or all averages. |
bool | $grouponly | Whether to return only group averages or all averages. |
array | Array of rows for the right part of the report |
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.
array | $rows | The Array of rows for the right part of the report |
array | Array of rows for the right part of the report |
grade_report_grader::get_right_range_row | ( | $rows = array() | ) |
Builds and return the row of ranges for the right part of the grader report.
array | $rows | The Array of rows for the right part of the report |
array | Array of rows for the right part of the report |
grade_report_grader::get_right_rows | ( | bool | $displayaverages | ) |
Builds and returns the rows that will make up the right part of the grader report.
boolean | $displayaverages | whether to display average rows in the table |
array | Array of html_table_row objects |
|
protectedinherited |
Returns an arrow icon inside an tag, for the purpose of sorting a column.
string | $direction | |
moodle_url | null | $sortlink |
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.
array | $extrafields | Array of extra fields being displayed, such as user idnumber |
array | An associative array of HTML sorting links+arrows |
grade_report_grader::get_students_per_page | ( | ) |
Returns the maximum number of students to be displayed on each page.
int | The maximum number of students to display per page |
grade_report_grader::get_toggles_html | ( | ) |
Gets html toggle.
|
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.
array | $mappings | Array of field mappings (fieldname => SQL code for the value) |
array | $userfields | An array that we cast from user profile fields to search within. |
array | SQL query data in the format ['where' => '', 'params' => []]. |
|
inherited |
Get grade item type names in a course to use in filter dropdown.
array | Item types. |
grade_report_grader::load_users | ( | bool | $allusers = false | ) |
pulls out the userids of the users to be display, and sorts them
bool | $allusers | If we are getting the users within the report, we want them all irrespective of paging. |
grade_report_grader::print_toggle | ( | $type | ) |
Prints html toggle.
unknown | $type |
grade_report_grader::process_action | ( | $target, | |
$action ) |
Processes a single action against a category, grade_item or grade.
string | $target | eid ({type}{id}, e.g. c4 for category4) |
string | $action | Which action to take (edit, delete etc...) |
Reimplemented from grade_report.
grade_report_grader::process_data | ( | $data | ) |
Processes the data sent by the form (grades).
Caller is responsible for all access control checks
array | $data | form submission (with magic quotes) |
array | empty array if success, array of warnings if something fails. |
Reimplemented from grade_report.
|
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.
int | $courseid | |
array | $collapsed |
|
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.
string | $pref | The name of the preference. |
mixed | $pref_value | The value of the preference. |
int | $itemid | An optional itemid to which the preference will be assigned |
bool | Success or failure. |
|
protectedinherited |
Sets up this object's group variables, mainly to restrict the selection of users to display.
Reimplemented in gradereport_singleview\report\singleview.
|
inherited |
To check if we only need to include active enrolments.
bool |
Reimplemented in grade_report_summary.
|
staticinherited |
Shows support for being used as a 'Grades' report.
Reimplemented in grade_report_overview.
|
inherited |
Get ungraded grade items info and sum of all grade items in a course.
bool | $grouponly | If we want to compute group average only. |
bool | $includehiddengrades | Include hidden grades. |
bool | $showonlyactiveenrol | Whether to only include active enrolments. |
array | Ungraded grade items counts with report preferences. |
|
inherited |
base url for sorting by first/last name.
$baseurl
|
inherited |
The context.
$context
|
inherited |
The course.
$course
|
inherited |
The courseid.
$courseid
|
inherited |
The current group being displayed.
$currentgroup
|
inherited |
The current groupname being displayed.
$currentgroupname
|
inherited |
Grade plugin return tracking object.
$gpr
|
inherited |
The roles for this report.
$gradebookroles
array grade_report_grader::$grades |
The final grades.
$grades
array grade_report_grader::$gradeserror = array() |
Array of errors for bulk grades updating.
$gradeserror
|
inherited |
A HTML select element used to select the current group.
$group_selector
|
protectedinherited |
An SQL fragment used to add linking information to the group tables.
$groupsql
|
protectedinherited |
An SQL constraint to append to the queries used by this object to build the report.
$groupwheresql
|
inherited |
The grade_tree object.
$gtree
|
inherited |
Current page (for paging).
$page
|
inherited |
base url for paging.
$pbarurl
|
inherited |
User preferences related to this report.
$prefs
int grade_report_grader::$rowcount = 0 |
A count of the rows, used for css classes.
$rowcount
int grade_report_grader::$sortitemid |
The id of the grade_item by which this report will be sorted.
$sortitemid
int grade_report_grader::$sortorder |
Sortorder used in the SQL selections.
$sortorder
|
protectedinherited |
If the user is wanting to show only one particular user their id will be placed here.
$userid
|
protectedinherited |
If the user is wanting to search for a particular user within searchable fields their needle will be placed here.
$usersearch
string grade_report_grader::$userselect |
An SQL fragment affecting the search for users.
$userselect
|
protectedinherited |
An SQL constraint to append to the queries used by this object to build the report.
$userwheresql