Search moodle.org's
Developer Documentation
Developer Documentation
See Release Notes
Long Term Support Release
- Bug fixes for general core bugs in 4.1.x will end 13 November 2023 (12 months).
- Bug fixes for security issues in 4.1.x will end 10 November 2025 (36 months).
- PHP version: minimum PHP 7.4.0 Note: minimum PHP version has increased since Moodle 4.0. PHP 8.0.x is supported too.
/grade/grading/form/ -> lib.php (source)
Differences Between: [Versions 401 and 402] [Versions 401 and 403]
Common classes used by gradingform plugintypes are defined here
| Copyright: | 2011 David Mudrak <david@moodle.com> |
| License: | http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later |
| File Size: | 1085 lines (40 kb) |
| Included or required: | 0 times |
| Referenced: | 1 time |
| Includes or requires: | 0 files |
Defines 3 classes
gradingform_controller:: (30 methods):
__construct()
get_context()
get_component()
get_area()
get_areaid()
is_form_defined()
is_form_available()
is_shared_template()
is_own_form()
form_unavailable_notification()
get_editor_url()
extend_settings_navigation()
extend_navigation()
get_definition()
get_definition_copy()
update_definition()
get_formatted_description()
get_current_instance()
get_active_instances()
get_all_active_instances()
has_active_instances()
get_instance()
create_instance()
get_or_create_instance()
fetch_instance()
delete_definition()
sql_search_from_tables()
sql_search_where()
load_definition()
get_method_name()
name:: (6 methods):
render_grade()
set_grade_range()
get_grade_range()
get_allow_grade_decimals()
get_external_definition_details()
get_external_instance_filling_details()
gradingform_instance:: (16 methods):
__construct()
create_new()
copy()
get_current_instance()
get_controller()
get_data()
get_id()
get_status()
make_active()
cancel()
update()
is_empty_form()
clear_attempt()
submit_and_get_grade()
validate_grading_element()
default_validation_error_message()
Class: gradingform_controller - X-Ref
Class represents a grading form definition used in a particular areaGeneral data about definition is stored in the standard DB table
grading_definitions. A separate entry is created for each grading area
(i.e. for each module). Plugins may define and use additional tables
to store additional data about definitions.
Advanced grading plugins must declare a class gradingform_xxxx_controller
extending this class and put it in lib.php in the plugin folder.
See {@link gradingform_rubric_controller} as an example
Except for overwriting abstract functions, plugin developers may want
to overwrite functions responsible for loading and saving of the
definition to include additional data stored.
| __construct(stdClass $context, $component, $area, $areaid) X-Ref |
| Do not instantinate this directly, use {@link grading_manager::get_controller()} param: stdClass $context the context of the form param: string $component the frankenstyle name of the component param: string $area the name of the gradable area param: int $areaid the id of the gradable area record |
| get_context() X-Ref |
| Returns controller context return: stdClass controller context |
| get_component() X-Ref |
| Returns gradable component name return: string gradable component name |
| get_area() X-Ref |
| Returns gradable area name return: string gradable area name |
| get_areaid() X-Ref |
| Returns gradable area id return: int gradable area id |
| is_form_defined() X-Ref |
| Is the form definition record available? Note that this actually checks whether the process of defining the form ever started and not whether the form definition should be considered as final. return: boolean |
| is_form_available() X-Ref |
| Is the grading form defined and ready for usage? return: boolean |
| is_shared_template() X-Ref |
| Is the grading form saved as a shared public template? return: boolean |
| is_own_form($userid = null) X-Ref |
| Is the grading form owned by the given user? The form owner is the user who created this instance of the form. param: int $userid the user id to check, defaults to the current user return: boolean|null null if the form not defined yet, boolean otherwise |
| form_unavailable_notification() X-Ref |
| Returns a message why this form is unavailable. Maybe overriden by plugins to give more details. return: string |
| get_editor_url(moodle_url $returnurl = null) X-Ref |
| Returns URL of a page where the grading form can be defined and edited. param: moodle_url $returnurl optional URL of a page where the user should be sent once they are finished with editing return: moodle_url |
| extend_settings_navigation(settings_navigation $settingsnav, navigation_node $node=null) X-Ref |
| Extends the module settings navigation This function is called when the context for the page is an activity module with the FEATURE_ADVANCED_GRADING, the user has the permission moodle/grade:managegradingforms and there is an area with the active grading method set to the given plugin. param: settings_navigation $settingsnav {@link settings_navigation} param: navigation_node $node {@link navigation_node} |
| extend_navigation(global_navigation $navigation, navigation_node $node=null) X-Ref |
| Extends the module navigation This function is called when the context for the page is an activity module with the FEATURE_ADVANCED_GRADING and there is an area with the active grading method set to the given plugin. param: global_navigation $navigation {@link global_navigation} param: navigation_node $node {@link navigation_node} |
| get_definition($force = false) X-Ref |
| Returns the grading form definition structure param: boolean $force whether to force loading from DB even if it was already loaded return: stdClass|false definition data or false if the form is not defined yet |
| get_definition_copy(gradingform_controller $target) X-Ref |
| Returns the form definition suitable for cloning into another area param: gradingform_controller $target the controller of the new copy return: stdClass definition structure to pass to the target's {@link update_definition()} |
| update_definition(stdClass $definition, $usermodified = null) X-Ref |
| Saves the defintion data into the database The implementation in this base class stores the common data into the record into the {grading_definition} table. The plugins are likely to extend this and save their data into own tables, too. param: stdClass $definition data containing values for the {grading_definition} table param: int|null $usermodified optional userid of the author of the definition, defaults to the current user |
| get_formatted_description() X-Ref |
| Formats the definition description for display on page return: string |
| get_current_instance($raterid, $itemid, $idonly = false) X-Ref |
| Returns the current instance (either with status ACTIVE or NEEDUPDATE) for this definition for the specified $raterid and $itemid (if multiple raters are allowed, or only for $itemid otherwise). param: int $raterid param: int $itemid param: boolean $idonly return: mixed if $idonly=true returns id of the found instance, otherwise returns the instance object |
| get_active_instances($itemid) X-Ref |
| Returns list of ACTIVE instances for the specified $itemid (intentionally does not return instances with status NEEDUPDATE) param: int $itemid return: array of gradingform_instance objects |
| get_all_active_instances($since = 0) X-Ref |
| Returns an array of all active instances for this definition. (intentionally does not return instances with status NEEDUPDATE) param: int since only return instances with timemodified >= since return: array of gradingform_instance objects |
| has_active_instances() X-Ref |
| Returns true if there are already people who has been graded on this definition. In this case plugins may restrict changes of the grading definition return: boolean |
| get_instance($instance) X-Ref |
| Returns the object of type gradingform_XXX_instance (where XXX is the plugin method name) param: mixed $instance id or row from grading_isntances table return: gradingform_instance |
| create_instance($raterid, $itemid = null) X-Ref |
| This function is invoked when user (teacher) starts grading. It creates and returns copy of the current ACTIVE instance if it exists. If this is the first grading attempt, a new instance is created. The status of the returned instance is INCOMPLETE param: int $raterid param: int $itemid return: gradingform_instance |
| get_or_create_instance($instanceid, $raterid, $itemid) X-Ref |
| If instanceid is specified and grading instance exists and it is created by this rater for this item, this instance is returned. Otherwise new instance is created for the specified rater and itemid param: int $instanceid param: int $raterid param: int $itemid return: gradingform_instance |
| fetch_instance(int $raterid, int $itemid, ?int $instanceid) X-Ref |
| If an instanceid is specified and grading instance exists and it is created by this rater for this item, then the instance is returned. If instanceid is not known, then null can be passed to fetch the current instance matchign the specified raterid and itemid. If the instanceid is falsey, or no instance was found, then create a new instance for the specified rater and item. param: int $raterid param: int $itemid param: int $instanceid return: gradingform_instance |
| delete_definition() X-Ref |
| Deletes the form definition and all the associated data return: void |
| sql_search_from_tables($gdid) X-Ref |
| Prepare the part of the search query to append to the FROM statement param: string $gdid the alias of grading_definitions.id column used by the caller return: string |
| sql_search_where($token) X-Ref |
| Prepare the parts of the SQL WHERE statement to search for the given token The returned array cosists of the list of SQL comparions and the list of respective parameters for the comparisons. The returned chunks will be joined with other conditions using the OR operator. param: string $token token to search for return: array |
| load_definition() X-Ref |
| Loads the form definition if it exists The default implementation just tries to load the record from the {grading_definitions} table. The plugins are likely to override this with a more complex query that loads all required data at once. |
| get_method_name() X-Ref |
| Returns the name of the grading method plugin, eg 'rubric' return: string the name of the grading method plugin, eg 'rubric' |
| render_grade($page, $itemid, $gradinginfo, $defaultcontent, $cangrade) X-Ref |
| Returns html code to be included in student's feedback. param: moodle_page $page param: int $itemid param: array $gradinginfo result of function grade_get_grades if plugin want to use some of their info param: string $defaultcontent default string to be returned if no active grading is found or for some reason can not be shown to a user param: boolean $cangrade whether current user has capability to grade in this context return: string |
| set_grade_range(array $graderange, $allowgradedecimals = false) X-Ref |
| Sets the range of grades used in this area. This is usually either range like 0-100 or the scale where keys start from 1. Typically modules will call it: $controller->set_grade_range(make_grades_menu($gradingtype), $gradingtype > 0); Negative $gradingtype means that scale is used and the grade must be rounded to the nearest int. Positive $gradingtype means that range 0..$gradingtype is used for the grades and in this case grade does not have to be rounded. Sometimes modules always expect grade to be rounded (like mod_assignment does). param: array $graderange array where first _key_ is the minimum grade and the param: bool $allowgradedecimals if decimal values are allowed as grades. |
| get_grade_range() X-Ref |
| Returns the range of grades used in this area return: array |
| get_allow_grade_decimals() X-Ref |
| Returns if decimal values are allowed as grades return: bool |
| get_external_definition_details() X-Ref |
| Overridden by sub classes that wish to make definition details available to web services. When not overridden, only definition data common to all grading methods is made available. When overriding, the return value should be an array containing one or more key/value pairs. These key/value pairs should match the definition returned by the get_definition() function. For examples, look at: $gradingform_rubric_controller->get_external_definition_details() $gradingform_guide_controller->get_external_definition_details() return: array An array of one or more key/value pairs containing the external_multiple_structure/s |
| get_external_instance_filling_details() X-Ref |
| Overridden by sub classes that wish to make instance filling details available to web services. When not overridden, only instance filling data common to all grading methods is made available. When overriding, the return value should be an array containing one or more key/value pairs. These key/value pairs should match the filling data returned by the get_<method>_filling() function in the gradingform_instance subclass. For examples, look at: $gradingform_rubric_controller->get_external_instance_filling_details() $gradingform_guide_controller->get_external_instance_filling_details() return: array An array of one or more key/value pairs containing the external_multiple_structure/s |
Class: gradingform_instance - X-Ref
Class to manage one gradingform instance.Gradingform instance is created for each evaluation of a student, using advanced grading.
It is stored as an entry in the DB table gradingform_instance.
One instance (usually the latest) has the status INSTANCE_STATUS_ACTIVE. Sometimes it may
happen that a teacher wants to change the definition when some students have already been
graded. In this case their instances change status to INSTANCE_STATUS_NEEDUPDATE.
To support future use of AJAX for background saving of incomplete evaluations the
status INSTANCE_STATUS_INCOMPLETE is introduced. If 'Cancel' is pressed this entry
is deleted.
When grade is updated the previous active instance receives status INSTANCE_STATUS_ACTIVE.
Advanced grading plugins must declare a class gradingform_xxxx_instance
extending this class and put it in lib.php in the plugin folder.
The reference to an instance of this class is passed to an advanced grading form element
included in the grading form, so this class must implement functions for rendering
and validation of this form element. See {@link MoodleQuickForm_grading}
| __construct($controller, $data) X-Ref |
| Creates an instance param: gradingform_controller $controller param: stdClass $data |
| create_new($definitionid, $raterid, $itemid) X-Ref |
| Creates a new empty instance in DB and mark its status as INCOMPLETE param: int $definitionid param: int $raterid param: int $itemid return: int id of the created instance |
| copy($raterid, $itemid) X-Ref |
| Duplicates the instance before editing (optionally substitutes raterid and/or itemid with the specified values) Plugins may want to override this function to copy data from additional tables as well param: int $raterid value for raterid in the duplicate param: int $itemid value for itemid in the duplicate return: int id of the new instance |
| get_current_instance() X-Ref |
| Returns the current (active or needupdate) instance for the same raterid and itemid as this instance. This function is useful to find the status of the currently modified instance return: gradingform_instance |
| get_controller() X-Ref |
| Returns the controller return: gradingform_controller |
| get_data($key) X-Ref |
| Returns the specified element from object $this->data param: string $key return: mixed |
| get_id() X-Ref |
| Returns instance id return: int |
| get_status() X-Ref |
| Returns instance status return: int |
| make_active() X-Ref |
| Marks the instance as ACTIVE and current active instance (if exists) as ARCHIVE |
| cancel() X-Ref |
| Deletes this (INCOMPLETE) instance from database. This function is invoked on cancelling the grading form and/or during cron cleanup. Plugins using additional tables must override this method to remove additional data. Note that if the teacher just closes the window or presses 'Back' button of the browser, this function is not invoked. |
| update($elementvalue) X-Ref |
| Updates the instance with the data received from grading form. This function may be called via AJAX when grading is not yet completed, so it does not change the status of the instance. param: array $elementvalue |
| is_empty_form($elementvalue) X-Ref |
| Determines whether the submitted form was empty. param: array $elementvalue value of element submitted from the form return: boolean true if the form is empty |
| clear_attempt($data) X-Ref |
| Removes the attempt from the gradingform_*_fillings table. This function is not abstract as to not break plugins that might use advanced grading. param: array $data the attempt data |
| submit_and_get_grade($elementvalue, $itemid) X-Ref |
| Called when teacher submits the grading form: updates the instance in DB, marks it as ACTIVE and returns the grade to be pushed to the gradebook. $itemid must be specified here (it was not required when the instance was created, because it might not existed in draft) param: array $elementvalue param: int $itemid return: int the grade on 0-100 scale |
| validate_grading_element($elementvalue) X-Ref |
| Server-side validation of the data received from grading form. param: mixed $elementvalue is the scalar or array received in $_POST return: boolean true if the form data is validated and contains no errors |
| default_validation_error_message() X-Ref |
| Returns the error message displayed if validation failed. If plugin wants to display custom message, the empty string should be returned here and the custom message should be output in render_grading_element() Please note that in assignments grading in 2.2 the grading form is not validated properly and this message is not being displayed. return: string |
