aa08dd19090a3e4896ebd4730a5160b2f26cd034
[moodle.git] / mod / workshop / locallib.php
1 <?php
3 // This file is part of Moodle - http://moodle.org/
4 //
5 // Moodle is free software: you can redistribute it and/or modify
6 // it under the terms of the GNU General Public License as published by
7 // the Free Software Foundation, either version 3 of the License, or
8 // (at your option) any later version.
9 //
10 // Moodle is distributed in the hope that it will be useful,
11 // but WITHOUT ANY WARRANTY; without even the implied warranty of
12 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
13 // GNU General Public License for more details.
14 //
15 // You should have received a copy of the GNU General Public License
16 // along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
18 /**
19  * Library of internal classes and functions for module workshop
20  *
21  * All the workshop specific functions, needed to implement the module
22  * logic, should go to here. Instead of having bunch of function named
23  * workshop_something() taking the workshop instance as the first
24  * parameter, we use a class workshop that provides all methods.
25  *
26  * @package    mod_workshop
27  * @copyright  2009 David Mudrak <david.mudrak@gmail.com>
28  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
29  */
31 defined('MOODLE_INTERNAL') || die();
33 require_once(dirname(__FILE__).'/lib.php');     // we extend this library here
34 require_once($CFG->libdir . '/gradelib.php');   // we use some rounding and comparing routines here
35 require_once($CFG->libdir . '/filelib.php');
37 /**
38  * Full-featured workshop API
39  *
40  * This wraps the workshop database record with a set of methods that are called
41  * from the module itself. The class should be initialized right after you get
42  * $workshop, $cm and $course records at the begining of the script.
43  */
44 class workshop {
46     /** error status of the {@link self::add_allocation()} */
47     const ALLOCATION_EXISTS             = -9999;
49     /** the internal code of the workshop phases as are stored in the database */
50     const PHASE_SETUP                   = 10;
51     const PHASE_SUBMISSION              = 20;
52     const PHASE_ASSESSMENT              = 30;
53     const PHASE_EVALUATION              = 40;
54     const PHASE_CLOSED                  = 50;
56     /** the internal code of the examples modes as are stored in the database */
57     const EXAMPLES_VOLUNTARY            = 0;
58     const EXAMPLES_BEFORE_SUBMISSION    = 1;
59     const EXAMPLES_BEFORE_ASSESSMENT    = 2;
61     /** @var cm_info course module record */
62     public $cm;
64     /** @var stdclass course record */
65     public $course;
67     /** @var stdclass context object */
68     public $context;
70     /** @var int workshop instance identifier */
71     public $id;
73     /** @var string workshop activity name */
74     public $name;
76     /** @var string introduction or description of the activity */
77     public $intro;
79     /** @var int format of the {@link $intro} */
80     public $introformat;
82     /** @var string instructions for the submission phase */
83     public $instructauthors;
85     /** @var int format of the {@link $instructauthors} */
86     public $instructauthorsformat;
88     /** @var string instructions for the assessment phase */
89     public $instructreviewers;
91     /** @var int format of the {@link $instructreviewers} */
92     public $instructreviewersformat;
94     /** @var int timestamp of when the module was modified */
95     public $timemodified;
97     /** @var int current phase of workshop, for example {@link workshop::PHASE_SETUP} */
98     public $phase;
100     /** @var bool optional feature: students practise evaluating on example submissions from teacher */
101     public $useexamples;
103     /** @var bool optional feature: students perform peer assessment of others' work (deprecated, consider always enabled) */
104     public $usepeerassessment;
106     /** @var bool optional feature: students perform self assessment of their own work */
107     public $useselfassessment;
109     /** @var float number (10, 5) unsigned, the maximum grade for submission */
110     public $grade;
112     /** @var float number (10, 5) unsigned, the maximum grade for assessment */
113     public $gradinggrade;
115     /** @var string type of the current grading strategy used in this workshop, for example 'accumulative' */
116     public $strategy;
118     /** @var string the name of the evaluation plugin to use for grading grades calculation */
119     public $evaluation;
121     /** @var int number of digits that should be shown after the decimal point when displaying grades */
122     public $gradedecimals;
124     /** @var int number of allowed submission attachments and the files embedded into submission */
125     public $nattachments;
127     /** @var bool allow submitting the work after the deadline */
128     public $latesubmissions;
130     /** @var int maximum size of the one attached file in bytes */
131     public $maxbytes;
133     /** @var int mode of example submissions support, for example {@link workshop::EXAMPLES_VOLUNTARY} */
134     public $examplesmode;
136     /** @var int if greater than 0 then the submission is not allowed before this timestamp */
137     public $submissionstart;
139     /** @var int if greater than 0 then the submission is not allowed after this timestamp */
140     public $submissionend;
142     /** @var int if greater than 0 then the peer assessment is not allowed before this timestamp */
143     public $assessmentstart;
145     /** @var int if greater than 0 then the peer assessment is not allowed after this timestamp */
146     public $assessmentend;
148     /** @var bool automatically switch to the assessment phase after the submissions deadline */
149     public $phaseswitchassessment;
151     /** @var string conclusion text to be displayed at the end of the activity */
152     public $conclusion;
154     /** @var int format of the conclusion text */
155     public $conclusionformat;
157     /** @var int the mode of the overall feedback */
158     public $overallfeedbackmode;
160     /** @var int maximum number of overall feedback attachments */
161     public $overallfeedbackfiles;
163     /** @var int maximum size of one file attached to the overall feedback */
164     public $overallfeedbackmaxbytes;
166     /**
167      * @var workshop_strategy grading strategy instance
168      * Do not use directly, get the instance using {@link workshop::grading_strategy_instance()}
169      */
170     protected $strategyinstance = null;
172     /**
173      * @var workshop_evaluation grading evaluation instance
174      * Do not use directly, get the instance using {@link workshop::grading_evaluation_instance()}
175      */
176     protected $evaluationinstance = null;
178     /**
179      * Initializes the workshop API instance using the data from DB
180      *
181      * Makes deep copy of all passed records properties.
182      *
183      * For unit testing only, $cm and $course may be set to null. This is so that
184      * you can test without having any real database objects if you like. Not all
185      * functions will work in this situation.
186      *
187      * @param stdClass $dbrecord Workshop instance data from {workshop} table
188      * @param stdClass|cm_info $cm Course module record
189      * @param stdClass $course Course record from {course} table
190      * @param stdClass $context The context of the workshop instance
191      */
192     public function __construct(stdclass $dbrecord, $cm, $course, stdclass $context=null) {
193         foreach ($dbrecord as $field => $value) {
194             if (property_exists('workshop', $field)) {
195                 $this->{$field} = $value;
196             }
197         }
198         if (is_null($cm) || is_null($course)) {
199             throw new coding_exception('Must specify $cm and $course');
200         }
201         $this->course = $course;
202         if ($cm instanceof cm_info) {
203             $this->cm = $cm;
204         } else {
205             $modinfo = get_fast_modinfo($course);
206             $this->cm = $modinfo->get_cm($cm->id);
207         }
208         if (is_null($context)) {
209             $this->context = context_module::instance($this->cm->id);
210         } else {
211             $this->context = $context;
212         }
213     }
215     ////////////////////////////////////////////////////////////////////////////////
216     // Static methods                                                             //
217     ////////////////////////////////////////////////////////////////////////////////
219     /**
220      * Return list of available allocation methods
221      *
222      * @return array Array ['string' => 'string'] of localized allocation method names
223      */
224     public static function installed_allocators() {
225         $installed = core_component::get_plugin_list('workshopallocation');
226         $forms = array();
227         foreach ($installed as $allocation => $allocationpath) {
228             if (file_exists($allocationpath . '/lib.php')) {
229                 $forms[$allocation] = get_string('pluginname', 'workshopallocation_' . $allocation);
230             }
231         }
232         // usability - make sure that manual allocation appears the first
233         if (isset($forms['manual'])) {
234             $m = array('manual' => $forms['manual']);
235             unset($forms['manual']);
236             $forms = array_merge($m, $forms);
237         }
238         return $forms;
239     }
241     /**
242      * Returns an array of options for the editors that are used for submitting and assessing instructions
243      *
244      * @param stdClass $context
245      * @uses EDITOR_UNLIMITED_FILES hard-coded value for the 'maxfiles' option
246      * @return array
247      */
248     public static function instruction_editors_options(stdclass $context) {
249         return array('subdirs' => 1, 'maxbytes' => 0, 'maxfiles' => -1,
250                      'changeformat' => 1, 'context' => $context, 'noclean' => 1, 'trusttext' => 0);
251     }
253     /**
254      * Given the percent and the total, returns the number
255      *
256      * @param float $percent from 0 to 100
257      * @param float $total   the 100% value
258      * @return float
259      */
260     public static function percent_to_value($percent, $total) {
261         if ($percent < 0 or $percent > 100) {
262             throw new coding_exception('The percent can not be less than 0 or higher than 100');
263         }
265         return $total * $percent / 100;
266     }
268     /**
269      * Returns an array of numeric values that can be used as maximum grades
270      *
271      * @return array Array of integers
272      */
273     public static function available_maxgrades_list() {
274         $grades = array();
275         for ($i=100; $i>=0; $i--) {
276             $grades[$i] = $i;
277         }
278         return $grades;
279     }
281     /**
282      * Returns the localized list of supported examples modes
283      *
284      * @return array
285      */
286     public static function available_example_modes_list() {
287         $options = array();
288         $options[self::EXAMPLES_VOLUNTARY]         = get_string('examplesvoluntary', 'workshop');
289         $options[self::EXAMPLES_BEFORE_SUBMISSION] = get_string('examplesbeforesubmission', 'workshop');
290         $options[self::EXAMPLES_BEFORE_ASSESSMENT] = get_string('examplesbeforeassessment', 'workshop');
291         return $options;
292     }
294     /**
295      * Returns the list of available grading strategy methods
296      *
297      * @return array ['string' => 'string']
298      */
299     public static function available_strategies_list() {
300         $installed = core_component::get_plugin_list('workshopform');
301         $forms = array();
302         foreach ($installed as $strategy => $strategypath) {
303             if (file_exists($strategypath . '/lib.php')) {
304                 $forms[$strategy] = get_string('pluginname', 'workshopform_' . $strategy);
305             }
306         }
307         return $forms;
308     }
310     /**
311      * Returns the list of available grading evaluation methods
312      *
313      * @return array of (string)name => (string)localized title
314      */
315     public static function available_evaluators_list() {
316         $evals = array();
317         foreach (core_component::get_plugin_list_with_file('workshopeval', 'lib.php', false) as $eval => $evalpath) {
318             $evals[$eval] = get_string('pluginname', 'workshopeval_' . $eval);
319         }
320         return $evals;
321     }
323     /**
324      * Return an array of possible values of assessment dimension weight
325      *
326      * @return array of integers 0, 1, 2, ..., 16
327      */
328     public static function available_dimension_weights_list() {
329         $weights = array();
330         for ($i=16; $i>=0; $i--) {
331             $weights[$i] = $i;
332         }
333         return $weights;
334     }
336     /**
337      * Return an array of possible values of assessment weight
338      *
339      * Note there is no real reason why the maximum value here is 16. It used to be 10 in
340      * workshop 1.x and I just decided to use the same number as in the maximum weight of
341      * a single assessment dimension.
342      * The value looks reasonable, though. Teachers who would want to assign themselves
343      * higher weight probably do not want peer assessment really...
344      *
345      * @return array of integers 0, 1, 2, ..., 16
346      */
347     public static function available_assessment_weights_list() {
348         $weights = array();
349         for ($i=16; $i>=0; $i--) {
350             $weights[$i] = $i;
351         }
352         return $weights;
353     }
355     /**
356      * Helper function returning the greatest common divisor
357      *
358      * @param int $a
359      * @param int $b
360      * @return int
361      */
362     public static function gcd($a, $b) {
363         return ($b == 0) ? ($a):(self::gcd($b, $a % $b));
364     }
366     /**
367      * Helper function returning the least common multiple
368      *
369      * @param int $a
370      * @param int $b
371      * @return int
372      */
373     public static function lcm($a, $b) {
374         return ($a / self::gcd($a,$b)) * $b;
375     }
377     /**
378      * Returns an object suitable for strings containing dates/times
379      *
380      * The returned object contains properties date, datefullshort, datetime, ... containing the given
381      * timestamp formatted using strftimedate, strftimedatefullshort, strftimedatetime, ... from the
382      * current lang's langconfig.php
383      * This allows translators and administrators customize the date/time format.
384      *
385      * @param int $timestamp the timestamp in UTC
386      * @return stdclass
387      */
388     public static function timestamp_formats($timestamp) {
389         $formats = array('date', 'datefullshort', 'dateshort', 'datetime',
390                 'datetimeshort', 'daydate', 'daydatetime', 'dayshort', 'daytime',
391                 'monthyear', 'recent', 'recentfull', 'time');
392         $a = new stdclass();
393         foreach ($formats as $format) {
394             $a->{$format} = userdate($timestamp, get_string('strftime'.$format, 'langconfig'));
395         }
396         $day = userdate($timestamp, '%Y%m%d', 99, false);
397         $today = userdate(time(), '%Y%m%d', 99, false);
398         $tomorrow = userdate(time() + DAYSECS, '%Y%m%d', 99, false);
399         $yesterday = userdate(time() - DAYSECS, '%Y%m%d', 99, false);
400         $distance = (int)round(abs(time() - $timestamp) / DAYSECS);
401         if ($day == $today) {
402             $a->distanceday = get_string('daystoday', 'workshop');
403         } elseif ($day == $yesterday) {
404             $a->distanceday = get_string('daysyesterday', 'workshop');
405         } elseif ($day < $today) {
406             $a->distanceday = get_string('daysago', 'workshop', $distance);
407         } elseif ($day == $tomorrow) {
408             $a->distanceday = get_string('daystomorrow', 'workshop');
409         } elseif ($day > $today) {
410             $a->distanceday = get_string('daysleft', 'workshop', $distance);
411         }
412         return $a;
413     }
415     ////////////////////////////////////////////////////////////////////////////////
416     // Workshop API                                                               //
417     ////////////////////////////////////////////////////////////////////////////////
419     /**
420      * Fetches all enrolled users with the capability mod/workshop:submit in the current workshop
421      *
422      * The returned objects contain properties required by user_picture and are ordered by lastname, firstname.
423      * Only users with the active enrolment are returned.
424      *
425      * @param bool $musthavesubmission if true, return only users who have already submitted
426      * @param int $groupid 0 means ignore groups, any other value limits the result by group id
427      * @param int $limitfrom return a subset of records, starting at this point (optional, required if $limitnum is set)
428      * @param int $limitnum return a subset containing this number of records (optional, required if $limitfrom is set)
429      * @return array array[userid] => stdClass
430      */
431     public function get_potential_authors($musthavesubmission=true, $groupid=0, $limitfrom=0, $limitnum=0) {
432         global $DB;
434         list($sql, $params) = $this->get_users_with_capability_sql('mod/workshop:submit', $musthavesubmission, $groupid);
436         if (empty($sql)) {
437             return array();
438         }
440         list($sort, $sortparams) = users_order_by_sql('tmp');
441         $sql = "SELECT *
442                   FROM ($sql) tmp
443               ORDER BY $sort";
445         return $DB->get_records_sql($sql, array_merge($params, $sortparams), $limitfrom, $limitnum);
446     }
448     /**
449      * Returns the total number of users that would be fetched by {@link self::get_potential_authors()}
450      *
451      * @param bool $musthavesubmission if true, count only users who have already submitted
452      * @param int $groupid 0 means ignore groups, any other value limits the result by group id
453      * @return int
454      */
455     public function count_potential_authors($musthavesubmission=true, $groupid=0) {
456         global $DB;
458         list($sql, $params) = $this->get_users_with_capability_sql('mod/workshop:submit', $musthavesubmission, $groupid);
460         if (empty($sql)) {
461             return 0;
462         }
464         $sql = "SELECT COUNT(*)
465                   FROM ($sql) tmp";
467         return $DB->count_records_sql($sql, $params);
468     }
470     /**
471      * Fetches all enrolled users with the capability mod/workshop:peerassess in the current workshop
472      *
473      * The returned objects contain properties required by user_picture and are ordered by lastname, firstname.
474      * Only users with the active enrolment are returned.
475      *
476      * @param bool $musthavesubmission if true, return only users who have already submitted
477      * @param int $groupid 0 means ignore groups, any other value limits the result by group id
478      * @param int $limitfrom return a subset of records, starting at this point (optional, required if $limitnum is set)
479      * @param int $limitnum return a subset containing this number of records (optional, required if $limitfrom is set)
480      * @return array array[userid] => stdClass
481      */
482     public function get_potential_reviewers($musthavesubmission=false, $groupid=0, $limitfrom=0, $limitnum=0) {
483         global $DB;
485         list($sql, $params) = $this->get_users_with_capability_sql('mod/workshop:peerassess', $musthavesubmission, $groupid);
487         if (empty($sql)) {
488             return array();
489         }
491         list($sort, $sortparams) = users_order_by_sql('tmp');
492         $sql = "SELECT *
493                   FROM ($sql) tmp
494               ORDER BY $sort";
496         return $DB->get_records_sql($sql, array_merge($params, $sortparams), $limitfrom, $limitnum);
497     }
499     /**
500      * Returns the total number of users that would be fetched by {@link self::get_potential_reviewers()}
501      *
502      * @param bool $musthavesubmission if true, count only users who have already submitted
503      * @param int $groupid 0 means ignore groups, any other value limits the result by group id
504      * @return int
505      */
506     public function count_potential_reviewers($musthavesubmission=false, $groupid=0) {
507         global $DB;
509         list($sql, $params) = $this->get_users_with_capability_sql('mod/workshop:peerassess', $musthavesubmission, $groupid);
511         if (empty($sql)) {
512             return 0;
513         }
515         $sql = "SELECT COUNT(*)
516                   FROM ($sql) tmp";
518         return $DB->count_records_sql($sql, $params);
519     }
521     /**
522      * Fetches all enrolled users that are authors or reviewers (or both) in the current workshop
523      *
524      * The returned objects contain properties required by user_picture and are ordered by lastname, firstname.
525      * Only users with the active enrolment are returned.
526      *
527      * @see self::get_potential_authors()
528      * @see self::get_potential_reviewers()
529      * @param bool $musthavesubmission if true, return only users who have already submitted
530      * @param int $groupid 0 means ignore groups, any other value limits the result by group id
531      * @param int $limitfrom return a subset of records, starting at this point (optional, required if $limitnum is set)
532      * @param int $limitnum return a subset containing this number of records (optional, required if $limitfrom is set)
533      * @return array array[userid] => stdClass
534      */
535     public function get_participants($musthavesubmission=false, $groupid=0, $limitfrom=0, $limitnum=0) {
536         global $DB;
538         list($sql, $params) = $this->get_participants_sql($musthavesubmission, $groupid);
540         if (empty($sql)) {
541             return array();
542         }
544         list($sort, $sortparams) = users_order_by_sql('tmp');
545         $sql = "SELECT *
546                   FROM ($sql) tmp
547               ORDER BY $sort";
549         return $DB->get_records_sql($sql, array_merge($params, $sortparams), $limitfrom, $limitnum);
550     }
552     /**
553      * Returns the total number of records that would be returned by {@link self::get_participants()}
554      *
555      * @param bool $musthavesubmission if true, return only users who have already submitted
556      * @param int $groupid 0 means ignore groups, any other value limits the result by group id
557      * @return int
558      */
559     public function count_participants($musthavesubmission=false, $groupid=0) {
560         global $DB;
562         list($sql, $params) = $this->get_participants_sql($musthavesubmission, $groupid);
564         if (empty($sql)) {
565             return 0;
566         }
568         $sql = "SELECT COUNT(*)
569                   FROM ($sql) tmp";
571         return $DB->count_records_sql($sql, $params);
572     }
574     /**
575      * Checks if the given user is an actively enrolled participant in the workshop
576      *
577      * @param int $userid, defaults to the current $USER
578      * @return boolean
579      */
580     public function is_participant($userid=null) {
581         global $USER, $DB;
583         if (is_null($userid)) {
584             $userid = $USER->id;
585         }
587         list($sql, $params) = $this->get_participants_sql();
589         if (empty($sql)) {
590             return false;
591         }
593         $sql = "SELECT COUNT(*)
594                   FROM {user} uxx
595                   JOIN ({$sql}) pxx ON uxx.id = pxx.id
596                  WHERE uxx.id = :uxxid";
597         $params['uxxid'] = $userid;
599         if ($DB->count_records_sql($sql, $params)) {
600             return true;
601         }
603         return false;
604     }
606     /**
607      * Groups the given users by the group membership
608      *
609      * This takes the module grouping settings into account. If a grouping is
610      * set, returns only groups withing the course module grouping. Always
611      * returns group [0] with all the given users.
612      *
613      * @param array $users array[userid] => stdclass{->id ->lastname ->firstname}
614      * @return array array[groupid][userid] => stdclass{->id ->lastname ->firstname}
615      */
616     public function get_grouped($users) {
617         global $DB;
618         global $CFG;
620         $grouped = array();  // grouped users to be returned
621         if (empty($users)) {
622             return $grouped;
623         }
624         if ($this->cm->groupingid) {
625             // Group workshop set to specified grouping - only consider groups
626             // within this grouping, and leave out users who aren't members of
627             // this grouping.
628             $groupingid = $this->cm->groupingid;
629             // All users that are members of at least one group will be
630             // added into a virtual group id 0
631             $grouped[0] = array();
632         } else {
633             $groupingid = 0;
634             // there is no need to be member of a group so $grouped[0] will contain
635             // all users
636             $grouped[0] = $users;
637         }
638         $gmemberships = groups_get_all_groups($this->cm->course, array_keys($users), $groupingid,
639                             'gm.id,gm.groupid,gm.userid');
640         foreach ($gmemberships as $gmembership) {
641             if (!isset($grouped[$gmembership->groupid])) {
642                 $grouped[$gmembership->groupid] = array();
643             }
644             $grouped[$gmembership->groupid][$gmembership->userid] = $users[$gmembership->userid];
645             $grouped[0][$gmembership->userid] = $users[$gmembership->userid];
646         }
647         return $grouped;
648     }
650     /**
651      * Returns the list of all allocations (i.e. assigned assessments) in the workshop
652      *
653      * Assessments of example submissions are ignored
654      *
655      * @return array
656      */
657     public function get_allocations() {
658         global $DB;
660         $sql = 'SELECT a.id, a.submissionid, a.reviewerid, s.authorid
661                   FROM {workshop_assessments} a
662             INNER JOIN {workshop_submissions} s ON (a.submissionid = s.id)
663                  WHERE s.example = 0 AND s.workshopid = :workshopid';
664         $params = array('workshopid' => $this->id);
666         return $DB->get_records_sql($sql, $params);
667     }
669     /**
670      * Returns the total number of records that would be returned by {@link self::get_submissions()}
671      *
672      * @param mixed $authorid int|array|'all' If set to [array of] integer, return submission[s] of the given user[s] only
673      * @param int $groupid If non-zero, return only submissions by authors in the specified group
674      * @return int number of records
675      */
676     public function count_submissions($authorid='all', $groupid=0) {
677         global $DB;
679         $params = array('workshopid' => $this->id);
680         $sql = "SELECT COUNT(s.id)
681                   FROM {workshop_submissions} s
682                   JOIN {user} u ON (s.authorid = u.id)";
683         if ($groupid) {
684             $sql .= " JOIN {groups_members} gm ON (gm.userid = u.id AND gm.groupid = :groupid)";
685             $params['groupid'] = $groupid;
686         }
687         $sql .= " WHERE s.example = 0 AND s.workshopid = :workshopid";
689         if ('all' === $authorid) {
690             // no additional conditions
691         } elseif (!empty($authorid)) {
692             list($usql, $uparams) = $DB->get_in_or_equal($authorid, SQL_PARAMS_NAMED);
693             $sql .= " AND authorid $usql";
694             $params = array_merge($params, $uparams);
695         } else {
696             // $authorid is empty
697             return 0;
698         }
700         return $DB->count_records_sql($sql, $params);
701     }
704     /**
705      * Returns submissions from this workshop
706      *
707      * Fetches data from {workshop_submissions} and adds some useful information from other
708      * tables. Does not return textual fields to prevent possible memory lack issues.
709      *
710      * @see self::count_submissions()
711      * @param mixed $authorid int|array|'all' If set to [array of] integer, return submission[s] of the given user[s] only
712      * @param int $groupid If non-zero, return only submissions by authors in the specified group
713      * @param int $limitfrom Return a subset of records, starting at this point (optional)
714      * @param int $limitnum Return a subset containing this many records in total (optional, required if $limitfrom is set)
715      * @return array of records or an empty array
716      */
717     public function get_submissions($authorid='all', $groupid=0, $limitfrom=0, $limitnum=0) {
718         global $DB;
720         $authorfields      = user_picture::fields('u', null, 'authoridx', 'author');
721         $gradeoverbyfields = user_picture::fields('t', null, 'gradeoverbyx', 'over');
722         $params            = array('workshopid' => $this->id);
723         $sql = "SELECT s.id, s.workshopid, s.example, s.authorid, s.timecreated, s.timemodified,
724                        s.title, s.grade, s.gradeover, s.gradeoverby, s.published,
725                        $authorfields, $gradeoverbyfields
726                   FROM {workshop_submissions} s
727                   JOIN {user} u ON (s.authorid = u.id)";
728         if ($groupid) {
729             $sql .= " JOIN {groups_members} gm ON (gm.userid = u.id AND gm.groupid = :groupid)";
730             $params['groupid'] = $groupid;
731         }
732         $sql .= " LEFT JOIN {user} t ON (s.gradeoverby = t.id)
733                  WHERE s.example = 0 AND s.workshopid = :workshopid";
735         if ('all' === $authorid) {
736             // no additional conditions
737         } elseif (!empty($authorid)) {
738             list($usql, $uparams) = $DB->get_in_or_equal($authorid, SQL_PARAMS_NAMED);
739             $sql .= " AND authorid $usql";
740             $params = array_merge($params, $uparams);
741         } else {
742             // $authorid is empty
743             return array();
744         }
745         list($sort, $sortparams) = users_order_by_sql('u');
746         $sql .= " ORDER BY $sort";
748         return $DB->get_records_sql($sql, array_merge($params, $sortparams), $limitfrom, $limitnum);
749     }
751     /**
752      * Returns a submission record with the author's data
753      *
754      * @param int $id submission id
755      * @return stdclass
756      */
757     public function get_submission_by_id($id) {
758         global $DB;
760         // we intentionally check the workshopid here, too, so the workshop can't touch submissions
761         // from other instances
762         $authorfields      = user_picture::fields('u', null, 'authoridx', 'author');
763         $gradeoverbyfields = user_picture::fields('g', null, 'gradeoverbyx', 'gradeoverby');
764         $sql = "SELECT s.*, $authorfields, $gradeoverbyfields
765                   FROM {workshop_submissions} s
766             INNER JOIN {user} u ON (s.authorid = u.id)
767              LEFT JOIN {user} g ON (s.gradeoverby = g.id)
768                  WHERE s.example = 0 AND s.workshopid = :workshopid AND s.id = :id";
769         $params = array('workshopid' => $this->id, 'id' => $id);
770         return $DB->get_record_sql($sql, $params, MUST_EXIST);
771     }
773     /**
774      * Returns a submission submitted by the given author
775      *
776      * @param int $id author id
777      * @return stdclass|false
778      */
779     public function get_submission_by_author($authorid) {
780         global $DB;
782         if (empty($authorid)) {
783             return false;
784         }
785         $authorfields      = user_picture::fields('u', null, 'authoridx', 'author');
786         $gradeoverbyfields = user_picture::fields('g', null, 'gradeoverbyx', 'gradeoverby');
787         $sql = "SELECT s.*, $authorfields, $gradeoverbyfields
788                   FROM {workshop_submissions} s
789             INNER JOIN {user} u ON (s.authorid = u.id)
790              LEFT JOIN {user} g ON (s.gradeoverby = g.id)
791                  WHERE s.example = 0 AND s.workshopid = :workshopid AND s.authorid = :authorid";
792         $params = array('workshopid' => $this->id, 'authorid' => $authorid);
793         return $DB->get_record_sql($sql, $params);
794     }
796     /**
797      * Returns published submissions with their authors data
798      *
799      * @return array of stdclass
800      */
801     public function get_published_submissions($orderby='finalgrade DESC') {
802         global $DB;
804         $authorfields = user_picture::fields('u', null, 'authoridx', 'author');
805         $sql = "SELECT s.id, s.authorid, s.timecreated, s.timemodified,
806                        s.title, s.grade, s.gradeover, COALESCE(s.gradeover,s.grade) AS finalgrade,
807                        $authorfields
808                   FROM {workshop_submissions} s
809             INNER JOIN {user} u ON (s.authorid = u.id)
810                  WHERE s.example = 0 AND s.workshopid = :workshopid AND s.published = 1
811               ORDER BY $orderby";
812         $params = array('workshopid' => $this->id);
813         return $DB->get_records_sql($sql, $params);
814     }
816     /**
817      * Returns full record of the given example submission
818      *
819      * @param int $id example submission od
820      * @return object
821      */
822     public function get_example_by_id($id) {
823         global $DB;
824         return $DB->get_record('workshop_submissions',
825                 array('id' => $id, 'workshopid' => $this->id, 'example' => 1), '*', MUST_EXIST);
826     }
828     /**
829      * Returns the list of example submissions in this workshop with reference assessments attached
830      *
831      * @return array of objects or an empty array
832      * @see workshop::prepare_example_summary()
833      */
834     public function get_examples_for_manager() {
835         global $DB;
837         $sql = 'SELECT s.id, s.title,
838                        a.id AS assessmentid, a.grade, a.gradinggrade
839                   FROM {workshop_submissions} s
840              LEFT JOIN {workshop_assessments} a ON (a.submissionid = s.id AND a.weight = 1)
841                  WHERE s.example = 1 AND s.workshopid = :workshopid
842               ORDER BY s.title';
843         return $DB->get_records_sql($sql, array('workshopid' => $this->id));
844     }
846     /**
847      * Returns the list of all example submissions in this workshop with the information of assessments done by the given user
848      *
849      * @param int $reviewerid user id
850      * @return array of objects, indexed by example submission id
851      * @see workshop::prepare_example_summary()
852      */
853     public function get_examples_for_reviewer($reviewerid) {
854         global $DB;
856         if (empty($reviewerid)) {
857             return false;
858         }
859         $sql = 'SELECT s.id, s.title,
860                        a.id AS assessmentid, a.grade, a.gradinggrade
861                   FROM {workshop_submissions} s
862              LEFT JOIN {workshop_assessments} a ON (a.submissionid = s.id AND a.reviewerid = :reviewerid AND a.weight = 0)
863                  WHERE s.example = 1 AND s.workshopid = :workshopid
864               ORDER BY s.title';
865         return $DB->get_records_sql($sql, array('workshopid' => $this->id, 'reviewerid' => $reviewerid));
866     }
868     /**
869      * Prepares renderable submission component
870      *
871      * @param stdClass $record required by {@see workshop_submission}
872      * @param bool $showauthor show the author-related information
873      * @return workshop_submission
874      */
875     public function prepare_submission(stdClass $record, $showauthor = false) {
877         $submission         = new workshop_submission($this, $record, $showauthor);
878         $submission->url    = $this->submission_url($record->id);
880         return $submission;
881     }
883     /**
884      * Prepares renderable submission summary component
885      *
886      * @param stdClass $record required by {@see workshop_submission_summary}
887      * @param bool $showauthor show the author-related information
888      * @return workshop_submission_summary
889      */
890     public function prepare_submission_summary(stdClass $record, $showauthor = false) {
892         $summary        = new workshop_submission_summary($this, $record, $showauthor);
893         $summary->url   = $this->submission_url($record->id);
895         return $summary;
896     }
898     /**
899      * Prepares renderable example submission component
900      *
901      * @param stdClass $record required by {@see workshop_example_submission}
902      * @return workshop_example_submission
903      */
904     public function prepare_example_submission(stdClass $record) {
906         $example = new workshop_example_submission($this, $record);
908         return $example;
909     }
911     /**
912      * Prepares renderable example submission summary component
913      *
914      * If the example is editable, the caller must set the 'editable' flag explicitly.
915      *
916      * @param stdClass $example as returned by {@link workshop::get_examples_for_manager()} or {@link workshop::get_examples_for_reviewer()}
917      * @return workshop_example_submission_summary to be rendered
918      */
919     public function prepare_example_summary(stdClass $example) {
921         $summary = new workshop_example_submission_summary($this, $example);
923         if (is_null($example->grade)) {
924             $summary->status = 'notgraded';
925             $summary->assesslabel = get_string('assess', 'workshop');
926         } else {
927             $summary->status = 'graded';
928             $summary->assesslabel = get_string('reassess', 'workshop');
929         }
931         $summary->gradeinfo           = new stdclass();
932         $summary->gradeinfo->received = $this->real_grade($example->grade);
933         $summary->gradeinfo->max      = $this->real_grade(100);
935         $summary->url       = new moodle_url($this->exsubmission_url($example->id));
936         $summary->editurl   = new moodle_url($this->exsubmission_url($example->id), array('edit' => 'on'));
937         $summary->assessurl = new moodle_url($this->exsubmission_url($example->id), array('assess' => 'on', 'sesskey' => sesskey()));
939         return $summary;
940     }
942     /**
943      * Prepares renderable assessment component
944      *
945      * The $options array supports the following keys:
946      * showauthor - should the author user info be available for the renderer
947      * showreviewer - should the reviewer user info be available for the renderer
948      * showform - show the assessment form if it is available
949      * showweight - should the assessment weight be available for the renderer
950      *
951      * @param stdClass $record as returned by eg {@link self::get_assessment_by_id()}
952      * @param workshop_assessment_form|null $form as returned by {@link workshop_strategy::get_assessment_form()}
953      * @param array $options
954      * @return workshop_assessment
955      */
956     public function prepare_assessment(stdClass $record, $form, array $options = array()) {
958         $assessment             = new workshop_assessment($this, $record, $options);
959         $assessment->url        = $this->assess_url($record->id);
960         $assessment->maxgrade   = $this->real_grade(100);
962         if (!empty($options['showform']) and !($form instanceof workshop_assessment_form)) {
963             debugging('Not a valid instance of workshop_assessment_form supplied', DEBUG_DEVELOPER);
964         }
966         if (!empty($options['showform']) and ($form instanceof workshop_assessment_form)) {
967             $assessment->form = $form;
968         }
970         if (empty($options['showweight'])) {
971             $assessment->weight = null;
972         }
974         if (!is_null($record->grade)) {
975             $assessment->realgrade = $this->real_grade($record->grade);
976         }
978         return $assessment;
979     }
981     /**
982      * Prepares renderable example submission's assessment component
983      *
984      * The $options array supports the following keys:
985      * showauthor - should the author user info be available for the renderer
986      * showreviewer - should the reviewer user info be available for the renderer
987      * showform - show the assessment form if it is available
988      *
989      * @param stdClass $record as returned by eg {@link self::get_assessment_by_id()}
990      * @param workshop_assessment_form|null $form as returned by {@link workshop_strategy::get_assessment_form()}
991      * @param array $options
992      * @return workshop_example_assessment
993      */
994     public function prepare_example_assessment(stdClass $record, $form = null, array $options = array()) {
996         $assessment             = new workshop_example_assessment($this, $record, $options);
997         $assessment->url        = $this->exassess_url($record->id);
998         $assessment->maxgrade   = $this->real_grade(100);
1000         if (!empty($options['showform']) and !($form instanceof workshop_assessment_form)) {
1001             debugging('Not a valid instance of workshop_assessment_form supplied', DEBUG_DEVELOPER);
1002         }
1004         if (!empty($options['showform']) and ($form instanceof workshop_assessment_form)) {
1005             $assessment->form = $form;
1006         }
1008         if (!is_null($record->grade)) {
1009             $assessment->realgrade = $this->real_grade($record->grade);
1010         }
1012         $assessment->weight = null;
1014         return $assessment;
1015     }
1017     /**
1018      * Prepares renderable example submission's reference assessment component
1019      *
1020      * The $options array supports the following keys:
1021      * showauthor - should the author user info be available for the renderer
1022      * showreviewer - should the reviewer user info be available for the renderer
1023      * showform - show the assessment form if it is available
1024      *
1025      * @param stdClass $record as returned by eg {@link self::get_assessment_by_id()}
1026      * @param workshop_assessment_form|null $form as returned by {@link workshop_strategy::get_assessment_form()}
1027      * @param array $options
1028      * @return workshop_example_reference_assessment
1029      */
1030     public function prepare_example_reference_assessment(stdClass $record, $form = null, array $options = array()) {
1032         $assessment             = new workshop_example_reference_assessment($this, $record, $options);
1033         $assessment->maxgrade   = $this->real_grade(100);
1035         if (!empty($options['showform']) and !($form instanceof workshop_assessment_form)) {
1036             debugging('Not a valid instance of workshop_assessment_form supplied', DEBUG_DEVELOPER);
1037         }
1039         if (!empty($options['showform']) and ($form instanceof workshop_assessment_form)) {
1040             $assessment->form = $form;
1041         }
1043         if (!is_null($record->grade)) {
1044             $assessment->realgrade = $this->real_grade($record->grade);
1045         }
1047         $assessment->weight = null;
1049         return $assessment;
1050     }
1052     /**
1053      * Removes the submission and all relevant data
1054      *
1055      * @param stdClass $submission record to delete
1056      * @return void
1057      */
1058     public function delete_submission(stdclass $submission) {
1059         global $DB;
1061         $assessments = $DB->get_records('workshop_assessments', array('submissionid' => $submission->id), '', 'id');
1062         $this->delete_assessment(array_keys($assessments));
1064         $fs = get_file_storage();
1065         $fs->delete_area_files($this->context->id, 'mod_workshop', 'submission_content', $submission->id);
1066         $fs->delete_area_files($this->context->id, 'mod_workshop', 'submission_attachment', $submission->id);
1068         $DB->delete_records('workshop_submissions', array('id' => $submission->id));
1069     }
1071     /**
1072      * Returns the list of all assessments in the workshop with some data added
1073      *
1074      * Fetches data from {workshop_assessments} and adds some useful information from other
1075      * tables. The returned object does not contain textual fields (i.e. comments) to prevent memory
1076      * lack issues.
1077      *
1078      * @return array [assessmentid] => assessment stdclass
1079      */
1080     public function get_all_assessments() {
1081         global $DB;
1083         $reviewerfields = user_picture::fields('reviewer', null, 'revieweridx', 'reviewer');
1084         $authorfields   = user_picture::fields('author', null, 'authorid', 'author');
1085         $overbyfields   = user_picture::fields('overby', null, 'gradinggradeoverbyx', 'overby');
1086         list($sort, $params) = users_order_by_sql('reviewer');
1087         $sql = "SELECT a.id, a.submissionid, a.reviewerid, a.timecreated, a.timemodified,
1088                        a.grade, a.gradinggrade, a.gradinggradeover, a.gradinggradeoverby,
1089                        $reviewerfields, $authorfields, $overbyfields,
1090                        s.title
1091                   FROM {workshop_assessments} a
1092             INNER JOIN {user} reviewer ON (a.reviewerid = reviewer.id)
1093             INNER JOIN {workshop_submissions} s ON (a.submissionid = s.id)
1094             INNER JOIN {user} author ON (s.authorid = author.id)
1095              LEFT JOIN {user} overby ON (a.gradinggradeoverby = overby.id)
1096                  WHERE s.workshopid = :workshopid AND s.example = 0
1097               ORDER BY $sort";
1098         $params['workshopid'] = $this->id;
1100         return $DB->get_records_sql($sql, $params);
1101     }
1103     /**
1104      * Get the complete information about the given assessment
1105      *
1106      * @param int $id Assessment ID
1107      * @return stdclass
1108      */
1109     public function get_assessment_by_id($id) {
1110         global $DB;
1112         $reviewerfields = user_picture::fields('reviewer', null, 'revieweridx', 'reviewer');
1113         $authorfields   = user_picture::fields('author', null, 'authorid', 'author');
1114         $overbyfields   = user_picture::fields('overby', null, 'gradinggradeoverbyx', 'overby');
1115         $sql = "SELECT a.*, s.title, $reviewerfields, $authorfields, $overbyfields
1116                   FROM {workshop_assessments} a
1117             INNER JOIN {user} reviewer ON (a.reviewerid = reviewer.id)
1118             INNER JOIN {workshop_submissions} s ON (a.submissionid = s.id)
1119             INNER JOIN {user} author ON (s.authorid = author.id)
1120              LEFT JOIN {user} overby ON (a.gradinggradeoverby = overby.id)
1121                  WHERE a.id = :id AND s.workshopid = :workshopid";
1122         $params = array('id' => $id, 'workshopid' => $this->id);
1124         return $DB->get_record_sql($sql, $params, MUST_EXIST);
1125     }
1127     /**
1128      * Get the complete information about the user's assessment of the given submission
1129      *
1130      * @param int $sid submission ID
1131      * @param int $uid user ID of the reviewer
1132      * @return false|stdclass false if not found, stdclass otherwise
1133      */
1134     public function get_assessment_of_submission_by_user($submissionid, $reviewerid) {
1135         global $DB;
1137         $reviewerfields = user_picture::fields('reviewer', null, 'revieweridx', 'reviewer');
1138         $authorfields   = user_picture::fields('author', null, 'authorid', 'author');
1139         $overbyfields   = user_picture::fields('overby', null, 'gradinggradeoverbyx', 'overby');
1140         $sql = "SELECT a.*, s.title, $reviewerfields, $authorfields, $overbyfields
1141                   FROM {workshop_assessments} a
1142             INNER JOIN {user} reviewer ON (a.reviewerid = reviewer.id)
1143             INNER JOIN {workshop_submissions} s ON (a.submissionid = s.id AND s.example = 0)
1144             INNER JOIN {user} author ON (s.authorid = author.id)
1145              LEFT JOIN {user} overby ON (a.gradinggradeoverby = overby.id)
1146                  WHERE s.id = :sid AND reviewer.id = :rid AND s.workshopid = :workshopid";
1147         $params = array('sid' => $submissionid, 'rid' => $reviewerid, 'workshopid' => $this->id);
1149         return $DB->get_record_sql($sql, $params, IGNORE_MISSING);
1150     }
1152     /**
1153      * Get the complete information about all assessments of the given submission
1154      *
1155      * @param int $submissionid
1156      * @return array
1157      */
1158     public function get_assessments_of_submission($submissionid) {
1159         global $DB;
1161         $reviewerfields = user_picture::fields('reviewer', null, 'revieweridx', 'reviewer');
1162         $overbyfields   = user_picture::fields('overby', null, 'gradinggradeoverbyx', 'overby');
1163         list($sort, $params) = users_order_by_sql('reviewer');
1164         $sql = "SELECT a.*, s.title, $reviewerfields, $overbyfields
1165                   FROM {workshop_assessments} a
1166             INNER JOIN {user} reviewer ON (a.reviewerid = reviewer.id)
1167             INNER JOIN {workshop_submissions} s ON (a.submissionid = s.id)
1168              LEFT JOIN {user} overby ON (a.gradinggradeoverby = overby.id)
1169                  WHERE s.example = 0 AND s.id = :submissionid AND s.workshopid = :workshopid
1170               ORDER BY $sort";
1171         $params['submissionid'] = $submissionid;
1172         $params['workshopid']   = $this->id;
1174         return $DB->get_records_sql($sql, $params);
1175     }
1177     /**
1178      * Get the complete information about all assessments allocated to the given reviewer
1179      *
1180      * @param int $reviewerid
1181      * @return array
1182      */
1183     public function get_assessments_by_reviewer($reviewerid) {
1184         global $DB;
1186         $reviewerfields = user_picture::fields('reviewer', null, 'revieweridx', 'reviewer');
1187         $authorfields   = user_picture::fields('author', null, 'authorid', 'author');
1188         $overbyfields   = user_picture::fields('overby', null, 'gradinggradeoverbyx', 'overby');
1189         $sql = "SELECT a.*, $reviewerfields, $authorfields, $overbyfields,
1190                        s.id AS submissionid, s.title AS submissiontitle, s.timecreated AS submissioncreated,
1191                        s.timemodified AS submissionmodified
1192                   FROM {workshop_assessments} a
1193             INNER JOIN {user} reviewer ON (a.reviewerid = reviewer.id)
1194             INNER JOIN {workshop_submissions} s ON (a.submissionid = s.id)
1195             INNER JOIN {user} author ON (s.authorid = author.id)
1196              LEFT JOIN {user} overby ON (a.gradinggradeoverby = overby.id)
1197                  WHERE s.example = 0 AND reviewer.id = :reviewerid AND s.workshopid = :workshopid";
1198         $params = array('reviewerid' => $reviewerid, 'workshopid' => $this->id);
1200         return $DB->get_records_sql($sql, $params);
1201     }
1203     /**
1204      * Get allocated assessments not graded yet by the given reviewer
1205      *
1206      * @see self::get_assessments_by_reviewer()
1207      * @param int $reviewerid the reviewer id
1208      * @param null|int|array $exclude optional assessment id (or list of them) to be excluded
1209      * @return array
1210      */
1211     public function get_pending_assessments_by_reviewer($reviewerid, $exclude = null) {
1213         $assessments = $this->get_assessments_by_reviewer($reviewerid);
1215         foreach ($assessments as $id => $assessment) {
1216             if (!is_null($assessment->grade)) {
1217                 unset($assessments[$id]);
1218                 continue;
1219             }
1220             if (!empty($exclude)) {
1221                 if (is_array($exclude) and in_array($id, $exclude)) {
1222                     unset($assessments[$id]);
1223                     continue;
1224                 } else if ($id == $exclude) {
1225                     unset($assessments[$id]);
1226                     continue;
1227                 }
1228             }
1229         }
1231         return $assessments;
1232     }
1234     /**
1235      * Allocate a submission to a user for review
1236      *
1237      * @param stdClass $submission Submission object with at least id property
1238      * @param int $reviewerid User ID
1239      * @param int $weight of the new assessment, from 0 to 16
1240      * @param bool $bulk repeated inserts into DB expected
1241      * @return int ID of the new assessment or an error code {@link self::ALLOCATION_EXISTS} if the allocation already exists
1242      */
1243     public function add_allocation(stdclass $submission, $reviewerid, $weight=1, $bulk=false) {
1244         global $DB;
1246         if ($DB->record_exists('workshop_assessments', array('submissionid' => $submission->id, 'reviewerid' => $reviewerid))) {
1247             return self::ALLOCATION_EXISTS;
1248         }
1250         $weight = (int)$weight;
1251         if ($weight < 0) {
1252             $weight = 0;
1253         }
1254         if ($weight > 16) {
1255             $weight = 16;
1256         }
1258         $now = time();
1259         $assessment = new stdclass();
1260         $assessment->submissionid           = $submission->id;
1261         $assessment->reviewerid             = $reviewerid;
1262         $assessment->timecreated            = $now;         // do not set timemodified here
1263         $assessment->weight                 = $weight;
1264         $assessment->feedbackauthorformat   = editors_get_preferred_format();
1265         $assessment->feedbackreviewerformat = editors_get_preferred_format();
1267         return $DB->insert_record('workshop_assessments', $assessment, true, $bulk);
1268     }
1270     /**
1271      * Delete assessment record or records.
1272      *
1273      * Removes associated records from the workshop_grades table, too.
1274      *
1275      * @param int|array $id assessment id or array of assessments ids
1276      * @todo Give grading strategy plugins a chance to clean up their data, too.
1277      * @return bool true
1278      */
1279     public function delete_assessment($id) {
1280         global $DB;
1282         if (empty($id)) {
1283             return true;
1284         }
1286         $fs = get_file_storage();
1288         if (is_array($id)) {
1289             $DB->delete_records_list('workshop_grades', 'assessmentid', $id);
1290             foreach ($id as $itemid) {
1291                 $fs->delete_area_files($this->context->id, 'mod_workshop', 'overallfeedback_content', $itemid);
1292                 $fs->delete_area_files($this->context->id, 'mod_workshop', 'overallfeedback_attachment', $itemid);
1293             }
1294             $DB->delete_records_list('workshop_assessments', 'id', $id);
1296         } else {
1297             $DB->delete_records('workshop_grades', array('assessmentid' => $id));
1298             $fs->delete_area_files($this->context->id, 'mod_workshop', 'overallfeedback_content', $id);
1299             $fs->delete_area_files($this->context->id, 'mod_workshop', 'overallfeedback_attachment', $id);
1300             $DB->delete_records('workshop_assessments', array('id' => $id));
1301         }
1303         return true;
1304     }
1306     /**
1307      * Returns instance of grading strategy class
1308      *
1309      * @return stdclass Instance of a grading strategy
1310      */
1311     public function grading_strategy_instance() {
1312         global $CFG;    // because we require other libs here
1314         if (is_null($this->strategyinstance)) {
1315             $strategylib = dirname(__FILE__) . '/form/' . $this->strategy . '/lib.php';
1316             if (is_readable($strategylib)) {
1317                 require_once($strategylib);
1318             } else {
1319                 throw new coding_exception('the grading forms subplugin must contain library ' . $strategylib);
1320             }
1321             $classname = 'workshop_' . $this->strategy . '_strategy';
1322             $this->strategyinstance = new $classname($this);
1323             if (!in_array('workshop_strategy', class_implements($this->strategyinstance))) {
1324                 throw new coding_exception($classname . ' does not implement workshop_strategy interface');
1325             }
1326         }
1327         return $this->strategyinstance;
1328     }
1330     /**
1331      * Sets the current evaluation method to the given plugin.
1332      *
1333      * @param string $method the name of the workshopeval subplugin
1334      * @return bool true if successfully set
1335      * @throws coding_exception if attempting to set a non-installed evaluation method
1336      */
1337     public function set_grading_evaluation_method($method) {
1338         global $DB;
1340         $evaluationlib = dirname(__FILE__) . '/eval/' . $method . '/lib.php';
1342         if (is_readable($evaluationlib)) {
1343             $this->evaluationinstance = null;
1344             $this->evaluation = $method;
1345             $DB->set_field('workshop', 'evaluation', $method, array('id' => $this->id));
1346             return true;
1347         }
1349         throw new coding_exception('Attempt to set a non-existing evaluation method.');
1350     }
1352     /**
1353      * Returns instance of grading evaluation class
1354      *
1355      * @return stdclass Instance of a grading evaluation
1356      */
1357     public function grading_evaluation_instance() {
1358         global $CFG;    // because we require other libs here
1360         if (is_null($this->evaluationinstance)) {
1361             if (empty($this->evaluation)) {
1362                 $this->evaluation = 'best';
1363             }
1364             $evaluationlib = dirname(__FILE__) . '/eval/' . $this->evaluation . '/lib.php';
1365             if (is_readable($evaluationlib)) {
1366                 require_once($evaluationlib);
1367             } else {
1368                 // Fall back in case the subplugin is not available.
1369                 $this->evaluation = 'best';
1370                 $evaluationlib = dirname(__FILE__) . '/eval/' . $this->evaluation . '/lib.php';
1371                 if (is_readable($evaluationlib)) {
1372                     require_once($evaluationlib);
1373                 } else {
1374                     // Fall back in case the subplugin is not available any more.
1375                     throw new coding_exception('Missing default grading evaluation library ' . $evaluationlib);
1376                 }
1377             }
1378             $classname = 'workshop_' . $this->evaluation . '_evaluation';
1379             $this->evaluationinstance = new $classname($this);
1380             if (!in_array('workshop_evaluation', class_parents($this->evaluationinstance))) {
1381                 throw new coding_exception($classname . ' does not extend workshop_evaluation class');
1382             }
1383         }
1384         return $this->evaluationinstance;
1385     }
1387     /**
1388      * Returns instance of submissions allocator
1389      *
1390      * @param string $method The name of the allocation method, must be PARAM_ALPHA
1391      * @return stdclass Instance of submissions allocator
1392      */
1393     public function allocator_instance($method) {
1394         global $CFG;    // because we require other libs here
1396         $allocationlib = dirname(__FILE__) . '/allocation/' . $method . '/lib.php';
1397         if (is_readable($allocationlib)) {
1398             require_once($allocationlib);
1399         } else {
1400             throw new coding_exception('Unable to find the allocation library ' . $allocationlib);
1401         }
1402         $classname = 'workshop_' . $method . '_allocator';
1403         return new $classname($this);
1404     }
1406     /**
1407      * @return moodle_url of this workshop's view page
1408      */
1409     public function view_url() {
1410         global $CFG;
1411         return new moodle_url('/mod/workshop/view.php', array('id' => $this->cm->id));
1412     }
1414     /**
1415      * @return moodle_url of the page for editing this workshop's grading form
1416      */
1417     public function editform_url() {
1418         global $CFG;
1419         return new moodle_url('/mod/workshop/editform.php', array('cmid' => $this->cm->id));
1420     }
1422     /**
1423      * @return moodle_url of the page for previewing this workshop's grading form
1424      */
1425     public function previewform_url() {
1426         global $CFG;
1427         return new moodle_url('/mod/workshop/editformpreview.php', array('cmid' => $this->cm->id));
1428     }
1430     /**
1431      * @param int $assessmentid The ID of assessment record
1432      * @return moodle_url of the assessment page
1433      */
1434     public function assess_url($assessmentid) {
1435         global $CFG;
1436         $assessmentid = clean_param($assessmentid, PARAM_INT);
1437         return new moodle_url('/mod/workshop/assessment.php', array('asid' => $assessmentid));
1438     }
1440     /**
1441      * @param int $assessmentid The ID of assessment record
1442      * @return moodle_url of the example assessment page
1443      */
1444     public function exassess_url($assessmentid) {
1445         global $CFG;
1446         $assessmentid = clean_param($assessmentid, PARAM_INT);
1447         return new moodle_url('/mod/workshop/exassessment.php', array('asid' => $assessmentid));
1448     }
1450     /**
1451      * @return moodle_url of the page to view a submission, defaults to the own one
1452      */
1453     public function submission_url($id=null) {
1454         global $CFG;
1455         return new moodle_url('/mod/workshop/submission.php', array('cmid' => $this->cm->id, 'id' => $id));
1456     }
1458     /**
1459      * @param int $id example submission id
1460      * @return moodle_url of the page to view an example submission
1461      */
1462     public function exsubmission_url($id) {
1463         global $CFG;
1464         return new moodle_url('/mod/workshop/exsubmission.php', array('cmid' => $this->cm->id, 'id' => $id));
1465     }
1467     /**
1468      * @param int $sid submission id
1469      * @param array $aid of int assessment ids
1470      * @return moodle_url of the page to compare assessments of the given submission
1471      */
1472     public function compare_url($sid, array $aids) {
1473         global $CFG;
1475         $url = new moodle_url('/mod/workshop/compare.php', array('cmid' => $this->cm->id, 'sid' => $sid));
1476         $i = 0;
1477         foreach ($aids as $aid) {
1478             $url->param("aid{$i}", $aid);
1479             $i++;
1480         }
1481         return $url;
1482     }
1484     /**
1485      * @param int $sid submission id
1486      * @param int $aid assessment id
1487      * @return moodle_url of the page to compare the reference assessments of the given example submission
1488      */
1489     public function excompare_url($sid, $aid) {
1490         global $CFG;
1491         return new moodle_url('/mod/workshop/excompare.php', array('cmid' => $this->cm->id, 'sid' => $sid, 'aid' => $aid));
1492     }
1494     /**
1495      * @return moodle_url of the mod_edit form
1496      */
1497     public function updatemod_url() {
1498         global $CFG;
1499         return new moodle_url('/course/modedit.php', array('update' => $this->cm->id, 'return' => 1));
1500     }
1502     /**
1503      * @param string $method allocation method
1504      * @return moodle_url to the allocation page
1505      */
1506     public function allocation_url($method=null) {
1507         global $CFG;
1508         $params = array('cmid' => $this->cm->id);
1509         if (!empty($method)) {
1510             $params['method'] = $method;
1511         }
1512         return new moodle_url('/mod/workshop/allocation.php', $params);
1513     }
1515     /**
1516      * @param int $phasecode The internal phase code
1517      * @return moodle_url of the script to change the current phase to $phasecode
1518      */
1519     public function switchphase_url($phasecode) {
1520         global $CFG;
1521         $phasecode = clean_param($phasecode, PARAM_INT);
1522         return new moodle_url('/mod/workshop/switchphase.php', array('cmid' => $this->cm->id, 'phase' => $phasecode));
1523     }
1525     /**
1526      * @return moodle_url to the aggregation page
1527      */
1528     public function aggregate_url() {
1529         global $CFG;
1530         return new moodle_url('/mod/workshop/aggregate.php', array('cmid' => $this->cm->id));
1531     }
1533     /**
1534      * @return moodle_url of this workshop's toolbox page
1535      */
1536     public function toolbox_url($tool) {
1537         global $CFG;
1538         return new moodle_url('/mod/workshop/toolbox.php', array('id' => $this->cm->id, 'tool' => $tool));
1539     }
1541     /**
1542      * Workshop wrapper around {@see add_to_log()}
1543      * @deprecated since 2.7 Please use the provided event classes for logging actions.
1544      *
1545      * @param string $action to be logged
1546      * @param moodle_url $url absolute url as returned by {@see workshop::submission_url()} and friends
1547      * @param mixed $info additional info, usually id in a table
1548      * @param bool $return true to return the arguments for add_to_log.
1549      * @return void|array array of arguments for add_to_log if $return is true
1550      */
1551     public function log($action, moodle_url $url = null, $info = null, $return = false) {
1552         debugging('The log method is now deprecated, please use event classes instead', DEBUG_DEVELOPER);
1554         if (is_null($url)) {
1555             $url = $this->view_url();
1556         }
1558         if (is_null($info)) {
1559             $info = $this->id;
1560         }
1562         $logurl = $this->log_convert_url($url);
1563         $args = array($this->course->id, 'workshop', $action, $logurl, $info, $this->cm->id);
1564         if ($return) {
1565             return $args;
1566         }
1567         call_user_func_array('add_to_log', $args);
1568     }
1570     /**
1571      * Is the given user allowed to create their submission?
1572      *
1573      * @param int $userid
1574      * @return bool
1575      */
1576     public function creating_submission_allowed($userid) {
1578         $now = time();
1579         $ignoredeadlines = has_capability('mod/workshop:ignoredeadlines', $this->context, $userid);
1581         if ($this->latesubmissions) {
1582             if ($this->phase != self::PHASE_SUBMISSION and $this->phase != self::PHASE_ASSESSMENT) {
1583                 // late submissions are allowed in the submission and assessment phase only
1584                 return false;
1585             }
1586             if (!$ignoredeadlines and !empty($this->submissionstart) and $this->submissionstart > $now) {
1587                 // late submissions are not allowed before the submission start
1588                 return false;
1589             }
1590             return true;
1592         } else {
1593             if ($this->phase != self::PHASE_SUBMISSION) {
1594                 // submissions are allowed during the submission phase only
1595                 return false;
1596             }
1597             if (!$ignoredeadlines and !empty($this->submissionstart) and $this->submissionstart > $now) {
1598                 // if enabled, submitting is not allowed before the date/time defined in the mod_form
1599                 return false;
1600             }
1601             if (!$ignoredeadlines and !empty($this->submissionend) and $now > $this->submissionend ) {
1602                 // if enabled, submitting is not allowed after the date/time defined in the mod_form unless late submission is allowed
1603                 return false;
1604             }
1605             return true;
1606         }
1607     }
1609     /**
1610      * Is the given user allowed to modify their existing submission?
1611      *
1612      * @param int $userid
1613      * @return bool
1614      */
1615     public function modifying_submission_allowed($userid) {
1617         $now = time();
1618         $ignoredeadlines = has_capability('mod/workshop:ignoredeadlines', $this->context, $userid);
1620         if ($this->phase != self::PHASE_SUBMISSION) {
1621             // submissions can be edited during the submission phase only
1622             return false;
1623         }
1624         if (!$ignoredeadlines and !empty($this->submissionstart) and $this->submissionstart > $now) {
1625             // if enabled, re-submitting is not allowed before the date/time defined in the mod_form
1626             return false;
1627         }
1628         if (!$ignoredeadlines and !empty($this->submissionend) and $now > $this->submissionend) {
1629             // if enabled, re-submitting is not allowed after the date/time defined in the mod_form even if late submission is allowed
1630             return false;
1631         }
1632         return true;
1633     }
1635     /**
1636      * Is the given reviewer allowed to create/edit their assessments?
1637      *
1638      * @param int $userid
1639      * @return bool
1640      */
1641     public function assessing_allowed($userid) {
1643         if ($this->phase != self::PHASE_ASSESSMENT) {
1644             // assessing is allowed in the assessment phase only, unless the user is a teacher
1645             // providing additional assessment during the evaluation phase
1646             if ($this->phase != self::PHASE_EVALUATION or !has_capability('mod/workshop:overridegrades', $this->context, $userid)) {
1647                 return false;
1648             }
1649         }
1651         $now = time();
1652         $ignoredeadlines = has_capability('mod/workshop:ignoredeadlines', $this->context, $userid);
1654         if (!$ignoredeadlines and !empty($this->assessmentstart) and $this->assessmentstart > $now) {
1655             // if enabled, assessing is not allowed before the date/time defined in the mod_form
1656             return false;
1657         }
1658         if (!$ignoredeadlines and !empty($this->assessmentend) and $now > $this->assessmentend) {
1659             // if enabled, assessing is not allowed after the date/time defined in the mod_form
1660             return false;
1661         }
1662         // here we go, assessing is allowed
1663         return true;
1664     }
1666     /**
1667      * Are reviewers allowed to create/edit their assessments of the example submissions?
1668      *
1669      * Returns null if example submissions are not enabled in this workshop. Otherwise returns
1670      * true or false. Note this does not check other conditions like the number of already
1671      * assessed examples, examples mode etc.
1672      *
1673      * @return null|bool
1674      */
1675     public function assessing_examples_allowed() {
1676         if (empty($this->useexamples)) {
1677             return null;
1678         }
1679         if (self::EXAMPLES_VOLUNTARY == $this->examplesmode) {
1680             return true;
1681         }
1682         if (self::EXAMPLES_BEFORE_SUBMISSION == $this->examplesmode and self::PHASE_SUBMISSION == $this->phase) {
1683             return true;
1684         }
1685         if (self::EXAMPLES_BEFORE_ASSESSMENT == $this->examplesmode and self::PHASE_ASSESSMENT == $this->phase) {
1686             return true;
1687         }
1688         return false;
1689     }
1691     /**
1692      * Are the peer-reviews available to the authors?
1693      *
1694      * @return bool
1695      */
1696     public function assessments_available() {
1697         return $this->phase == self::PHASE_CLOSED;
1698     }
1700     /**
1701      * Switch to a new workshop phase
1702      *
1703      * Modifies the underlying database record. You should terminate the script shortly after calling this.
1704      *
1705      * @param int $newphase new phase code
1706      * @return bool true if success, false otherwise
1707      */
1708     public function switch_phase($newphase) {
1709         global $DB;
1711         $known = $this->available_phases_list();
1712         if (!isset($known[$newphase])) {
1713             return false;
1714         }
1716         if (self::PHASE_CLOSED == $newphase) {
1717             // push the grades into the gradebook
1718             $workshop = new stdclass();
1719             foreach ($this as $property => $value) {
1720                 $workshop->{$property} = $value;
1721             }
1722             $workshop->course     = $this->course->id;
1723             $workshop->cmidnumber = $this->cm->id;
1724             $workshop->modname    = 'workshop';
1725             workshop_update_grades($workshop);
1726         }
1728         $DB->set_field('workshop', 'phase', $newphase, array('id' => $this->id));
1729         $this->phase = $newphase;
1730         $eventdata = array(
1731             'objectid' => $this->id,
1732             'context' => $this->context,
1733             'other' => array(
1734                 'workshopphase' => $this->phase
1735             )
1736         );
1737         $event = \mod_workshop\event\phase_switched::create($eventdata);
1738         $event->trigger();
1739         return true;
1740     }
1742     /**
1743      * Saves a raw grade for submission as calculated from the assessment form fields
1744      *
1745      * @param array $assessmentid assessment record id, must exists
1746      * @param mixed $grade        raw percentual grade from 0.00000 to 100.00000
1747      * @return false|float        the saved grade
1748      */
1749     public function set_peer_grade($assessmentid, $grade) {
1750         global $DB;
1752         if (is_null($grade)) {
1753             return false;
1754         }
1755         $data = new stdclass();
1756         $data->id = $assessmentid;
1757         $data->grade = $grade;
1758         $data->timemodified = time();
1759         $DB->update_record('workshop_assessments', $data);
1760         return $grade;
1761     }
1763     /**
1764      * Prepares data object with all workshop grades to be rendered
1765      *
1766      * @param int $userid the user we are preparing the report for
1767      * @param int $groupid if non-zero, prepare the report for the given group only
1768      * @param int $page the current page (for the pagination)
1769      * @param int $perpage participants per page (for the pagination)
1770      * @param string $sortby lastname|firstname|submissiontitle|submissiongrade|gradinggrade
1771      * @param string $sorthow ASC|DESC
1772      * @return stdclass data for the renderer
1773      */
1774     public function prepare_grading_report_data($userid, $groupid, $page, $perpage, $sortby, $sorthow) {
1775         global $DB;
1777         $canviewall     = has_capability('mod/workshop:viewallassessments', $this->context, $userid);
1778         $isparticipant  = $this->is_participant($userid);
1780         if (!$canviewall and !$isparticipant) {
1781             // who the hell is this?
1782             return array();
1783         }
1785         if (!in_array($sortby, array('lastname','firstname','submissiontitle', 'submissionmodified','submissiongrade','gradinggrade'))) {
1786             $sortby = 'lastname';
1787         }
1789         if (!($sorthow === 'ASC' or $sorthow === 'DESC')) {
1790             $sorthow = 'ASC';
1791         }
1793         // get the list of user ids to be displayed
1794         if ($canviewall) {
1795             $participants = $this->get_participants(false, $groupid);
1796         } else {
1797             // this is an ordinary workshop participant (aka student) - display the report just for him/her
1798             $participants = array($userid => (object)array('id' => $userid));
1799         }
1801         // we will need to know the number of all records later for the pagination purposes
1802         $numofparticipants = count($participants);
1804         if ($numofparticipants > 0) {
1805             // load all fields which can be used for sorting and paginate the records
1806             list($participantids, $params) = $DB->get_in_or_equal(array_keys($participants), SQL_PARAMS_NAMED);
1807             $params['workshopid1'] = $this->id;
1808             $params['workshopid2'] = $this->id;
1809             $sqlsort = array();
1810             $sqlsortfields = array($sortby => $sorthow) + array('lastname' => 'ASC', 'firstname' => 'ASC', 'u.id' => 'ASC');
1811             foreach ($sqlsortfields as $sqlsortfieldname => $sqlsortfieldhow) {
1812                 $sqlsort[] = $sqlsortfieldname . ' ' . $sqlsortfieldhow;
1813             }
1814             $sqlsort = implode(',', $sqlsort);
1815             $picturefields = user_picture::fields('u', array(), 'userid');
1816             $sql = "SELECT $picturefields, s.title AS submissiontitle, s.timemodified AS submissionmodified,
1817                                         s.grade AS submissiongrade, ag.gradinggrade
1818                       FROM {user} u
1819                  LEFT JOIN {workshop_submissions} s ON (s.authorid = u.id AND s.workshopid = :workshopid1 AND s.example = 0)
1820                  LEFT JOIN {workshop_aggregations} ag ON (ag.userid = u.id AND ag.workshopid = :workshopid2)
1821                      WHERE u.id $participantids
1822                   ORDER BY $sqlsort";
1823             $participants = $DB->get_records_sql($sql, $params, $page * $perpage, $perpage);
1824         } else {
1825             $participants = array();
1826         }
1828         // this will hold the information needed to display user names and pictures
1829         $userinfo = array();
1831         // get the user details for all participants to display
1832         $additionalnames = get_all_user_name_fields();
1833         foreach ($participants as $participant) {
1834             if (!isset($userinfo[$participant->userid])) {
1835                 $userinfo[$participant->userid]            = new stdclass();
1836                 $userinfo[$participant->userid]->id        = $participant->userid;
1837                 $userinfo[$participant->userid]->picture   = $participant->picture;
1838                 $userinfo[$participant->userid]->imagealt  = $participant->imagealt;
1839                 $userinfo[$participant->userid]->email     = $participant->email;
1840                 foreach ($additionalnames as $addname) {
1841                     $userinfo[$participant->userid]->$addname = $participant->$addname;
1842                 }
1843             }
1844         }
1846         // load the submissions details
1847         $submissions = $this->get_submissions(array_keys($participants));
1849         // get the user details for all moderators (teachers) that have overridden a submission grade
1850         foreach ($submissions as $submission) {
1851             if (!isset($userinfo[$submission->gradeoverby])) {
1852                 $userinfo[$submission->gradeoverby]            = new stdclass();
1853                 $userinfo[$submission->gradeoverby]->id        = $submission->gradeoverby;
1854                 $userinfo[$submission->gradeoverby]->picture   = $submission->overpicture;
1855                 $userinfo[$submission->gradeoverby]->imagealt  = $submission->overimagealt;
1856                 $userinfo[$submission->gradeoverby]->email     = $submission->overemail;
1857                 foreach ($additionalnames as $addname) {
1858                     $temp = 'over' . $addname;
1859                     $userinfo[$submission->gradeoverby]->$addname = $submission->$temp;
1860                 }
1861             }
1862         }
1864         // get the user details for all reviewers of the displayed participants
1865         $reviewers = array();
1867         if ($submissions) {
1868             list($submissionids, $params) = $DB->get_in_or_equal(array_keys($submissions), SQL_PARAMS_NAMED);
1869             list($sort, $sortparams) = users_order_by_sql('r');
1870             $picturefields = user_picture::fields('r', array(), 'reviewerid');
1871             $sql = "SELECT a.id AS assessmentid, a.submissionid, a.grade, a.gradinggrade, a.gradinggradeover, a.weight,
1872                            $picturefields, s.id AS submissionid, s.authorid
1873                       FROM {workshop_assessments} a
1874                       JOIN {user} r ON (a.reviewerid = r.id)
1875                       JOIN {workshop_submissions} s ON (a.submissionid = s.id AND s.example = 0)
1876                      WHERE a.submissionid $submissionids
1877                   ORDER BY a.weight DESC, $sort";
1878             $reviewers = $DB->get_records_sql($sql, array_merge($params, $sortparams));
1879             foreach ($reviewers as $reviewer) {
1880                 if (!isset($userinfo[$reviewer->reviewerid])) {
1881                     $userinfo[$reviewer->reviewerid]            = new stdclass();
1882                     $userinfo[$reviewer->reviewerid]->id        = $reviewer->reviewerid;
1883                     $userinfo[$reviewer->reviewerid]->picture   = $reviewer->picture;
1884                     $userinfo[$reviewer->reviewerid]->imagealt  = $reviewer->imagealt;
1885                     $userinfo[$reviewer->reviewerid]->email     = $reviewer->email;
1886                     foreach ($additionalnames as $addname) {
1887                         $userinfo[$reviewer->reviewerid]->$addname = $reviewer->$addname;
1888                     }
1889                 }
1890             }
1891         }
1893         // get the user details for all reviewees of the displayed participants
1894         $reviewees = array();
1895         if ($participants) {
1896             list($participantids, $params) = $DB->get_in_or_equal(array_keys($participants), SQL_PARAMS_NAMED);
1897             list($sort, $sortparams) = users_order_by_sql('e');
1898             $params['workshopid'] = $this->id;
1899             $picturefields = user_picture::fields('e', array(), 'authorid');
1900             $sql = "SELECT a.id AS assessmentid, a.submissionid, a.grade, a.gradinggrade, a.gradinggradeover, a.reviewerid, a.weight,
1901                            s.id AS submissionid, $picturefields
1902                       FROM {user} u
1903                       JOIN {workshop_assessments} a ON (a.reviewerid = u.id)
1904                       JOIN {workshop_submissions} s ON (a.submissionid = s.id AND s.example = 0)
1905                       JOIN {user} e ON (s.authorid = e.id)
1906                      WHERE u.id $participantids AND s.workshopid = :workshopid
1907                   ORDER BY a.weight DESC, $sort";
1908             $reviewees = $DB->get_records_sql($sql, array_merge($params, $sortparams));
1909             foreach ($reviewees as $reviewee) {
1910                 if (!isset($userinfo[$reviewee->authorid])) {
1911                     $userinfo[$reviewee->authorid]            = new stdclass();
1912                     $userinfo[$reviewee->authorid]->id        = $reviewee->authorid;
1913                     $userinfo[$reviewee->authorid]->picture   = $reviewee->picture;
1914                     $userinfo[$reviewee->authorid]->imagealt  = $reviewee->imagealt;
1915                     $userinfo[$reviewee->authorid]->email     = $reviewee->email;
1916                     foreach ($additionalnames as $addname) {
1917                         $userinfo[$reviewee->authorid]->$addname = $reviewee->$addname;
1918                     }
1919                 }
1920             }
1921         }
1923         // finally populate the object to be rendered
1924         $grades = $participants;
1926         foreach ($participants as $participant) {
1927             // set up default (null) values
1928             $grades[$participant->userid]->submissionid = null;
1929             $grades[$participant->userid]->submissiontitle = null;
1930             $grades[$participant->userid]->submissiongrade = null;
1931             $grades[$participant->userid]->submissiongradeover = null;
1932             $grades[$participant->userid]->submissiongradeoverby = null;
1933             $grades[$participant->userid]->submissionpublished = null;
1934             $grades[$participant->userid]->reviewedby = array();
1935             $grades[$participant->userid]->reviewerof = array();
1936         }
1937         unset($participants);
1938         unset($participant);
1940         foreach ($submissions as $submission) {
1941             $grades[$submission->authorid]->submissionid = $submission->id;
1942             $grades[$submission->authorid]->submissiontitle = $submission->title;
1943             $grades[$submission->authorid]->submissiongrade = $this->real_grade($submission->grade);
1944             $grades[$submission->authorid]->submissiongradeover = $this->real_grade($submission->gradeover);
1945             $grades[$submission->authorid]->submissiongradeoverby = $submission->gradeoverby;
1946             $grades[$submission->authorid]->submissionpublished = $submission->published;
1947         }
1948         unset($submissions);
1949         unset($submission);
1951         foreach($reviewers as $reviewer) {
1952             $info = new stdclass();
1953             $info->userid = $reviewer->reviewerid;
1954             $info->assessmentid = $reviewer->assessmentid;
1955             $info->submissionid = $reviewer->submissionid;
1956             $info->grade = $this->real_grade($reviewer->grade);
1957             $info->gradinggrade = $this->real_grading_grade($reviewer->gradinggrade);
1958             $info->gradinggradeover = $this->real_grading_grade($reviewer->gradinggradeover);
1959             $info->weight = $reviewer->weight;
1960             $grades[$reviewer->authorid]->reviewedby[$reviewer->reviewerid] = $info;
1961         }
1962         unset($reviewers);
1963         unset($reviewer);
1965         foreach($reviewees as $reviewee) {
1966             $info = new stdclass();
1967             $info->userid = $reviewee->authorid;
1968             $info->assessmentid = $reviewee->assessmentid;
1969             $info->submissionid = $reviewee->submissionid;
1970             $info->grade = $this->real_grade($reviewee->grade);
1971             $info->gradinggrade = $this->real_grading_grade($reviewee->gradinggrade);
1972             $info->gradinggradeover = $this->real_grading_grade($reviewee->gradinggradeover);
1973             $info->weight = $reviewee->weight;
1974             $grades[$reviewee->reviewerid]->reviewerof[$reviewee->authorid] = $info;
1975         }
1976         unset($reviewees);
1977         unset($reviewee);
1979         foreach ($grades as $grade) {
1980             $grade->gradinggrade = $this->real_grading_grade($grade->gradinggrade);
1981         }
1983         $data = new stdclass();
1984         $data->grades = $grades;
1985         $data->userinfo = $userinfo;
1986         $data->totalcount = $numofparticipants;
1987         $data->maxgrade = $this->real_grade(100);
1988         $data->maxgradinggrade = $this->real_grading_grade(100);
1989         return $data;
1990     }
1992     /**
1993      * Calculates the real value of a grade
1994      *
1995      * @param float $value percentual value from 0 to 100
1996      * @param float $max   the maximal grade
1997      * @return string
1998      */
1999     public function real_grade_value($value, $max) {
2000         $localized = true;
2001         if (is_null($value) or $value === '') {
2002             return null;
2003         } elseif ($max == 0) {
2004             return 0;
2005         } else {
2006             return format_float($max * $value / 100, $this->gradedecimals, $localized);
2007         }
2008     }
2010     /**
2011      * Calculates the raw (percentual) value from a real grade
2012      *
2013      * This is used in cases when a user wants to give a grade such as 12 of 20 and we need to save
2014      * this value in a raw percentual form into DB
2015      * @param float $value given grade
2016      * @param float $max   the maximal grade
2017      * @return float       suitable to be stored as numeric(10,5)
2018      */
2019     public function raw_grade_value($value, $max) {
2020         if (is_null($value) or $value === '') {
2021             return null;
2022         }
2023         if ($max == 0 or $value < 0) {
2024             return 0;
2025         }
2026         $p = $value / $max * 100;
2027         if ($p > 100) {
2028             return $max;
2029         }
2030         return grade_floatval($p);
2031     }
2033     /**
2034      * Calculates the real value of grade for submission
2035      *
2036      * @param float $value percentual value from 0 to 100
2037      * @return string
2038      */
2039     public function real_grade($value) {
2040         return $this->real_grade_value($value, $this->grade);
2041     }
2043     /**
2044      * Calculates the real value of grade for assessment
2045      *
2046      * @param float $value percentual value from 0 to 100
2047      * @return string
2048      */
2049     public function real_grading_grade($value) {
2050         return $this->real_grade_value($value, $this->gradinggrade);
2051     }
2053     /**
2054      * Sets the given grades and received grading grades to null
2055      *
2056      * This does not clear the information about how the peers filled the assessment forms, but
2057      * clears the calculated grades in workshop_assessments. Therefore reviewers have to re-assess
2058      * the allocated submissions.
2059      *
2060      * @return void
2061      */
2062     public function clear_assessments() {
2063         global $DB;
2065         $submissions = $this->get_submissions();
2066         if (empty($submissions)) {
2067             // no money, no love
2068             return;
2069         }
2070         $submissions = array_keys($submissions);
2071         list($sql, $params) = $DB->get_in_or_equal($submissions, SQL_PARAMS_NAMED);
2072         $sql = "submissionid $sql";
2073         $DB->set_field_select('workshop_assessments', 'grade', null, $sql, $params);
2074         $DB->set_field_select('workshop_assessments', 'gradinggrade', null, $sql, $params);
2075     }
2077     /**
2078      * Sets the grades for submission to null
2079      *
2080      * @param null|int|array $restrict If null, update all authors, otherwise update just grades for the given author(s)
2081      * @return void
2082      */
2083     public function clear_submission_grades($restrict=null) {
2084         global $DB;
2086         $sql = "workshopid = :workshopid AND example = 0";
2087         $params = array('workshopid' => $this->id);
2089         if (is_null($restrict)) {
2090             // update all users - no more conditions
2091         } elseif (!empty($restrict)) {
2092             list($usql, $uparams) = $DB->get_in_or_equal($restrict, SQL_PARAMS_NAMED);
2093             $sql .= " AND authorid $usql";
2094             $params = array_merge($params, $uparams);
2095         } else {
2096             throw new coding_exception('Empty value is not a valid parameter here');
2097         }
2099         $DB->set_field_select('workshop_submissions', 'grade', null, $sql, $params);
2100     }
2102     /**
2103      * Calculates grades for submission for the given participant(s) and updates it in the database
2104      *
2105      * @param null|int|array $restrict If null, update all authors, otherwise update just grades for the given author(s)
2106      * @return void
2107      */
2108     public function aggregate_submission_grades($restrict=null) {
2109         global $DB;
2111         // fetch a recordset with all assessments to process
2112         $sql = 'SELECT s.id AS submissionid, s.grade AS submissiongrade,
2113                        a.weight, a.grade
2114                   FROM {workshop_submissions} s
2115              LEFT JOIN {workshop_assessments} a ON (a.submissionid = s.id)
2116                  WHERE s.example=0 AND s.workshopid=:workshopid'; // to be cont.
2117         $params = array('workshopid' => $this->id);
2119         if (is_null($restrict)) {
2120             // update all users - no more conditions
2121         } elseif (!empty($restrict)) {
2122             list($usql, $uparams) = $DB->get_in_or_equal($restrict, SQL_PARAMS_NAMED);
2123             $sql .= " AND s.authorid $usql";
2124             $params = array_merge($params, $uparams);
2125         } else {
2126             throw new coding_exception('Empty value is not a valid parameter here');
2127         }
2129         $sql .= ' ORDER BY s.id'; // this is important for bulk processing
2131         $rs         = $DB->get_recordset_sql($sql, $params);
2132         $batch      = array();    // will contain a set of all assessments of a single submission
2133         $previous   = null;       // a previous record in the recordset
2135         foreach ($rs as $current) {
2136             if (is_null($previous)) {
2137                 // we are processing the very first record in the recordset
2138                 $previous   = $current;
2139             }
2140             if ($current->submissionid == $previous->submissionid) {
2141                 // we are still processing the current submission
2142                 $batch[] = $current;
2143             } else {
2144                 // process all the assessments of a sigle submission
2145                 $this->aggregate_submission_grades_process($batch);
2146                 // and then start to process another submission
2147                 $batch      = array($current);
2148                 $previous   = $current;
2149             }
2150         }
2151         // do not forget to process the last batch!
2152         $this->aggregate_submission_grades_process($batch);
2153         $rs->close();
2154     }
2156     /**
2157      * Sets the aggregated grades for assessment to null
2158      *
2159      * @param null|int|array $restrict If null, update all reviewers, otherwise update just grades for the given reviewer(s)
2160      * @return void
2161      */
2162     public function clear_grading_grades($restrict=null) {
2163         global $DB;
2165         $sql = "workshopid = :workshopid";
2166         $params = array('workshopid' => $this->id);
2168         if (is_null($restrict)) {
2169             // update all users - no more conditions
2170         } elseif (!empty($restrict)) {
2171             list($usql, $uparams) = $DB->get_in_or_equal($restrict, SQL_PARAMS_NAMED);
2172             $sql .= " AND userid $usql";
2173             $params = array_merge($params, $uparams);
2174         } else {
2175             throw new coding_exception('Empty value is not a valid parameter here');
2176         }
2178         $DB->set_field_select('workshop_aggregations', 'gradinggrade', null, $sql, $params);
2179     }
2181     /**
2182      * Calculates grades for assessment for the given participant(s)
2183      *
2184      * Grade for assessment is calculated as a simple mean of all grading grades calculated by the grading evaluator.
2185      * The assessment weight is not taken into account here.
2186      *
2187      * @param null|int|array $restrict If null, update all reviewers, otherwise update just grades for the given reviewer(s)
2188      * @return void
2189      */
2190     public function aggregate_grading_grades($restrict=null) {
2191         global $DB;
2193         // fetch a recordset with all assessments to process
2194         $sql = 'SELECT a.reviewerid, a.gradinggrade, a.gradinggradeover,
2195                        ag.id AS aggregationid, ag.gradinggrade AS aggregatedgrade
2196                   FROM {workshop_assessments} a
2197             INNER JOIN {workshop_submissions} s ON (a.submissionid = s.id)
2198              LEFT JOIN {workshop_aggregations} ag ON (ag.userid = a.reviewerid AND ag.workshopid = s.workshopid)
2199                  WHERE s.example=0 AND s.workshopid=:workshopid'; // to be cont.
2200         $params = array('workshopid' => $this->id);
2202         if (is_null($restrict)) {
2203             // update all users - no more conditions
2204         } elseif (!empty($restrict)) {
2205             list($usql, $uparams) = $DB->get_in_or_equal($restrict, SQL_PARAMS_NAMED);
2206             $sql .= " AND a.reviewerid $usql";
2207             $params = array_merge($params, $uparams);
2208         } else {
2209             throw new coding_exception('Empty value is not a valid parameter here');
2210         }
2212         $sql .= ' ORDER BY a.reviewerid'; // this is important for bulk processing
2214         $rs         = $DB->get_recordset_sql($sql, $params);
2215         $batch      = array();    // will contain a set of all assessments of a single submission
2216         $previous   = null;       // a previous record in the recordset
2218         foreach ($rs as $current) {
2219             if (is_null($previous)) {
2220                 // we are processing the very first record in the recordset
2221                 $previous   = $current;
2222             }
2223             if ($current->reviewerid == $previous->reviewerid) {
2224                 // we are still processing the current reviewer
2225                 $batch[] = $current;
2226             } else {
2227                 // process all the assessments of a sigle submission
2228                 $this->aggregate_grading_grades_process($batch);
2229                 // and then start to process another reviewer
2230                 $batch      = array($current);
2231                 $previous   = $current;
2232             }
2233         }
2234         // do not forget to process the last batch!
2235         $this->aggregate_grading_grades_process($batch);
2236         $rs->close();
2237     }
2239     /**
2240      * Returns the mform the teachers use to put a feedback for the reviewer
2241      *
2242      * @param moodle_url $actionurl
2243      * @param stdClass $assessment
2244      * @param array $options editable, editableweight, overridablegradinggrade
2245      * @return workshop_feedbackreviewer_form
2246      */
2247     public function get_feedbackreviewer_form(moodle_url $actionurl, stdclass $assessment, $options=array()) {
2248         global $CFG;
2249         require_once(dirname(__FILE__) . '/feedbackreviewer_form.php');
2251         $current = new stdclass();
2252         $current->asid                      = $assessment->id;
2253         $current->weight                    = $assessment->weight;
2254         $current->gradinggrade              = $this->real_grading_grade($assessment->gradinggrade);
2255         $current->gradinggradeover          = $this->real_grading_grade($assessment->gradinggradeover);
2256         $current->feedbackreviewer          = $assessment->feedbackreviewer;
2257         $current->feedbackreviewerformat    = $assessment->feedbackreviewerformat;
2258         if (is_null($current->gradinggrade)) {
2259             $current->gradinggrade = get_string('nullgrade', 'workshop');
2260         }
2261         if (!isset($options['editable'])) {
2262             $editable = true;   // by default
2263         } else {
2264             $editable = (bool)$options['editable'];
2265         }
2267         // prepare wysiwyg editor
2268         $current = file_prepare_standard_editor($current, 'feedbackreviewer', array());
2270         return new workshop_feedbackreviewer_form($actionurl,
2271                 array('workshop' => $this, 'current' => $current, 'editoropts' => array(), 'options' => $options),
2272                 'post', '', null, $editable);
2273     }
2275     /**
2276      * Returns the mform the teachers use to put a feedback for the author on their submission
2277      *
2278      * @param moodle_url $actionurl
2279      * @param stdClass $submission
2280      * @param array $options editable
2281      * @return workshop_feedbackauthor_form
2282      */
2283     public function get_feedbackauthor_form(moodle_url $actionurl, stdclass $submission, $options=array()) {
2284         global $CFG;
2285         require_once(dirname(__FILE__) . '/feedbackauthor_form.php');
2287         $current = new stdclass();
2288         $current->submissionid          = $submission->id;
2289         $current->published             = $submission->published;
2290         $current->grade                 = $this->real_grade($submission->grade);
2291         $current->gradeover             = $this->real_grade($submission->gradeover);
2292         $current->feedbackauthor        = $submission->feedbackauthor;
2293         $current->feedbackauthorformat  = $submission->feedbackauthorformat;
2294         if (is_null($current->grade)) {
2295             $current->grade = get_string('nullgrade', 'workshop');
2296         }
2297         if (!isset($options['editable'])) {
2298             $editable = true;   // by default
2299         } else {
2300             $editable = (bool)$options['editable'];
2301         }
2303         // prepare wysiwyg editor
2304         $current = file_prepare_standard_editor($current, 'feedbackauthor', array());
2306         return new workshop_feedbackauthor_form($actionurl,
2307                 array('workshop' => $this, 'current' => $current, 'editoropts' => array(), 'options' => $options),
2308                 'post', '', null, $editable);
2309     }
2311     /**
2312      * Returns the information about the user's grades as they are stored in the gradebook
2313      *
2314      * The submission grade is returned for users with the capability mod/workshop:submit and the
2315      * assessment grade is returned for users with the capability mod/workshop:peerassess. Unless the
2316      * user has the capability to view hidden grades, grades must be visible to be returned. Null
2317      * grades are not returned. If none grade is to be returned, this method returns false.
2318      *
2319      * @param int $userid the user's id
2320      * @return workshop_final_grades|false
2321      */
2322     public function get_gradebook_grades($userid) {
2323         global $CFG;
2324         require_once($CFG->libdir.'/gradelib.php');
2326         if (empty($userid)) {
2327             throw new coding_exception('User id expected, empty value given.');
2328         }
2330         // Read data via the Gradebook API
2331         $gradebook = grade_get_grades($this->course->id, 'mod', 'workshop', $this->id, $userid);
2333         $grades = new workshop_final_grades();
2335         if (has_capability('mod/workshop:submit', $this->context, $userid)) {
2336             if (!empty($gradebook->items[0]->grades)) {
2337                 $submissiongrade = reset($gradebook->items[0]->grades);
2338                 if (!is_null($submissiongrade->grade)) {
2339                     if (!$submissiongrade->hidden or has_capability('moodle/grade:viewhidden', $this->context, $userid)) {
2340                         $grades->submissiongrade = $submissiongrade;
2341                     }
2342                 }
2343             }
2344         }
2346         if (has_capability('mod/workshop:peerassess', $this->context, $userid)) {
2347             if (!empty($gradebook->items[1]->grades)) {
2348                 $assessmentgrade = reset($gradebook->items[1]->grades);
2349                 if (!is_null($assessmentgrade->grade)) {
2350                     if (!$assessmentgrade->hidden or has_capability('moodle/grade:viewhidden', $this->context, $userid)) {
2351                         $grades->assessmentgrade = $assessmentgrade;
2352                     }
2353                 }
2354             }
2355         }
2357         if (!is_null($grades->submissiongrade) or !is_null($grades->assessmentgrade)) {
2358             return $grades;
2359         }
2361         return false;
2362     }
2364     /**
2365      * Return the editor options for the overall feedback for the author.
2366      *
2367      * @return array
2368      */
2369     public function overall_feedback_content_options() {
2370         return array(
2371             'subdirs' => 0,
2372             'maxbytes' => $this->overallfeedbackmaxbytes,
2373             'maxfiles' => $this->overallfeedbackfiles,
2374             'changeformat' => 1,
2375             'context' => $this->context,
2376         );
2377     }
2379     /**
2380      * Return the filemanager options for the overall feedback for the author.
2381      *
2382      * @return array
2383      */
2384     public function overall_feedback_attachment_options() {
2385         return array(
2386             'subdirs' => 1,
2387             'maxbytes' => $this->overallfeedbackmaxbytes,
2388             'maxfiles' => $this->overallfeedbackfiles,
2389             'return_types' => FILE_INTERNAL,
2390         );
2391     }
2393     /**
2394      * Performs the reset of this workshop instance.
2395      *
2396      * @param stdClass $data The actual course reset settings.
2397      * @return array List of results, each being array[(string)component, (string)item, (string)error]
2398      */
2399     public function reset_userdata(stdClass $data) {
2401         $componentstr = get_string('pluginname', 'workshop').': '.format_string($this->name);
2402         $status = array();
2404         if (!empty($data->reset_workshop_assessments) or !empty($data->reset_workshop_submissions)) {
2405             // Reset all data related to assessments, including assessments of
2406             // example submissions.
2407             $result = $this->reset_userdata_assessments($data);
2408             if ($result === true) {
2409                 $status[] = array(
2410                     'component' => $componentstr,
2411                     'item' => get_string('resetassessments', 'mod_workshop'),
2412                     'error' => false,
2413                 );
2414             } else {
2415                 $status[] = array(
2416                     'component' => $componentstr,
2417                     'item' => get_string('resetassessments', 'mod_workshop'),
2418                     'error' => $result,
2419                 );
2420             }
2421         }
2423         if (!empty($data->reset_workshop_submissions)) {
2424             // Reset all remaining data related to submissions.
2425             $result = $this->reset_userdata_submissions($data);
2426             if ($result === true) {
2427                 $status[] = array(
2428                     'component' => $componentstr,
2429                     'item' => get_string('resetsubmissions', 'mod_workshop'),
2430                     'error' => false,
2431                 );
2432             } else {
2433                 $status[] = array(
2434                     'component' => $componentstr,
2435                     'item' => get_string('resetsubmissions', 'mod_workshop'),
2436                     'error' => $result,
2437                 );
2438             }
2439         }
2441         if (!empty($data->reset_workshop_phase)) {
2442             // Do not use the {@link workshop::switch_phase()} here, we do not
2443             // want to trigger events.
2444             $this->reset_phase();
2445             $status[] = array(
2446                 'component' => $componentstr,
2447                 'item' => get_string('resetsubmissions', 'mod_workshop'),
2448                 'error' => false,
2449             );
2450         }
2452         return $status;
2453     }
2456     ////////////////////////////////////////////////////////////////////////////////
2457     // Internal methods (implementation details)                                  //
2458     ////////////////////////////////////////////////////////////////////////////////
2460     /**
2461      * Given an array of all assessments of a single submission, calculates the final grade for this submission
2462      *
2463      * This calculates the weighted mean of the passed assessment grades. If, however, the submission grade
2464      * was overridden by a teacher, the gradeover value is returned and the rest of grades are ignored.
2465      *
2466      * @param array $assessments of stdclass(->submissionid ->submissiongrade ->gradeover ->weight ->grade)
2467      * @return void
2468      */
2469     protected function aggregate_submission_grades_process(array $assessments) {
2470         global $DB;
2472         $submissionid   = null; // the id of the submission being processed
2473         $current        = null; // the grade currently saved in database
2474         $finalgrade     = null; // the new grade to be calculated
2475         $sumgrades      = 0;
2476         $sumweights     = 0;
2478         foreach ($assessments as $assessment) {
2479             if (is_null($submissionid)) {
2480                 // the id is the same in all records, fetch it during the first loop cycle
2481                 $submissionid = $assessment->submissionid;
2482             }
2483             if (is_null($current)) {
2484                 // the currently saved grade is the same in all records, fetch it during the first loop cycle
2485                 $current = $assessment->submissiongrade;
2486             }
2487             if (is_null($assessment->grade)) {
2488                 // this was not assessed yet
2489                 continue;
2490             }
2491             if ($assessment->weight == 0) {
2492                 // this does not influence the calculation
2493                 continue;
2494             }
2495             $sumgrades  += $assessment->grade * $assessment->weight;
2496             $sumweights += $assessment->weight;
2497         }
2498         if ($sumweights > 0 and is_null($finalgrade)) {
2499             $finalgrade = grade_floatval($sumgrades / $sumweights);
2500         }
2501         // check if the new final grade differs from the one stored in the database
2502         if (grade_floats_different($finalgrade, $current)) {
2503             // we need to save new calculation into the database
2504             $record = new stdclass();
2505             $record->id = $submissionid;
2506             $record->grade = $finalgrade;
2507             $record->timegraded = time();
2508             $DB->update_record('workshop_submissions', $record);
2509         }
2510     }
2512     /**
2513      * Given an array of all assessments done by a single reviewer, calculates the final grading grade
2514      *
2515      * This calculates the simple mean of the passed grading grades. If, however, the grading grade
2516      * was overridden by a teacher, the gradinggradeover value is returned and the rest of grades are ignored.
2517      *
2518      * @param array $assessments of stdclass(->reviewerid ->gradinggrade ->gradinggradeover ->aggregationid ->aggregatedgrade)
2519      * @param null|int $timegraded explicit timestamp of the aggregation, defaults to the current time
2520      * @return void
2521      */
2522     protected function aggregate_grading_grades_process(array $assessments, $timegraded = null) {
2523         global $DB;
2525         $reviewerid = null; // the id of the reviewer being processed
2526         $current    = null; // the gradinggrade currently saved in database
2527         $finalgrade = null; // the new grade to be calculated
2528         $agid       = null; // aggregation id
2529         $sumgrades  = 0;
2530         $count      = 0;
2532         if (is_null($timegraded)) {
2533             $timegraded = time();
2534         }
2536         foreach ($assessments as $assessment) {
2537             if (is_null($reviewerid)) {
2538                 // the id is the same in all records, fetch it during the first loop cycle
2539                 $reviewerid = $assessment->reviewerid;
2540             }
2541             if (is_null($agid)) {
2542                 // the id is the same in all records, fetch it during the first loop cycle
2543                 $agid = $assessment->aggregationid;
2544             }
2545             if (is_null($current)) {
2546                 // the currently saved grade is the same in all records, fetch it during the first loop cycle
2547                 $current = $assessment->aggregatedgrade;
2548             }
2549             if (!is_null($assessment->gradinggradeover)) {
2550                 // the grading grade for this assessment is overridden by a teacher
2551                 $sumgrades += $assessment->gradinggradeover;
2552                 $count++;
2553             } else {
2554                 if (!is_null($assessment->gradinggrade)) {
2555                     $sumgrades += $assessment->gradinggrade;
2556                     $count++;
2557                 }
2558             }
2559         }
2560         if ($count > 0) {
2561             $finalgrade = grade_floatval($sumgrades / $count);
2562         }
2564         // Event information.
2565         $params = array(
2566             'context' => $this->context,
2567             'courseid' => $this->course->id,
2568             'relateduserid' => $reviewerid
2569         );
2571         // check if the new final grade differs from the one stored in the database
2572         if (grade_floats_different($finalgrade, $current)) {
2573             $params['other'] = array(
2574                 'currentgrade' => $current,
2575                 'finalgrade' => $finalgrade
2576             );
2578             // we need to save new calculation into the database
2579             if (is_null($agid)) {
2580                 // no aggregation record yet
2581                 $record = new stdclass();
2582                 $record->workshopid = $this->id;
2583                 $record->userid = $reviewerid;
2584                 $record->gradinggrade = $finalgrade;
2585                 $record->timegraded = $timegraded;
2586                 $record->id = $DB->insert_record('workshop_aggregations', $record);
2587                 $params['objectid'] = $record->id;
2588                 $event = \mod_workshop\event\assessment_evaluated::create($params);
2589                 $event->trigger();
2590             } else {
2591                 $record = new stdclass();
2592                 $record->id = $agid;
2593                 $record->gradinggrade = $finalgrade;
2594                 $record->timegraded = $timegraded;
2595                 $DB->update_record('workshop_aggregations', $record);
2596                 $params['objectid'] = $agid;
2597                 $event = \mod_workshop\event\assessment_reevaluated::create($params);
2598                 $event->trigger();
2599             }
2600         }
2601     }
2603     /**
2604      * Returns SQL to fetch all enrolled users with the given capability in the current workshop
2605      *
2606      * The returned array consists of string $sql and the $params array. Note that the $sql can be
2607      * empty if a grouping is selected and it has no groups.
2608      *
2609      * The list is automatically restricted according to any availability restrictions
2610      * that apply to user lists (e.g. group, grouping restrictions).
2611      *
2612      * @param string $capability the name of the capability
2613      * @param bool $musthavesubmission ff true, return only users who have already submitted
2614      * @param int $groupid 0 means ignore groups, any other value limits the result by group id
2615      * @return array of (string)sql, (array)params
2616      */
2617     protected function get_users_with_capability_sql($capability, $musthavesubmission, $groupid) {
2618         global $CFG;
2619         /** @var int static counter used to generate unique parameter holders */
2620         static $inc = 0;
2621         $inc++;
2623         // If the caller requests all groups and we are using a selected grouping,
2624         // recursively call this function for each group in the grouping (this is
2625         // needed because get_enrolled_sql only supports a single group).
2626         if (empty($groupid) and $this->cm->groupingid) {
2627             $groupingid = $this->cm->groupingid;
2628             $groupinggroupids = array_keys(groups_get_all_groups($this->cm->course, 0, $this->cm->groupingid, 'g.id'));
2629             $sql = array();
2630             $params = array();
2631             foreach ($groupinggroupids as $groupinggroupid) {
2632                 if ($groupinggroupid > 0) { // just in case in order not to fall into the endless loop
2633                     list($gsql, $gparams) = $this->get_users_with_capability_sql($capability, $musthavesubmission, $groupinggroupid);
2634                     $sql[] = $gsql;
2635                     $params = array_merge($params, $gparams);
2636                 }
2637             }
2638             $sql = implode(PHP_EOL." UNION ".PHP_EOL, $sql);
2639             return array($sql, $params);
2640         }
2642         list($esql, $params) = get_enrolled_sql($this->context, $capability, $groupid, true);
2644         $userfields = user_picture::fields('u');
2646         $sql = "SELECT $userfields
2647                   FROM {user} u
2648                   JOIN ($esql) je ON (je.id = u.id AND u.deleted = 0) ";
2650         if ($musthavesubmission) {
2651             $sql .= " JOIN {workshop_submissions} ws ON (ws.authorid = u.id AND ws.example = 0 AND ws.workshopid = :workshopid{$inc}) ";
2652             $params['workshopid'.$inc] = $this->id;
2653         }
2655         // If the activity is restricted so that only certain users should appear
2656         // in user lists, integrate this into the same SQL.
2657         $info = new \core_availability\info_module($this->cm);
2658         list ($listsql, $listparams) = $info->get_user_list_sql(false);
2659         if ($listsql) {
2660             $sql .= " JOIN ($listsql) restricted ON restricted.id = u.id ";
2661             $params = array_merge($params, $listparams);
2662         }
2664         return array($sql, $params);
2665     }
2667     /**
2668      * Returns SQL statement that can be used to fetch all actively enrolled participants in the workshop
2669      *
2670      * @param bool $musthavesubmission if true, return only users who have already submitted
2671      * @param int $groupid 0 means ignore groups, any other value limits the result by group id
2672      * @return array of (string)sql, (array)params
2673      */
2674     protected function get_participants_sql($musthavesubmission=false, $groupid=0) {
2676         list($sql1, $params1) = $this->get_users_with_capability_sql('mod/workshop:submit', $musthavesubmission, $groupid);
2677         list($sql2, $params2) = $this->get_users_with_capability_sql('mod/workshop:peerassess', $musthavesubmission, $groupid);
2679         if (empty($sql1) or empty($sql2)) {
2680             if (empty($sql1) and empty($sql2)) {
2681                 return array('', array());
2682             } else if (empty($sql1)) {
2683                 $sql = $sql2;
2684                 $params = $params2;
2685             } else {
2686                 $sql = $sql1;
2687                 $params = $params1;
2688             }
2689         } else {
2690             $sql = $sql1.PHP_EOL." UNION ".PHP_EOL.$sql2;
2691             $params = array_merge($params1, $params2);
2692         }
2694         return array($sql, $params);
2695     }
2697     /**
2698      * @return array of available workshop phases
2699      */
2700     protected function available_phases_list() {
2701         return array(
2702             self::PHASE_SETUP       => true,
2703             self::PHASE_SUBMISSION  => true,
2704             self::PHASE_ASSESSMENT  => true,
2705             self::PHASE_EVALUATION  => true,
2706             self::PHASE_CLOSED      => true,
2707         );
2708     }
2710     /**
2711      * Converts absolute URL to relative URL needed by {@see add_to_log()}
2712      *
2713      * @param moodle_url $url absolute URL
2714      * @return string
2715      */
2716     protected function log_convert_url(moodle_url $fullurl) {
2717         static $baseurl;
2719         if (!isset($baseurl)) {
2720             $baseurl = new moodle_url('/mod/workshop/');
2721             $baseurl = $baseurl->out();
2722         }
2724         return substr($fullurl->out(), strlen($baseurl));
2725     }
2727     /**
2728      * Removes all user data related to assessments (including allocations).
2729      *
2730      * This includes assessments of example submissions as long as they are not
2731      * referential assessments.
2732      *
2733      * @param stdClass $data The actual course reset settings.
2734      * @return bool|string True on success, error message otherwise.
2735      */
2736     protected function reset_userdata_assessments(stdClass $data) {
2737         global $DB;
2739         $sql = "SELECT a.id
2740                   FROM {workshop_assessments} a
2741                   JOIN {workshop_submissions} s ON (a.submissionid = s.id)
2742                  WHERE s.workshopid = :workshopid
2743                        AND (s.example = 0 OR (s.example = 1 AND a.weight = 0))";
2745         $assessments = $DB->get_records_sql($sql, array('workshopid' => $this->id));
2746         $this->delete_assessment(array_keys($assessments));
2748         $DB->delete_records('workshop_aggregations', array('workshopid' => $this->id));
2750         return true;
2751     }
2753     /**
2754      * Removes all user data related to participants' submissions.
2755      *
2756      * @param stdClass $data The actual course reset settings.
2757      * @return bool|string True on success, error message otherwise.
2758      */
2759     protected function reset_userdata_submissions(stdClass $data) {
2760         global $DB;
2762         $submissions = $this->get_submissions();
2763         foreach ($submissions as $submission) {
2764             $this->delete_submission($submission);
2765         }
2767         return true;
2768     }
2770     /**
2771      * Hard set the workshop phase to the setup one.
2772      */
2773     protected function reset_phase() {
2774         global $DB;
2776         $DB->set_field('workshop', 'phase', self::PHASE_SETUP, array('id' => $this->id));
2777         $this->phase = self::PHASE_SETUP;
2778     }
2781 ////////////////////////////////////////////////////////////////////////////////
2782 // Renderable components
2783 ////////////////////////////////////////////////////////////////////////////////
2785 /**
2786  * Represents the user planner tool
2787  *
2788  * Planner contains list of phases. Each phase contains list of tasks. Task is a simple object with
2789  * title, link and completed (true/false/null logic).
2790  */
2791 class workshop_user_plan implements renderable {
2793     /** @var int id of the user this plan is for */
2794     public $userid;
2795     /** @var workshop */
2796     public $workshop;
2797     /** @var array of (stdclass)tasks */
2798     public $phases = array();
2799     /** @var null|array of example submissions to be assessed by the planner owner */
2800     protected $examples = null;
2802     /**
2803      * Prepare an individual workshop plan for the given user.
2804      *
2805      * @param workshop $workshop instance
2806      * @param int $userid whom the plan is prepared for
2807      */
2808     public function __construct(workshop $workshop, $userid) {
2809         global $DB;
2811         $this->workshop = $workshop;
2812         $this->userid   = $userid;
2814         //---------------------------------------------------------
2815         // * SETUP | submission | assessment | evaluation | closed
2816         //---------------------------------------------------------
2817         $phase = new stdclass();
2818         $phase->title = get_string('phasesetup', 'workshop');
2819         $phase->tasks = array();
2820         if (has_capability('moodle/course:manageactivities', $workshop->context, $userid)) {
2821             $task = new stdclass();
2822             $task->title = get_string('taskintro', 'workshop');
2823             $task->link = $workshop->updatemod_url();
2824             $task->completed = !(trim($workshop->intro) == '');
2825             $phase->tasks['intro'] = $task;
2826         }
2827         if (has_capability('moodle/course:manageactivities', $workshop->context, $userid)) {
2828             $task = new stdclass();
2829             $task->title = get_string('taskinstructauthors', 'workshop');
2830             $task->link = $workshop->updatemod_url();
2831             $task->completed = !(trim($workshop->instructauthors) == '');
2832             $phase->tasks['instructauthors'] = $task;
2833         }
2834         if (has_capability('mod/workshop:editdimensions', $workshop->context, $userid)) {
2835             $task = new stdclass();
2836             $task->title = get_string('editassessmentform', 'workshop');
2837             $task->link = $workshop->editform_url();
2838             if ($workshop->grading_strategy_instance()->form_ready()) {
2839                 $task->completed = true;
2840             } elseif ($workshop->phase > workshop::PHASE_SETUP) {
2841                 $task->completed = false;
2842             }
2843             $phase->tasks['editform'] = $task;
2844         }
2845         if ($workshop->useexamples and has_capability('mod/workshop:manageexamples', $workshop->context, $userid)) {
2846             $task = new stdclass();
2847             $task->title = get_string('prepareexamples', 'workshop');
2848             if ($DB->count_records('workshop_submissions', array('example' => 1, 'workshopid' => $workshop->id)) > 0) {
2849                 $task->completed = true;
2850             } elseif ($workshop->phase > workshop::PHASE_SETUP) {
2851                 $task->completed = false;
2852             }
2853             $phase->tasks['prepareexamples'] = $task;
2854         }
2855         if (empty($phase->tasks) and $workshop->phase == workshop::PHASE_SETUP) {
2856             // if we are in the setup phase and there is no task (typical for students), let us
2857             // display some explanation what is going on
2858             $task = new stdclass();
2859             $task->title = get_string('undersetup', 'workshop');
2860             $task->completed = 'info';
2861             $phase->tasks['setupinfo'] = $task;
2862         }
2863         $this->phases[workshop::PHASE_SETUP] = $phase;
2865         //---------------------------------------------------------
2866         // setup | * SUBMISSION | assessment | evaluation | closed
2867         //---------------------------------------------------------
2868         $phase = new stdclass();
2869         $phase->title = get_string('phasesubmission', 'workshop');
2870         $phase->tasks = array();
2871         if (has_capability('moodle/course:manageactivities', $workshop->context, $userid)) {
2872             $task = new stdclass();
2873             $task->title = get_string('taskinstructreviewers', 'workshop');
2874             $task->link = $workshop->updatemod_url();
2875             if (trim($workshop->instructreviewers)) {
2876                 $task->completed = true;
2877             } elseif ($workshop->phase >= workshop::PHASE_ASSESSMENT) {
2878                 $task->completed = false;
2879             }
2880             $phase->tasks['instructreviewers'] = $task;
2881         }
2882         if ($workshop->useexamples and $workshop->examplesmode == workshop::EXAMPLES_BEFORE_SUBMISSION
2883                 and has_capability('mod/workshop:submit', $workshop->context, $userid, false)
2884                     and !has_capability('mod/workshop:manageexamples', $workshop->context, $userid)) {
2885             $task = new stdclass();
2886             $task->title = get_string('exampleassesstask', 'workshop');
2887             $examples = $this->get_examples();
2888             $a = new stdclass();
2889             $a->expected = count($examples);
2890             $a->assessed = 0;
2891             foreach ($examples as $exampleid => $example) {
2892                 if (!is_null($example->grade)) {
2893                     $a->assessed++;
2894                 }
2895             }
2896             $task->details = get_string('exampleassesstaskdetails', 'workshop', $a);
2897             if ($a->assessed == $a->expected) {
2898                 $task->completed = true;
2899             } elseif ($workshop->phase >= workshop::PHASE_ASSESSMENT) {
2900                 $task->completed = false;
2901             }
2902             $phase->tasks['examples'] = $task;
2903         }
2904         if (has_capability('mod/workshop:submit', $workshop->context, $userid, false)) {
2905             $task = new stdclass();
2906             $task->title = get_string('tasksubmit', 'workshop');
2907             $task->link = $workshop->submission_url();
2908             if ($DB->record_exists('workshop_submissions', array('workshopid'=>$workshop->id, 'example'=>0, 'authorid'=>$userid))) {
2909                 $task->completed = true;
2910             } elseif ($workshop->phase >= workshop::PHASE_ASSESSMENT) {
2911                 $task->completed = false;
2912             } else {
2913                 $task->completed = null;    // still has a chance to submit
2914             }
2915             $phase->tasks['submit'] = $task;
2916         }
2917         if (has_capability('mod/workshop:allocate', $workshop->context, $userid)) {
2918             if ($workshop->phaseswitchassessment) {
2919                 $task = new stdClass();
2920                 $allocator = $DB->get_record('workshopallocation_scheduled', array('workshopid' => $workshop->id));
2921                 if (empty($allocator)) {
2922                     $task->completed = false;
2923                 } else if ($allocator->enabled and is_null($allocator->resultstatus)) {
2924                     $task->completed = true;
2925                 } else if ($workshop->submissionend > time()) {
2926                     $task->completed = null;
2927                 } else {
2928                     $task->completed = false;
2929                 }
2930                 $task->title = get_string('setup', 'workshopallocation_scheduled');
2931                 $task->link = $workshop->allocation_url('scheduled');
2932                 $phase->tasks['allocatescheduled'] = $task;
2933             }
2934             $task = new stdclass();
2935             $task->title = get_string('allocate', 'workshop');
2936             $task->link = $workshop->allocation_url();
2937             $numofauthors = $workshop->count_potential_authors(false);
2938             $numofsubmissions = $DB->count_records('workshop_submissions', array('workshopid'=>$workshop->id, 'example'=>0));
2939             $sql = 'SELECT COUNT(s.id) AS nonallocated
2940                       FROM {workshop_submissions} s
2941                  LEFT JOIN {workshop_assessments} a ON (a.submissionid=s.id)
2942                      WHERE s.workshopid = :workshopid AND s.example=0 AND a.submissionid IS NULL';
2943             $params['workshopid'] = $workshop->id;
2944             $numnonallocated = $DB->count_records_sql($sql, $params);
2945             if ($numofsubmissions == 0) {
2946                 $task->completed = null;
2947             } elseif ($numnonallocated == 0) {
2948                 $task->completed = true;
2949             } elseif ($workshop->phase > workshop::PHASE_SUBMISSION) {
2950                 $task->completed = false;
2951             } else {
2952                 $task->completed = null;    // still has a chance to allocate
2953             }
2954             $a = new stdclass();
2955             $a->expected    = $numofauthors;
2956             $a->submitted   = $numofsubmissions;
2957             $a->allocate    = $numnonallocated;
2958             $task->details  = get_string('allocatedetails', 'workshop', $a);
2959             unset($a);
2960             $phase->tasks['allocate'] = $task;
2962             if ($numofsubmissions < $numofauthors and $workshop->phase >= workshop::PHASE_SUBMISSION) {
2963                 $task = new stdclass();
2964                 $task->title = get_string('someuserswosubmission', 'workshop');
2965                 $task->completed = 'info';
2966                 $phase->tasks['allocateinfo'] = $task;
2967             }
2969         }
2970         if ($workshop->submissionstart) {
2971             $task = new stdclass();
2972             $task->title = get_string('submissionstartdatetime', 'workshop', workshop::timestamp_formats($workshop->submissionstart));
2973             $task->completed = 'info';
2974             $phase->tasks['submissionstartdatetime'] = $task;
2975         }
2976         if ($workshop->submissionend) {
2977             $task = new stdclass();
2978             $task->title = get_string('submissionenddatetime', 'workshop', workshop::timestamp_formats($workshop->submissionend));
2979             $task->completed = 'info';
2980             $phase->tasks['submissionenddatetime'] = $task;
2981         }
2982         if (($workshop->submissionstart < time()) and $workshop->latesubmissions) {
2983             $task = new stdclass();
2984             $task->title = get_string('latesubmissionsallowed', 'workshop');
2985             $task->completed = 'info';
2986             $phase->tasks['latesubmissionsallowed'] = $task;
2987         }
2988         if (isset($phase->tasks['submissionstartdatetime']) or isset($phase->tasks['submissionenddatetime'])) {
2989             if (has_capability('mod/workshop:ignoredeadlines', $workshop->context, $userid)) {
2990                 $task = new stdclass();
2991                 $task->title = get_string('deadlinesignored', 'workshop');
2992                 $task->completed = 'info';
2993                 $phase->tasks['deadlinesignored'] = $task;
2994             }
2995         }
2996         $this->phases[workshop::PHASE_SUBMISSION] = $phase;
2998         //---------------------------------------------------------
2999         // setup | submission | * ASSESSMENT | evaluation | closed
3000         //---------------------------------------------------------
3001         $phase = new stdclass();
3002         $phase->title = get_string('phaseassessment', 'workshop');
3003         $phase->tasks = array();
3004         $phase->isreviewer = has_capability('mod/workshop:peerassess', $workshop->context, $userid);
3005         if ($workshop->phase == workshop::PHASE_SUBMISSION and $workshop->phaseswitchassessment
3006                 and has_capability('mod/workshop:switchphase', $workshop->context, $userid)) {
3007             $task = new stdClass();
3008             $task->title = get_string('switchphase30auto', 'mod_workshop', workshop::timestamp_formats($workshop->submissionend));
3009             $task->completed = 'info';
3010             $phase->tasks['autoswitchinfo'] = $task;
3011         }
3012         if ($workshop->useexamples and $workshop->examplesmode == workshop::EXAMPLES_BEFORE_ASSESSMENT
3013                 and $phase->isreviewer and !has_capability('mod/workshop:manageexamples', $workshop->context, $userid)) {
3014             $task = new stdclass();
3015             $task->title = get_string('exampleassesstask', 'workshop');
3016             $examples = $workshop->get_examples_for_reviewer($userid);
3017             $a = new stdclass();
3018             $a->expected = count($examples);
3019             $a->assessed = 0;
3020             foreach ($examples as $exampleid => $example) {
3021                 if (!is_null($example->grade)) {
3022                     $a->assessed++;
3023                 }
3024             }
3025             $task->details = get_string('exampleassesstaskdetails', 'workshop', $a);
3026             if ($a->assessed == $a->expected) {
3027                 $task->completed = true;
3028             } elseif ($workshop->phase > workshop::PHASE_ASSESSMENT) {
3029                 $task->completed = false;
3030             }
3031             $phase->tasks['examples'] = $task;
3032         }
3033         if (empty($phase->tasks['examples']) or !empty($phase->tasks['examples']->completed)) {
3034             $phase->assessments = $workshop->get_assessments_by_reviewer($userid);
3035             $numofpeers     = 0;    // number of allocated peer-assessments
3036             $numofpeerstodo = 0;    // number of peer-assessments to do
3037             $numofself      = 0;    // number of allocated self-assessments - should be 0 or 1
3038             $numofselftodo  = 0;    // number of self-assessments to do - should be 0 or 1
3039             foreach ($phase->assessments as $a) {
3040                 if ($a->authorid == $userid) {
3041                     $numofself++;
3042                     if (is_null($a->grade)) {
3043                         $numofselftodo++;
3044                     }
3045                 } else {
3046                     $numofpeers++;
3047                     if (is_null($a->grade)) {
3048                         $numofpeerstodo++;
3049                     }
3050                 }
3051             }
3052             unset($a);
3053             if ($numofpeers) {
3054                 $task = new stdclass();
3055                 if ($numofpeerstodo == 0) {
3056                     $task->completed = true;
3057                 } elseif ($workshop->phase > workshop::PHASE_ASSESSMENT) {
3058                     $task->completed = false;
3059                 }
3060                 $a = new stdclass();
3061                 $a->total = $numofpeers;
3062                 $a->todo  = $numofpeerstodo;
3063                 $task->title = get_string('taskassesspeers', 'workshop');
3064                 $task->details = get_string('taskassesspeersdetails', 'workshop', $a);
3065                 unset($a);
3066                 $phase->tasks['assesspeers'] = $task;
3067             }
3068             if ($workshop->useselfassessment and $numofself) {
3069                 $task = new stdclass();
3070                 if ($numofselftodo == 0) {
3071                     $task->completed = true;
3072                 } elseif ($workshop->phase > workshop::PHASE_ASSESSMENT) {
3073                     $task->completed = false;
3074                 }
3075                 $task->title = get_string('taskassessself', 'workshop');
3076                 $phase->tasks['assessself'] = $task;
3077             }
3078         }
3079         if ($workshop->assessmentstart) {
3080             $task = new stdclass();
3081             $task->title = get_string('assessmentstartdatetime', 'workshop', workshop::timestamp_formats($workshop->assessmentstart));
3082             $task->completed = 'info';
3083             $phase->tasks['assessmentstartdatetime'] = $task;
3084         }
3085         if ($workshop->assessmentend) {
3086             $task = new stdclass();
3087             $task->title = get_string('assessmentenddatetime', 'workshop', workshop::timestamp_formats($workshop->assessmentend));
3088             $task->completed = 'info';
3089             $phase->tasks['assessmentenddatetime'] = $task;
3090         }
3091         if (isset($phase->tasks['assessmentstartdatetime']) or isset($phase->tasks['assessmentenddatetime'])) {
3092             if (has_capability('mod/workshop:ignoredeadlines', $workshop->context, $userid)) {
3093                 $task = new stdclass();
3094                 $task->title = get_string('deadlinesignored', 'workshop');
3095                 $task->completed = 'info';
3096                 $phase->tasks['deadlinesignored'] = $task;
3097             }
3098         }
3099         $this->phases[workshop::PHASE_ASSESSMENT] = $phase;
3101         //---------------------------------------------------------
3102         // setup | submission | assessment | * EVALUATION | closed
3103         //---------------------------------------------------------
3104         $phase = new stdclass();
3105         $phase->title = get_string('phaseevaluation', 'workshop');
3106         $phase->tasks = array();
3107         if (has_capability('mod/workshop:overridegrades', $workshop->context)) {
3108             $expected = $workshop->count_potential_authors(false);
3109             $calculated = $DB->count_records_select('workshop_submissions',
3110                     'workshopid = ? AND (grade IS NOT NULL OR gradeover IS NOT NULL)', array($workshop->id));
3111             $task = new stdclass();
3112             $task->title = get_string('calculatesubmissiongrades', 'workshop');
3113             $a = new stdclass();
3114             $a->expected    = $expected;
3115             $a->calculated  = $calculated;
3116             $task->details  = get_string('calculatesubmissiongradesdetails', 'workshop', $a);
3117             if ($calculated >= $expected) {
3118                 $task->completed = true;
3119             } elseif ($workshop->phase > workshop::PHASE_EVALUATION) {
3120                 $task->completed = false;
3121             }
3122             $phase->tasks['calculatesubmissiongrade'] = $task;
3124             $expected = $workshop->count_potential_reviewers(false);
3125             $calculated = $DB->count_records_select('workshop_aggregations',
3126                     'workshopid = ? AND gradinggrade IS NOT NULL', array($workshop->id));
3127             $task = new stdclass();
3128             $task->title = get_string('calculategradinggrades', 'workshop');
3129             $a = new stdclass();
3130             $a->expected    = $expected;
3131             $a->calculated  = $calculated;
3132             $task->details  = get_string('calculategradinggradesdetails', 'workshop', $a);
3133             if ($calculated >= $expected) {
3134                 $task->completed = true;
3135             } elseif ($workshop->phase > workshop::PHASE_EVALUATION) {
3136                 $task->completed = false;
3137             }
3138             $phase->tasks['calculategradinggrade'] = $task;
3140         } elseif ($workshop->phase == workshop::PHASE_EVALUATION) {
3141             $task = new stdclass();
3142             $task->title = get_string('evaluategradeswait', 'workshop');
3143             $task->completed = 'info';
3144             $phase->tasks['evaluateinfo'] = $task;
3145         }
3147         if (has_capability('moodle/course:manageactivities', $workshop->context, $userid)) {
3148             $task = new stdclass();
3149             $task->title = get_string('taskconclusion', 'workshop');
3150             $task->link = $workshop->updatemod_url();
3151             if (trim($workshop->conclusion)) {
3152                 $task->completed = true;
3153             } elseif ($workshop->phase >= workshop::PHASE_EVALUATION) {
3154                 $task->completed = false;
3155             }
3156             $phase->tasks['conclusion'] = $task;
3157         }
3159         $this->phases[workshop::PHASE_EVALUATION] = $phase;
3161         //---------------------------------------------------------
3162         // setup | submission | assessment | evaluation | * CLOSED
3163         //---------------------------------------------------------
3164         $phase = new stdclass();
3165         $phase->title = get_string('phaseclosed', 'workshop');
3166         $phase->tasks = array();
3167         $this->phases[workshop::PHASE_CLOSED] = $phase;
3169         // Polish data, set default values if not done explicitly
3170         foreach ($this->phases as $phasecode => $phase) {
3171             $phase->title       = isset($phase->title)      ? $phase->title     : '';
3172             $phase->tasks       = isset($phase->tasks)      ? $phase->tasks     : array();
3173             if ($phasecode == $workshop->phase) {
3174                 $phase->active = true;
3175             } else {
3176                 $phase->active = false;
3177             }
3178             if (!isset($phase->actions)) {
3179                 $phase->actions = array();
3180             }
3182             foreach ($phase->tasks as $taskcode => $task) {
3183                 $task->title        = isset($task->title)       ? $task->title      : '';
3184                 $task->link         = isset($task->link)        ? $task->link       : null;
3185                 $task->details      = isset($task->details)     ? $task->details    : '';
3186                 $task->completed    = isset($task->completed)   ? $task->completed  : null;
3187             }
3188         }
3190         // Add phase switching actions
3191         if (has_capability('mod/workshop:switchphase', $workshop->context, $userid)) {
3192             foreach ($this->phases as $phasecode => $phase) {
3193                 if (! $phase->active) {
3194                     $action = new stdclass();
3195                     $action->type = 'switchphase';
3196                     $action->url  = $workshop->switchphase_url($phasecode);
3197                     $phase->actions[] = $action;
3198                 }
3199             }
3200         }
3201     }
3203     /**
3204      * Returns example submissions to be assessed by the owner of the planner
3205      *
3206      * This is here to cache the DB query because the same list is needed later in view.php
3207      *
3208      * @see workshop::get_examples_for_reviewer() for the format of returned value
3209      * @return array
3210      */
3211     public function get_examples() {
3212         if (is_null($this->examples)) {
3213             $this->examples = $this->workshop->get_examples_for_reviewer($this->userid);
3214         }
3215         return $this->examples;
3216     }
3219 /**
3220  * Common base class for submissions and example submissions rendering
3221  *
3222  * Subclasses of this class convert raw submission record from
3223  * workshop_submissions table (as returned by {@see workshop::get_submission_by_id()}
3224  * for example) into renderable objects.
3225  */
3226 abstract class workshop_submission_base {
3228     /** @var bool is the submission anonymous (i.e. contains author information) */
3229     protected $anonymous;
3231     /* @var array of columns from workshop_submissions that are assigned as properties */
3232     protected $fields = array();
3234     /** @var workshop */
3235     protected $workshop;
3237     /**
3238      * Copies the properties of the given database record into properties of $this instance
3239      *
3240      * @param workshop $workshop
3241      * @param stdClass $submission full record
3242      * @param bool $showauthor show the author-related information
3243      * @param array $options additional properties
3244      */
3245     public function __construct(workshop $workshop, stdClass $submission, $showauthor = false) {
3247         $this->workshop = $workshop;
3249         foreach ($this->fields as $field) {
3250             if (!property_exists($submission, $field)) {
3251                 throw new coding_exception('Submission record must provide public property ' . $field);
3252             }
3253             if (!property_exists($this, $field)) {
3254                 throw new coding_exception('Renderable component must accept public property ' . $field);
3255             }
3256             $this->{$field} = $submission->{$field};
3257         }
3259         if ($showauthor) {
3260             $this->anonymous = false;
3261         } else {
3262             $this->anonymize();
3263         }
3264     }
3266     /**
3267      * Unsets all author-related properties so that the renderer does not have access to them
3268      *
3269      * Usually this is called by the contructor but can be called explicitely, too.
3270      */
3271     public function anonymize() {
3272         $authorfields = explode(',', user_picture::fields());
3273         foreach ($authorfields as $field) {
3274             $prefixedusernamefield = 'author' . $field;
3275             unset($this->{$prefixedusernamefield});
3276         }
3277         $this->anonymous = true;
3278     }
3280     /**
3281      * Does the submission object contain author-related information?
3282      *
3283      * @return null|boolean
3284      */
3285     public function is_anonymous() {
3286         return $this->anonymous;
3287     }
3290 /**
3291  * Renderable object containing a basic set of information needed to display the submission summary
3292  *
3293  * @see workshop_renderer::render_workshop_submission_summary
3294  */
3295 class workshop_submission_summary extends workshop_submission_base implements renderable {
3297     /** @var int */
3298     public $id;
3299     /** @var string */
3300     public $title;
3301     /** @var string graded|notgraded */
3302     public $status;
3303     /** @var int */
3304     public $timecreated;
3305     /** @var int */
3306     public $timemodified;
3307     /** @var int */
3308     public $authorid;
3309     /** @var string */
3310     public $authorfirstname;
3311     /** @var string */
3312     public $authorlastname;
3313     /** @var string */
3314     public $authorfirstnamephonetic;
3315     /** @var string */
3316     public $authorlastnamephonetic;
3317     /** @var string */
3318     public $authormiddlename;
3319     /** @var string */
3320     public $authoralternatename;
3321     /** @var int */
3322     public $authorpicture;
3323     /** @var string */
3324     public $authorimagealt;
3325     /** @var string */
3326     public $authoremail;
3327     /** @var moodle_url to display submission */
3328     public $url;
3330     /**
3331      * @var array of columns from workshop_submissions that are assigned as properties
3332      * of instances of this class
3333      */
3334     protected $fields = array(
3335         'id', 'title', 'timecreated', 'timemodified',
3336         'authorid', 'authorfirstname', 'authorlastname', 'authorfirstnamephonetic', 'authorlastnamephonetic',
3337         'authormiddlename', 'authoralternatename', 'authorpicture',
3338         'authorimagealt', 'authoremail');
3341 /**
3342  * Renderable object containing all the information needed to display the submission
3343  *
3344  * @see workshop_renderer::render_workshop_submission()
3345  */
3346 class workshop_submission extends workshop_submission_summary implements renderable {
3348     /** @var string */
3349     public $content;
3350     /** @var int */
3351     public $contentformat;
3352     /** @var bool */
3353     public $contenttrust;
3354     /** @var array */
3355     public $attachment;
3357     /**
3358      * @var array of columns from workshop_submissions that are assigned as properties
3359      * of instances of this class
3360      */
3361     protected $fields = array(
3362         'id', 'title', 'timecreated', 'timemodified', 'content', 'contentformat', 'contenttrust',
3363         'attachment', 'authorid', 'authorfirstname', 'authorlastname', 'authorfirstnamephonetic', 'authorlastnamephonetic',
3364         'authormiddlename', 'authoralternatename', 'authorpicture', 'authorimagealt', 'authoremail');
3367 /**
3368  * Renderable object containing a basic set of information needed to display the example submission summary
3369  *
3370  * @see workshop::prepare_example_summary()
3371  * @see workshop_renderer::render_workshop_example_submission_summary()
3372  */
3373 class workshop_example_submission_summary extends workshop_submission_base implements renderable {
3375     /** @var int */
3376     public $id;
3377     /** @var string */
3378     public $title;
3379     /** @var string graded|notgraded */
3380     public $status;
3381     /** @var stdClass */
3382     public $gradeinfo;
3383     /** @var moodle_url */
3384     public $url;
3385     /** @var moodle_url */
3386     public $editurl;
3387     /** @var string */
3388     public $assesslabel;
3389     /** @var moodle_url */
3390     public $assessurl;
3391     /** @var bool must be set explicitly by the caller */
3392     public $editable = false;
3394     /**
3395      * @var array of columns from workshop_submissions that are assigned as properties
3396      * of instances of this class
3397      */
3398     protected $fields = array('id', 'title');
3400     /**
3401      * Example submissions are always anonymous
3402      *
3403      * @return true
3404      */
3405     public function is_anonymous() {
3406         return true;
3407     }
3410 /**
3411  * Renderable object containing all the information needed to display the example submission
3412  *
3413  * @see workshop_renderer::render_workshop_example_submission()
3414  */
3415 class workshop_example_submission extends workshop_example_submission_summary implements renderable {
3417     /** @var string */
3418     public $content;
3419     /** @var int */
3420     public $contentformat;
3421     /** @var bool */
3422     public $contenttrust;
3423     /** @var array */
3424     public $attachment;
3426     /**
3427      * @var array of columns from workshop_submissions that are assigned as properties
3428      * of instances of this class
3429      */
3430     protected $fields = array('id', 'title', 'content', 'contentformat', 'contenttrust', 'attachment');
3434 /**
3435  * Common base class for assessments rendering
3436  *
3437  * Subclasses of this class convert raw assessment record from
3438  * workshop_assessments table (as returned by {@see workshop::get_assessment_by_id()}
3439  * for example) into renderable objects.
3440  */
3441 abstract class workshop_assessment_base {
3443     /** @var string the optional title of the assessment */
3444     public $title = '';
3446     /** @var workshop_assessment_form $form as returned by {@link workshop_strategy::get_assessment_form()} */
3447     public $form;
3449     /** @var moodle_url */
3450     public $url;
3452     /** @var float|null the real received grade */
3453     public $realgrade = null;
3455     /** @var float the real maximum grade */
3456     public $maxgrade;
3458     /** @var stdClass|null reviewer user info */
3459     public $reviewer = null;
3461     /** @var stdClass|null assessed submission's author user info */
3462     public $author = null;
3464     /** @var array of actions */
3465     public $actions = array();
3467     /* @var array of columns that are assigned as properties */
3468     protected $fields = array();
3470     /** @var workshop */
3471     protected $workshop;
3473     /**
3474      * Copies the properties of the given database record into properties of $this instance
3475      *
3476      * The $options keys are: showreviewer, showauthor
3477      * @param workshop $workshop
3478      * @param stdClass $assessment full record
3479      * @param array $options additional properties
3480      */
3481     public function __construct(workshop $workshop, stdClass $record, array $options = array()) {
3483         $this->workshop = $workshop;
3484         $this->validate_raw_record($record);
3486         foreach ($this->fields as $field) {
3487             if (!property_exists($record, $field)) {
3488                 throw new coding_exception('Assessment record must provide public property ' . $field);
3489             }
3490             if (!property_exists($this, $field)) {
3491                 throw new coding_exception('Renderable component must accept public property ' . $field);
3492             }
3493             $this->{$field} = $record->{$field};
3494         }
3496         if (!empty($options['showreviewer'])) {
3497             $this->reviewer = user_picture::unalias($record, null, 'revieweridx', 'reviewer');
3498         }
3500         if (!empty($options['showauthor'])) {
3501             $this->author = user_picture::unalias($record, null, 'authorid', 'author');
3502         }
3503     }
3505     /**
3506      * Adds a new action
3507      *
3508      * @param moodle_url $url action URL
3509      * @param string $label action label
3510      * @param string $method get|post
3511      */
3512     public function add_action(moodle_url $url, $label, $method = 'get') {
3514         $action = new stdClass();
3515         $action->url = $url;
3516         $action->label = $label;
3517         $action->method = $method;
3519         $this->actions[] = $action;
3520     }
3522     /**
3523      * Makes sure that we can cook the renderable component from the passed raw database record
3524      *
3525      * @param stdClass $assessment full assessment record
3526      * @throws coding_exception if the caller passed unexpected data
3527      */
3528     protected function validate_raw_record(stdClass $record) {
3529         // nothing to do here
3530     }
3534 /**
3535  * Represents a rendarable full assessment
3536  */
3537 class workshop_assessment extends workshop_assessment_base implements renderable {
3539     /** @var int */
3540     public $id;
3542     /** @var int */
3543     public $submissionid;
3545     /** @var int */
3546     public $weight;
3548     /** @var int */
3549     public $timecreated;
3551     /** @var int */
3552     public $timemodified;
3554     /** @var float */
3555     public $grade;
3557     /** @var float */
3558     public $gradinggrade;
3560     /** @var float */
3561     public $gradinggradeover;
3563     /** @var string */
3564     public $feedbackauthor;
3566     /** @var int */
3567     public $feedbackauthorformat;
3569     /** @var int */
3570     public $feedbackauthorattachment;
3572     /** @var array */
3573     protected $fields = array('id', 'submissionid', 'weight', 'timecreated',
3574         'timemodified', 'grade', 'gradinggrade', 'gradinggradeover', 'feedbackauthor',
3575         'feedbackauthorformat', 'feedbackauthorattachment');
3577     /**
3578      * Format the overall feedback text content
3579      *
3580      * False is returned if the overall feedback feature is disabled. Null is returned
3581      * if the overall feedback content has not been found. Otherwise, string with
3582      * formatted feedback text is returned.
3583      *
3584      * @return string|bool|null
3585      */
3586     public function get_overall_feedback_content() {
3588         if ($this->workshop->overallfeedbackmode == 0) {
3589             return false;
3590         }
3592         if (trim($this->feedbackauthor) === '') {
3593             return null;
3594         }
3596         $content = file_rewrite_pluginfile_urls($this->feedbackauthor, 'pluginfile.php', $this->workshop->context->id,
3597             'mod_workshop', 'overallfeedback_content', $this->id);
3598         $content = format_text($content, $this->feedbackauthorformat,
3599             array('overflowdiv' => true, 'context' => $this->workshop->context));
3601         return $content;
3602     }
3604     /**
3605      * Prepares the list of overall feedback attachments
3606      *
3607      * Returns false if overall feedback attachments are not allowed. Otherwise returns
3608      * list of attachments (may be empty).
3609      *
3610      * @return bool|array of stdClass
3611      */
3612     public function get_overall_feedback_attachments() {
3614         if ($this->workshop->overallfeedbackmode == 0) {
3615             return false;
3616         }
3618         if ($this->workshop->overallfeedbackfiles == 0) {
3619             return false;
3620         }
3622         if (empty($this->feedbackauthorattachment)) {
3623             return array();
3624         }
3626         $attachments = array();
3627         $fs = get_file_storage();
3628         $files = $fs->get_area_files($this->workshop->context->id, 'mod_workshop', 'overallfeedback_attachment', $this->id);
3629         foreach ($files as $file) {
3630             if ($file->is_directory()) {
3631                 continue;
3632             }
3633             $filepath = $file->get_filepath();
3634             $filename = $file->get_filename();
3635             $fileurl = moodle_url::make_pluginfile_url($this->workshop->context->id, 'mod_workshop',
3636                 'overallfeedback_attachment', $this->id, $filepath, $filename, true);
3637             $previewurl = new moodle_url(moodle_url::make_pluginfile_url($this->workshop->context->id, 'mod_workshop',
3638                 'overallfeedback_attachment', $this->id, $filepath, $filename, false), array('preview' => 'bigthumb'));
3639             $attachments[] = (object)array(
3640                 'filepath' => $filepath,
3641                 'filename' => $filename,
3642                 'fileurl' => $fileurl,
3643                 'previewurl' => $previewurl,
3644                 'mimetype' => $file->get_mimetype(),
3646             );
3647         }
3649         return $attachments;
3650     }
3654 /**
3655  * Represents a renderable training assessment of an example submission
3656  */
3657 class workshop_example_assessment extends workshop_assessment implements renderable {
3659     /**
3660      * @see parent::validate_raw_record()
3661      */
3662     protected function validate_raw_record(stdClass $record) {
3663         if ($record->weight != 0) {
3664             throw new coding_exception('Invalid weight of example submission assessment');
3665         }
3666         parent::validate_raw_record($record);
3667     }
3671 /**
3672  * Represents a renderable reference assessment of an example submission
3673  */
3674 class workshop_example_reference_assessment extends workshop_assessment implements renderable {
3676     /**
3677      * @see parent::validate_raw_record()
3678      */
3679     protected function validate_raw_record(stdClass $record) {
3680         if ($record->weight != 1) {
3681             throw new coding_exception('Invalid weight of the reference example submission assessment');
3682         }
3683         parent::validate_raw_record($record);
3684     }
3688 /**
3689  * Renderable message to be displayed to the user
3690  *
3691  * Message can contain an optional action link with a label that is supposed to be rendered
3692  * as a button or a link.
3693  *
3694  * @see workshop::renderer::render_workshop_message()
3695  */
3696 class workshop_message implements renderable {
3698     const TYPE_INFO     = 10;
3699     const TYPE_OK       = 20;
3700     const TYPE_ERROR    = 30;
3702     /** @var string */
3703     protected $text = '';
3704     /** @var int */
3705     protected $type = self::TYPE_INFO;
3706     /** @var moodle_url */
3707     protected $actionurl = null;
3708     /** @var string */
3709     protected $actionlabel = '';
3711     /**
3712      * @param string $text short text to be displayed
3713      * @param string $type optional message type info|ok|error
3714      */
3715     public function __construct($text = null, $type = self::TYPE_INFO) {
3716         $this->set_text($text);
3717         $this->set_type($type);
3718     }
3720     /**
3721      * Sets the message text
3722      *
3723      * @param string $text short text to be displayed
3724      */
3725     public function set_text($text) {
3726         $this->text = $text;
3727     }
3729     /**
3730      * Sets the message type
3731      *
3732      * @param int $type
3733      */
3734     public function set_type($type = self::TYPE_INFO) {
3735         if (in_array($type, array(self::TYPE_OK, self::TYPE_ERROR, self::TYPE_INFO))) {
3736             $this->type = $type;
3737         } else {
3738             throw new coding_exception('Unknown message type.');
3739         }
3740     }
3742     /**
3743      * Sets the optional message action
3744      *
3745      * @param moodle_url $url to follow on action
3746      * @param string $label action label
3747      */
3748     public function set_action(moodle_url $url, $label) {
3749         $this->actionurl    = $url;
3750         $this->actionlabel  = $label;
3751     }
3753     /**
3754      * Returns message text with HTML tags quoted
3755      *
3756      * @return string
3757      */
3758     public function get_message() {
3759         return s($this->text);
3760     }
3762     /**
3763      * Returns message type
3764      *
3765      * @return int
3766      */
3767     public function get_type() {
3768         return $this->type;
3769     }
3771     /**
3772      * Returns action URL
3773      *
3774      * @return moodle_url|null
3775      */
3776     public function get_action_url() {
3777         return $this->actionurl;
3778     }
3780     /**
3781      * Returns action label
3782      *
3783      * @return string
3784      */
3785     public function get_action_label() {
3786         return $this->actionlabel;
3787     }
3791 /**
3792  * Renderable component containing all the data needed to display the grading report
3793  */
3794 class workshop_grading_report implements renderable {
3796     /** @var stdClass returned by {@see workshop::prepare_grading_report_data()} */
3797     protected $data;
3798     /** @var stdClass rendering options */
3799     protected $options;
3801     /**
3802      * Grades in $data must be already rounded to the set number of decimals or must be null
3803      * (in which later case, the [mod_workshop,nullgrade] string shall be displayed)
3804      *
3805      * @param stdClass $data prepared by {@link workshop::prepare_grading_report_data()}
3806      * @param stdClass $options display options (showauthornames, showreviewernames, sortby, sorthow, showsubmissiongrade, showgradinggrade)
3807      */
3808     public function __construct(stdClass $data, stdClass $options) {
3809         $this->data     = $data;
3810         $this->options  = $options;
3811     }
3813     /**
3814      * @return stdClass grading report data
3815      */
3816     public function get_data() {
3817         return $this->data;
3818     }
3820     /**
3821      * @return stdClass rendering options
3822      */
3823     public function get_options() {
3824         return $this->options;
3825     }
3829 /**
3830  * Base class for renderable feedback for author and feedback for reviewer
3831  */
3832 abstract class workshop_feedback {
3834     /** @var stdClass the user info */
3835     protected $provider = null;
3837     /** @var string the feedback text */
3838     protected $content = null;
3840     /** @var int format of the feedback text */
3841     protected $format = null;
3843     /**
3844      * @return stdClass the user info
3845      */
3846     public function get_provider() {
3848         if (is_null($this->provider)) {
3849             throw new coding_exception('Feedback provider not set');
3850         }
3852         return $this->provider;
3853     }
3855     /**
3856      * @return string the feedback text
3857      */
3858     public function get_content() {
3860         if (is_null($this->content)) {
3861             throw new coding_exception('Feedback content not set');
3862         }
3864         return $this->content;
3865     }
3867     /**
3868      * @return int format of the feedback text
3869      */
3870     public function get_format() {
3872         if (is_null($this->format)) {
3873             throw new coding_exception('Feedback text format not set');
3874         }
3876         return $this->format;
3877     }
3881 /**
3882  * Renderable feedback for the author of submission
3883  */
3884 class workshop_feedback_author extends workshop_feedback implements renderable {
3886     /**
3887      * Extracts feedback from the given submission record
3888      *
3889      * @param stdClass $submission record as returned by {@see self::get_submission_by_id()}
3890      */
3891     public function __construct(stdClass $submission) {
3893         $this->provider = user_picture::unalias($submission, null, 'gradeoverbyx', 'gradeoverby');
3894         $this->content  = $submission->feedbackauthor;
3895         $this->format   = $submission->feedbackauthorformat;
3896     }
3900 /**
3901  * Renderable feedback for the reviewer
3902  */
3903 class workshop_feedback_reviewer extends workshop_feedback implements renderable {
3905     /**
3906      * Extracts feedback from the given assessment record
3907      *
3908      * @param stdClass $assessment record as returned by eg {@see self::get_assessment_by_id()}
3909      */
3910     public function __construct(stdClass $assessment) {
3912         $this->provider = user_picture::unalias($assessment, null, 'gradinggradeoverbyx', 'overby');
3913         $this->content  = $assessment->feedbackreviewer;
3914         $this->format   = $assessment->feedbackreviewerformat;
3915     }
3919 /**
3920  * Holds the final grades for the activity as are stored in the gradebook
3921  */
3922 class workshop_final_grades implements renderable {
3924     /** @var object the info from the gradebook about the grade for submission */
3925     public $submissiongrade = null;
3927     /** @var object the infor from the gradebook about the grade for assessment */
3928     public $assessmentgrade = null;