AutorÃa | Ultima modificación | Ver Log |
<?php// This file is part of Moodle - http://moodle.org///// Moodle is free software: you can redistribute it and/or modify// it under the terms of the GNU General Public License as published by// the Free Software Foundation, either version 3 of the License, or// (at your option) any later version.//// Moodle is distributed in the hope that it will be useful,// but WITHOUT ANY WARRANTY; without even the implied warranty of// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the// GNU General Public License for more details.//// You should have received a copy of the GNU General Public License// along with Moodle. If not, see <http://www.gnu.org/licenses/>./*** This file defines a class with rubric grading strategy logic** @package workshopform_rubric* @copyright 2009 David Mudrak <david.mudrak@gmail.com>* @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later*/defined('MOODLE_INTERNAL') || die();require_once(__DIR__ . '/../lib.php'); // Interface definition.require_once($CFG->libdir . '/gradelib.php'); // To handle float vs decimal issues./*** Server workshop files** @category files* @param stdClass $course course object* @param stdClass $cm course module object* @param stdClass $context context object* @param string $filearea file area* @param array $args extra arguments* @param bool $forcedownload whether or not force download* @param array $options additional options affecting the file serving* @return bool*/function workshopform_rubric_pluginfile($course, $cm, $context, $filearea, array $args, $forcedownload, array $options=array()) {global $DB;if ($context->contextlevel != CONTEXT_MODULE) {return false;}require_login($course, true, $cm);if ($filearea !== 'description') {return false;}$itemid = (int)array_shift($args); // the id of the assessment form dimensionif (!$workshop = $DB->get_record('workshop', array('id' => $cm->instance))) {send_file_not_found();}if (!$dimension = $DB->get_record('workshopform_rubric', array('id' => $itemid ,'workshopid' => $workshop->id))) {send_file_not_found();}// TODO now make sure the user is allowed to see the file// (media embedded into the dimension description)$fs = get_file_storage();$relativepath = implode('/', $args);$fullpath = "/$context->id/workshopform_rubric/$filearea/$itemid/$relativepath";if (!$file = $fs->get_file_by_hash(sha1($fullpath)) or $file->is_directory()) {return false;}// finally send the filesend_stored_file($file, 0, 0, $forcedownload, $options);}/*** Rubric grading strategy logic.*/class workshop_rubric_strategy implements workshop_strategy {/** @var default number of dimensions to show */const MINDIMS = 3;/** @var number of dimensions to add */const ADDDIMS = 2;/** @var workshop the parent workshop instance */protected $workshop;/** @var array definition of the assessment form fields */protected $dimensions = null;/** @var array options for dimension description fields */protected $descriptionopts;/** @var array options for level definition fields */protected $definitionopts;/** @var object rubric configuration */protected $config;/*** Constructor** @param workshop $workshop The workshop instance record* @return void*/public function __construct(workshop $workshop) {$this->workshop = $workshop;$this->dimensions = $this->load_fields();$this->config = $this->load_config();$this->descriptionopts = array('trusttext' => true, 'subdirs' => false, 'maxfiles' => -1);//one day the definitions may become proper wysiwyg fields - not used yet$this->definitionopts = array('trusttext' => true, 'subdirs' => false, 'maxfiles' => -1);}/*** Factory method returning an instance of an assessment form editor class** @param $actionurl URL of form handler, defaults to auto detect the current url*/public function get_edit_strategy_form($actionurl=null) {global $CFG; // needed because the included files use itrequire_once(__DIR__ . '/edit_form.php');$fields = $this->prepare_form_fields($this->dimensions);$fields->config_layout = $this->config->layout;$nodimensions = count($this->dimensions);$norepeatsdefault = max($nodimensions + self::ADDDIMS, self::MINDIMS);$norepeats = optional_param('norepeats', $norepeatsdefault, PARAM_INT); // number of dimensions$adddims = optional_param('adddims', '', PARAM_ALPHA); // shall we add more dimensions?if ($adddims) {$norepeats += self::ADDDIMS;}// Append editor context to editor options, giving preference to existing context.$this->descriptionopts = array_merge(array('context' => $this->workshop->context), $this->descriptionopts);// prepare the embeded filesfor ($i = 0; $i < $nodimensions; $i++) {// prepare all editor elements$fields = file_prepare_standard_editor($fields, 'description__idx_'.$i, $this->descriptionopts,$this->workshop->context, 'workshopform_rubric', 'description', $fields->{'dimensionid__idx_'.$i});}$customdata = array();$customdata['workshop'] = $this->workshop;$customdata['strategy'] = $this;$customdata['norepeats'] = $norepeats;$customdata['descriptionopts'] = $this->descriptionopts;$customdata['current'] = $fields;$attributes = array('class' => 'editstrategyform');return new workshop_edit_rubric_strategy_form($actionurl, $customdata, 'post', '', $attributes);}/*** Save the assessment dimensions into database** Saves data into the main strategy form table. If the record->id is null or zero,* new record is created. If the record->id is not empty, the existing record is updated. Records with* empty 'description' field are removed from database.* The passed data object are the raw data returned by the get_data().** @uses $DB* @param stdClass $data Raw data returned by the dimension editor form* @return void*/public function save_edit_strategy_form(stdclass $data) {global $DB;$norepeats = $data->norepeats;$layout = $data->config_layout;$data = $this->prepare_database_fields($data);$deletedims = array(); // dimension ids to be deleted$deletelevs = array(); // level ids to be deletedif ($DB->record_exists('workshopform_rubric_config', array('workshopid' => $this->workshop->id))) {$DB->set_field('workshopform_rubric_config', 'layout', $layout, array('workshopid' => $this->workshop->id));} else {$record = new stdclass();$record->workshopid = $this->workshop->id;$record->layout = $layout;$DB->insert_record('workshopform_rubric_config', $record, false);}foreach ($data as $record) {if (0 == strlen(trim($record->description_editor['text']))) {if (!empty($record->id)) {// existing record with empty description - to be deleted$deletedims[] = $record->id;foreach ($record->levels as $level) {if (!empty($level->id)) {$deletelevs[] = $level->id;}}}continue;}if (empty($record->id)) {// new field$record->id = $DB->insert_record('workshopform_rubric', $record);} else {// exiting field$DB->update_record('workshopform_rubric', $record);}// re-save with correct path to embeded media files$record = file_postupdate_standard_editor($record, 'description', $this->descriptionopts,$this->workshop->context, 'workshopform_rubric', 'description', $record->id);$DB->update_record('workshopform_rubric', $record);// create/update the criterion levelsforeach ($record->levels as $level) {$level->dimensionid = $record->id;if (0 == strlen(trim($level->definition))) {if (!empty($level->id)) {$deletelevs[] = $level->id;}continue;}if (empty($level->id)) {// new field$level->id = $DB->insert_record('workshopform_rubric_levels', $level);} else {// exiting field$DB->update_record('workshopform_rubric_levels', $level);}}}$DB->delete_records_list('workshopform_rubric_levels', 'id', $deletelevs);$this->delete_dimensions($deletedims);}/*** Factory method returning an instance of an assessment form** @param moodle_url $actionurl URL of form handler, defaults to auto detect the current url* @param string $mode Mode to open the form in: preview/assessment/readonly* @param stdClass $assessment The current assessment* @param bool $editable* @param array $options*/public function get_assessment_form(moodle_url $actionurl=null, $mode='preview', stdclass $assessment=null, $editable=true, $options=array()) {global $CFG; // needed because the included files use itglobal $DB;require_once(__DIR__ . '/assessment_form.php');$fields = $this->prepare_form_fields($this->dimensions);$nodimensions = count($this->dimensions);// rewrite URLs to the embeded filesfor ($i = 0; $i < $nodimensions; $i++) {$fields->{'description__idx_'.$i} = file_rewrite_pluginfile_urls($fields->{'description__idx_'.$i},'pluginfile.php', $this->workshop->context->id, 'workshopform_rubric', 'description',$fields->{'dimensionid__idx_'.$i});}if ('assessment' === $mode and !empty($assessment)) {// load the previously saved assessment data$grades = $this->get_current_assessment_data($assessment);$current = new stdclass();for ($i = 0; $i < $nodimensions; $i++) {$dimid = $fields->{'dimensionid__idx_'.$i};if (isset($grades[$dimid])) {$givengrade = $grades[$dimid]->grade;// find a level with this grade$levelid = null;foreach ($this->dimensions[$dimid]->levels as $level) {if (grade_floats_equal($level->grade, $givengrade)) {$levelid = $level->id;break;}}$current->{'gradeid__idx_'.$i} = $grades[$dimid]->id;$current->{'chosenlevelid__idx_'.$i} = $levelid;}}}// set up the required custom data common for all strategies$customdata['strategy'] = $this;$customdata['workshop'] = $this->workshop;$customdata['mode'] = $mode;$customdata['options'] = $options;// set up strategy-specific custom data$customdata['nodims'] = $nodimensions;$customdata['fields'] = $fields;$customdata['current'] = isset($current) ? $current : null;$attributes = array('class' => 'assessmentform rubric ' . $this->config->layout);$formclassname = 'workshop_rubric_' . $this->config->layout . '_assessment_form';return new $formclassname($actionurl, $customdata, 'post', '', $attributes, $editable);}/*** Saves the filled assessment** This method processes data submitted using the form returned by {@link get_assessment_form()}** @param stdClass $assessment Assessment being filled* @param stdClass $data Raw data as returned by the assessment form* @return float|null Raw grade (0.00000 to 100.00000) for submission as suggested by the peer*/public function save_assessment(stdclass $assessment, stdclass $data) {global $DB;for ($i = 0; isset($data->{'dimensionid__idx_' . $i}); $i++) {$grade = new stdclass();$grade->id = $data->{'gradeid__idx_' . $i};$grade->assessmentid = $assessment->id;$grade->strategy = 'rubric';$grade->dimensionid = $data->{'dimensionid__idx_' . $i};$chosenlevel = $data->{'chosenlevelid__idx_'.$i};$grade->grade = $this->dimensions[$grade->dimensionid]->levels[$chosenlevel]->grade;if (empty($grade->id)) {// new grade$grade->id = $DB->insert_record('workshop_grades', $grade);} else {// updated grade$DB->update_record('workshop_grades', $grade);}}return $this->update_peer_grade($assessment);}/*** Has the assessment form been defined and is ready to be used by the reviewers?** @return boolean*/public function form_ready() {if (count($this->dimensions) > 0) {return true;}return false;}/*** @see parent::get_assessments_recordset()*/public function get_assessments_recordset($restrict=null) {global $DB;$sql = 'SELECT s.id AS submissionid,a.id AS assessmentid, a.weight AS assessmentweight, a.reviewerid, a.gradinggrade,g.dimensionid, g.gradeFROM {workshop_submissions} sJOIN {workshop_assessments} a ON (a.submissionid = s.id)JOIN {workshop_grades} g ON (g.assessmentid = a.id AND g.strategy = :strategy)WHERE s.example=0 AND s.workshopid=:workshopid'; // to be cont.$params = array('workshopid' => $this->workshop->id, 'strategy' => $this->workshop->strategy);if (is_null($restrict)) {// update all users - no more conditions} elseif (!empty($restrict)) {list($usql, $uparams) = $DB->get_in_or_equal($restrict, SQL_PARAMS_NAMED);$sql .= " AND a.reviewerid $usql";$params = array_merge($params, $uparams);} else {throw new coding_exception('Empty value is not a valid parameter here');}$sql .= ' ORDER BY s.id'; // this is important for bulk processingreturn $DB->get_recordset_sql($sql, $params);}/*** @see parent::get_dimensions_info()*/public function get_dimensions_info() {global $DB;$sql = 'SELECT d.id AS id, MIN(l.grade) AS min, MAX(l.grade) AS max, 1 AS weightFROM {workshopform_rubric} dINNER JOIN {workshopform_rubric_levels} l ON (d.id = l.dimensionid)WHERE d.workshopid = :workshopidGROUP BY d.id';$params = array('workshopid' => $this->workshop->id);return $DB->get_records_sql($sql, $params);}/*** Is a given scale used by the instance of workshop?** This grading strategy does not use scales.** @param int $scaleid id of the scale to check* @param int|null $workshopid id of workshop instance to check, checks all in case of null* @return bool*/public static function scale_used($scaleid, $workshopid=null) {return false;}/*** Delete all data related to a given workshop module instance** @see workshop_delete_instance()* @param int $workshopid id of the workshop module instance being deleted* @return void*/public static function delete_instance($workshopid) {global $DB;$dimensions = $DB->get_records('workshopform_rubric', array('workshopid' => $workshopid), '', 'id');$DB->delete_records_list('workshopform_rubric_levels', 'dimensionid', array_keys($dimensions));$DB->delete_records('workshopform_rubric', array('workshopid' => $workshopid));$DB->delete_records('workshopform_rubric_config', array('workshopid' => $workshopid));}////////////////////////////////////////////////////////////////////////////////// Internal methods ///////////////////////////////////////////////////////////////////////////////////*** Loads the fields of the assessment form currently used in this workshop** @return array definition of assessment dimensions*/protected function load_fields() {global $DB;$sql = "SELECT r.id AS rid, r.sort, r.description, r.descriptionformat,l.id AS lid, l.grade, l.definition, l.definitionformatFROM {workshopform_rubric} rLEFT JOIN {workshopform_rubric_levels} l ON (l.dimensionid = r.id)WHERE r.workshopid = :workshopidORDER BY r.sort, l.grade";$params = array('workshopid' => $this->workshop->id);$rs = $DB->get_recordset_sql($sql, $params);$fields = array();foreach ($rs as $record) {if (!isset($fields[$record->rid])) {$fields[$record->rid] = new stdclass();$fields[$record->rid]->id = $record->rid;$fields[$record->rid]->sort = $record->sort;$fields[$record->rid]->description = $record->description;$fields[$record->rid]->descriptionformat = $record->descriptionformat;$fields[$record->rid]->levels = array();}if (!empty($record->lid)) {$fields[$record->rid]->levels[$record->lid] = new stdclass();$fields[$record->rid]->levels[$record->lid]->id = $record->lid;$fields[$record->rid]->levels[$record->lid]->grade = $record->grade;$fields[$record->rid]->levels[$record->lid]->definition = $record->definition;$fields[$record->rid]->levels[$record->lid]->definitionformat = $record->definitionformat;}}$rs->close();return $fields;}/*** Get the configuration for the current rubric strategy** @return object*/protected function load_config() {global $DB;if (!$config = $DB->get_record('workshopform_rubric_config', array('workshopid' => $this->workshop->id), 'layout')) {$config = (object)array('layout' => 'list');}return $config;}/*** Maps the dimension data from DB to the form fields** @param array $fields Array of dimensions definition as returned by {@link load_fields()}* @return stdclass of fields data to be used by the mform set_data*/protected function prepare_form_fields(array $fields) {$formdata = new stdclass();$key = 0;foreach ($fields as $field) {$formdata->{'dimensionid__idx_' . $key} = $field->id;$formdata->{'description__idx_' . $key} = $field->description;$formdata->{'description__idx_' . $key.'format'} = $field->descriptionformat;$formdata->{'numoflevels__idx_' . $key} = count($field->levels);$lev = 0;foreach ($field->levels as $level) {$formdata->{'levelid__idx_' . $key . '__idy_' . $lev} = $level->id;$formdata->{'grade__idx_' . $key . '__idy_' . $lev} = $level->grade;$formdata->{'definition__idx_' . $key . '__idy_' . $lev} = $level->definition;$formdata->{'definition__idx_' . $key . '__idy_' . $lev . 'format'} = $level->definitionformat;$lev++;}$key++;}return $formdata;}/*** Deletes dimensions and removes embedded media from its descriptions** todo we may check that there are no assessments done using these dimensions and probably remove them** @param array $masterids* @return void*/protected function delete_dimensions(array $ids) {global $DB;$fs = get_file_storage();foreach ($ids as $id) {if (!empty($id)) { // to prevent accidental removal of all files in the area$fs->delete_area_files($this->workshop->context->id, 'workshopform_rubric', 'description', $id);}}$DB->delete_records_list('workshopform_rubric', 'id', $ids);}/*** Prepares data returned by {@link workshop_edit_rubric_strategy_form} so they can be saved into database** It automatically adds some columns into every record. The sorting is* done by the order of the returned array and starts with 1.* Called internally from {@link save_edit_strategy_form()} only. Could be private but* keeping protected for unit testing purposes.** @param stdClass $raw Raw data returned by mform* @return array Array of objects to be inserted/updated in DB*/protected function prepare_database_fields(stdclass $raw) {$cook = array();for ($i = 0; $i < $raw->norepeats; $i++) {$cook[$i] = new stdclass();$cook[$i]->id = $raw->{'dimensionid__idx_'.$i};$cook[$i]->workshopid = $this->workshop->id;$cook[$i]->sort = $i + 1;$cook[$i]->description_editor = $raw->{'description__idx_'.$i.'_editor'};$cook[$i]->levels = array();$j = 0;while (isset($raw->{'levelid__idx_' . $i . '__idy_' . $j})) {$level = new stdclass();$level->id = $raw->{'levelid__idx_' . $i . '__idy_' . $j};$level->grade = $raw->{'grade__idx_'.$i.'__idy_'.$j};$level->definition = $raw->{'definition__idx_'.$i.'__idy_'.$j};$level->definitionformat = FORMAT_HTML;$cook[$i]->levels[] = $level;$j++;}}return $cook;}/*** Returns the list of current grades filled by the reviewer indexed by dimensionid** @param stdClass $assessment Assessment record* @return array [int dimensionid] => stdclass workshop_grades record*/protected function get_current_assessment_data(stdclass $assessment) {global $DB;if (empty($this->dimensions)) {return array();}list($dimsql, $dimparams) = $DB->get_in_or_equal(array_keys($this->dimensions), SQL_PARAMS_NAMED);// beware! the caller may rely on the returned array is indexed by dimensionid$sql = "SELECT dimensionid, wg.*FROM {workshop_grades} wgWHERE assessmentid = :assessmentid AND strategy= :strategy AND dimensionid $dimsql";$params = array('assessmentid' => $assessment->id, 'strategy' => 'rubric');$params = array_merge($params, $dimparams);return $DB->get_records_sql($sql, $params);}/*** Aggregates the assessment form data and sets the grade for the submission given by the peer** @param stdClass $assessment Assessment record* @return float|null Raw grade (from 0.00000 to 100.00000) for submission as suggested by the peer*/protected function update_peer_grade(stdclass $assessment) {$grades = $this->get_current_assessment_data($assessment);$suggested = $this->calculate_peer_grade($grades);if (!is_null($suggested)) {$this->workshop->set_peer_grade($assessment->id, $suggested);}return $suggested;}/*** Calculates the aggregated grade given by the reviewer** @param array $grades Grade records as returned by {@link get_current_assessment_data}* @uses $this->dimensions* @return float|null Raw grade (from 0.00000 to 100.00000) for submission as suggested by the peer*/protected function calculate_peer_grade(array $grades) {if (empty($grades)) {return null;}// summarize the grades given in rubrics$sumgrades = 0;foreach ($grades as $grade) {$sumgrades += $grade->grade;}// get the minimal and maximal possible grade (sum of minimal/maximal grades across all dimensions)$mingrade = 0;$maxgrade = 0;foreach ($this->dimensions as $dimension) {$mindimensiongrade = null;$maxdimensiongrade = null;foreach ($dimension->levels as $level) {if (is_null($mindimensiongrade) or $level->grade < $mindimensiongrade) {$mindimensiongrade = $level->grade;}if (is_null($maxdimensiongrade) or $level->grade > $maxdimensiongrade) {$maxdimensiongrade = $level->grade;}}$mingrade += $mindimensiongrade;$maxgrade += $maxdimensiongrade;}if ($maxgrade - $mingrade > 0) {return grade_floatval(100 * ($sumgrades - $mingrade) / ($maxgrade - $mingrade));} else {return null;}}}