moodle/mod/workshop/form/rubric/lib.php

<?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 dimension
    if (!$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 file
    send_stored_file($file, 0, 0, $forcedownload, $options);
}

/**
 * Rubric grading strategy logic.
 */
class workshop_rubric_strategy implements workshop_strategy {

    /** @const default number of dimensions to show */
    const MINDIMS = 3;

    /** @const 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 it

        require_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 files
        for ($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 deleted

        if ($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 levels
            foreach ($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 it
        global $DB;
        require_once(__DIR__ . '/assessment_form.php');

        $fields         = $this->prepare_form_fields($this->dimensions);
        $nodimensions   = count($this->dimensions);

        // rewrite URLs to the embeded files
        for ($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.grade
                  FROM {workshop_submissions} s
                  JOIN {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 processing

        return $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 weight
                  FROM {workshopform_rubric} d
            INNER JOIN {workshopform_rubric_levels} l ON (d.id = l.dimensionid)
                 WHERE d.workshopid = :workshopid
              GROUP 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.definitionformat
                  FROM {workshopform_rubric} r
             LEFT JOIN {workshopform_rubric_levels} l ON (l.dimensionid = r.id)
                 WHERE r.workshopid = :workshopid
                 ORDER 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} wg
                 WHERE 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;
        }
    }
}