MDL-70374 qtype_multichoice: improve alignment of choices
[moodle.git] / question / classes / external.php
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/>.
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  */
27 defined('MOODLE_INTERNAL') || die();
29 require_once("$CFG->libdir/externallib.php");
30 require_once($CFG->dirroot . '/question/engine/lib.php');
31 require_once($CFG->dirroot . '/question/engine/datalib.php');
32 require_once($CFG->libdir . '/questionlib.php');
34 /**
35  * Question external functions
36  *
37  * @package    core_question
38  * @category   external
39  * @copyright  2016 Pau Ferrer <pau@moodle.com>
40  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
41  * @since Moodle 3.1
42  */
43 class core_question_external extends external_api {
45     /**
46      * Returns description of method parameters
47      *
48      * @return external_function_parameters
49      * @since Moodle 3.1
50      */
51     public static function update_flag_parameters() {
52         return new external_function_parameters(
53             array(
54                 'qubaid' => new external_value(PARAM_INT, 'the question usage id.'),
55                 'questionid' => new external_value(PARAM_INT, 'the question id'),
56                 'qaid' => new external_value(PARAM_INT, 'the question_attempt id'),
57                 'slot' => new external_value(PARAM_INT, 'the slot number within the usage'),
58                 'checksum' => new external_value(PARAM_ALPHANUM, 'computed checksum with the last three arguments and
59                              the users username'),
60                 'newstate' => new external_value(PARAM_BOOL, 'the new state of the flag. true = flagged')
61             )
62         );
63     }
65     /**
66      * Update the flag state of a question attempt.
67      *
68      * @param int $qubaid the question usage id.
69      * @param int $questionid the question id.
70      * @param int $qaid the question_attempt id.
71      * @param int $slot the slot number within the usage.
72      * @param string $checksum checksum, as computed by {@link get_toggle_checksum()}
73      *      corresponding to the last three arguments and the users username.
74      * @param bool $newstate the new state of the flag. true = flagged.
75      * @return array (success infos and fail infos)
76      * @since Moodle 3.1
77      */
78     public static function update_flag($qubaid, $questionid, $qaid, $slot, $checksum, $newstate) {
79         global $CFG, $DB;
81         $params = self::validate_parameters(self::update_flag_parameters(),
82             array(
83                 'qubaid' => $qubaid,
84                 'questionid' => $questionid,
85                 'qaid' => $qaid,
86                 'slot' => $slot,
87                 'checksum' => $checksum,
88                 'newstate' => $newstate
89             )
90         );
92         $warnings = array();
93         self::validate_context(context_system::instance());
95         // The checksum will be checked to provide security flagging other users questions.
96         question_flags::update_flag($params['qubaid'], $params['questionid'], $params['qaid'], $params['slot'], $params['checksum'],
97                                     $params['newstate']);
99         $result = array();
100         $result['status'] = true;
101         $result['warnings'] = $warnings;
102         return $result;
103     }
105     /**
106      * Returns description of method result value
107      *
108      * @return external_description
109      * @since Moodle 3.1
110      */
111     public static function update_flag_returns() {
112         return new external_single_structure(
113             array(
114                 'status' => new external_value(PARAM_BOOL, 'status: true if success'),
115                 'warnings' => new external_warnings()
116             )
117         );
118     }
120     /**
121      * Returns description of method parameters.
122      *
123      * @return external_function_parameters.
124      */
125     public static function submit_tags_form_parameters() {
126         return new external_function_parameters([
127                 'questionid' => new external_value(PARAM_INT, 'The question id'),
128                 'contextid' => new external_value(PARAM_INT, 'The editing context id'),
129                 'formdata' => new external_value(PARAM_RAW, 'The data from the tag form'),
130         ]);
131     }
133     /**
134      * Handles the tags form submission.
135      *
136      * @param int $questionid The question id.
137      * @param int $contextid The editing context id.
138      * @param string $formdata The question tag form data in a URI encoded param string
139      * @return array The created or modified question tag
140      */
141     public static function submit_tags_form($questionid, $contextid, $formdata) {
142         global $DB, $CFG;
144         $data = [];
145         $result = ['status' => false];
147         // Parameter validation.
148         $params = self::validate_parameters(self::submit_tags_form_parameters(), [
149             'questionid' => $questionid,
150             'contextid' => $contextid,
151             'formdata' => $formdata
152         ]);
154         $editingcontext = \context::instance_by_id($contextid);
155         self::validate_context($editingcontext);
156         parse_str($params['formdata'], $data);
158         if (!$question = $DB->get_record_sql('
159                 SELECT q.*, qc.contextid
160                 FROM {question} q
161                 JOIN {question_categories} qc ON qc.id = q.category
162                 WHERE q.id = ?', [$questionid])) {
163             print_error('questiondoesnotexist', 'question');
164         }
166         require_once($CFG->libdir . '/questionlib.php');
167         require_once($CFG->dirroot . '/question/type/tags_form.php');
169         $cantag = question_has_capability_on($question, 'tag');
170         $questioncontext = \context::instance_by_id($question->contextid);
171         $contexts = new \question_edit_contexts($editingcontext);
173         $formoptions = [
174             'editingcontext' => $editingcontext,
175             'questioncontext' => $questioncontext,
176             'contexts' => $contexts->all()
177         ];
179         $mform = new \core_question\form\tags(null, $formoptions, 'post', '', null, $cantag, $data);
181         if ($validateddata = $mform->get_data()) {
182             if ($cantag) {
183                 if (isset($validateddata->tags)) {
184                     // Due to a mform bug, if there's no tags set on the tag element, it submits the name as the value.
185                     // The only way to discover is checking if the tag element is an array.
186                     $tags = is_array($validateddata->tags) ? $validateddata->tags : [];
188                     core_tag_tag::set_item_tags('core_question', 'question', $validateddata->id,
189                         $questioncontext, $tags);
191                     $result['status'] = true;
192                 }
194                 if (isset($validateddata->coursetags)) {
195                     $coursetags = is_array($validateddata->coursetags) ? $validateddata->coursetags : [];
196                     core_tag_tag::set_item_tags('core_question', 'question', $validateddata->id,
197                         $editingcontext->get_course_context(false), $coursetags);
199                     $result['status'] = true;
200                 }
201             }
202         }
204         return $result;
205     }
207     /**
208      * Returns description of method result value.
209      */
210     public static function  submit_tags_form_returns() {
211         return new external_single_structure([
212                 'status' => new external_value(PARAM_BOOL, 'status: true if success')
213         ]);
214     }
216     /**
217      * Returns description of method parameters.
218      *
219      * @return external_function_parameters.
220      */
221     public static function get_random_question_summaries_parameters() {
222         return new external_function_parameters([
223                 'categoryid' => new external_value(PARAM_INT, 'Category id to find random questions'),
224                 'includesubcategories' => new external_value(PARAM_BOOL, 'Include the subcategories in the search'),
225                 'tagids' => new external_multiple_structure(
226                     new external_value(PARAM_INT, 'Tag id')
227                 ),
228                 'contextid' => new external_value(PARAM_INT,
229                     'Context id that the questions will be rendered in (used for exporting)'),
230                 'limit' => new external_value(PARAM_INT, 'Maximum number of results to return',
231                     VALUE_DEFAULT, 0),
232                 'offset' => new external_value(PARAM_INT, 'Number of items to skip from the begging of the result set',
233                     VALUE_DEFAULT, 0)
234         ]);
235     }
237     /**
238      * Gets the list of random questions for the given criteria. The questions
239      * will be exported in a summaries format and won't include all of the
240      * question data.
241      *
242      * @param int $categoryid Category id to find random questions
243      * @param bool $includesubcategories Include the subcategories in the search
244      * @param int[] $tagids Only include questions with these tags
245      * @param int $contextid The context id where the questions will be rendered
246      * @param int $limit Maximum number of results to return
247      * @param int $offset Number of items to skip from the beginning of the result set.
248      * @return array The list of questions and total question count.
249      */
250     public static function get_random_question_summaries(
251         $categoryid,
252         $includesubcategories,
253         $tagids,
254         $contextid,
255         $limit = 0,
256         $offset = 0
257     ) {
258         global $DB, $PAGE;
260         // Parameter validation.
261         $params = self::validate_parameters(
262             self::get_random_question_summaries_parameters(),
263             [
264                 'categoryid' => $categoryid,
265                 'includesubcategories' => $includesubcategories,
266                 'tagids' => $tagids,
267                 'contextid' => $contextid,
268                 'limit' => $limit,
269                 'offset' => $offset
270             ]
271         );
272         $categoryid = $params['categoryid'];
273         $includesubcategories = $params['includesubcategories'];
274         $tagids = $params['tagids'];
275         $contextid = $params['contextid'];
276         $limit = $params['limit'];
277         $offset = $params['offset'];
279         $context = \context::instance_by_id($contextid);
280         self::validate_context($context);
282         $categorycontextid = $DB->get_field('question_categories', 'contextid', ['id' => $categoryid], MUST_EXIST);
283         $categorycontext = \context::instance_by_id($categorycontextid);
284         $editcontexts = new \question_edit_contexts($categorycontext);
285         // The user must be able to view all questions in the category that they are requesting.
286         $editcontexts->require_cap('moodle/question:viewall');
288         $loader = new \core_question\bank\random_question_loader(new qubaid_list([]));
289         // Only load the properties we require from the DB.
290         $properties = \core_question\external\question_summary_exporter::get_mandatory_properties();
291         $questions = $loader->get_questions($categoryid, $includesubcategories, $tagids, $limit, $offset, $properties);
292         $totalcount = $loader->count_questions($categoryid, $includesubcategories, $tagids);
293         $renderer = $PAGE->get_renderer('core');
295         $formattedquestions = array_map(function($question) use ($context, $renderer) {
296             $exporter = new \core_question\external\question_summary_exporter($question, ['context' => $context]);
297             return $exporter->export($renderer);
298         }, $questions);
300         return [
301             'totalcount' => $totalcount,
302             'questions' => $formattedquestions
303         ];
304     }
306     /**
307      * Returns description of method result value.
308      */
309     public static function  get_random_question_summaries_returns() {
310         return new external_single_structure([
311             'totalcount' => new external_value(PARAM_INT, 'total number of questions in result set'),
312             'questions' => new external_multiple_structure(
313                 \core_question\external\question_summary_exporter::get_read_structure()
314             )
315         ]);
316     }