2 // This file is part of Moodle - http://moodle.org/
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.
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.
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/>.
18 * Choice module external API
22 * @copyright 2015 Costantino Cito <ccito@cvaconsulting.com>
23 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
27 defined('MOODLE_INTERNAL') ||
die;
28 require_once($CFG->libdir
. '/externallib.php');
29 require_once($CFG->dirroot
. '/mod/choice/lib.php');
32 * Choice module external functions
36 * @copyright 2015 Costantino Cito <ccito@cvaconsulting.com>
37 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
40 class mod_choice_external
extends external_api
{
43 * Describes the parameters for get_choices_by_courses.
45 * @return external_function_parameters
48 public static function get_choice_results_parameters() {
49 return new external_function_parameters (array('choiceid' => new external_value(PARAM_INT
, 'choice instance id')));
52 * Returns user's results for a specific choice
53 * and a list of those users that did not answered yet.
55 * @param int $choiceid the choice instance id
56 * @return array of responses details
59 public static function get_choice_results($choiceid) {
62 $params = self
::validate_parameters(self
::get_choice_results_parameters(), array('choiceid' => $choiceid));
64 if (!$choice = choice_get_choice($params['choiceid'])) {
65 throw new moodle_exception("invalidcoursemodule", "error");
67 list($course, $cm) = get_course_and_cm_from_instance($choice, 'choice');
69 $context = context_module
::instance($cm->id
);
70 self
::validate_context($context);
72 $groupmode = groups_get_activity_groupmode($cm);
73 // Check if we have to include responses from inactive users.
74 $onlyactive = $choice->includeinactive ?
false : true;
75 $users = choice_get_response_data($choice, $cm, $groupmode, $onlyactive);
76 // Show those who haven't answered the question.
77 if (!empty($choice->showunanswered
)) {
78 $choice->option
[0] = get_string('notanswered', 'choice');
79 $choice->maxanswers
[0] = 0;
81 $results = prepare_choice_show_results($choice, $course, $cm, $users);
84 $fullnamecap = has_capability('moodle/site:viewfullnames', $context);
85 foreach ($results->options
as $optionid => $option) {
87 $userresponses = array();
89 $percentageamount = 0;
90 if (property_exists($option, 'user') and
91 (has_capability('mod/choice:readresponses', $context) or choice_can_view_results($choice))) {
92 $numberofuser = count($option->user
);
93 $percentageamount = ((float)$numberofuser / (float)$results->numberofuser
) * 100.0;
94 if ($choice->publish
) {
95 foreach ($option->user
as $userresponse) {
97 $response['userid'] = $userresponse->id
;
98 $response['fullname'] = fullname($userresponse, $fullnamecap);
100 $userpicture = new user_picture($userresponse);
101 $userpicture->size
= 1; // Size f1.
102 $response['profileimageurl'] = $userpicture->get_url($PAGE)->out(false);
104 // Add optional properties.
105 foreach (array('answerid', 'timemodified') as $field) {
106 if (property_exists($userresponse, 'answerid')) {
107 $response[$field] = $userresponse->$field;
110 $userresponses[] = $response;
115 $options[] = array('id' => $optionid,
116 'text' => external_format_string($option->text
, $context->id
),
117 'maxanswer' => $option->maxanswer
,
118 'userresponses' => $userresponses,
119 'numberofuser' => $numberofuser,
120 'percentageamount' => $percentageamount
126 'options' => $options,
127 'warnings' => $warnings
132 * Describes the get_choice_results return value.
134 * @return external_single_structure
137 public static function get_choice_results_returns() {
138 return new external_single_structure(
140 'options' => new external_multiple_structure(
141 new external_single_structure(
143 'id' => new external_value(PARAM_INT
, 'choice instance id'),
144 'text' => new external_value(PARAM_RAW
, 'text of the choice'),
145 'maxanswer' => new external_value(PARAM_INT
, 'maximum number of answers'),
146 'userresponses' => new external_multiple_structure(
147 new external_single_structure(
149 'userid' => new external_value(PARAM_INT
, 'user id'),
150 'fullname' => new external_value(PARAM_NOTAGS
, 'user full name'),
151 'profileimageurl' => new external_value(PARAM_URL
, 'profile user image url'),
152 'answerid' => new external_value(PARAM_INT
, 'answer id', VALUE_OPTIONAL
),
153 'timemodified' => new external_value(PARAM_INT
, 'time of modification', VALUE_OPTIONAL
),
157 'numberofuser' => new external_value(PARAM_INT
, 'number of users answers'),
158 'percentageamount' => new external_value(PARAM_FLOAT
, 'percentage of users answers')
162 'warnings' => new external_warnings(),
168 * Describes the parameters for mod_choice_get_choice_options.
170 * @return external_function_parameters
173 public static function get_choice_options_parameters() {
174 return new external_function_parameters (array('choiceid' => new external_value(PARAM_INT
, 'choice instance id')));
178 * Returns options for a specific choice
180 * @param int $choiceid the choice instance id
181 * @return array of options details
184 public static function get_choice_options($choiceid) {
187 $params = self
::validate_parameters(self
::get_choice_options_parameters(), array('choiceid' => $choiceid));
189 if (!$choice = choice_get_choice($params['choiceid'])) {
190 throw new moodle_exception("invalidcoursemodule", "error");
192 list($course, $cm) = get_course_and_cm_from_instance($choice, 'choice');
194 $context = context_module
::instance($cm->id
);
195 self
::validate_context($context);
197 require_capability('mod/choice:choose', $context);
199 $groupmode = groups_get_activity_groupmode($cm);
200 $onlyactive = $choice->includeinactive ?
false : true;
201 $allresponses = choice_get_response_data($choice, $cm, $groupmode, $onlyactive);
205 $showpreview = false;
207 if (!empty($choice->timeopen
) && ($choice->timeopen
> $timenow)) {
209 $warnings[1] = get_string("notopenyet", "choice", userdate($choice->timeopen
));
210 if ($choice->showpreview
) {
211 $warnings[2] = get_string('previewonly', 'choice', userdate($choice->timeopen
));
215 if (!empty($choice->timeclose
) && ($timenow > $choice->timeclose
)) {
217 $warnings[3] = get_string("expired", "choice", userdate($choice->timeclose
));
220 $optionsarray = array();
222 if ($choiceopen or $showpreview) {
224 $options = choice_prepare_options($choice, $USER, $cm, $allresponses);
226 foreach ($options['options'] as $option) {
227 $optionarr = array();
228 $optionarr['id'] = $option->attributes
->value
;
229 $optionarr['text'] = external_format_string($option->text
, $context->id
);
230 $optionarr['maxanswers'] = $option->maxanswers
;
231 $optionarr['displaylayout'] = $option->displaylayout
;
232 $optionarr['countanswers'] = $option->countanswers
;
233 foreach (array('checked', 'disabled') as $field) {
234 if (property_exists($option->attributes
, $field) and $option->attributes
->$field == 1) {
235 $optionarr[$field] = 1;
237 $optionarr[$field] = 0;
240 // When showpreview is active, we show options as disabled.
241 if ($showpreview or ($optionarr['checked'] == 1 and !$choice->allowupdate
)) {
242 $optionarr['disabled'] = 1;
244 $optionsarray[] = $optionarr;
247 foreach ($warnings as $key => $message) {
248 $warnings[$key] = array(
251 'warningcode' => $key,
252 'message' => $message
256 'options' => $optionsarray,
257 'warnings' => $warnings
262 * Describes the get_choice_results return value.
264 * @return external_multiple_structure
267 public static function get_choice_options_returns() {
268 return new external_single_structure(
270 'options' => new external_multiple_structure(
271 new external_single_structure(
273 'id' => new external_value(PARAM_INT
, 'option id'),
274 'text' => new external_value(PARAM_RAW
, 'text of the choice'),
275 'maxanswers' => new external_value(PARAM_INT
, 'maximum number of answers'),
276 'displaylayout' => new external_value(PARAM_BOOL
, 'true for orizontal, otherwise vertical'),
277 'countanswers' => new external_value(PARAM_INT
, 'number of answers'),
278 'checked' => new external_value(PARAM_BOOL
, 'we already answered'),
279 'disabled' => new external_value(PARAM_BOOL
, 'option disabled'),
283 'warnings' => new external_warnings(),
289 * Describes the parameters for submit_choice_response.
291 * @return external_function_parameters
294 public static function submit_choice_response_parameters() {
295 return new external_function_parameters (
297 'choiceid' => new external_value(PARAM_INT
, 'choice instance id'),
298 'responses' => new external_multiple_structure(
299 new external_value(PARAM_INT
, 'answer id'),
300 'Array of response ids'
307 * Submit choice responses
309 * @param int $choiceid the choice instance id
310 * @param array $responses the response ids
311 * @return array answers information and warnings
314 public static function submit_choice_response($choiceid, $responses) {
318 $params = self
::validate_parameters(self
::submit_choice_response_parameters(),
320 'choiceid' => $choiceid,
321 'responses' => $responses
324 if (!$choice = choice_get_choice($params['choiceid'])) {
325 throw new moodle_exception("invalidcoursemodule", "error");
327 list($course, $cm) = get_course_and_cm_from_instance($choice, 'choice');
329 $context = context_module
::instance($cm->id
);
330 self
::validate_context($context);
332 require_capability('mod/choice:choose', $context);
335 if (!empty($choice->timeopen
) && ($choice->timeopen
> $timenow)) {
336 throw new moodle_exception("notopenyet", "choice", '', userdate($choice->timeopen
));
337 } else if (!empty($choice->timeclose
) && ($timenow > $choice->timeclose
)) {
338 throw new moodle_exception("expired", "choice", '', userdate($choice->timeclose
));
341 if (!choice_get_my_response($choice) or $choice->allowupdate
) {
342 // When a single response is given, we convert the array to a simple variable
343 // in order to avoid choice_user_submit_response to check with allowmultiple even
344 // for a single response.
345 if (count($params['responses']) == 1) {
346 $params['responses'] = reset($params['responses']);
348 choice_user_submit_response($params['responses'], $choice, $USER->id
, $course, $cm);
350 throw new moodle_exception('missingrequiredcapability', 'webservice', '', 'allowupdate');
352 $answers = choice_get_my_response($choice);
355 'answers' => $answers,
356 'warnings' => $warnings
361 * Describes the submit_choice_response return value.
363 * @return external_multiple_structure
366 public static function submit_choice_response_returns() {
367 return new external_single_structure(
369 'answers' => new external_multiple_structure(
370 new external_single_structure(
372 'id' => new external_value(PARAM_INT
, 'answer id'),
373 'choiceid' => new external_value(PARAM_INT
, 'choiceid'),
374 'userid' => new external_value(PARAM_INT
, 'user id'),
375 'optionid' => new external_value(PARAM_INT
, 'optionid'),
376 'timemodified' => new external_value(PARAM_INT
, 'time of last modification')
380 'warnings' => new external_warnings(),
386 * Returns description of method parameters
388 * @return external_function_parameters
391 public static function view_choice_parameters() {
392 return new external_function_parameters(
394 'choiceid' => new external_value(PARAM_INT
, 'choice instance id')
400 * Trigger the course module viewed event and update the module completion status.
402 * @param int $choiceid the choice instance id
403 * @return array of warnings and status result
405 * @throws moodle_exception
407 public static function view_choice($choiceid) {
410 $params = self
::validate_parameters(self
::view_choice_parameters(),
412 'choiceid' => $choiceid
416 // Request and permission validation.
417 if (!$choice = choice_get_choice($params['choiceid'])) {
418 throw new moodle_exception("invalidcoursemodule", "error");
420 list($course, $cm) = get_course_and_cm_from_instance($choice, 'choice');
422 $context = context_module
::instance($cm->id
);
423 self
::validate_context($context);
425 // Trigger course_module_viewed event and completion.
426 choice_view($choice, $course, $cm, $context);
429 $result['status'] = true;
430 $result['warnings'] = $warnings;
435 * Returns description of method result value
437 * @return external_description
440 public static function view_choice_returns() {
441 return new external_single_structure(
443 'status' => new external_value(PARAM_BOOL
, 'status: true if success'),
444 'warnings' => new external_warnings()
450 * Describes the parameters for get_choices_by_courses.
452 * @return external_function_parameters
455 public static function get_choices_by_courses_parameters() {
456 return new external_function_parameters (
458 'courseids' => new external_multiple_structure(
459 new external_value(PARAM_INT
, 'course id'), 'Array of course ids', VALUE_DEFAULT
, array()
466 * Returns a list of choices in a provided list of courses,
467 * if no list is provided all choices that the user can view will be returned.
469 * @param array $courseids the course ids
470 * @return array of choices details
473 public static function get_choices_by_courses($courseids = array()) {
476 $returnedchoices = array();
479 $params = self
::validate_parameters(self
::get_choices_by_courses_parameters(), array('courseids' => $courseids));
482 if (empty($params['courseids'])) {
483 $courses = enrol_get_my_courses();
484 $params['courseids'] = array_keys($courses);
487 // Ensure there are courseids to loop through.
488 if (!empty($params['courseids'])) {
490 list($courses, $warnings) = external_util
::validate_courses($params['courseids'], $courses);
492 // Get the choices in this course, this function checks users visibility permissions.
493 // We can avoid then additional validate_context calls.
494 $choices = get_all_instances_in_courses("choice", $courses);
495 foreach ($choices as $choice) {
496 $context = context_module
::instance($choice->coursemodule
);
498 $choicedetails = array();
499 // First, we return information that any user can see in the web interface.
500 $choicedetails['id'] = $choice->id
;
501 $choicedetails['coursemodule'] = $choice->coursemodule
;
502 $choicedetails['course'] = $choice->course
;
503 $choicedetails['name'] = external_format_string($choice->name
, $context->id
);
505 $options = array('noclean' => true);
506 list($choicedetails['intro'], $choicedetails['introformat']) =
507 external_format_text($choice->intro
, $choice->introformat
, $context->id
, 'mod_choice', 'intro', null, $options);
508 $choicedetails['introfiles'] = external_util
::get_area_files($context->id
, 'mod_choice', 'intro', false, false);
510 if (has_capability('mod/choice:choose', $context)) {
511 $choicedetails['publish'] = $choice->publish
;
512 $choicedetails['showresults'] = $choice->showresults
;
513 $choicedetails['showpreview'] = $choice->showpreview
;
514 $choicedetails['timeopen'] = $choice->timeopen
;
515 $choicedetails['timeclose'] = $choice->timeclose
;
516 $choicedetails['display'] = $choice->display
;
517 $choicedetails['allowupdate'] = $choice->allowupdate
;
518 $choicedetails['allowmultiple'] = $choice->allowmultiple
;
519 $choicedetails['limitanswers'] = $choice->limitanswers
;
520 $choicedetails['showunanswered'] = $choice->showunanswered
;
521 $choicedetails['includeinactive'] = $choice->includeinactive
;
522 $choicedetails['showavailable'] = $choice->showavailable
;
525 if (has_capability('moodle/course:manageactivities', $context)) {
526 $choicedetails['timemodified'] = $choice->timemodified
;
527 $choicedetails['completionsubmit'] = $choice->completionsubmit
;
528 $choicedetails['section'] = $choice->section
;
529 $choicedetails['visible'] = $choice->visible
;
530 $choicedetails['groupmode'] = $choice->groupmode
;
531 $choicedetails['groupingid'] = $choice->groupingid
;
533 $returnedchoices[] = $choicedetails;
537 $result['choices'] = $returnedchoices;
538 $result['warnings'] = $warnings;
543 * Describes the mod_choice_get_choices_by_courses return value.
545 * @return external_single_structure
548 public static function get_choices_by_courses_returns() {
549 return new external_single_structure(
551 'choices' => new external_multiple_structure(
552 new external_single_structure(
554 'id' => new external_value(PARAM_INT
, 'Choice instance id'),
555 'coursemodule' => new external_value(PARAM_INT
, 'Course module id'),
556 'course' => new external_value(PARAM_INT
, 'Course id'),
557 'name' => new external_value(PARAM_RAW
, 'Choice name'),
558 'intro' => new external_value(PARAM_RAW
, 'The choice intro'),
559 'introformat' => new external_format_value('intro'),
560 'introfiles' => new external_files('Files in the introduction text', VALUE_OPTIONAL
),
561 'publish' => new external_value(PARAM_BOOL
, 'If choice is published', VALUE_OPTIONAL
),
562 'showresults' => new external_value(PARAM_INT
, '0 never, 1 after answer, 2 after close, 3 always',
564 'display' => new external_value(PARAM_INT
, 'Display mode (vertical, horizontal)', VALUE_OPTIONAL
),
565 'allowupdate' => new external_value(PARAM_BOOL
, 'Allow update', VALUE_OPTIONAL
),
566 'allowmultiple' => new external_value(PARAM_BOOL
, 'Allow multiple choices', VALUE_OPTIONAL
),
567 'showunanswered' => new external_value(PARAM_BOOL
, 'Show users who not answered yet', VALUE_OPTIONAL
),
568 'includeinactive' => new external_value(PARAM_BOOL
, 'Include inactive users', VALUE_OPTIONAL
),
569 'limitanswers' => new external_value(PARAM_BOOL
, 'Limit unswers', VALUE_OPTIONAL
),
570 'timeopen' => new external_value(PARAM_INT
, 'Date of opening validity', VALUE_OPTIONAL
),
571 'timeclose' => new external_value(PARAM_INT
, 'Date of closing validity', VALUE_OPTIONAL
),
572 'showpreview' => new external_value(PARAM_BOOL
, 'Show preview before timeopen', VALUE_OPTIONAL
),
573 'timemodified' => new external_value(PARAM_INT
, 'Time of last modification', VALUE_OPTIONAL
),
574 'completionsubmit' => new external_value(PARAM_BOOL
, 'Completion on user submission', VALUE_OPTIONAL
),
575 'showavailable' => new external_value(PARAM_BOOL
, 'Show available spaces', VALUE_OPTIONAL
),
576 'section' => new external_value(PARAM_INT
, 'Course section id', VALUE_OPTIONAL
),
577 'visible' => new external_value(PARAM_BOOL
, 'Visible', VALUE_OPTIONAL
),
578 'groupmode' => new external_value(PARAM_INT
, 'Group mode', VALUE_OPTIONAL
),
579 'groupingid' => new external_value(PARAM_INT
, 'Group id', VALUE_OPTIONAL
),
583 'warnings' => new external_warnings(),
589 * Describes the parameters for delete_choice_responses.
591 * @return external_function_parameters
594 public static function delete_choice_responses_parameters() {
595 return new external_function_parameters (
597 'choiceid' => new external_value(PARAM_INT
, 'choice instance id'),
598 'responses' => new external_multiple_structure(
599 new external_value(PARAM_INT
, 'response id'),
600 'Array of response ids, empty for deleting all the current user responses.',
609 * Delete the given submitted responses in a choice
611 * @param int $choiceid the choice instance id
612 * @param array $responses the response ids, empty for deleting all the current user responses
613 * @return array status information and warnings
614 * @throws moodle_exception
617 public static function delete_choice_responses($choiceid, $responses = array()) {
621 $params = self
::validate_parameters(self
::delete_choice_responses_parameters(),
623 'choiceid' => $choiceid,
624 'responses' => $responses
627 if (!$choice = choice_get_choice($params['choiceid'])) {
628 throw new moodle_exception("invalidcoursemodule", "error");
630 list($course, $cm) = get_course_and_cm_from_instance($choice, 'choice');
632 $context = context_module
::instance($cm->id
);
633 self
::validate_context($context);
635 require_capability('mod/choice:choose', $context);
637 $candeleteall = has_capability('mod/choice:deleteresponses', $context);
638 if ($candeleteall ||
$choice->allowupdate
) {
640 // Check if we can delete our own responses.
641 if (!$candeleteall) {
643 if (!empty($choice->timeclose
) && ($timenow > $choice->timeclose
)) {
644 throw new moodle_exception("expired", "choice", '', userdate($choice->timeclose
));
648 if (empty($params['responses'])) {
649 // No responses indicated so delete only my responses.
650 $todelete = array_keys(choice_get_my_response($choice));
652 // Fill an array with the responses that can be deleted for this choice.
654 // Teacher/managers can delete any.
655 $allowedresponses = array_keys(choice_get_all_responses($choice));
657 // Students can delete only their own responses.
658 $allowedresponses = array_keys(choice_get_my_response($choice));
662 foreach ($params['responses'] as $response) {
663 if (!in_array($response, $allowedresponses)) {
665 'item' => 'response',
666 'itemid' => $response,
667 'warningcode' => 'nopermissions',
668 'message' => 'Invalid response id, the response does not exist or you are not allowed to delete it.'
671 $todelete[] = $response;
676 $status = choice_delete_responses($todelete, $choice, $cm, $course);
678 // The user requires the capability to delete responses.
679 throw new required_capability_exception($context, 'mod/choice:deleteresponses', 'nopermissions', '');
684 'warnings' => $warnings
689 * Describes the delete_choice_responses return value.
691 * @return external_multiple_structure
694 public static function delete_choice_responses_returns() {
695 return new external_single_structure(
697 'status' => new external_value(PARAM_BOOL
, 'status, true if everything went right'),
698 'warnings' => new external_warnings(),