ecc48767739a750e8dbe897a276434b557b4a8df
[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                 'formdata' => new external_value(PARAM_RAW, 'The data from the tag form'),
126         ]);
127     }
129     /**
130      * Handles the tags form submission.
131      *
132      * @param string $formdata The question tag form data in a URI encoded param string
133      * @return array The created or modified question tag
134      * @throws moodle_exception
135      */
136     public static function submit_tags_form($formdata) {
137         global $USER, $DB, $CFG;
139         $data = [];
140         $result = ['status' => false];
142         // Parameter validation.
143         $params = self::validate_parameters(self::submit_tags_form_parameters(), ['formdata' => $formdata]);
144         $context = \context_user::instance($USER->id);
146         self::validate_context($context);
147         parse_str($params['formdata'], $data);
149         if (!empty($data['id'])) {
150             $questionid = clean_param($data['id'], PARAM_INT);
151             $question = $DB->get_record('question', array('id' => $questionid));
153             require_once($CFG->libdir . '/questionlib.php');
154             $cantag = question_has_capability_on($question, 'tag');
156             require_once($CFG->dirroot . '/question/type/tags_form.php');
157             $mform = new \core_question\form\tags(null, null, 'post', '', null, $cantag, $data);
159             if ($validateddata = $mform->get_data()) {
160                 // Due to a mform bug, if there's no tags set on the tag element, it submits the name as the value.
161                 // The only way to discover is checking if the tag element is an array.
162                 if ($cantag) {
163                     if (is_array($validateddata->tags)) {
164                         $categorycontext = context::instance_by_id($validateddata->contextid);
166                         core_tag_tag::set_item_tags('core_question', 'question', $validateddata->id,
167                             $categorycontext, $validateddata->tags);
169                         $result['status'] = true;
170                     } else {
171                         // If the tags element is not array, this means we don't have any tags to be set.
172                         // This is the only way to assume the user removed all tags from the question.
173                         core_tag_tag::remove_all_item_tags('core_question', 'question', $validateddata->id);
175                         $result['status'] = true;
176                     }
177                 }
178             }
179         }
181         return $result;
182     }
184     /**
185      * Returns description of method result value.
186      */
187     public static function  submit_tags_form_returns() {
188         return new external_single_structure([
189                 'status' => new external_value(PARAM_BOOL, 'status: true if success')
190         ]);
191     }