 |
Moodle PHP Documentation 4.2
Moodle 4.2.8 (Build: 20240610) (2d41ac46f45)
|
|
Moodle PHP Documentation 4.2
Moodle 4.2.8 (Build: 20240610) (2d41ac46f45)
|
Class represents a grading form definition used in a particular area. More...
Public Member Functions | |
| __construct (stdClass $context, $component, $area, $areaid) | |
| Do not instantinate this directly, use grading_manager::get_controller(). | |
| create_instance ($raterid, $itemid=null) | |
| This function is invoked when user (teacher) starts grading. | |
| delete_definition () | |
| Deletes the form definition and all the associated data. | |
| extend_navigation (global_navigation $navigation, navigation_node $node=null) | |
| Extends the module navigation. | |
| extend_settings_navigation (settings_navigation $settingsnav, navigation_node $node=null) | |
| Extends the module settings navigation. | |
| fetch_instance (int $raterid, int $itemid, ?int $instanceid) | |
| If an instanceid is specified and grading instance exists and it is created by this rater for this item, then the instance is returned. | |
| form_unavailable_notification () | |
| Returns a message why this form is unavailable. | |
| get_active_instances ($itemid) | |
| Returns list of ACTIVE instances for the specified $itemid (intentionally does not return instances with status NEEDUPDATE) | |
| get_all_active_instances ($since=0) | |
| Returns an array of all active instances for this definition. | |
| get_allow_grade_decimals () | |
| Returns if decimal values are allowed as grades. | |
| get_area () | |
| Returns gradable area name. | |
| get_areaid () | |
| Returns gradable area id. | |
| get_component () | |
| Returns gradable component name. | |
| get_context () | |
| Returns controller context. | |
| get_current_instance ($raterid, $itemid, $idonly=false) | |
| 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). | |
| get_definition ($force=false) | |
| Returns the grading form definition structure. | |
| get_definition_copy (gradingform_controller $target) | |
| Returns the form definition suitable for cloning into another area. | |
| get_editor_url (moodle_url $returnurl=null) | |
| Returns URL of a page where the grading form can be defined and edited. | |
| get_formatted_description () | |
| Formats the definition description for display on page. | |
| get_grade_range () | |
| Returns the range of grades used in this area. | |
| get_or_create_instance ($instanceid, $raterid, $itemid) | |
| If instanceid is specified and grading instance exists and it is created by this rater for this item, this instance is returned. | |
| has_active_instances () | |
| Returns true if there are already people who has been graded on this definition. | |
| is_form_available () | |
| Is the grading form defined and ready for usage? | |
| is_form_defined () | |
| Is the form definition record available? | |
| is_own_form ($userid=null) | |
| Is the grading form owned by the given user? | |
| is_shared_template () | |
| Is the grading form saved as a shared public template? | |
| render_grade ($page, $itemid, $gradinginfo, $defaultcontent, $cangrade) | |
| Returns html code to be included in student's feedback. | |
| render_preview (moodle_page $page) | |
| Returns the HTML code displaying the preview of the grading form. | |
| set_grade_range (array $graderange, $allowgradedecimals=false) | |
| Sets the range of grades used in this area. | |
| update_definition (stdClass $definition, $usermodified=null) | |
| Saves the defintion data into the database. | |
Static Public Member Functions | |
| static | get_external_definition_details () |
| Overridden by sub classes that wish to make definition details available to web services. | |
| static | get_external_instance_filling_details () |
| Overridden by sub classes that wish to make instance filling details available to web services. | |
| static | sql_search_from_tables ($gdid) |
| Prepare the part of the search query to append to the FROM statement. | |
| static | sql_search_where ($token) |
| Prepare the parts of the SQL WHERE statement to search for the given token. | |
Protected Member Functions | |
| delete_plugin_definition () | |
| Deletes all plugin data associated with the given form definiton. | |
| get_instance ($instance) | |
| Returns the object of type gradingform_XXX_instance (where XXX is the plugin method name) | |
| get_method_name () | |
| Returns the name of the grading method plugin, eg 'rubric'. | |
| load_definition () | |
| Loads the form definition if it exists. | |
Class represents a grading form definition used in a particular area.
General 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 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.
| gradingform_controller::__construct | ( | stdClass | $context, |
| $component, | |||
| $area, | |||
| $areaid ) |
Do not instantinate this directly, use grading_manager::get_controller().
| stdClass | $context | the context of the form |
| string | $component | the frankenstyle name of the component |
| string | $area | the name of the gradable area |
| int | $areaid | the id of the gradable area record |
| gradingform_controller::create_instance | ( | $raterid, | |
| $itemid = null ) |
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
| int | $raterid | |
| int | $itemid |
| gradingform_instance |
| gradingform_controller::delete_definition | ( | ) |
Deletes the form definition and all the associated data.
| void |
|
abstractprotected |
Deletes all plugin data associated with the given form definiton.
Reimplemented in gradingform_guide_controller, and gradingform_rubric_controller.
| gradingform_controller::extend_navigation | ( | global_navigation | $navigation, |
| navigation_node | $node = null ) |
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.
| global_navigation | $navigation | global_navigation |
| navigation_node | $node | navigation_node |
Reimplemented in gradingform_guide_controller, and gradingform_rubric_controller.
| gradingform_controller::extend_settings_navigation | ( | settings_navigation | $settingsnav, |
| navigation_node | $node = null ) |
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.
| settings_navigation | $settingsnav | settings_navigation |
| navigation_node | $node | navigation_node |
Reimplemented in gradingform_guide_controller, and gradingform_rubric_controller.
| gradingform_controller::fetch_instance | ( | int | $raterid, |
| int | $itemid, | ||
| ?int | $instanceid ) |
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.
| int | $raterid | |
| int | $itemid | |
| int | $instanceid |
| gradingform_instance |
| dml_exception |
| gradingform_controller::form_unavailable_notification | ( | ) |
Returns a message why this form is unavailable.
Maybe overriden by plugins to give more details.
| string |
| gradingform_controller::get_active_instances | ( | $itemid | ) |
Returns list of ACTIVE instances for the specified $itemid (intentionally does not return instances with status NEEDUPDATE)
| int | $itemid |
| array | of gradingform_instance objects |
| gradingform_controller::get_all_active_instances | ( | $since = 0 | ) |
Returns an array of all active instances for this definition.
(intentionally does not return instances with status NEEDUPDATE)
| int | since only return instances with timemodified >= since |
| array | of gradingform_instance objects |
|
final |
Returns if decimal values are allowed as grades.
| bool |
| gradingform_controller::get_area | ( | ) |
Returns gradable area name.
| string | gradable area name |
| gradingform_controller::get_areaid | ( | ) |
Returns gradable area id.
| int | gradable area id |
| gradingform_controller::get_component | ( | ) |
Returns gradable component name.
| string | gradable component name |
| gradingform_controller::get_context | ( | ) |
Returns controller context.
| stdClass | controller context |
| gradingform_controller::get_current_instance | ( | $raterid, | |
| $itemid, | |||
| $idonly = false ) |
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).
| int | $raterid | |
| int | $itemid | |
| boolean | $idonly |
| mixed | if $idonly=true returns id of the found instance, otherwise returns the instance object |
| gradingform_controller::get_definition | ( | $force = false | ) |
Returns the grading form definition structure.
| boolean | $force | whether to force loading from DB even if it was already loaded |
| stdClass|false | definition data or false if the form is not defined yet |
| gradingform_controller::get_definition_copy | ( | gradingform_controller | $target | ) |
Returns the form definition suitable for cloning into another area.
| gradingform_controller | $target | the controller of the new copy |
| stdClass | definition structure to pass to the target's update_definition() |
Reimplemented in gradingform_guide_controller, and gradingform_rubric_controller.
| gradingform_controller::get_editor_url | ( | moodle_url | $returnurl = null | ) |
Returns URL of a page where the grading form can be defined and edited.
| moodle_url | $returnurl | optional URL of a page where the user should be sent once they are finished with editing |
| moodle_url |
|
static |
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()
| array | An array of one or more key/value pairs containing the external_multiple_structure/s corresponding to the definition returned by $controller->get_definition() |
Reimplemented in gradingform_guide_controller, and gradingform_rubric_controller.
|
static |
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()
| array | An array of one or more key/value pairs containing the external_multiple_structure/s corresponding to the definition returned by $gradingform_<method>instance->get<method>_filling() |
Reimplemented in gradingform_guide_controller, and gradingform_rubric_controller.
| gradingform_controller::get_formatted_description | ( | ) |
Formats the definition description for display on page.
| string |
Reimplemented in gradingform_guide_controller, and gradingform_rubric_controller.
|
final |
Returns the range of grades used in this area.
| array |
|
protected |
Returns the object of type gradingform_XXX_instance (where XXX is the plugin method name)
| mixed | $instance | id or row from grading_isntances table |
| gradingform_instance |
|
protected |
Returns the name of the grading method plugin, eg 'rubric'.
| string | the name of the grading method plugin, eg 'rubric' |
| gradingform_controller::get_or_create_instance | ( | $instanceid, | |
| $raterid, | |||
| $itemid ) |
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
| int | $instanceid | |
| int | $raterid | |
| int | $itemid |
| gradingform_instance |
| dml_exception |
Reimplemented in gradingform_guide_controller, and gradingform_rubric_controller.
| gradingform_controller::has_active_instances | ( | ) |
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
| boolean |
| gradingform_controller::is_form_available | ( | ) |
Is the grading form defined and ready for usage?
| boolean |
| gradingform_controller::is_form_defined | ( | ) |
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.
| boolean |
| gradingform_controller::is_own_form | ( | $userid = null | ) |
Is the grading form owned by the given user?
The form owner is the user who created this instance of the form.
| int | $userid | the user id to check, defaults to the current user |
| boolean|null | null if the form not defined yet, boolean otherwise |
| gradingform_controller::is_shared_template | ( | ) |
Is the grading form saved as a shared public template?
| boolean |
|
protected |
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.
Reimplemented in gradingform_guide_controller, and gradingform_rubric_controller.
| gradingform_controller::render_grade | ( | $page, | |
| $itemid, | |||
| $gradinginfo, | |||
| $defaultcontent, | |||
| $cangrade ) |
Returns html code to be included in student's feedback.
| moodle_page | $page | |
| int | $itemid | |
| array | $gradinginfo | result of function grade_get_grades if plugin want to use some of their info |
| string | $defaultcontent | default string to be returned if no active grading is found or for some reason can not be shown to a user |
| boolean | $cangrade | whether current user has capability to grade in this context |
| string |
Reimplemented in gradingform_guide_controller, and gradingform_rubric_controller.
|
abstract |
Returns the HTML code displaying the preview of the grading form.
Plugins are forced to override this. Ideally they should delegate the task to their own renderer.
| moodle_page | $page | the target page |
| string |
Reimplemented in gradingform_guide_controller, and gradingform_rubric_controller.
|
final |
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_assign does).
| array | $graderange | array where first key is the minimum grade and the last key is the maximum grade. |
| bool | $allowgradedecimals | if decimal values are allowed as grades. |
|
static |
Prepare the part of the search query to append to the FROM statement.
| string | $gdid | the alias of grading_definitions.id column used by the caller |
| string |
Reimplemented in gradingform_guide_controller, and gradingform_rubric_controller.
|
static |
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.
| string | $token | token to search for |
| array |
Reimplemented in gradingform_guide_controller, and gradingform_rubric_controller.
| gradingform_controller::update_definition | ( | stdClass | $definition, |
| $usermodified = null ) |
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.
| stdClass | $definition | data containing values for the {grading_definition} table |
| int | null | $usermodified | optional userid of the author of the definition, defaults to the current user |
Reimplemented in gradingform_guide_controller, and gradingform_rubric_controller.
1.11.0