From d22e9e32e432165ccec692cceef28f20d988727b Mon Sep 17 00:00:00 2001 From: Marina Glancy Date: Thu, 15 Mar 2012 14:04:55 +0800 Subject: [PATCH] MDL-30998: updated docblocks for advanced grading --- grade/grading/form/lib.php | 76 ++++++++++++++++--- ...backup_gradingform_rubric_plugin.class.php | 7 +- ...estore_gradingform_rubric_plugin.class.php | 13 +++- grade/grading/form/rubric/db/upgrade.php | 6 +- grade/grading/form/rubric/edit.php | 4 +- grade/grading/form/rubric/edit_form.php | 10 +-- .../rubric/lang/en/gradingform_rubric.php | 6 +- grade/grading/form/rubric/lib.php | 26 ++++--- grade/grading/form/rubric/renderer.php | 44 +++++++---- grade/grading/form/rubric/rubriceditor.php | 43 ++++++++--- grade/grading/form/rubric/version.php | 6 +- grade/grading/lib.php | 19 +++-- grade/grading/manage.php | 3 +- grade/grading/pick.php | 6 +- grade/grading/pick_form.php | 7 +- grade/grading/renderer.php | 10 ++- grade/grading/tests/lib_test.php | 15 +++- 17 files changed, 207 insertions(+), 94 deletions(-) diff --git a/grade/grading/form/lib.php b/grade/grading/form/lib.php index 5a27b8f6e1e..7679c195dc3 100644 --- a/grade/grading/form/lib.php +++ b/grade/grading/form/lib.php @@ -1,5 +1,4 @@ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later */ @@ -27,7 +25,25 @@ 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 + * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later + * @category grading */ abstract class gradingform_controller { @@ -35,7 +51,7 @@ abstract class gradingform_controller { 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,6 +96,8 @@ abstract class gradingform_controller { } /** + * Returns controller context + * * @return stdClass controller context */ public function get_context() { @@ -87,6 +105,8 @@ abstract class gradingform_controller { } /** + * Returns gradable component name + * * @return string gradable component name */ public function get_component() { @@ -94,6 +114,8 @@ abstract class gradingform_controller { } /** + * Returns gradable area name + * * @return string gradable area name */ public function get_area() { @@ -101,6 +123,8 @@ abstract class gradingform_controller { } /** + * Returns gradable area id + * * @return int gradable area id */ public function get_areaid() { @@ -366,7 +390,7 @@ abstract class gradingform_controller { '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 @@ abstract class gradingform_controller { return array($subsql, $params); } - //////////////////////////////////////////////////////////////////////////// + // ////////////////////////////////////////////////////////////////////////// /** * Loads the form definition if it exists @@ -567,6 +591,8 @@ abstract class gradingform_controller { 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 @@ abstract class gradingform_controller { } /** - * 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 @@ abstract class gradingform_instance { */ 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 @@ abstract class gradingform_instance { 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 @@ abstract class gradingform_instance { * 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 */ diff --git a/grade/grading/form/rubric/backup/moodle2/backup_gradingform_rubric_plugin.class.php b/grade/grading/form/rubric/backup/moodle2/backup_gradingform_rubric_plugin.class.php index 387406d93e4..26c487ca7d3 100644 --- a/grade/grading/form/rubric/backup/moodle2/backup_gradingform_rubric_plugin.class.php +++ b/grade/grading/form/rubric/backup/moodle2/backup_gradingform_rubric_plugin.class.php @@ -1,5 +1,4 @@ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later */ @@ -28,6 +26,9 @@ defined('MOODLE_INTERNAL') || die(); /** * Defines rubric backup structures + * + * @copyright 2011 David Mudrak + * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later */ class backup_gradingform_rubric_plugin extends backup_gradingform_plugin { diff --git a/grade/grading/form/rubric/backup/moodle2/restore_gradingform_rubric_plugin.class.php b/grade/grading/form/rubric/backup/moodle2/restore_gradingform_rubric_plugin.class.php index adb95978aa9..9239782be0c 100644 --- a/grade/grading/form/rubric/backup/moodle2/restore_gradingform_rubric_plugin.class.php +++ b/grade/grading/form/rubric/backup/moodle2/restore_gradingform_rubric_plugin.class.php @@ -1,5 +1,4 @@ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later */ @@ -28,6 +26,9 @@ defined('MOODLE_INTERNAL') || die(); /** * Restores the rubric specific data from grading.xml file + * + * @copyright 2011 David Mudrak + * @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 @@ class restore_gradingform_rubric_plugin extends restore_gradingform_plugin { * * 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 @@ class restore_gradingform_rubric_plugin extends restore_gradingform_plugin { * * 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 @@ class restore_gradingform_rubric_plugin extends restore_gradingform_plugin { /** * Processes filling element data + * + * @param stdClass|array $data */ public function process_gradinform_rubric_filling($data) { global $DB; diff --git a/grade/grading/form/rubric/db/upgrade.php b/grade/grading/form/rubric/db/upgrade.php index b460fb4d143..8b682d29bd0 100644 --- a/grade/grading/form/rubric/db/upgrade.php +++ b/grade/grading/form/rubric/db/upgrade.php @@ -1,5 +1,4 @@ . /** - * @package gradingform - * @subpackage rubric + * This file keeps track of upgrades to plugin gradingform_rubric + * + * @package gradingform_rubric * @copyright 2011 David Mudrak * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later */ diff --git a/grade/grading/form/rubric/edit.php b/grade/grading/form/rubric/edit.php index 09daca91e49..3ef31571ab9 100644 --- a/grade/grading/form/rubric/edit.php +++ b/grade/grading/form/rubric/edit.php @@ -1,5 +1,4 @@ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later */ @@ -32,6 +30,9 @@ MoodleQuickForm::registerElementType('rubriceditor', $CFG->dirroot.'/grade/gradi /** * Defines the rubric edit form + * + * @copyright 2011 Marina Glancy + * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later */ class gradingform_rubric_editrubric extends moodleform { @@ -65,7 +66,6 @@ class gradingform_rubric_editrubric extends moodleform { // 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 @@ class gradingform_rubric_editrubric extends moodleform { } // 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); diff --git a/grade/grading/form/rubric/lang/en/gradingform_rubric.php b/grade/grading/form/rubric/lang/en/gradingform_rubric.php index 527e8fb0de1..079bf315e7a 100644 --- a/grade/grading/form/rubric/lang/en/gradingform_rubric.php +++ b/grade/grading/form/rubric/lang/en/gradingform_rubric.php @@ -1,5 +1,4 @@ . /** - * @package gradingform - * @subpackage rubric + * Language file for plugin gradingform_rubric + * + * @package gradingform_rubric * @copyright 2011 David Mudrak * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later */ diff --git a/grade/grading/form/rubric/lib.php b/grade/grading/form/rubric/lib.php index 247724d3daa..891987b1c5b 100644 --- a/grade/grading/form/rubric/lib.php +++ b/grade/grading/form/rubric/lib.php @@ -1,5 +1,4 @@ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later */ @@ -30,6 +28,9 @@ require_once($CFG->dirroot.'/grade/grading/form/lib.php'); /** * This controller encapsulates the rubric grading logic + * + * @copyright 2011 David Mudrak + * @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 @@ class gradingform_rubric_controller extends gradingform_controller { $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 @@ class gradingform_rubric_controller extends gradingform_controller { 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 @@ class gradingform_rubric_controller extends gradingform_controller { 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 @@ class gradingform_rubric_controller extends gradingform_controller { } /** - * 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 @@ class gradingform_rubric_instance extends gradingform_instance { $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 @@ class gradingform_rubric_instance extends gradingform_instance { * 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) { diff --git a/grade/grading/form/rubric/renderer.php b/grade/grading/form/rubric/renderer.php index c269c0afba9..db8a4fa5762 100644 --- a/grade/grading/form/rubric/renderer.php +++ b/grade/grading/form/rubric/renderer.php @@ -1,5 +1,4 @@ . /** - * @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 @@ defined('MOODLE_INTERNAL') || die(); /** * 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,7 +47,8 @@ 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 @@ -52,7 +56,7 @@ class gradingform_rubric_renderer extends plugin_renderer_base { * @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 @@ class gradingform_rubric_renderer extends plugin_renderer_base { } 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 @@ 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 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 @@ 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 string $criteriastr evaluated templates for this rubric's criteria * @return string @@ -271,8 +277,8 @@ class gradingform_rubric_renderer extends plugin_renderer_base { * 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 @@ class gradingform_rubric_renderer extends plugin_renderer_base { $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 @@ class gradingform_rubric_renderer extends plugin_renderer_base { * 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 @@ class gradingform_rubric_renderer extends plugin_renderer_base { * 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 @@ class gradingform_rubric_renderer extends plugin_renderer_base { 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) { diff --git a/grade/grading/form/rubric/rubriceditor.php b/grade/grading/form/rubric/rubriceditor.php index 61d8307f179..88878869afe 100644 --- a/grade/grading/form/rubric/rubriceditor.php +++ b/grade/grading/form/rubric/rubriceditor.php @@ -1,5 +1,4 @@ . /** - * @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,18 +26,39 @@ defined('MOODLE_INTERNAL') || die(); 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); } @@ -45,8 +66,7 @@ class MoodleQuickForm_rubriceditor extends HTML_QuickForm_input { /** * 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 @@ class MoodleQuickForm_rubriceditor extends HTML_QuickForm_input { $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 @@ class MoodleQuickForm_rubriceditor extends HTML_QuickForm_input { /** * Prepares the data for saving - * @see prepare_data() * + * @see prepare_data() * @param array $submitValues * @param boolean $assoc * @return array diff --git a/grade/grading/form/rubric/version.php b/grade/grading/form/rubric/version.php index cb8ef58ddf4..68b70648c69 100644 --- a/grade/grading/form/rubric/version.php +++ b/grade/grading/form/rubric/version.php @@ -1,5 +1,4 @@ . /** - * @package gradingform - * @subpackage rubric + * Version information for plugin gradingform_rubric + * + * @package gradingform_rubric * @copyright 2011 David Mudrak * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later */ diff --git a/grade/grading/lib.php b/grade/grading/lib.php index 0a3de68b306..2a0bd47be2b 100644 --- a/grade/grading/lib.php +++ b/grade/grading/lib.php @@ -1,5 +1,4 @@ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later */ @@ -35,10 +33,11 @@ defined('MOODLE_INTERNAL') || die(); * 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 + * @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 @@ class grading_manager { } /** + * Returns grading manager component + * * @return string grading manager component */ public function get_component() { @@ -136,6 +143,8 @@ class grading_manager { } /** + * Returns grading manager area name + * * @return string grading manager area name */ public function get_area() { @@ -654,7 +663,7 @@ class grading_manager { return array_values($tokens); } - //////////////////////////////////////////////////////////////////////////// + // ////////////////////////////////////////////////////////////////////////// /** * Make sure that the given properties were set to some not-null value diff --git a/grade/grading/manage.php b/grade/grading/manage.php index f796640cc78..fc8483ecd4d 100644 --- a/grade/grading/manage.php +++ b/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 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later */ diff --git a/grade/grading/pick.php b/grade/grading/pick.php index d140cd6466e..075ca272e0b 100644 --- a/grade/grading/pick.php +++ b/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 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later */ @@ -256,6 +255,3 @@ echo $output->single_button( echo $output->footer(); -//////////////////////////////////////////////////////////////////////////////// - - diff --git a/grade/grading/pick_form.php b/grade/grading/pick_form.php index 2498942dcf4..f9f49e07a38 100644 --- a/grade/grading/pick_form.php +++ b/grade/grading/pick_form.php @@ -1,5 +1,4 @@ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later */ @@ -30,6 +28,9 @@ require_once($CFG->dirroot.'/lib/formslib.php'); /** * Allows to search for a specific shared template + * + * @copyright 2011 David Mudrak + * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later */ class grading_search_template_form extends moodleform { diff --git a/grade/grading/renderer.php b/grade/grading/renderer.php index 1ab295599d5..3ebad48ea25 100644 --- a/grade/grading/renderer.php +++ b/grade/grading/renderer.php @@ -1,5 +1,4 @@ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later */ @@ -28,13 +26,17 @@ defined('MOODLE_INTERNAL') || die(); /** * Standard HTML output renderer for core_grading subsystem + * + * @copyright 2011 David Mudrak + * @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 */ diff --git a/grade/grading/tests/lib_test.php b/grade/grading/tests/lib_test.php index e28c85bc175..35c15f37442 100644 --- a/grade/grading/tests/lib_test.php +++ b/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 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later @@ -32,6 +31,9 @@ require_once($CFG->dirroot . '/grade/grading/lib.php'); // Include the code to t /** * Makes protected method accessible for testing purposes + * + * @copyright 2011 David Mudrak + * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later */ class testable_grading_manager extends grading_manager { } @@ -39,6 +41,9 @@ class testable_grading_manager extends grading_manager { /** * Test cases for the grading manager API + * + * @copyright 2011 David Mudrak + * @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 @@ class grading_manager_testcase extends advanced_testcase { $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 @@ class grading_manager_testcase extends advanced_testcase { $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)'; -- 2.17.1