mod/workshop/form/lib.php

   1 <?php
   2 // This file is part of Moodle - http://moodle.org/
   3 //
   4 // Moodle is free software: you can redistribute it and/or modify
   5 // it under the terms of the GNU General Public License as published by
   6 // the Free Software Foundation, either version 3 of the License, or
   7 // (at your option) any later version.
   8 //
   9 // Moodle is distributed in the hope that it will be useful,
  10 // but WITHOUT ANY WARRANTY; without even the implied warranty of
  11 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  12 // GNU General Public License for more details.
  13 //
  14 // You should have received a copy of the GNU General Public License
  15 // along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
  16
  17 /**
  18  * This file defines interface of all grading strategy logic classes
  19  *
  20  * @package    mod_workshop
  21  * @copyright  2009 David Mudrak <david.mudrak@gmail.com>
  22  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  23  */
  24
  25 defined('MOODLE_INTERNAL') || die();
  26
  27 /**
  28  * Strategy interface defines all methods that strategy subplugins has to implement
  29  */
  30 interface workshop_strategy {
  31
  32     /**
  33      * Factory method returning a form that is used to define the assessment form
  34      *
  35      * @param string $actionurl URL of the action handler script, defaults to auto detect
  36      * @return stdclass The instance of the assessment form editor class
  37      */
  38     public function get_edit_strategy_form($actionurl=null);
  39
  40     /**
  41      * Saves the assessment dimensions and other grading form elements
  42      *
  43      * Assessment dimension (also know as assessment element) represents one aspect or criterion
  44      * to be evaluated. Each dimension consists of a set of form fields. Strategy-specific information
  45      * are saved in workshopform_{strategyname} tables.
  46      *
  47      * @param stdClass $data Raw data as returned by the form editor
  48      * @return void
  49      */
  50     public function save_edit_strategy_form(stdclass $data);
  51
  52     /**
  53      * Factory method returning an instance of an assessment form
  54      *
  55      * @param moodle_url $actionurl URL of form handler, defaults to auto detect the current url
  56      * @param string $mode          Mode to open the form in: preview|assessment
  57      * @param stdClass $assessment  If opening in the assessment mode, the current assessment record
  58      * @param bool $editable        Shall the form be opened as editable (true) or read-only (false)
  59      * @param array $options        More assessment form options, editableweight implemented only now
  60      */
  61     public function get_assessment_form(moodle_url $actionurl=null, $mode='preview', stdclass $assessment=null, $editable=true, $options=array());
  62
  63     /**
  64      * Saves the filled assessment and returns the grade for submission as suggested by the reviewer
  65      *
  66      * This method processes data submitted using the form returned by {@link get_assessment_form()}
  67      * The returned grade should be rounded to 5 decimals as with round($grade, 5).
  68      *
  69      * @see grade_floatval()
  70      * @param stdClass $assessment Assessment being filled
  71      * @param stdClass $data       Raw data as returned by the assessment form
  72      * @return float|null          Raw percentual grade (0.00000 to 100.00000) for submission
  73      *                             as suggested by the peer or null if impossible to count
  74      */
  75     public function save_assessment(stdclass $assessment, stdclass $data);
  76
  77     /**
  78      * Has the assessment form been defined and is ready to be used by the reviewers?
  79      *
  80      * @return boolean
  81      */
  82     public function form_ready();
  83
  84     /**
  85      * Returns a general information about the assessment dimensions
  86      *
  87      * @return array [dimid] => stdclass (->id ->max ->min ->weight)
  88      */
  89     public function get_dimensions_info();
  90
  91     /**
  92      * Returns recordset with detailed information of all assessments done using this strategy
  93      *
  94      * The returned structure must be a recordset of objects containing at least properties:
  95      * submissionid, assessmentid, assessmentweight, reviewerid, gradinggrade, dimensionid and grade.
  96      * It is possible to pass user id(s) of reviewer(s). Then, the method returns just the reviewer's
  97      * assessments info.
  98      *
  99      * @param array|int|null $restrict optional id or ids of the reviewer
 100      * @return moodle_recordset
 101      */
 102     public function get_assessments_recordset($restrict=null);
 103
 104     /**
 105      * Is a given scale used by the instance of workshop?
 106      *
 107      * If the grading strategy does not use scales, it should just return false. If the strategy
 108      * supports scales, it returns true if the given scale is used.
 109      * If workshopid is null, it checks for any workshop instance. If workshopid is provided,
 110      * it checks the given instance only.
 111      *
 112      * @param int $scaleid id of the scale to check
 113      * @param int|null $workshopid id of workshop instance to check, checks all in case of null
 114      * @return bool
 115      */
 116     public static function scale_used($scaleid, $workshopid=null);
 117
 118     /**
 119      * Delete all data related to a given workshop module instance
 120      *
 121      * This is called from {@link workshop_delete_instance()}.
 122      *
 123      * @param int $workshopid id of the workshop module instance being deleted
 124      * @return void
 125      */
 126     public static function delete_instance($workshopid);
 127 }