MDL-61364 question: add support for course tags on modal
[moodle.git] / question / classes / external.php
CommitLineData
7361b968
PFO
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/**
19 * External question API
20 *
21 * @package core_question
22 * @category external
23 * @copyright 2016 Pau Ferrer <pau@moodle.com>
24 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
25 */
26
e71687ba
JL
27defined('MOODLE_INTERNAL') || die();
28
7361b968
PFO
29require_once("$CFG->libdir/externallib.php");
30require_once($CFG->dirroot . '/question/engine/lib.php');
31
32/**
33 * Question external functions
34 *
35 * @package core_question
36 * @category external
37 * @copyright 2016 Pau Ferrer <pau@moodle.com>
38 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
39 * @since Moodle 3.1
40 */
41class core_question_external extends external_api {
42
43 /**
44 * Returns description of method parameters
45 *
46 * @return external_function_parameters
47 * @since Moodle 3.1
48 */
49 public static function update_flag_parameters() {
50 return new external_function_parameters(
51 array(
52 'qubaid' => new external_value(PARAM_INT, 'the question usage id.'),
53 'questionid' => new external_value(PARAM_INT, 'the question id'),
54 'qaid' => new external_value(PARAM_INT, 'the question_attempt id'),
55 'slot' => new external_value(PARAM_INT, 'the slot number within the usage'),
56 'checksum' => new external_value(PARAM_ALPHANUM, 'computed checksum with the last three arguments and
57 the users username'),
58 'newstate' => new external_value(PARAM_BOOL, 'the new state of the flag. true = flagged')
59 )
60 );
61 }
62
63 /**
64 * Update the flag state of a question attempt.
65 *
66 * @param int $qubaid the question usage id.
67 * @param int $questionid the question id.
68 * @param int $qaid the question_attempt id.
69 * @param int $slot the slot number within the usage.
70 * @param string $checksum checksum, as computed by {@link get_toggle_checksum()}
71 * corresponding to the last three arguments and the users username.
72 * @param bool $newstate the new state of the flag. true = flagged.
73 * @return array (success infos and fail infos)
74 * @since Moodle 3.1
75 */
76 public static function update_flag($qubaid, $questionid, $qaid, $slot, $checksum, $newstate) {
77 global $CFG, $DB;
78
79 $params = self::validate_parameters(self::update_flag_parameters(),
80 array(
81 'qubaid' => $qubaid,
82 'questionid' => $questionid,
83 'qaid' => $qaid,
84 'slot' => $slot,
85 'checksum' => $checksum,
86 'newstate' => $newstate
87 )
88 );
89
90 $warnings = array();
67ee1030 91 self::validate_context(context_system::instance());
7361b968
PFO
92
93 // The checksum will be checked to provide security flagging other users questions.
94 question_flags::update_flag($params['qubaid'], $params['questionid'], $params['qaid'], $params['slot'], $params['checksum'],
95 $params['newstate']);
96
97 $result = array();
98 $result['status'] = true;
99 $result['warnings'] = $warnings;
100 return $result;
101 }
102
103 /**
104 * Returns description of method result value
105 *
106 * @return external_description
107 * @since Moodle 3.1
108 */
109 public static function update_flag_returns() {
110 return new external_single_structure(
111 array(
112 'status' => new external_value(PARAM_BOOL, 'status: true if success'),
113 'warnings' => new external_warnings()
114 )
115 );
116 }
680d5c5b
SL
117
118 /**
119 * Returns description of method parameters.
120 *
121 * @return external_function_parameters.
122 */
123 public static function submit_tags_form_parameters() {
124 return new external_function_parameters([
e6890b11
SL
125 'questionid' => new external_value(PARAM_INT, 'The question id'),
126 'contextid' => new external_value(PARAM_INT, 'The editing context id'),
680d5c5b
SL
127 'formdata' => new external_value(PARAM_RAW, 'The data from the tag form'),
128 ]);
129 }
130
131 /**
132 * Handles the tags form submission.
133 *
e6890b11
SL
134 * @param int $questionid The question id.
135 * @param int $contextid The editing context id.
680d5c5b
SL
136 * @param string $formdata The question tag form data in a URI encoded param string
137 * @return array The created or modified question tag
680d5c5b 138 */
e6890b11
SL
139 public static function submit_tags_form($questionid, $contextid, $formdata) {
140 global $DB, $CFG;
680d5c5b
SL
141
142 $data = [];
143 $result = ['status' => false];
144
145 // Parameter validation.
e6890b11
SL
146 $params = self::validate_parameters(self::submit_tags_form_parameters(), [
147 'questionid' => $questionid,
148 'contextid' => $contextid,
149 'formdata' => $formdata
150 ]);
680d5c5b 151
e6890b11
SL
152 $editingcontext = \context::instance_by_id($contextid);
153 self::validate_context($editingcontext);
680d5c5b
SL
154 parse_str($params['formdata'], $data);
155
e6890b11
SL
156 if (!$question = $DB->get_record_sql('
157 SELECT q.*, qc.contextid
158 FROM {question} q
159 JOIN {question_categories} qc ON qc.id = q.category
160 WHERE q.id = ?', [$questionid])) {
161 print_error('questiondoesnotexist', 'question');
162 }
163
164 require_once($CFG->libdir . '/questionlib.php');
165 require_once($CFG->dirroot . '/question/type/tags_form.php');
680d5c5b 166
e6890b11
SL
167 $cantag = question_has_capability_on($question, 'tag');
168 $questioncontext = \context::instance_by_id($question->contextid);
169 $formoptions = [
170 'editingcontext' => $editingcontext,
171 'questioncontext' => $questioncontext
172 ];
680d5c5b 173
e6890b11 174 $mform = new \core_question\form\tags(null, $formoptions, 'post', '', null, $cantag, $data);
680d5c5b 175
e6890b11
SL
176 if ($validateddata = $mform->get_data()) {
177 if ($cantag) {
178 if (isset($validateddata->tags)) {
179 // Due to a mform bug, if there's no tags set on the tag element, it submits the name as the value.
180 // The only way to discover is checking if the tag element is an array.
181 $tags = is_array($validateddata->tags) ? $validateddata->tags : [];
680d5c5b 182
e6890b11
SL
183 core_tag_tag::set_item_tags('core_question', 'question', $validateddata->id,
184 $questioncontext, $tags);
185
186 $result['status'] = true;
187 }
680d5c5b 188
e6890b11
SL
189 if (isset($validateddata->coursetags)) {
190 $coursetags = is_array($validateddata->coursetags) ? $validateddata->coursetags : [];
191 core_tag_tag::set_item_tags('core_question', 'question', $validateddata->id,
192 $editingcontext->get_course_context(false), $coursetags);
680d5c5b 193
e6890b11 194 $result['status'] = true;
680d5c5b
SL
195 }
196 }
197 }
198
199 return $result;
200 }
201
202 /**
203 * Returns description of method result value.
204 */
205 public static function submit_tags_form_returns() {
206 return new external_single_structure([
207 'status' => new external_value(PARAM_BOOL, 'status: true if success')
208 ]);
209 }
7361b968 210}