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