[Summary view]

Differences Between: [Versions 310 and 402] [Versions 311 and 402] [Versions 39 and 402] [Versions 400 and 402] [Versions 401 and 402]

   1  <?php
   2  // This file is part of Moodle - http://moodle.org/
   3  //
   4  // Moodle is free software: you can redistribute it and/or modify
   5  // it under the terms of the GNU General Public License as published by
   6  // the Free Software Foundation, either version 3 of the License, or
   7  // (at your option) any later version.
   8  //
   9  // Moodle is distributed in the hope that it will be useful,
  10  // but WITHOUT ANY WARRANTY; without even the implied warranty of
  11  // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  12  // GNU General Public License for more details.
  13  //
  14  // You should have received a copy of the GNU General Public License
  15  // along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
  16  
  17  /**
  18   * Survey external API
  19   *
  20   * @package    mod_survey
  21   * @category   external
  22   * @copyright  2015 Juan Leyva <juan@moodle.com>
  23   * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  24   * @since      Moodle 3.0
  25   */
  26  
  27  use core_course\external\helper_for_get_mods_by_courses;
  28  use core_external\external_api;
  29  use core_external\external_function_parameters;
  30  use core_external\external_multiple_structure;
  31  use core_external\external_single_structure;
  32  use core_external\external_value;
  33  use core_external\external_warnings;
  34  use core_external\util;
  35  
  36  defined('MOODLE_INTERNAL') || die;
  37  
  38  require_once($CFG->dirroot . '/mod/survey/lib.php');
  39  
  40  /**
  41   * Survey external functions
  42   *
  43   * @package    mod_survey
  44   * @category   external
  45   * @copyright  2015 Juan Leyva <juan@moodle.com>
  46   * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  47   * @since      Moodle 3.0
  48   */
  49  class mod_survey_external extends external_api {
  50  
  51      /**
  52       * Describes the parameters for get_surveys_by_courses.
  53       *
  54       * @return external_function_parameters
  55       * @since Moodle 3.0
  56       */
  57      public static function get_surveys_by_courses_parameters() {
  58          return new external_function_parameters (
  59              array(
  60                  'courseids' => new external_multiple_structure(
  61                      new external_value(PARAM_INT, 'course id'), 'Array of course ids', VALUE_DEFAULT, array()
  62                  ),
  63              )
  64          );
  65      }
  66  
  67      /**
  68       * Returns a list of surveys in a provided list of courses,
  69       * if no list is provided all surveys that the user can view will be returned.
  70       *
  71       * @param array $courseids the course ids
  72       * @return array of surveys details
  73       * @since Moodle 3.0
  74       */
  75      public static function get_surveys_by_courses($courseids = array()) {
  76          global $CFG, $USER, $DB;
  77  
  78          $returnedsurveys = array();
  79          $warnings = array();
  80  
  81          $params = self::validate_parameters(self::get_surveys_by_courses_parameters(), array('courseids' => $courseids));
  82  
  83          $mycourses = array();
  84          if (empty($params['courseids'])) {
  85              $mycourses = enrol_get_my_courses();
  86              $params['courseids'] = array_keys($mycourses);
  87          }
  88  
  89          // Ensure there are courseids to loop through.
  90          if (!empty($params['courseids'])) {
  91              list($courses, $warnings) = util::validate_courses($params['courseids'], $mycourses);
  92  
  93              // Get the surveys in this course, this function checks users visibility permissions.
  94              // We can avoid then additional validate_context calls.
  95              $surveys = get_all_instances_in_courses("survey", $courses);
  96              foreach ($surveys as $survey) {
  97                  $context = context_module::instance($survey->coursemodule);
  98                  if (empty(trim($survey->intro))) {
  99                      $tempo = $DB->get_field("survey", "intro", array("id" => $survey->template));
 100                      $survey->intro = get_string($tempo, "survey");
 101                  }
 102  
 103                  // Entry to return.
 104                  $surveydetails = helper_for_get_mods_by_courses::standard_coursemodule_element_values(
 105                          $survey, 'mod_survey', 'moodle/course:manageactivities', 'mod/survey:participate');
 106  
 107                  if (has_capability('mod/survey:participate', $context)) {
 108                      $surveydetails['template']  = $survey->template;
 109                      $surveydetails['days']      = $survey->days;
 110                      $surveydetails['questions'] = $survey->questions;
 111                      $surveydetails['surveydone'] = survey_already_done($survey->id, $USER->id) ? 1 : 0;
 112                  }
 113  
 114                  if (has_capability('moodle/course:manageactivities', $context)) {
 115                      $surveydetails['timecreated']   = $survey->timecreated;
 116                      $surveydetails['timemodified']  = $survey->timemodified;
 117                  }
 118                  $returnedsurveys[] = $surveydetails;
 119              }
 120          }
 121          $result = array();
 122          $result['surveys'] = $returnedsurveys;
 123          $result['warnings'] = $warnings;
 124          return $result;
 125      }
 126  
 127      /**
 128       * Describes the get_surveys_by_courses return value.
 129       *
 130       * @return external_single_structure
 131       * @since Moodle 3.0
 132       */
 133      public static function get_surveys_by_courses_returns() {
 134          return new external_single_structure(
 135              array(
 136                  'surveys' => new external_multiple_structure(
 137                      new external_single_structure(array_merge(
 138                         helper_for_get_mods_by_courses::standard_coursemodule_elements_returns(true),
 139                         [
 140                              'template' => new external_value(PARAM_INT, 'Survey type', VALUE_OPTIONAL),
 141                              'days' => new external_value(PARAM_INT, 'Days', VALUE_OPTIONAL),
 142                              'questions' => new external_value(PARAM_RAW, 'Question ids', VALUE_OPTIONAL),
 143                              'surveydone' => new external_value(PARAM_INT, 'Did I finish the survey?', VALUE_OPTIONAL),
 144                              'timecreated' => new external_value(PARAM_INT, 'Time of creation', VALUE_OPTIONAL),
 145                              'timemodified' => new external_value(PARAM_INT, 'Time of last modification', VALUE_OPTIONAL),
 146                          ]
 147                      ), 'Surveys')
 148                  ),
 149                  'warnings' => new external_warnings(),
 150              )
 151          );
 152      }
 153  
 154      /**
 155       * Returns description of method parameters
 156       *
 157       * @return external_function_parameters
 158       * @since Moodle 3.0
 159       */
 160      public static function view_survey_parameters() {
 161          return new external_function_parameters(
 162              array(
 163                  'surveyid' => new external_value(PARAM_INT, 'survey instance id')
 164              )
 165          );
 166      }
 167  
 168      /**
 169       * Trigger the course module viewed event and update the module completion status.
 170       *
 171       * @param int $surveyid the survey instance id
 172       * @return array of warnings and status result
 173       * @since Moodle 3.0
 174       * @throws moodle_exception
 175       */
 176      public static function view_survey($surveyid) {
 177          global $DB, $USER;
 178  
 179          $params = self::validate_parameters(self::view_survey_parameters(),
 180                                              array(
 181                                                  'surveyid' => $surveyid
 182                                              ));
 183          $warnings = array();
 184  
 185          // Request and permission validation.
 186          $survey = $DB->get_record('survey', array('id' => $params['surveyid']), '*', MUST_EXIST);
 187          list($course, $cm) = get_course_and_cm_from_instance($survey, 'survey');
 188  
 189          $context = context_module::instance($cm->id);
 190          self::validate_context($context);
 191          require_capability('mod/survey:participate', $context);
 192  
 193          $viewed = survey_already_done($survey->id, $USER->id) ? 'graph' : 'form';
 194  
 195          // Trigger course_module_viewed event and completion.
 196          survey_view($survey, $course, $cm, $context, $viewed);
 197  
 198          $result = array();
 199          $result['status'] = true;
 200          $result['warnings'] = $warnings;
 201          return $result;
 202      }
 203  
 204      /**
 205       * Returns description of method result value
 206       *
 207       * @return \core_external\external_description
 208       * @since Moodle 3.0
 209       */
 210      public static function view_survey_returns() {
 211          return new external_single_structure(
 212              array(
 213                  'status' => new external_value(PARAM_BOOL, 'status: true if success'),
 214                  'warnings' => new external_warnings()
 215              )
 216          );
 217      }
 218  
 219      /**
 220       * Returns description of method parameters
 221       *
 222       * @return external_function_parameters
 223       * @since Moodle 3.0
 224       */
 225      public static function get_questions_parameters() {
 226          return new external_function_parameters(
 227              array(
 228                  'surveyid' => new external_value(PARAM_INT, 'survey instance id')
 229              )
 230          );
 231      }
 232  
 233      /**
 234       * Get the complete list of questions for the survey, including subquestions.
 235       *
 236       * @param int $surveyid the survey instance id
 237       * @return array of warnings and the question list
 238       * @since Moodle 3.0
 239       * @throws moodle_exception
 240       */
 241      public static function get_questions($surveyid) {
 242          global $DB, $USER;
 243  
 244          $params = self::validate_parameters(self::get_questions_parameters(),
 245                                              array(
 246                                                  'surveyid' => $surveyid
 247                                              ));
 248          $warnings = array();
 249  
 250          // Request and permission validation.
 251          $survey = $DB->get_record('survey', array('id' => $params['surveyid']), '*', MUST_EXIST);
 252          list($course, $cm) = get_course_and_cm_from_instance($survey, 'survey');
 253  
 254          $context = context_module::instance($cm->id);
 255          self::validate_context($context);
 256          require_capability('mod/survey:participate', $context);
 257  
 258          $mainquestions = survey_get_questions($survey);
 259  
 260          foreach ($mainquestions as $question) {
 261              if ($question->type >= 0) {
 262                  // Parent is used in subquestions.
 263                  $question->parent = 0;
 264                  $questions[] = survey_translate_question($question);
 265  
 266                  // Check if the question has subquestions.
 267                  if ($question->multi) {
 268                      $subquestions = survey_get_subquestions($question);
 269                      foreach ($subquestions as $sq) {
 270                          $sq->parent = $question->id;
 271                          $questions[] = survey_translate_question($sq);
 272                      }
 273                  }
 274              }
 275          }
 276  
 277          $result = array();
 278          $result['questions'] = $questions;
 279          $result['warnings'] = $warnings;
 280          return $result;
 281      }
 282  
 283      /**
 284       * Returns description of method result value
 285       *
 286       * @return \core_external\external_description
 287       * @since Moodle 3.0
 288       */
 289      public static function get_questions_returns() {
 290          return new external_single_structure(
 291              array(
 292                  'questions' => new external_multiple_structure(
 293                      new external_single_structure(
 294                          array(
 295                              'id' => new external_value(PARAM_INT, 'Question id'),
 296                              'text' => new external_value(PARAM_RAW, 'Question text'),
 297                              'shorttext' => new external_value(PARAM_RAW, 'Question short text'),
 298                              'multi' => new external_value(PARAM_RAW, 'Subquestions ids'),
 299                              'intro' => new external_value(PARAM_RAW, 'The question intro'),
 300                              'type' => new external_value(PARAM_INT, 'Question type'),
 301                              'options' => new external_value(PARAM_RAW, 'Question options'),
 302                              'parent' => new external_value(PARAM_INT, 'Parent question (for subquestions)'),
 303                          ), 'Questions'
 304                      )
 305                  ),
 306                  'warnings' => new external_warnings()
 307              )
 308          );
 309      }
 310  
 311      /**
 312       * Describes the parameters for submit_answers.
 313       *
 314       * @return external_function_parameters
 315       * @since Moodle 3.0
 316       */
 317      public static function submit_answers_parameters() {
 318          return new external_function_parameters(
 319              array(
 320                  'surveyid' => new external_value(PARAM_INT, 'Survey id'),
 321                  'answers' => new external_multiple_structure(
 322                      new external_single_structure(
 323                          array(
 324                              'key' => new external_value(PARAM_RAW, 'Answer key'),
 325                              'value' => new external_value(PARAM_RAW, 'Answer value')
 326                          )
 327                      )
 328                  ),
 329              )
 330          );
 331      }
 332  
 333      /**
 334       * Submit the answers for a given survey.
 335       *
 336       * @param int $surveyid the survey instance id
 337       * @param array $answers the survey answers
 338       * @return array of warnings and status result
 339       * @since Moodle 3.0
 340       * @throws moodle_exception
 341       */
 342      public static function submit_answers($surveyid, $answers) {
 343          global $DB, $USER;
 344  
 345          $params = self::validate_parameters(self::submit_answers_parameters(),
 346                                              array(
 347                                                  'surveyid' => $surveyid,
 348                                                  'answers' => $answers
 349                                              ));
 350          $warnings = array();
 351  
 352          // Request and permission validation.
 353          $survey = $DB->get_record('survey', array('id' => $params['surveyid']), '*', MUST_EXIST);
 354          list($course, $cm) = get_course_and_cm_from_instance($survey, 'survey');
 355  
 356          $context = context_module::instance($cm->id);
 357          self::validate_context($context);
 358          require_capability('mod/survey:participate', $context);
 359  
 360          if (survey_already_done($survey->id, $USER->id)) {
 361              throw new moodle_exception("alreadysubmitted", "survey");
 362          }
 363  
 364          // Build the answers array. Data is cleaned inside the survey_save_answers function.
 365          $answers = array();
 366          foreach ($params['answers'] as $answer) {
 367              $key = $answer['key'];
 368              $answers[$key] = $answer['value'];
 369          }
 370  
 371          survey_save_answers($survey, $answers, $course, $context);
 372  
 373          $result = array();
 374          $result['status'] = true;
 375          $result['warnings'] = $warnings;
 376          return $result;
 377      }
 378  
 379      /**
 380       * Returns description of method result value
 381       *
 382       * @return \core_external\external_description
 383       * @since Moodle 3.0
 384       */
 385      public static function submit_answers_returns() {
 386          return new external_single_structure(
 387              array(
 388                  'status' => new external_value(PARAM_BOOL, 'status: true if success'),
 389                  'warnings' => new external_warnings()
 390              )
 391          );
 392      }
 393  
 394  }