[Summary view]

   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 and optionally ->scale containing scale items)
  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  }