MDL-57961 course: change wording of module availability
[moodle.git] / mod / survey / lib.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  * @package   mod_survey
20  * @copyright 1999 onwards Martin Dougiamas  {@link http://moodle.com}
21  * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
22  */
24 /**
25  * Graph size
26  * @global int $SURVEY_GHEIGHT
27  */
28 global $SURVEY_GHEIGHT;
29 $SURVEY_GHEIGHT = 500;
30 /**
31  * Graph size
32  * @global int $SURVEY_GWIDTH
33  */
34 global $SURVEY_GWIDTH;
35 $SURVEY_GWIDTH  = 900;
36 /**
37  * Question Type
38  * @global array $SURVEY_QTYPE
39  */
40 global $SURVEY_QTYPE;
41 $SURVEY_QTYPE = array (
42         "-3" => "Virtual Actual and Preferred",
43         "-2" => "Virtual Preferred",
44         "-1" => "Virtual Actual",
45          "0" => "Text",
46          "1" => "Actual",
47          "2" => "Preferred",
48          "3" => "Actual and Preferred",
49         );
52 define("SURVEY_COLLES_ACTUAL",           "1");
53 define("SURVEY_COLLES_PREFERRED",        "2");
54 define("SURVEY_COLLES_PREFERRED_ACTUAL", "3");
55 define("SURVEY_ATTLS",                   "4");
56 define("SURVEY_CIQ",                     "5");
59 // STANDARD FUNCTIONS ////////////////////////////////////////////////////////
60 /**
61  * Given an object containing all the necessary data,
62  * (defined by the form in mod_form.php) this function
63  * will create a new instance and return the id number
64  * of the new instance.
65  *
66  * @global object
67  * @param object $survey
68  * @return int|bool
69  */
70 function survey_add_instance($survey) {
71     global $DB;
73     if (!$template = $DB->get_record("survey", array("id"=>$survey->template))) {
74         return 0;
75     }
77     $survey->questions    = $template->questions;
78     $survey->timecreated  = time();
79     $survey->timemodified = $survey->timecreated;
81     return $DB->insert_record("survey", $survey);
83 }
85 /**
86  * Given an object containing all the necessary data,
87  * (defined by the form in mod_form.php) this function
88  * will update an existing instance with new data.
89  *
90  * @global object
91  * @param object $survey
92  * @return bool
93  */
94 function survey_update_instance($survey) {
95     global $DB;
97     if (!$template = $DB->get_record("survey", array("id"=>$survey->template))) {
98         return 0;
99     }
101     $survey->id           = $survey->instance;
102     $survey->questions    = $template->questions;
103     $survey->timemodified = time();
105     return $DB->update_record("survey", $survey);
108 /**
109  * Given an ID of an instance of this module,
110  * this function will permanently delete the instance
111  * and any data that depends on it.
112  *
113  * @global object
114  * @param int $id
115  * @return bool
116  */
117 function survey_delete_instance($id) {
118     global $DB;
120     if (! $survey = $DB->get_record("survey", array("id"=>$id))) {
121         return false;
122     }
124     $result = true;
126     if (! $DB->delete_records("survey_analysis", array("survey"=>$survey->id))) {
127         $result = false;
128     }
130     if (! $DB->delete_records("survey_answers", array("survey"=>$survey->id))) {
131         $result = false;
132     }
134     if (! $DB->delete_records("survey", array("id"=>$survey->id))) {
135         $result = false;
136     }
138     return $result;
141 /**
142  * @global object
143  * @param object $course
144  * @param object $user
145  * @param object $mod
146  * @param object $survey
147  * @return $result
148  */
149 function survey_user_outline($course, $user, $mod, $survey) {
150     global $DB;
152     if ($answers = $DB->get_records("survey_answers", array('survey'=>$survey->id, 'userid'=>$user->id))) {
153         $lastanswer = array_pop($answers);
155         $result = new stdClass();
156         $result->info = get_string("done", "survey");
157         $result->time = $lastanswer->time;
158         return $result;
159     }
160     return NULL;
163 /**
164  * @global stdObject
165  * @global object
166  * @uses SURVEY_CIQ
167  * @param object $course
168  * @param object $user
169  * @param object $mod
170  * @param object $survey
171  */
172 function survey_user_complete($course, $user, $mod, $survey) {
173     global $CFG, $DB, $OUTPUT;
175     if (survey_already_done($survey->id, $user->id)) {
176         if ($survey->template == SURVEY_CIQ) { // print out answers for critical incidents
177             $table = new html_table();
178             $table->align = array("left", "left");
180             $questions = $DB->get_records_list("survey_questions", "id", explode(',', $survey->questions));
181             $questionorder = explode(",", $survey->questions);
183             foreach ($questionorder as $key=>$val) {
184                 $question = $questions[$val];
185                 $questiontext = get_string($question->shorttext, "survey");
187                 if ($answer = survey_get_user_answer($survey->id, $question->id, $user->id)) {
188                     $answertext = "$answer->answer1";
189                 } else {
190                     $answertext = "No answer";
191                 }
192                 $table->data[] = array("<b>$questiontext</b>", s($answertext));
193             }
194             echo html_writer::table($table);
196         } else {
198             survey_print_graph("id=$mod->id&amp;sid=$user->id&amp;type=student.png");
199         }
201     } else {
202         print_string("notdone", "survey");
203     }
206 /**
207  * @global stdClass
208  * @global object
209  * @param object $course
210  * @param mixed $viewfullnames
211  * @param int $timestamp
212  * @return bool
213  */
214 function survey_print_recent_activity($course, $viewfullnames, $timestart) {
215     global $CFG, $DB, $OUTPUT;
217     $modinfo = get_fast_modinfo($course);
218     $ids = array();
219     foreach ($modinfo->cms as $cm) {
220         if ($cm->modname != 'survey') {
221             continue;
222         }
223         if (!$cm->uservisible) {
224             continue;
225         }
226         $ids[$cm->instance] = $cm->instance;
227     }
229     if (!$ids) {
230         return false;
231     }
233     $slist = implode(',', $ids); // there should not be hundreds of glossaries in one course, right?
235     $allusernames = user_picture::fields('u');
236     $rs = $DB->get_recordset_sql("SELECT sa.userid, sa.survey, MAX(sa.time) AS time,
237                                          $allusernames
238                                     FROM {survey_answers} sa
239                                     JOIN {user} u ON u.id = sa.userid
240                                    WHERE sa.survey IN ($slist) AND sa.time > ?
241                                 GROUP BY sa.userid, sa.survey, $allusernames
242                                 ORDER BY time ASC", array($timestart));
243     if (!$rs->valid()) {
244         $rs->close(); // Not going to iterate (but exit), close rs
245         return false;
246     }
248     $surveys = array();
250     foreach ($rs as $survey) {
251         $cm = $modinfo->instances['survey'][$survey->survey];
252         $survey->name = $cm->name;
253         $survey->cmid = $cm->id;
254         $surveys[] = $survey;
255     }
256     $rs->close();
258     if (!$surveys) {
259         return false;
260     }
262     echo $OUTPUT->heading(get_string('newsurveyresponses', 'survey').':', 3);
263     foreach ($surveys as $survey) {
264         $url = $CFG->wwwroot.'/mod/survey/view.php?id='.$survey->cmid;
265         print_recent_activity_note($survey->time, $survey, $survey->name, $url, false, $viewfullnames);
266     }
268     return true;
271 // SQL FUNCTIONS ////////////////////////////////////////////////////////
273 /**
274  * @global object
275  * @param sting $log
276  * @return array
277  */
278 function survey_log_info($log) {
279     global $DB;
280     return $DB->get_record_sql("SELECT s.name, u.firstname, u.lastname, u.picture
281                                   FROM {survey} s, {user} u
282                                  WHERE s.id = ?  AND u.id = ?", array($log->info, $log->userid));
285 /**
286  * @global object
287  * @param int $surveyid
288  * @param int $groupid
289  * @param int $groupingid
290  * @return array
291  */
292 function survey_get_responses($surveyid, $groupid, $groupingid) {
293     global $DB;
295     $params = array('surveyid'=>$surveyid, 'groupid'=>$groupid, 'groupingid'=>$groupingid);
297     if ($groupid) {
298         $groupsjoin = "JOIN {groups_members} gm ON u.id = gm.userid AND gm.groupid = :groupid ";
300     } else if ($groupingid) {
301         $groupsjoin = "JOIN {groups_members} gm ON u.id = gm.userid
302                        JOIN {groupings_groups} gg ON gm.groupid = gg.groupid AND gg.groupingid = :groupingid ";
303     } else {
304         $groupsjoin = "";
305     }
307     $userfields = user_picture::fields('u');
308     return $DB->get_records_sql("SELECT $userfields, MAX(a.time) as time
309                                    FROM {survey_answers} a
310                                    JOIN {user} u ON a.userid = u.id
311                             $groupsjoin
312                                   WHERE a.survey = :surveyid
313                                GROUP BY $userfields
314                                ORDER BY time ASC", $params);
317 /**
318  * @global object
319  * @param int $survey
320  * @param int $user
321  * @return array
322  */
323 function survey_get_analysis($survey, $user) {
324     global $DB;
326     return $DB->get_record_sql("SELECT notes
327                                   FROM {survey_analysis}
328                                  WHERE survey=? AND userid=?", array($survey, $user));
331 /**
332  * @global object
333  * @param int $survey
334  * @param int $user
335  * @param string $notes
336  */
337 function survey_update_analysis($survey, $user, $notes) {
338     global $DB;
340     return $DB->execute("UPDATE {survey_analysis}
341                             SET notes=?
342                           WHERE survey=?
343                             AND userid=?", array($notes, $survey, $user));
346 /**
347  * @global object
348  * @param int $surveyid
349  * @param int $groupid
350  * @param string $sort
351  * @return array
352  */
353 function survey_get_user_answers($surveyid, $questionid, $groupid, $sort="sa.answer1,sa.answer2 ASC") {
354     global $DB;
356     $params = array('surveyid'=>$surveyid, 'questionid'=>$questionid);
358     if ($groupid) {
359         $groupfrom = ', {groups_members} gm';
360         $groupsql  = 'AND gm.groupid = :groupid AND u.id = gm.userid';
361         $params['groupid'] = $groupid;
362     } else {
363         $groupfrom = '';
364         $groupsql  = '';
365     }
367     $userfields = user_picture::fields('u');
368     return $DB->get_records_sql("SELECT sa.*, $userfields
369                                    FROM {survey_answers} sa,  {user} u $groupfrom
370                                   WHERE sa.survey = :surveyid
371                                         AND sa.question = :questionid
372                                         AND u.id = sa.userid $groupsql
373                                ORDER BY $sort", $params);
376 /**
377  * @global object
378  * @param int $surveyid
379  * @param int $questionid
380  * @param int $userid
381  * @return array
382  */
383 function survey_get_user_answer($surveyid, $questionid, $userid) {
384     global $DB;
386     return $DB->get_record_sql("SELECT sa.*
387                                   FROM {survey_answers} sa
388                                  WHERE sa.survey = ?
389                                        AND sa.question = ?
390                                        AND sa.userid = ?", array($surveyid, $questionid, $userid));
393 // MODULE FUNCTIONS ////////////////////////////////////////////////////////
394 /**
395  * @global object
396  * @param int $survey
397  * @param int $user
398  * @param string $notes
399  * @return bool|int
400  */
401 function survey_add_analysis($survey, $user, $notes) {
402     global $DB;
404     $record = new stdClass();
405     $record->survey = $survey;
406     $record->userid = $user;
407     $record->notes = $notes;
409     return $DB->insert_record("survey_analysis", $record, false);
411 /**
412  * @global object
413  * @param int $survey
414  * @param int $user
415  * @return bool
416  */
417 function survey_already_done($survey, $user) {
418     global $DB;
420     return $DB->record_exists("survey_answers", array("survey"=>$survey, "userid"=>$user));
422 /**
423  * @param int $surveyid
424  * @param int $groupid
425  * @param int $groupingid
426  * @return int
427  */
428 function survey_count_responses($surveyid, $groupid, $groupingid) {
429     if ($responses = survey_get_responses($surveyid, $groupid, $groupingid)) {
430         return count($responses);
431     } else {
432         return 0;
433     }
436 /**
437  * @param int $cmid
438  * @param array $results
439  * @param int $courseid
440  */
441 function survey_print_all_responses($cmid, $results, $courseid) {
442     global $OUTPUT;
443     $table = new html_table();
444     $table->head  = array ("", get_string("name"),  get_string("time"));
445     $table->align = array ("", "left", "left");
446     $table->size = array (35, "", "" );
448     foreach ($results as $a) {
449         $table->data[] = array($OUTPUT->user_picture($a, array('courseid'=>$courseid)),
450                html_writer::link("report.php?action=student&student=$a->id&id=$cmid", fullname($a)),
451                userdate($a->time));
452     }
454     echo html_writer::table($table);
457 /**
458  * @global object
459  * @param int $templateid
460  * @return string
461  */
462 function survey_get_template_name($templateid) {
463     global $DB;
465     if ($templateid) {
466         if ($ss = $DB->get_record("surveys", array("id"=>$templateid))) {
467             return $ss->name;
468         }
469     } else {
470         return "";
471     }
475 /**
476  * @param string $name
477  * @param array $numwords
478  * @return string
479  */
480 function survey_shorten_name ($name, $numwords) {
481     $words = explode(" ", $name);
482     $output = '';
483     for ($i=0; $i < $numwords; $i++) {
484         $output .= $words[$i]." ";
485     }
486     return $output;
489 /**
490  * @todo Check this function
491  *
492  * @global object
493  * @global object
494  * @global int
495  * @global void This is never defined
496  * @global object This is defined twice?
497  * @param object $question
498  */
499 function survey_print_multi($question) {
500     global $USER, $DB, $qnum, $DB, $OUTPUT; //TODO: this is sloppy globals abuse
502     $stripreferthat = get_string("ipreferthat", "survey");
503     $strifoundthat = get_string("ifoundthat", "survey");
504     $strdefault    = get_string('notyetanswered', 'survey');
505     $strresponses  = get_string('responses', 'survey');
507     echo $OUTPUT->heading($question->text, 3);
508     echo "\n<table width=\"90%\" cellpadding=\"4\" cellspacing=\"1\" border=\"0\" class=\"surveytable\">";
510     $options = explode( ",", $question->options);
511     $numoptions = count($options);
513     // COLLES Actual (which is having questions of type 1) and COLLES Preferred (type 2)
514     // expect just one answer per question. COLLES Actual and Preferred (type 3) expects
515     // two answers per question. ATTLS (having a single question of type 1) expects one
516     // answer per question. CIQ is not using multiquestions (i.e. a question with subquestions).
517     // Note that the type of subquestions does not really matter, it's the type of the
518     // question itself that determines everything.
519     $oneanswer = ($question->type == 1 || $question->type == 2) ? true : false;
521     // COLLES Preferred (having questions of type 2) will use the radio elements with the name
522     // like qP1, qP2 etc. COLLES Actual and ATTLS have radios like q1, q2 etc.
523     if ($question->type == 2) {
524         $P = "P";
525     } else {
526         $P = "";
527     }
529     echo "<tr class=\"smalltext\"><th scope=\"row\">$strresponses</th>";
530     echo "<th scope=\"col\" class=\"hresponse\">". get_string('notyetanswered', 'survey'). "</th>";
531     while (list ($key, $val) = each ($options)) {
532         echo "<th scope=\"col\" class=\"hresponse\">$val</th>\n";
533     }
534     echo "</tr>\n";
536     echo "<tr><th scope=\"col\" colspan=\"7\">$question->intro</th></tr>\n";
538     $subquestions = survey_get_subquestions($question);
540     foreach ($subquestions as $q) {
541         $qnum++;
542         if ($oneanswer) {
543             $rowclass = survey_question_rowclass($qnum);
544         } else {
545             $rowclass = survey_question_rowclass(round($qnum / 2));
546         }
547         if ($q->text) {
548             $q->text = get_string($q->text, "survey");
549         }
551         echo "<tr class=\"$rowclass rblock\">";
552         if ($oneanswer) {
553             echo "<th scope=\"row\" class=\"optioncell\">";
554             echo "<b class=\"qnumtopcell\">$qnum</b> &nbsp; ";
555             echo $q->text ."</th>\n";
557             $default = get_accesshide($strdefault);
558             echo "<td class=\"whitecell\"><label for=\"q$P$q->id\"><input type=\"radio\" name=\"q$P$q->id\" id=\"q$P" . $q->id . "_D\" value=\"0\" checked=\"checked\" data-survey-default=\"true\" />$default</label></td>";
560             for ($i=1;$i<=$numoptions;$i++) {
561                 $hiddentext = get_accesshide($options[$i-1]);
562                 $id = "q$P" . $q->id . "_$i";
563                 echo "<td><label for=\"$id\"><input type=\"radio\" name=\"q$P$q->id\" id=\"$id\" value=\"$i\" />$hiddentext</label></td>";
564             }
565         } else {
566             echo "<th scope=\"row\" class=\"optioncell\">";
567             echo "<b class=\"qnumtopcell\">$qnum</b> &nbsp; ";
568             $qnum++;
569             echo "<span class=\"preferthat\">$stripreferthat</span> &nbsp; ";
570             echo "<span class=\"option\">$q->text</span></th>\n";
572             $default = get_accesshide($strdefault);
573             echo '<td class="whitecell"><label for="qP'.$q->id.'"><input type="radio" name="qP'.$q->id.'" id="qP'.$q->id.'" value="0" checked="checked" data-survey-default="true" />'.$default.'</label></td>';
576             for ($i=1;$i<=$numoptions;$i++) {
577                 $hiddentext = get_accesshide($options[$i-1]);
578                 $id = "qP" . $q->id . "_$i";
579                 echo "<td><label for=\"$id\"><input type=\"radio\" name=\"qP$q->id\" id=\"$id\" value=\"$i\" />$hiddentext</label></td>";
580             }
581             echo "</tr>";
583             echo "<tr class=\"$rowclass rblock\">";
584             echo "<th scope=\"row\" class=\"optioncell\">";
585             echo "<b class=\"qnumtopcell\">$qnum</b> &nbsp; ";
586             echo "<span class=\"foundthat\">$strifoundthat</span> &nbsp; ";
587             echo "<span class=\"option\">$q->text</span></th>\n";
589             $default = get_accesshide($strdefault);
590             echo '<td class="whitecell"><label for="q'. $q->id .'"><input type="radio" name="q'.$q->id. '" id="q'. $q->id .'" value="0" checked="checked" data-survey-default="true" />'.$default.'</label></td>';
592             for ($i=1;$i<=$numoptions;$i++) {
593                 $hiddentext = get_accesshide($options[$i-1]);
594                 $id = "q" . $q->id . "_$i";
595                 echo "<td><label for=\"$id\"><input type=\"radio\" name=\"q$q->id\" id=\"$id\" value=\"$i\" />$hiddentext</label></td>";
596             }
597         }
598         echo "</tr>\n";
599     }
600     echo "</table>";
604 /**
605  * @global object
606  * @global int
607  * @param object $question
608  */
609 function survey_print_single($question) {
610     global $DB, $qnum, $OUTPUT;
612     $rowclass = survey_question_rowclass(0);
614     $qnum++;
616     echo "<br />\n";
617     echo "<table width=\"90%\" cellpadding=\"4\" cellspacing=\"0\">\n";
618     echo "<tr class=\"$rowclass\">";
619     echo "<th scope=\"row\" class=\"optioncell\"><label for=\"q$question->id\"><b class=\"qnumtopcell\">$qnum</b> &nbsp; ";
620     echo "<span class=\"questioncell\">$question->text</span></label></th>\n";
621     echo "<td class=\"questioncell smalltext\">\n";
624     if ($question->type == 0) {           // Plain text field
625         echo "<textarea rows=\"3\" cols=\"30\" class=\"form-control\" name=\"q$question->id\" id=\"q$question->id\">$question->options</textarea>";
627     } else if ($question->type > 0) {     // Choose one of a number
628         $strchoose = get_string("choose");
629         echo "<select name=\"q$question->id\" id=\"q$question->id\" class=\"custom-select\">";
630         echo "<option value=\"0\" selected=\"selected\">$strchoose...</option>";
631         $options = explode( ",", $question->options);
632         foreach ($options as $key => $val) {
633             $key++;
634             echo "<option value=\"$key\">$val</option>";
635         }
636         echo "</select>";
638     } else if ($question->type < 0) {     // Choose several of a number
639         $options = explode( ",", $question->options);
640         echo $OUTPUT->notification("This question type not supported yet");
641     }
643     echo "</td></tr></table>";
647 /**
648  *
649  * @param int $qnum
650  * @return string
651  */
652 function survey_question_rowclass($qnum) {
654     if ($qnum) {
655         return $qnum % 2 ? 'r0' : 'r1';
656     } else {
657         return 'r0';
658     }
661 /**
662  * @global object
663  * @global int
664  * @global int
665  * @param string $url
666  */
667 function survey_print_graph($url) {
668     global $CFG, $SURVEY_GHEIGHT, $SURVEY_GWIDTH;
670     echo "<img class='resultgraph' height=\"$SURVEY_GHEIGHT\" width=\"$SURVEY_GWIDTH\"".
671          " src=\"$CFG->wwwroot/mod/survey/graph.php?$url\" alt=\"".get_string("surveygraph", "survey")."\" />";
674 /**
675  * List the actions that correspond to a view of this module.
676  * This is used by the participation report.
677  *
678  * Note: This is not used by new logging system. Event with
679  *       crud = 'r' and edulevel = LEVEL_PARTICIPATING will
680  *       be considered as view action.
681  *
682  * @return array
683  */
684 function survey_get_view_actions() {
685     return array('download','view all','view form','view graph','view report');
688 /**
689  * List the actions that correspond to a post of this module.
690  * This is used by the participation report.
691  *
692  * Note: This is not used by new logging system. Event with
693  *       crud = ('c' || 'u' || 'd') and edulevel = LEVEL_PARTICIPATING
694  *       will be considered as post action.
695  *
696  * @return array
697  */
698 function survey_get_post_actions() {
699     return array('submit');
703 /**
704  * Implementation of the function for printing the form elements that control
705  * whether the course reset functionality affects the survey.
706  *
707  * @param object $mform form passed by reference
708  */
709 function survey_reset_course_form_definition(&$mform) {
710     $mform->addElement('header', 'surveyheader', get_string('modulenameplural', 'survey'));
711     $mform->addElement('checkbox', 'reset_survey_answers', get_string('deleteallanswers','survey'));
712     $mform->addElement('checkbox', 'reset_survey_analysis', get_string('deleteanalysis','survey'));
713     $mform->disabledIf('reset_survey_analysis', 'reset_survey_answers', 'checked');
716 /**
717  * Course reset form defaults.
718  * @return array
719  */
720 function survey_reset_course_form_defaults($course) {
721     return array('reset_survey_answers'=>1, 'reset_survey_analysis'=>1);
724 /**
725  * Actual implementation of the reset course functionality, delete all the
726  * survey responses for course $data->courseid.
727  *
728  * @global object
729  * @param $data the data submitted from the reset course.
730  * @return array status array
731  */
732 function survey_reset_userdata($data) {
733     global $DB;
735     $componentstr = get_string('modulenameplural', 'survey');
736     $status = array();
738     $surveyssql = "SELECT ch.id
739                      FROM {survey} ch
740                     WHERE ch.course=?";
741     $params = array($data->courseid);
743     if (!empty($data->reset_survey_answers)) {
744         $DB->delete_records_select('survey_answers', "survey IN ($surveyssql)", $params);
745         $DB->delete_records_select('survey_analysis', "survey IN ($surveyssql)", $params);
746         $status[] = array('component'=>$componentstr, 'item'=>get_string('deleteallanswers', 'survey'), 'error'=>false);
747     }
749     if (!empty($data->reset_survey_analysis)) {
750         $DB->delete_records_select('survey_analysis', "survey IN ($surveyssql)", $params);
751         $status[] = array('component'=>$componentstr, 'item'=>get_string('deleteallanswers', 'survey'), 'error'=>false);
752     }
754     // no date shifting
755     return $status;
758 /**
759  * Returns all other caps used in module
760  *
761  * @return array
762  */
763 function survey_get_extra_capabilities() {
764     return array('moodle/site:accessallgroups');
767 /**
768  * @uses FEATURE_GROUPS
769  * @uses FEATURE_GROUPINGS
770  * @uses FEATURE_MOD_INTRO
771  * @uses FEATURE_COMPLETION_TRACKS_VIEWS
772  * @uses FEATURE_GRADE_HAS_GRADE
773  * @uses FEATURE_GRADE_OUTCOMES
774  * @param string $feature FEATURE_xx constant for requested feature
775  * @return mixed True if module supports feature, false if not, null if doesn't know
776  */
777 function survey_supports($feature) {
778     switch($feature) {
779         case FEATURE_GROUPS:                  return true;
780         case FEATURE_GROUPINGS:               return true;
781         case FEATURE_MOD_INTRO:               return true;
782         case FEATURE_COMPLETION_TRACKS_VIEWS: return true;
783         case FEATURE_COMPLETION_HAS_RULES:    return true;
784         case FEATURE_GRADE_HAS_GRADE:         return false;
785         case FEATURE_GRADE_OUTCOMES:          return false;
786         case FEATURE_BACKUP_MOODLE2:          return true;
787         case FEATURE_SHOW_DESCRIPTION:        return true;
789         default: return null;
790     }
793 /**
794  * This function extends the settings navigation block for the site.
795  *
796  * It is safe to rely on PAGE here as we will only ever be within the module
797  * context when this is called
798  *
799  * @param navigation_node $settings
800  * @param navigation_node $surveynode
801  */
802 function survey_extend_settings_navigation($settings, $surveynode) {
803     global $PAGE;
805     if (has_capability('mod/survey:readresponses', $PAGE->cm->context)) {
806         $responsesnode = $surveynode->add(get_string("responsereports", "survey"));
808         $url = new moodle_url('/mod/survey/report.php', array('id' => $PAGE->cm->id, 'action'=>'summary'));
809         $responsesnode->add(get_string("summary", "survey"), $url);
811         $url = new moodle_url('/mod/survey/report.php', array('id' => $PAGE->cm->id, 'action'=>'scales'));
812         $responsesnode->add(get_string("scales", "survey"), $url);
814         $url = new moodle_url('/mod/survey/report.php', array('id' => $PAGE->cm->id, 'action'=>'questions'));
815         $responsesnode->add(get_string("question", "survey"), $url);
817         $url = new moodle_url('/mod/survey/report.php', array('id' => $PAGE->cm->id, 'action'=>'students'));
818         $responsesnode->add(get_string('participants'), $url);
820         if (has_capability('mod/survey:download', $PAGE->cm->context)) {
821             $url = new moodle_url('/mod/survey/report.php', array('id' => $PAGE->cm->id, 'action'=>'download'));
822             $surveynode->add(get_string('downloadresults', 'survey'), $url);
823         }
824     }
827 /**
828  * Return a list of page types
829  * @param string $pagetype current page type
830  * @param stdClass $parentcontext Block's parent context
831  * @param stdClass $currentcontext Current context of block
832  */
833 function survey_page_type_list($pagetype, $parentcontext, $currentcontext) {
834     $module_pagetype = array('mod-survey-*'=>get_string('page-mod-survey-x', 'survey'));
835     return $module_pagetype;
838 /**
839  * Mark the activity completed (if required) and trigger the course_module_viewed event.
840  *
841  * @param  stdClass $survey     survey object
842  * @param  stdClass $course     course object
843  * @param  stdClass $cm         course module object
844  * @param  stdClass $context    context object
845  * @param  string $viewed       which page viewed
846  * @since Moodle 3.0
847  */
848 function survey_view($survey, $course, $cm, $context, $viewed) {
850     // Trigger course_module_viewed event.
851     $params = array(
852         'context' => $context,
853         'objectid' => $survey->id,
854         'courseid' => $course->id,
855         'other' => array('viewed' => $viewed)
856     );
858     $event = \mod_survey\event\course_module_viewed::create($params);
859     $event->add_record_snapshot('course_modules', $cm);
860     $event->add_record_snapshot('course', $course);
861     $event->add_record_snapshot('survey', $survey);
862     $event->trigger();
864     // Completion.
865     $completion = new completion_info($course);
866     $completion->set_module_viewed($cm);
869 /**
870  * Helper function for ordering a set of questions by the given ids.
871  *
872  * @param  array $questions     array of questions objects
873  * @param  array $questionorder array of questions ids indicating the correct order
874  * @return array                list of questions ordered
875  * @since Moodle 3.0
876  */
877 function survey_order_questions($questions, $questionorder) {
879     $finalquestions = array();
880     foreach ($questionorder as $qid) {
881         $finalquestions[] = $questions[$qid];
882     }
883     return $finalquestions;
886 /**
887  * Translate the question texts and options.
888  *
889  * @param  stdClass $question question object
890  * @return stdClass question object with all the text fields translated
891  * @since Moodle 3.0
892  */
893 function survey_translate_question($question) {
895     if ($question->text) {
896         $question->text = get_string($question->text, "survey");
897     }
899     if ($question->shorttext) {
900         $question->shorttext = get_string($question->shorttext, "survey");
901     }
903     if ($question->intro) {
904         $question->intro = get_string($question->intro, "survey");
905     }
907     if ($question->options) {
908         $question->options = get_string($question->options, "survey");
909     }
910     return $question;
913 /**
914  * Returns the questions for a survey (ordered).
915  *
916  * @param  stdClass $survey survey object
917  * @return array list of questions ordered
918  * @since Moodle 3.0
919  * @throws  moodle_exception
920  */
921 function survey_get_questions($survey) {
922     global $DB;
924     $questionids = explode(',', $survey->questions);
925     if (! $questions = $DB->get_records_list("survey_questions", "id", $questionids)) {
926         throw new moodle_exception('cannotfindquestion', 'survey');
927     }
929     return survey_order_questions($questions, $questionids);
932 /**
933  * Returns subquestions for a given question (ordered).
934  *
935  * @param  stdClass $question questin object
936  * @return array list of subquestions ordered
937  * @since Moodle 3.0
938  */
939 function survey_get_subquestions($question) {
940     global $DB;
942     $questionids = explode(',', $question->multi);
943     $questions = $DB->get_records_list("survey_questions", "id", $questionids);
945     return survey_order_questions($questions, $questionids);
948 /**
949  * Save the answer for the given survey
950  *
951  * @param  stdClass $survey   a survey object
952  * @param  array $answersrawdata the answers to be saved
953  * @param  stdClass $course   a course object (required for trigger the submitted event)
954  * @param  stdClass $context  a context object (required for trigger the submitted event)
955  * @since Moodle 3.0
956  */
957 function survey_save_answers($survey, $answersrawdata, $course, $context) {
958     global $DB, $USER;
960     $answers = array();
962     // Sort through the data and arrange it.
963     // This is necessary because some of the questions may have two answers, eg Question 1 -> 1 and P1.
964     foreach ($answersrawdata as $key => $val) {
965         if ($key != "userid" && $key != "id") {
966             if (substr($key, 0, 1) == "q") {
967                 $key = clean_param(substr($key, 1), PARAM_ALPHANUM);   // Keep everything but the 'q', number or P number.
968             }
969             if (substr($key, 0, 1) == "P") {
970                 $realkey = (int) substr($key, 1);
971                 $answers[$realkey][1] = $val;
972             } else {
973                 $answers[$key][0] = $val;
974             }
975         }
976     }
978     // Now store the data.
979     $timenow = time();
980     $answerstoinsert = array();
981     foreach ($answers as $key => $val) {
982         if ($key != 'sesskey') {
983             $newdata = new stdClass();
984             $newdata->time = $timenow;
985             $newdata->userid = $USER->id;
986             $newdata->survey = $survey->id;
987             $newdata->question = $key;
988             if (!empty($val[0])) {
989                 $newdata->answer1 = $val[0];
990             } else {
991                 $newdata->answer1 = "";
992             }
993             if (!empty($val[1])) {
994                 $newdata->answer2 = $val[1];
995             } else {
996                 $newdata->answer2 = "";
997             }
999             $answerstoinsert[] = $newdata;
1000         }
1001     }
1003     if (!empty($answerstoinsert)) {
1004         $DB->insert_records("survey_answers", $answerstoinsert);
1005     }
1007     // Update completion state.
1008     $cm = get_coursemodule_from_instance('survey', $survey->id, $course->id);
1009     $completion = new completion_info($course);
1010     if (isloggedin() && !isguestuser() && $completion->is_enabled($cm) && $survey->completionsubmit) {
1011         $completion->update_state($cm, COMPLETION_COMPLETE);
1012     }
1014     $params = array(
1015         'context' => $context,
1016         'courseid' => $course->id,
1017         'other' => array('surveyid' => $survey->id)
1018     );
1019     $event = \mod_survey\event\response_submitted::create($params);
1020     $event->trigger();
1023 /**
1024  * Obtains the automatic completion state for this survey based on the condition
1025  * in feedback settings.
1026  *
1027  * @param object $course Course
1028  * @param object $cm Course-module
1029  * @param int $userid User ID
1030  * @param bool $type Type of comparison (or/and; can be used as return value if no conditions)
1031  * @return bool True if completed, false if not, $type if conditions not set.
1032  */
1033 function survey_get_completion_state($course, $cm, $userid, $type) {
1034     global $DB;
1036     // Get survey details.
1037     $survey = $DB->get_record('survey', array('id' => $cm->instance), '*', MUST_EXIST);
1039     // If completion option is enabled, evaluate it and return true/false.
1040     if ($survey->completionsubmit) {
1041         $params = array('userid' => $userid, 'survey' => $survey->id);
1042         return $DB->record_exists('survey_answers', $params);
1043     } else {
1044         // Completion option is not enabled so just return $type.
1045         return $type;
1046     }
1049 /**
1050  * Check if the module has any update that affects the current user since a given time.
1051  *
1052  * @param  cm_info $cm course module data
1053  * @param  int $from the time to check updates from
1054  * @param  array $filter  if we need to check only specific updates
1055  * @return stdClass an object with the different type of areas indicating if they were updated or not
1056  * @since Moodle 3.2
1057  */
1058 function survey_check_updates_since(cm_info $cm, $from, $filter = array()) {
1059     global $DB, $USER;
1061     $updates = new stdClass();
1062     if (!has_capability('mod/survey:participate', $cm->context)) {
1063         return $updates;
1064     }
1065     $updates = course_check_module_updates_since($cm, $from, array(), $filter);
1067     $updates->answers = (object) array('updated' => false);
1068     $select = 'survey = ? AND userid = ? AND time > ?';
1069     $params = array($cm->instance, $USER->id, $from);
1070     $answers = $DB->get_records_select('survey_answers', $select, $params, '', 'id');
1071     if (!empty($answers)) {
1072         $updates->answers->updated = true;
1073         $updates->answers->itemids = array_keys($answers);
1074     }
1076     // Now, teachers should see other students updates.
1077     if (has_capability('mod/survey:readresponses', $cm->context)) {
1078         $select = 'survey = ? AND time > ?';
1079         $params = array($cm->instance, $from);
1081         if (groups_get_activity_groupmode($cm) == SEPARATEGROUPS) {
1082             $groupusers = array_keys(groups_get_activity_shared_group_members($cm));
1083             if (empty($groupusers)) {
1084                 return $updates;
1085             }
1086             list($insql, $inparams) = $DB->get_in_or_equal($groupusers);
1087             $select .= ' AND userid ' . $insql;
1088             $params = array_merge($params, $inparams);
1089         }
1091         $updates->useranswers = (object) array('updated' => false);
1092         $answers = $DB->get_records_select('survey_answers', $select, $params, '', 'id');
1093         if (!empty($answers)) {
1094             $updates->useranswers->updated = true;
1095             $updates->useranswers->itemids = array_keys($answers);
1096         }
1097     }
1098     return $updates;