Browse files

MDL-30998: updated docblocks for advanced grading

  • Loading branch information...
1 parent fa4c60c commit d22e9e32e432165ccec692cceef28f20d988727b @marinaglancy marinaglancy committed Mar 15, 2012
View
76 grade/grading/form/lib.php
@@ -1,5 +1,4 @@
<?php
-
// This file is part of Moodle - http://moodle.org/
//
// Moodle is free software: you can redistribute it and/or modify
@@ -18,24 +17,41 @@
/**
* Common classes used by gradingform plugintypes are defined here
*
- * @package core
- * @subpackage grading
+ * @package core_grading
* @copyright 2011 David Mudrak <david@moodle.com>
* @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
*/
defined('MOODLE_INTERNAL') || die();
/**
- * Grading method controller represents a plugin used in a particular area
+ * 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 {@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.
+ *
+ * @copyright 2011 David Mudrak <david@moodle.com>
+ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ * @category grading
*/
abstract class gradingform_controller {
/** undefined definition status */
const DEFINITION_STATUS_NULL = 0;
/** the form is currently being edited and is not ready for usage yet */
const DEFINITION_STATUS_DRAFT = 10;
- /** the for was marked as ready for actual usage */
+ /** the form was marked as ready for actual usage */
const DEFINITION_STATUS_READY = 20;
/** @var stdClass the context */
@@ -80,27 +96,35 @@ public function __construct(stdClass $context, $component, $area, $areaid) {
}
/**
+ * Returns controller context
+ *
* @return stdClass controller context
*/
public function get_context() {
return $this->context;
}
/**
+ * Returns gradable component name
+ *
* @return string gradable component name
*/
public function get_component() {
return $this->component;
}
/**
+ * Returns gradable area name
+ *
* @return string gradable area name
*/
public function get_area() {
return $this->area;
}
/**
+ * Returns gradable area id
+ *
* @return int gradable area id
*/
public function get_areaid() {
@@ -366,7 +390,7 @@ public function get_current_instance($raterid, $itemid, $idonly = false) {
'status1' => gradingform_instance::INSTANCE_STATUS_ACTIVE,
'status2' => gradingform_instance::INSTANCE_STATUS_NEEDUPDATE);
$select = 'definitionid=:definitionid and itemid=:itemid and (status=:status1 or status=:status2)';
- if (false /* TODO $manager->allow_multiple_raters() */) {
+ if (false /* TODO MDL-31237 $manager->allow_multiple_raters() */) {
$select .= ' and raterid=:raterid';
$params['raterid'] = $raterid;
}
@@ -543,7 +567,7 @@ public static function sql_search_where($token) {
return array($subsql, $params);
}
- ////////////////////////////////////////////////////////////////////////////
+ // //////////////////////////////////////////////////////////////////////////
/**
* Loads the form definition if it exists
@@ -567,6 +591,8 @@ protected function load_definition() {
abstract protected function delete_plugin_definition();
/**
+ * Returns the name of the grading method plugin, eg 'rubric'
+ *
* @return string the name of the grading method plugin, eg 'rubric'
* @see PARAM_PLUGIN
*/
@@ -617,15 +643,39 @@ public function render_grade($page, $itemid, $gradinginfo, $defaultcontent, $can
}
/**
- * Class to manage one grading instance. Stores information and performs actions like
- * update, copy, validate, submit, etc.
+ * 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}
*
* @copyright 2011 Marina Glancy
+ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ * @category grading
*/
abstract class gradingform_instance {
+ /** Valid istance status */
const INSTANCE_STATUS_ACTIVE = 1;
+ /** The grade needs to be updated by grader (usually because of changes is grading method) */
const INSTANCE_STATUS_NEEDUPDATE = 2;
+ /** The grader started grading but did clicked neither submit nor cancel */
const INSTANCE_STATUS_INCOMPLETE = 0;
+ /** Grader re-graded the student and this is the status for previous grade stored as history */
const INSTANCE_STATUS_ARCHIVE = 3;
/** @var stdClass record from table grading_instances */
@@ -768,8 +818,7 @@ protected function make_active() {
*/
public function cancel() {
global $DB;
- // TODO what if we happen delete the ACTIVE instance, shall we rollback to the last ARCHIVE? or throw an exception?
- // TODO create cleanup cron
+ // TODO MDL-31239 throw exception if status is not INSTANCE_STATUS_INCOMPLETE
$DB->delete_records('grading_instances', array('id' => $this->get_id()));
}
@@ -788,7 +837,7 @@ public function update($elementvalue) {
if (isset($elementvalue['itemid']) && $elementvalue['itemid'] != $this->data->itemid) {
$newdata->itemid = $elementvalue['itemid'];
}
- // TODO also update: rawgrade, feedback, feedbackformat
+ // TODO MDL-31087 also update: rawgrade, feedback, feedbackformat
$DB->update_record('grading_instances', $newdata);
foreach ($newdata as $key => $value) {
$this->data->$key = $value;
@@ -873,6 +922,9 @@ public function validate_grading_element($elementvalue) {
* 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 validate_grading_element()
* @return string
*/
View
7 grade/grading/form/rubric/backup/moodle2/backup_gradingform_rubric_plugin.class.php
@@ -1,5 +1,4 @@
<?php
-
// This file is part of Moodle - http://moodle.org/
//
// Moodle is free software: you can redistribute it and/or modify
@@ -18,8 +17,7 @@
/**
* Support for backup API
*
- * @package gradingform
- * @subpackage rubric
+ * @package gradingform_rubric
* @copyright 2011 David Mudrak <david@moodle.com>
* @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
*/
@@ -28,6 +26,9 @@
/**
* Defines rubric backup structures
+ *
+ * @copyright 2011 David Mudrak <david@moodle.com>
+ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
*/
class backup_gradingform_rubric_plugin extends backup_gradingform_plugin {
View
13 grade/grading/form/rubric/backup/moodle2/restore_gradingform_rubric_plugin.class.php
@@ -1,5 +1,4 @@
<?php
-
// This file is part of Moodle - http://moodle.org/
//
// Moodle is free software: you can redistribute it and/or modify
@@ -18,8 +17,7 @@
/**
* Support for restore API
*
- * @package gradingform
- * @subpackage rubric
+ * @package gradingform_rubric
* @copyright 2011 David Mudrak <david@moodle.com>
* @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
*/
@@ -28,6 +26,9 @@
/**
* Restores the rubric specific data from grading.xml file
+ *
+ * @copyright 2011 David Mudrak <david@moodle.com>
+ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
*/
class restore_gradingform_rubric_plugin extends restore_gradingform_plugin {
@@ -69,6 +70,8 @@ protected function define_instance_plugin_structure() {
*
* Sets the mapping 'gradingform_rubric_criterion' to be used later by
* {@link self::process_gradinform_rubric_filling()}
+ *
+ * @param stdClass|array $data
*/
public function process_gradingform_rubric_criterion($data) {
global $DB;
@@ -86,6 +89,8 @@ public function process_gradingform_rubric_criterion($data) {
*
* Sets the mapping 'gradingform_rubric_level' to be used later by
* {@link self::process_gradinform_rubric_filling()}
+ *
+ * @param stdClass|array $data
*/
public function process_gradingform_rubric_level($data) {
global $DB;
@@ -100,6 +105,8 @@ public function process_gradingform_rubric_level($data) {
/**
* Processes filling element data
+ *
+ * @param stdClass|array $data
*/
public function process_gradinform_rubric_filling($data) {
global $DB;
View
6 grade/grading/form/rubric/db/upgrade.php
@@ -1,5 +1,4 @@
<?php
-
// This file is part of Moodle - http://moodle.org/
//
// Moodle is free software: you can redistribute it and/or modify
@@ -16,8 +15,9 @@
// along with Moodle. If not, see <http://www.gnu.org/licenses/>.
/**
- * @package gradingform
- * @subpackage rubric
+ * This file keeps track of upgrades to plugin gradingform_rubric
+ *
+ * @package gradingform_rubric
* @copyright 2011 David Mudrak <david@moodle.com>
* @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
*/
View
4 grade/grading/form/rubric/edit.php
@@ -1,5 +1,4 @@
<?php
-
// This file is part of Moodle - http://moodle.org/
//
// Moodle is free software: you can redistribute it and/or modify
@@ -18,8 +17,7 @@
/**
* Rubric editor page
*
- * @package gradingform
- * @subpackage rubric
+ * @package gradingform_rubric
* @copyright 2011 Marina Glancy
* @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
*/
View
10 grade/grading/form/rubric/edit_form.php
@@ -1,5 +1,4 @@
<?php
-
// This file is part of Moodle - http://moodle.org/
//
// Moodle is free software: you can redistribute it and/or modify
@@ -18,8 +17,7 @@
/**
* The form used at the rubric editor page is defined here
*
- * @package gradingform
- * @subpackage rubric
+ * @package gradingform_rubric
* @copyright 2011 Marina Glancy <marina@moodle.com>
* @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
*/
@@ -32,6 +30,9 @@
/**
* Defines the rubric edit form
+ *
+ * @copyright 2011 Marina Glancy <marina@moodle.com>
+ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
*/
class gradingform_rubric_editrubric extends moodleform {
@@ -65,7 +66,6 @@ public function definition() {
// rubric editor
$element = $form->addElement('rubriceditor', 'rubric', get_string('rubric', 'gradingform_rubric'));
$form->setType('rubric', PARAM_RAW);
- //$element->freeze(); // TODO freeze rubric editor if needed
$buttonarray = array();
$buttonarray[] = &$form->createElement('submit', 'saverubric', get_string('saverubric', 'gradingform_rubric'));
@@ -175,7 +175,7 @@ public function need_confirm_regrading($controller) {
}
// freeze form elements and pass the values in hidden fields
- // TODO description_editor does not freeze the normal way!
+ // TODO MDL-29421 description_editor does not freeze the normal way, uncomment below when fixed
$form = $this->_form;
foreach (array('rubric', 'name'/*, 'description_editor'*/) as $fieldname) {
$el =& $form->getElement($fieldname);
View
6 grade/grading/form/rubric/lang/en/gradingform_rubric.php
@@ -1,5 +1,4 @@
<?php
-
// This file is part of Moodle - http://moodle.org/
//
// Moodle is free software: you can redistribute it and/or modify
@@ -16,8 +15,9 @@
// along with Moodle. If not, see <http://www.gnu.org/licenses/>.
/**
- * @package gradingform
- * @subpackage rubric
+ * Language file for plugin gradingform_rubric
+ *
+ * @package gradingform_rubric
* @copyright 2011 David Mudrak <david@moodle.com>
* @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
*/
View
26 grade/grading/form/rubric/lib.php
@@ -1,5 +1,4 @@
<?php
-
// This file is part of Moodle - http://moodle.org/
//
// Moodle is free software: you can redistribute it and/or modify
@@ -18,8 +17,7 @@
/**
* Grading method controller for the Rubric plugin
*
- * @package gradingform
- * @subpackage rubric
+ * @package gradingform_rubric
* @copyright 2011 David Mudrak <david@moodle.com>
* @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
*/
@@ -30,6 +28,9 @@
/**
* This controller encapsulates the rubric grading logic
+ *
+ * @copyright 2011 David Mudrak <david@moodle.com>
+ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
*/
class gradingform_rubric_controller extends gradingform_controller {
// Modes of displaying the rubric (used in gradingform_rubric_renderer)
@@ -160,7 +161,7 @@ public function update_or_check_rubric(stdClass $newdefinition, $usermodified =
$criterionmaxscore = null;
if (preg_match('/^NEWID\d+$/', $id)) {
// insert criterion into DB
- $data = array('definitionid' => $this->definition->id, 'descriptionformat' => FORMAT_MOODLE); // TODO format is not supported yet
+ $data = array('definitionid' => $this->definition->id, 'descriptionformat' => FORMAT_MOODLE); // TODO MDL-31235 format is not supported yet
foreach ($criteriafields as $key) {
if (array_key_exists($key, $criterion)) {
$data[$key] = $criterion[$key];
@@ -203,13 +204,12 @@ public function update_or_check_rubric(stdClass $newdefinition, $usermodified =
if (isset($level['score'])) {
$level['score'] = (float)$level['score'];
if ($level['score']<0) {
- // TODO why we can't allow negative score for rubric?
$level['score'] = 0;
}
}
if (preg_match('/^NEWID\d+$/', $levelid)) {
// insert level into DB
- $data = array('criterionid' => $id, 'definitionformat' => FORMAT_MOODLE); // TODO format is not supported yet
+ $data = array('criterionid' => $id, 'definitionformat' => FORMAT_MOODLE); // TODO MDL-31235 format is not supported yet
foreach ($levelfields as $key) {
if (array_key_exists($key, $level)) {
$data[$key] = $level[$key];
@@ -592,7 +592,7 @@ public function render_grade($page, $itemid, $gradinginfo, $defaultcontent, $can
return $this->get_renderer($page)->display_instances($this->get_active_instances($itemid), $defaultcontent, $cangrade);
}
- //// full-text search support /////////////////////////////////////////////
+ // ///// full-text search support /////////////////////////////////////////////
/**
* Prepare the part of the search query to append to the FROM statement
@@ -656,13 +656,16 @@ public function get_min_max_score() {
}
/**
- * Class to manage one rubric grading instance. Stores information and performs actions like
- * update, copy, validate, submit, etc.
+ * Class to manage one rubric grading instance.
+ *
+ * Stores information and performs actions like update, copy, validate, submit, etc.
*
* @copyright 2011 Marina Glancy
+ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
*/
class gradingform_rubric_instance extends gradingform_instance {
+ /** @var array stores the rubric, has two keys: 'criteria' and 'options' */
protected $rubric;
/**
@@ -753,7 +756,8 @@ public function update($data) {
$DB->insert_record('gradingform_rubric_fillings', $newrecord);
} else {
$newrecord = array('id' => $currentgrade['criteria'][$criterionid]['id']);
- foreach (array('levelid', 'remark'/*, 'remarkformat' TODO */) as $key) {
+ foreach (array('levelid', 'remark'/*, 'remarkformat' */) as $key) {
+ // TODO MDL-31235 format is not supported yet
if (isset($record[$key]) && $currentgrade['criteria'][$criterionid][$key] != $record[$key]) {
$newrecord[$key] = $record[$key];
}
@@ -803,7 +807,7 @@ public function get_grade() {
* Returns html for form element of type 'grading'.
*
* @param moodle_page $page
- * @param MoodleQuickForm_grading $formelement
+ * @param MoodleQuickForm_grading $gradingformelement
* @return string
*/
public function render_grading_element($page, $gradingformelement) {
View
44 grade/grading/form/rubric/renderer.php
@@ -1,5 +1,4 @@
<?php
-
// This file is part of Moodle - http://moodle.org/
//
// Moodle is free software: you can redistribute it and/or modify
@@ -16,8 +15,9 @@
// along with Moodle. If not, see <http://www.gnu.org/licenses/>.
/**
- * @package gradingform
- * @subpackage rubric
+ * Contains renderer used for displaying rubric
+ *
+ * @package gradingform_rubric
* @copyright 2011 Marina Glancy
* @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
*/
@@ -26,6 +26,9 @@
/**
* Grading method plugin renderer
+ *
+ * @copyright 2011 Marina Glancy
+ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
*/
class gradingform_rubric_renderer extends plugin_renderer_base {
@@ -44,15 +47,16 @@ class gradingform_rubric_renderer extends plugin_renderer_base {
* Also JavaScript relies on the class names of elements and when developer changes them
* script might stop working.
*
- * @param int $mode rubric display mode @see gradingform_rubric_controller
+ * @param int $mode rubric display mode, see {@link gradingform_rubric_controller}
+ * @param array $options display options for this rubric, defaults are: {@link gradingform_rubric_controller::get_default_options()}
* @param string $elementname the name of the form element (in editor mode) or the prefix for div ids (in view mode)
* @param array|null $criterion criterion data
* @param string $levelsstr evaluated templates for this criterion levels
* @param array|null $value (only in view mode) teacher's feedback on this criterion
* @return string
*/
public function criterion_template($mode, $options, $elementname = '{NAME}', $criterion = null, $levelsstr = '{LEVELS}', $value = null) {
- // TODO description format, remark format
+ // TODO MDL-31235 description format, remark format
if ($criterion === null || !is_array($criterion) || !array_key_exists('id', $criterion)) {
$criterion = array('id' => '{CRITERION-id}', 'description' => '{CRITERION-description}', 'sortorder' => '{CRITERION-sortorder}', 'class' => '{CRITERION-class}');
} else {
@@ -111,7 +115,7 @@ public function criterion_template($mode, $options, $elementname = '{NAME}', $cr
} else if ($mode == gradingform_rubric_controller::DISPLAY_EVAL_FROZEN) {
$criteriontemplate .= html_writer::empty_tag('input', array('type' => 'hidden', 'name' => '{NAME}[criteria][{CRITERION-id}][remark]', 'value' => $currentremark));
}else if ($mode == gradingform_rubric_controller::DISPLAY_REVIEW || $mode == gradingform_rubric_controller::DISPLAY_VIEW) {
- $criteriontemplate .= html_writer::tag('td', $currentremark, array('class' => 'remark')); // TODO maybe some prefix here like 'Teacher remark:'
+ $criteriontemplate .= html_writer::tag('td', $currentremark, array('class' => 'remark'));
}
}
$criteriontemplate .= html_writer::end_tag('tr'); // .criterion
@@ -136,14 +140,15 @@ public function criterion_template($mode, $options, $elementname = '{NAME}', $cr
* Also JavaScript relies on the class names of elements and when developer changes them
* script might stop working.
*
- * @param int $mode rubric display mode @see gradingform_rubric_controller
+ * @param int $mode rubric display mode see {@link gradingform_rubric_controller}
+ * @param array $options display options for this rubric, defaults are: {@link gradingform_rubric_controller::get_default_options()}
* @param string $elementname the name of the form element (in editor mode) or the prefix for div ids (in view mode)
* @param string|int $criterionid either id of the nesting criterion or a macro for template
* @param array|null $level level data, also in view mode it might also have property $level['checked'] whether this level is checked
* @return string
*/
public function level_template($mode, $options, $elementname = '{NAME}', $criterionid = '{CRITERION-id}', $level = null) {
- // TODO definition format
+ // TODO MDL-31235 definition format
if (!isset($level['id'])) {
$level = array('id' => '{LEVEL-id}', 'definition' => '{LEVEL-definition}', 'score' => '{LEVEL-score}', 'class' => '{LEVEL-class}', 'checked' => false);
} else {
@@ -229,7 +234,8 @@ public function level_template($mode, $options, $elementname = '{NAME}', $criter
* Also JavaScript relies on the class names of elements and when developer changes them
* script might stop working.
*
- * @param int $mode rubric display mode @see gradingform_rubric_controller
+ * @param int $mode rubric display mode see {@link gradingform_rubric_controller}
+ * @param array $options display options for this rubric, defaults are: {@link gradingform_rubric_controller::get_default_options()}
* @param string $elementname the name of the form element (in editor mode) or the prefix for div ids (in view mode)
* @param string $criteriastr evaluated templates for this rubric's criteria
* @return string
@@ -271,8 +277,8 @@ protected function rubric_template($mode, $options, $elementname, $criteriastr)
* Generates html template to view/edit the rubric options. Expression {NAME} is used in
* template for the form element name
*
- * @param int $mode
- * @param array $options
+ * @param int $mode rubric display mode see {@link gradingform_rubric_controller}
+ * @param array $options display options for this rubric, defaults are: {@link gradingform_rubric_controller::get_default_options()}
* @return string
*/
protected function rubric_edit_options($mode, $options) {
@@ -297,7 +303,6 @@ protected function rubric_edit_options($mode, $options) {
$selectoptions = array(0 => get_string($option.'0', 'gradingform_rubric'), 1 => get_string($option.'1', 'gradingform_rubric'));
$valuestr = html_writer::select($selectoptions, $attrs['name'], $value, false, array('id' => $attrs['id']));
$html .= html_writer::tag('span', $valuestr, array('class' => 'value'));
- // TODO add here button 'Sort levels'
} else {
$html .= html_writer::tag('span', get_string($option.$value, 'gradingform_rubric'), array('class' => 'value'));
if ($mode == gradingform_rubric_controller::DISPLAY_EDIT_FROZEN) {
@@ -339,7 +344,8 @@ protected function rubric_edit_options($mode, $options) {
* rubric_template
*
* @param array $criteria data about the rubric design
- * @param int $mode rubric display mode @see gradingform_rubric_controller
+ * @param array $options display options for this rubric, defaults are: {@link gradingform_rubric_controller::get_default_options()}
+ * @param int $mode rubric display mode, see {@link gradingform_rubric_controller}
* @param string $elementname the name of the form element (in editor mode) or the prefix for div ids (in view mode)
* @param array $values evaluation result
* @return string
@@ -424,8 +430,8 @@ public function display_instances($instances, $defaultcontent, $cangrade) {
* Displays one grading instance
*
* @param gradingform_rubric_instance $instance
- * @param int idx unique number of instance on page
- * @param boolean $cangrade whether current user has capability to grade in this context
+ * @param int $idx unique number of instance on page
+ * @param bool $cangrade whether current user has capability to grade in this context
*/
public function display_instance(gradingform_rubric_instance $instance, $idx, $cangrade) {
$criteria = $instance->get_controller()->get_definition()->rubric_criteria;
@@ -446,6 +452,14 @@ public function display_instance(gradingform_rubric_instance $instance, $idx, $c
return $output;
}
+ /**
+ * Displays confirmation that students require re-grading
+ *
+ * @param string $elementname
+ * @param int $changelevel
+ * @param string $value
+ * @return string
+ */
public function display_regrade_confirmation($elementname, $changelevel, $value) {
$html = html_writer::start_tag('div', array('class' => 'gradingform_rubric-regrade'));
if ($changelevel<=2) {
View
43 grade/grading/form/rubric/rubriceditor.php
@@ -1,5 +1,4 @@
<?php
-
// This file is part of Moodle - http://moodle.org/
//
// Moodle is free software: you can redistribute it and/or modify
@@ -16,8 +15,9 @@
// along with Moodle. If not, see <http://www.gnu.org/licenses/>.
/**
- * @package gradingform
- * @subpackage rubric
+ * File contains definition of class MoodleQuickForm_rubriceditor
+ *
+ * @package gradingform_rubric
* @copyright 2011 Marina Glancy
* @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
*/
@@ -26,27 +26,47 @@
require_once("HTML/QuickForm/input.php");
+/**
+ * Form element for handling rubric editor
+ *
+ * The rubric editor is defined as a separate form element. This allows us to render
+ * criteria, levels and buttons using the rubric's own renderer. Also, the required
+ * Javascript library is included, which processes, on the client, buttons needed
+ * for reordering, adding and deleting criteria.
+ *
+ * If Javascript is disabled when one of those special buttons is pressed, the form
+ * element is not validated and, instead of submitting the form, we process button presses.
+ *
+ * @copyright 2011 Marina Glancy
+ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
class MoodleQuickForm_rubriceditor extends HTML_QuickForm_input {
- /** help message */
+ /** @var string help message */
public $_helpbutton = '';
- /** stores the result of the last validation: null - undefined, false - no errors, string - error(s) text */
+ /** @var string|bool stores the result of the last validation: null - undefined, false - no errors, string - error(s) text */
protected $validationerrors = null;
- /** if element has already been validated **/
+ /** @var bool if element has already been validated **/
protected $wasvalidated = false;
- /** If non-submit (JS) button was pressed: null - unknown, true/false - button was/wasn't pressed */
+ /** @var bool If non-submit (JS) button was pressed: null - unknown, true/false - button was/wasn't pressed */
protected $nonjsbuttonpressed = false;
- /** Message to display in front of the editor (that there exist grades on this rubric being edited) */
+ /** @var bool Message to display in front of the editor (that there exist grades on this rubric being edited) */
protected $regradeconfirmation = false;
+ /**
+ * Constructor for rubric editor
+ *
+ * @param string $elementName
+ * @param string $elementLabel
+ * @param array $attributes
+ */
function MoodleQuickForm_rubriceditor($elementName=null, $elementLabel=null, $attributes=null) {
parent::HTML_QuickForm_input($elementName, $elementLabel, $attributes);
}
/**
* get html for help button
*
- * @access public
- * @return string html for help button
+ * @return string html for help button
*/
public function getHelpButton() {
return $this->_helpbutton;
@@ -212,7 +232,6 @@ protected function prepare_data($value = null, $withvalidation = false) {
$level['error_definition'] = true;
}
if (!preg_match('#^[\+]?\d*$#', trim($level['score'])) && !preg_match('#^[\+]?\d*[\.,]\d+$#', trim($level['score']))) {
- // TODO why we can't allow negative score for rubric?
$errors['err_scoreformat'] = 1;
$level['error_score'] = true;
}
@@ -339,8 +358,8 @@ public function validate($value) {
/**
* Prepares the data for saving
- * @see prepare_data()
*
+ * @see prepare_data()
* @param array $submitValues
* @param boolean $assoc
* @return array
View
6 grade/grading/form/rubric/version.php
@@ -1,5 +1,4 @@
<?php
-
// This file is part of Moodle - http://moodle.org/
//
// Moodle is free software: you can redistribute it and/or modify
@@ -16,8 +15,9 @@
// along with Moodle. If not, see <http://www.gnu.org/licenses/>.
/**
- * @package gradingform
- * @subpackage rubric
+ * Version information for plugin gradingform_rubric
+ *
+ * @package gradingform_rubric
* @copyright 2011 David Mudrak <david@moodle.com>
* @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
*/
View
19 grade/grading/lib.php
@@ -1,5 +1,4 @@
<?php
-
// This file is part of Moodle - http://moodle.org/
//
// Moodle is free software: you can redistribute it and/or modify
@@ -18,8 +17,7 @@
/**
* Advanced grading methods support
*
- * @package core
- * @subpackage grading
+ * @package core_grading
* @copyright 2011 David Mudrak <david@moodle.com>
* @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
*/
@@ -35,10 +33,11 @@
* can be provided. Note that null values are allowed in the second case as the context,
* component and the area name can be set explicitly later.
*
+ * @category grading
* @example $manager = get_grading_manager($areaid);
* @example $manager = get_grading_manager(get_system_context());
* @example $manager = get_grading_manager($context, 'mod_assignment', 'submission');
- * @param stdClass|int|null $context or $areaid if $areaid is passed, no other parameter is needed
+ * @param stdClass|int|null $context_or_areaid if $areaid is passed, no other parameter is needed
* @param string|null $component the frankenstyle name of the component
* @param string|null $area the name of the gradable area
* @return grading_manager
@@ -85,6 +84,10 @@ function get_grading_manager($context_or_areaid = null, $component = null, $area
* that knows just context and component without known area, for example.
* It is also possible to change context, component and area of an existing
* manager. Such pattern is used when copying form definitions, for example.
+ *
+ * @copyright 2011 David Mudrak <david@moodle.com>
+ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ * @category grading
*/
class grading_manager {
@@ -101,6 +104,8 @@ class grading_manager {
private $areacache = null;
/**
+ * Returns grading manager context
+ *
* @return stdClass grading manager context
*/
public function get_context() {
@@ -118,6 +123,8 @@ public function set_context(stdClass $context) {
}
/**
+ * Returns grading manager component
+ *
* @return string grading manager component
*/
public function get_component() {
@@ -136,6 +143,8 @@ public function set_component($component) {
}
/**
+ * Returns grading manager area name
+ *
* @return string grading manager area name
*/
public function get_area() {
@@ -654,7 +663,7 @@ public static function tokenize($needle) {
return array_values($tokens);
}
- ////////////////////////////////////////////////////////////////////////////
+ // //////////////////////////////////////////////////////////////////////////
/**
* Make sure that the given properties were set to some not-null value
View
3 grade/grading/manage.php
@@ -21,8 +21,7 @@
* area, provides access to the plugin editor and allows user to save the
* current form as a template or re-use some existing form.
*
- * @package core_grades
- * @subpackage grading
+ * @package core_grading
* @copyright 2011 David Mudrak <david@moodle.com>
* @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
*/
View
6 grade/grading/pick.php
@@ -17,8 +17,7 @@
/**
* Allows to choose a form from the list of available templates
*
- * @package core_grades
- * @subpackage grading
+ * @package core_grading
* @copyright 2011 David Mudrak <david@moodle.com>
* @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
*/
@@ -256,6 +255,3 @@
echo $output->footer();
-////////////////////////////////////////////////////////////////////////////////
-
-
View
7 grade/grading/pick_form.php
@@ -1,5 +1,4 @@
<?php
-
// This file is part of Moodle - http://moodle.org/
//
// Moodle is free software: you can redistribute it and/or modify
@@ -18,8 +17,7 @@
/**
* Defines forms used by pick.php
*
- * @package core
- * @subpackage grading
+ * @package core_grading
* @copyright 2011 David Mudrak <david@moodle.com>
* @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
*/
@@ -30,6 +28,9 @@
/**
* Allows to search for a specific shared template
+ *
+ * @copyright 2011 David Mudrak <david@moodle.com>
+ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
*/
class grading_search_template_form extends moodleform {
View
10 grade/grading/renderer.php
@@ -1,5 +1,4 @@
<?php
-
// This file is part of Moodle - http://moodle.org/
//
// Moodle is free software: you can redistribute it and/or modify
@@ -18,8 +17,7 @@
/**
* Renderer for core_grading subsystem
*
- * @package core
- * @subpackage grading
+ * @package core_grading
* @copyright 2011 David Mudrak <david@moodle.com>
* @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
*/
@@ -28,13 +26,17 @@
/**
* Standard HTML output renderer for core_grading subsystem
+ *
+ * @copyright 2011 David Mudrak <david@moodle.com>
+ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ * @category grading
*/
class core_grading_renderer extends plugin_renderer_base {
/**
* Renders the active method selector at the grading method management screen
*
- * @param grading_manager $gradingman
+ * @param grading_manager $manager
* @param moodle_url $targeturl
* @return string
*/
View
15 grade/grading/tests/lib_test.php
@@ -17,8 +17,7 @@
/**
* Unit tests for the advanced grading subsystem
*
- * @package core
- * @subpackage grading
+ * @package core_grading
* @category phpunit
* @copyright 2011 David Mudrak <david@moodle.com>
* @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
@@ -32,13 +31,19 @@
/**
* Makes protected method accessible for testing purposes
+ *
+ * @copyright 2011 David Mudrak <david@moodle.com>
+ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
*/
class testable_grading_manager extends grading_manager {
}
/**
* Test cases for the grading manager API
+ *
+ * @copyright 2011 David Mudrak <david@moodle.com>
+ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
*/
class grading_manager_testcase extends advanced_testcase {
public function test_basic_instantiation() {
@@ -56,6 +61,9 @@ public function test_basic_instantiation() {
$manager4 = get_grading_manager($fakecontext, 'assignment_upload', 'submission');
}
+ /**
+ * Unit test to set and get grading areas
+ */
public function test_set_and_get_grading_area() {
global $DB;
@@ -95,6 +103,9 @@ public function test_set_and_get_grading_area() {
$gradingman->set_active_method('no_one_should_ever_try_to_implement_a_method_with_this_silly_name');
}
+ /**
+ * Unit test to check the tokenize method
+ */
public function test_tokenize() {
$UTFfailuremessage = 'A test using UTF-8 characters has failed. Consider updating PHP and PHP\'s PCRE or INTL extensions (MDL-30494)';

0 comments on commit d22e9e3

Please sign in to comment.