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

Class to manage one gradingform instance. More...

Inheritance diagram for gradingform_instance:
gradingform_guide_instance gradingform_rubric_instance

Public Member Functions

 __construct ($controller, $data)
 Creates an instance.
 
 cancel ()
 Deletes this (INCOMPLETE) instance from database.
 
 clear_attempt ($data)
 Removes the attempt from the gradingform_*_fillings table.
 
 copy ($raterid, $itemid)
 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.
 
 default_validation_error_message ()
 Returns the error message displayed if validation failed.
 
 get_controller ()
 Returns the controller.
 
 get_current_instance ()
 Returns the current (active or needupdate) instance for the same raterid and itemid as this instance.
 
 get_data ($key)
 Returns the specified element from object $this->data.
 
 get_grade ()
 Calculates the grade to be pushed to the gradebook.
 
 get_id ()
 Returns instance id.
 
 get_status ()
 Returns instance status.
 
 is_empty_form ($elementvalue)
 Determines whether the submitted form was empty.
 
 render_grading_element ($page, $gradingformelement)
 Returns html for form element of type 'grading'.
 
 submit_and_get_grade ($elementvalue, $itemid)
 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.
 
 update ($elementvalue)
 Updates the instance with the data received from grading form.
 
 validate_grading_element ($elementvalue)
 Server-side validation of the data received from grading form.
 

Static Public Member Functions

static create_new ($definitionid, $raterid, $itemid)
 Creates a new empty instance in DB and mark its status as INCOMPLETE.
 

Public Attributes

const INSTANCE_STATUS_ACTIVE = 1
 Valid istance status.
 
const INSTANCE_STATUS_ARCHIVE = 3
 Grader re-graded the student and this is the status for previous grade stored as history.
 
const INSTANCE_STATUS_INCOMPLETE = 0
 The grader started grading but did clicked neither submit nor cancel.
 
const INSTANCE_STATUS_NEEDUPDATE = 2
 The grade needs to be updated by grader (usually because of changes is grading method)
 

Protected Member Functions

 make_active ()
 Marks the instance as ACTIVE and current active instance (if exists) as ARCHIVE.
 

Protected Attributes

gradingform_controller $controller
 link to the corresponding controller
 
stdClass $data
 record from table grading_instances
 

Detailed Description

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 MoodleQuickForm_grading

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

Constructor & Destructor Documentation

◆ __construct()

gradingform_instance::__construct ( $controller,
$data )

Creates an instance.

Parameters
gradingform_controller$controller
stdClass$data

Member Function Documentation

◆ cancel()

gradingform_instance::cancel ( )

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.

Reimplemented in gradingform_guide_instance, and gradingform_rubric_instance.

◆ clear_attempt()

gradingform_instance::clear_attempt ( $data)

Removes the attempt from the gradingform_*_fillings table.

This function is not abstract as to not break plugins that might use advanced grading.

Parameters
array$datathe attempt data

Reimplemented in gradingform_guide_instance, and gradingform_rubric_instance.

◆ copy()

gradingform_instance::copy ( $raterid,
$itemid )

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.

Parameters
int$rateridvalue for raterid in the duplicate
int$itemidvalue for itemid in the duplicate
Return values
intid of the new instance

Reimplemented in gradingform_guide_instance, and gradingform_rubric_instance.

◆ create_new()

static gradingform_instance::create_new ( $definitionid,
$raterid,
$itemid )
static

Creates a new empty instance in DB and mark its status as INCOMPLETE.

Parameters
int$definitionid
int$raterid
int$itemid
Return values
intid of the created instance

◆ default_validation_error_message()

gradingform_instance::default_validation_error_message ( )

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.

See also
validate_grading_element()
Return values
string

◆ get_controller()

gradingform_instance::get_controller ( )

Returns the controller.

Return values
gradingform_controller

◆ get_current_instance()

gradingform_instance::get_current_instance ( )

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 values
gradingform_instance

◆ get_data()

gradingform_instance::get_data ( $key)

Returns the specified element from object $this->data.

Parameters
string$key
Return values
mixed

◆ get_grade()

gradingform_instance::get_grade ( )
abstract

Calculates the grade to be pushed to the gradebook.

Returned grade must be in range $this->get_controller()->get_grade_range() Plugins must returned grade converted to int unless $this->get_controller()->get_allow_grade_decimals() is true.

Return values
float|int

Reimplemented in gradingform_guide_instance, and gradingform_rubric_instance.

◆ get_id()

gradingform_instance::get_id ( )

Returns instance id.

Return values
int

◆ get_status()

gradingform_instance::get_status ( )

Returns instance status.

Return values
int

◆ is_empty_form()

gradingform_instance::is_empty_form ( $elementvalue)

Determines whether the submitted form was empty.

Parameters
array$elementvaluevalue of element submitted from the form
Return values
booleantrue if the form is empty

Reimplemented in gradingform_guide_instance, and gradingform_rubric_instance.

◆ render_grading_element()

gradingform_instance::render_grading_element ( $page,
$gradingformelement )
abstract

Returns html for form element of type 'grading'.

If there is a form input element it must have the name $gradingformelement->getName(). If there are more than one input elements they MUST be elements of array with name $gradingformelement->getName(). Example: {NAME}[myelement1], {NAME}[myelement2][sub1], {NAME}[myelement2][sub2], etc. ( {NAME} is a shortcut for $gradingformelement->getName() ) After submitting the form the value of $_POST[{NAME}] is passed to the functions validate_grading_element() and submit_and_get_grade()

Plugins may use $gradingformelement->getValue() to get the value passed on previous form submit

When forming html it is a plugin's responsibility to analyze flags $gradingformelement->_flagFrozen and $gradingformelement->_persistantFreeze:

(_flagFrozen == false) => form element is editable

(_flagFrozen == false && _persistantFreeze == true) => form element is not editable but all values are passed as hidden elements

(_flagFrozen == false && _persistantFreeze == false) => form element is not editable and no values are passed as hidden elements

Plugins are welcome to use AJAX in the form element. But it is strongly recommended that the grading only becomes active when teacher presses 'Submit' button (the method submit_and_get_grade() is invoked)

Also client-side JS validation may be implemented here

See also
MoodleQuickForm_grading in lib/form/grading.php
Parameters
moodle_page$page
MoodleQuickForm_grading$gradingformelement
Return values
string

Reimplemented in gradingform_guide_instance, and gradingform_rubric_instance.

◆ submit_and_get_grade()

gradingform_instance::submit_and_get_grade ( $elementvalue,
$itemid )

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)

Parameters
array$elementvalue
int$itemid
Return values
intthe grade on 0-100 scale

◆ update()

gradingform_instance::update ( $elementvalue)

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.

Parameters
array$elementvalue

Reimplemented in gradingform_guide_instance, and gradingform_rubric_instance.

◆ validate_grading_element()

gradingform_instance::validate_grading_element ( $elementvalue)

Server-side validation of the data received from grading form.

Parameters
mixed$elementvalueis the scalar or array received in $_POST
Return values
booleantrue if the form data is validated and contains no errors

Reimplemented in gradingform_guide_instance, and gradingform_rubric_instance.


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