MDL-61364 question: add support for course tags on modal
[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');
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  */
41 class core_question_external extends external_api {
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     }
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;
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         );
90         $warnings = array();
91         self::validate_context(context_system::instance());
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']);
97         $result = array();
98         $result['status'] = true;
99         $result['warnings'] = $warnings;
100         return $result;
101     }
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     }
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([
125                 'questionid' => new external_value(PARAM_INT, 'The question id'),
126                 'contextid' => new external_value(PARAM_INT, 'The editing context id'),
127                 'formdata' => new external_value(PARAM_RAW, 'The data from the tag form'),
128         ]);
129     }
131     /**
132      * Handles the tags form submission.
133      *
134      * @param int $questionid The question id.
135      * @param int $contextid The editing context id.
136      * @param string $formdata The question tag form data in a URI encoded param string
137      * @return array The created or modified question tag
138      */
139     public static function submit_tags_form($questionid, $contextid, $formdata) {
140         global $DB, $CFG;
142         $data = [];
143         $result = ['status' => false];
145         // Parameter validation.
146         $params = self::validate_parameters(self::submit_tags_form_parameters(), [
147             'questionid' => $questionid,
148             'contextid' => $contextid,
149             'formdata' => $formdata
150         ]);
152         $editingcontext = \context::instance_by_id($contextid);
153         self::validate_context($editingcontext);
154         parse_str($params['formdata'], $data);
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         }
164         require_once($CFG->libdir . '/questionlib.php');
165         require_once($CFG->dirroot . '/question/type/tags_form.php');
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         ];
174         $mform = new \core_question\form\tags(null, $formoptions, 'post', '', null, $cantag, $data);
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 : [];
183                     core_tag_tag::set_item_tags('core_question', 'question', $validateddata->id,
184                         $questioncontext, $tags);
186                     $result['status'] = true;
187                 }
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);
194                     $result['status'] = true;
195                 }
196             }
197         }
199         return $result;
200     }
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     }