gradingform_instance Class Reference

Class to manage one gradingform instance. More...

Inheritance diagram for gradingform_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

Copyright

2011 Marina Glancy

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

$data

the 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	$raterid	value for raterid in the duplicate
int	$itemid	value for itemid in the duplicate

Return values

int	id 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

int	id 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

$elementvalue

value of element submitted from the form

Return values

boolean

true 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

int	the 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

$elementvalue

is the scalar or array received in $_POST

Return values

boolean

true 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:

• grade/grading/form/lib.php