MDL-59243 mod_workshop: Move submission creation to API
[moodle.git] / mod / workshop / classes / external.php
CommitLineData
9f1ab2db
JL
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 * Workshop external API
19 *
20 * @package mod_workshop
21 * @category external
22 * @copyright 2017 Juan Leyva <juan@moodle.com>
23 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
24 * @since Moodle 3.4
25 */
26
27defined('MOODLE_INTERNAL') || die;
28
29require_once("$CFG->libdir/externallib.php");
977fdfa3 30require_once($CFG->dirroot . '/mod/workshop/locallib.php');
9f1ab2db
JL
31
32use mod_workshop\external\workshop_summary_exporter;
33
34/**
35 * Workshop external functions
36 *
37 * @package mod_workshop
38 * @category external
39 * @copyright 2017 Juan Leyva <juan@moodle.com>
40 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
41 * @since Moodle 3.4
42 */
43class mod_workshop_external extends external_api {
44
45 /**
46 * Describes the parameters for get_workshops_by_courses.
47 *
48 * @return external_function_parameters
49 * @since Moodle 3.4
50 */
51 public static function get_workshops_by_courses_parameters() {
52 return new external_function_parameters (
53 array(
54 'courseids' => new external_multiple_structure(
55 new external_value(PARAM_INT, 'Course id'), 'Array of course ids', VALUE_DEFAULT, array()
56 ),
57 )
58 );
59 }
60
61 /**
62 * Returns a list of workshops in a provided list of courses.
63 * If no list is provided all workshops that the user can view will be returned.
64 *
65 * @param array $courseids course ids
66 * @return array of warnings and workshops
67 * @since Moodle 3.4
68 */
69 public static function get_workshops_by_courses($courseids = array()) {
70 global $PAGE;
71
72 $warnings = array();
73 $returnedworkshops = array();
74
75 $params = array(
76 'courseids' => $courseids,
77 );
78 $params = self::validate_parameters(self::get_workshops_by_courses_parameters(), $params);
79
80 $mycourses = array();
81 if (empty($params['courseids'])) {
82 $mycourses = enrol_get_my_courses();
83 $params['courseids'] = array_keys($mycourses);
84 }
85
86 // Ensure there are courseids to loop through.
87 if (!empty($params['courseids'])) {
88
89 list($courses, $warnings) = external_util::validate_courses($params['courseids'], $mycourses);
90 $output = $PAGE->get_renderer('core');
91
92 // Get the workshops in this course, this function checks users visibility permissions.
93 // We can avoid then additional validate_context calls.
94 $workshops = get_all_instances_in_courses("workshop", $courses);
95 foreach ($workshops as $workshop) {
96
97 $context = context_module::instance($workshop->coursemodule);
98 // Remove fields that are not from the workshop (added by get_all_instances_in_courses).
99 unset($workshop->coursemodule, $workshop->context, $workshop->visible, $workshop->section, $workshop->groupmode,
100 $workshop->groupingid);
101
102 $exporter = new workshop_summary_exporter($workshop, array('context' => $context));
103 $returnedworkshops[] = $exporter->export($output);
104 }
105 }
106
107 $result = array(
108 'workshops' => $returnedworkshops,
109 'warnings' => $warnings
110 );
111 return $result;
112 }
113
114 /**
115 * Describes the get_workshops_by_courses return value.
116 *
117 * @return external_single_structure
118 * @since Moodle 3.4
119 */
120 public static function get_workshops_by_courses_returns() {
121 return new external_single_structure(
122 array(
123 'workshops' => new external_multiple_structure(
124 workshop_summary_exporter::get_read_structure()
125 ),
126 'warnings' => new external_warnings(),
127 )
128 );
129 }
977fdfa3
JL
130
131 /**
132 * Utility function for validating a workshop.
133 *
134 * @param int $workshopid workshop instance id
135 * @return array array containing the workshop object, course, context and course module objects
136 * @since Moodle 3.4
137 */
138 protected static function validate_workshop($workshopid) {
139 global $DB, $USER;
140
141 // Request and permission validation.
142 $workshop = $DB->get_record('workshop', array('id' => $workshopid), '*', MUST_EXIST);
143 list($course, $cm) = get_course_and_cm_from_instance($workshop, 'workshop');
144
145 $context = context_module::instance($cm->id);
146 self::validate_context($context);
147
148 $workshop = new workshop($workshop, $cm, $course);
149
150 return array($workshop, $course, $cm, $context);
151 }
152
153
154 /**
155 * Describes the parameters for get_workshop_access_information.
156 *
157 * @return external_external_function_parameters
158 * @since Moodle 3.4
159 */
160 public static function get_workshop_access_information_parameters() {
161 return new external_function_parameters (
162 array(
163 'workshopid' => new external_value(PARAM_INT, 'Workshop instance id.')
164 )
165 );
166 }
167
168 /**
169 * Return access information for a given workshop.
170 *
171 * @param int $workshopid workshop instance id
172 * @return array of warnings and the access information
173 * @since Moodle 3.4
174 * @throws moodle_exception
175 */
176 public static function get_workshop_access_information($workshopid) {
177 global $USER;
178
179 $params = self::validate_parameters(self::get_workshop_access_information_parameters(), array('workshopid' => $workshopid));
180
181 list($workshop, $course, $cm, $context) = self::validate_workshop($params['workshopid']);
182
183 $result = array();
184 // Return all the available capabilities.
185 $capabilities = load_capability_def('mod_workshop');
186 foreach ($capabilities as $capname => $capdata) {
187 // Get fields like cansubmit so it is consistent with the access_information function implemented in other modules.
188 $field = 'can' . str_replace('mod/workshop:', '', $capname);
189 $result[$field] = has_capability($capname, $context);
190 }
191
192 // Now, specific features access information.
193 $result['creatingsubmissionallowed'] = $workshop->creating_submission_allowed($USER->id);
194 $result['modifyingsubmissionallowed'] = $workshop->modifying_submission_allowed($USER->id);
195 $result['assessingallowed'] = $workshop->assessing_allowed($USER->id);
196 $result['assessingexamplesallowed'] = $workshop->assessing_examples_allowed();
197 if (is_null($result['assessingexamplesallowed'])) {
198 $result['assessingexamplesallowed'] = false;
199 }
200
201 $result['warnings'] = array();
202 return $result;
203 }
204
205 /**
206 * Describes the get_workshop_access_information return value.
207 *
208 * @return external_single_structure
209 * @since Moodle 3.4
210 */
211 public static function get_workshop_access_information_returns() {
212
213 $structure = array(
214 'creatingsubmissionallowed' => new external_value(PARAM_BOOL,
215 'Is the given user allowed to create their submission?'),
216 'modifyingsubmissionallowed' => new external_value(PARAM_BOOL,
217 'Is the user allowed to modify his existing submission?'),
218 'assessingallowed' => new external_value(PARAM_BOOL,
219 'Is the user allowed to create/edit his assessments?'),
220 'assessingexamplesallowed' => new external_value(PARAM_BOOL,
221 'Are reviewers allowed to create/edit their assessments of the example submissions?.'),
222 'warnings' => new external_warnings()
223 );
224
225 $capabilities = load_capability_def('mod_workshop');
226 foreach ($capabilities as $capname => $capdata) {
227 // Get fields like cansubmit so it is consistent with the access_information function implemented in other modules.
228 $field = 'can' . str_replace('mod/workshop:', '', $capname);
229 $structure[$field] = new external_value(PARAM_BOOL, 'Whether the user has the capability ' . $capname . ' allowed.');
230 }
231
232 return new external_single_structure($structure);
233 }
cd495029
JL
234
235 /**
236 * Describes the parameters for get_user_plan.
237 *
238 * @return external_external_function_parameters
239 * @since Moodle 3.4
240 */
241 public static function get_user_plan_parameters() {
242 return new external_function_parameters (
243 array(
244 'workshopid' => new external_value(PARAM_INT, 'Workshop instance id.'),
245 'userid' => new external_value(PARAM_INT, 'User id (empty or 0 for current user).', VALUE_DEFAULT, 0),
246 )
247 );
248 }
249
250 /**
251 * Return the planner information for the given user.
252 *
253 * @param int $workshopid workshop instance id
254 * @param int $userid user id
255 * @return array of warnings and the user plan
256 * @since Moodle 3.4
257 * @throws moodle_exception
258 */
259 public static function get_user_plan($workshopid, $userid = 0) {
260 global $USER;
261
262 $params = array(
263 'workshopid' => $workshopid,
264 'userid' => $userid,
265 );
266 $params = self::validate_parameters(self::get_user_plan_parameters(), $params);
267
268 list($workshop, $course, $cm, $context) = self::validate_workshop($params['workshopid']);
269
270 // Extra checks so only users with permissions can view other users plans.
271 if (empty($params['userid']) || $params['userid'] == $USER->id) {
272 $userid = $USER->id;
273 } else {
274 require_capability('moodle/course:manageactivities', $context);
275 $user = core_user::get_user($params['userid'], '*', MUST_EXIST);
276 core_user::require_active_user($user);
277 if (!$workshop->check_group_membership($user->id)) {
278 throw new moodle_exception('notingroup');
279 }
280 $userid = $user->id;
281 }
282
283 // Get the user plan information ready for external functions.
284 $userplan = new workshop_user_plan($workshop, $userid);
285 $userplan = array('phases' => $userplan->phases, 'examples' => $userplan->get_examples());
286 foreach ($userplan['phases'] as $phasecode => $phase) {
287 $phase->code = $phasecode;
288 $userplan['phases'][$phasecode] = (array) $phase;
289 foreach ($userplan['phases'][$phasecode]['tasks'] as $taskcode => $task) {
290 $task->code = $taskcode;
291 if ($task->link instanceof moodle_url) {
292 $task->link = $task->link->out(false);
293 }
294 $userplan['phases'][$phasecode]['tasks'][$taskcode] = (array) $task;
295 }
296 foreach ($userplan['phases'][$phasecode]['actions'] as $actioncode => $action) {
297 if ($action->url instanceof moodle_url) {
298 $action->url = $action->url->out(false);
299 }
300 $userplan['phases'][$phasecode]['actions'][$actioncode] = (array) $action;
301 }
302 }
303
304 $result['userplan'] = $userplan;
305 $result['warnings'] = array();
306 return $result;
307 }
308
309 /**
310 * Describes the get_user_plan return value.
311 *
312 * @return external_single_structure
313 * @since Moodle 3.4
314 */
315 public static function get_user_plan_returns() {
316 return new external_single_structure(
317 array(
318 'userplan' => new external_single_structure(
319 array(
320 'phases' => new external_multiple_structure(
321 new external_single_structure(
322 array(
323 'code' => new external_value(PARAM_INT, 'Phase code.'),
324 'title' => new external_value(PARAM_NOTAGS, 'Phase title.'),
325 'active' => new external_value(PARAM_BOOL, 'Whether is the active task.'),
326 'tasks' => new external_multiple_structure(
327 new external_single_structure(
328 array(
329 'code' => new external_value(PARAM_ALPHA, 'Task code.'),
330 'title' => new external_value(PARAM_RAW, 'Task title.'),
331 'link' => new external_value(PARAM_URL, 'Link to task.'),
332 'details' => new external_value(PARAM_RAW, 'Task details.', VALUE_OPTIONAL),
333 'completed' => new external_value(PARAM_NOTAGS,
334 'Completion information (maybe empty, maybe a boolean or generic info.'),
335 )
336 )
337 ),
338 'actions' => new external_multiple_structure(
339 new external_single_structure(
340 array(
341 'type' => new external_value(PARAM_ALPHA, 'Action type.', VALUE_OPTIONAL),
342 'label' => new external_value(PARAM_RAW, 'Action label.', VALUE_OPTIONAL),
343 'url' => new external_value(PARAM_URL, 'Link to action.'),
344 'method' => new external_value(PARAM_ALPHA, 'Get or post.', VALUE_OPTIONAL),
345 )
346 )
347 ),
348 )
349 )
350 ),
351 'examples' => new external_multiple_structure(
352 new external_single_structure(
353 array(
354 'id' => new external_value(PARAM_INT, 'Example submission id.'),
355 'title' => new external_value(PARAM_RAW, 'Example submission title.'),
356 'assessmentid' => new external_value(PARAM_INT, 'Example submission assessment id.'),
357 'grade' => new external_value(PARAM_FLOAT, 'The submission grade.'),
358 'gradinggrade' => new external_value(PARAM_FLOAT, 'The assessment grade.'),
359 )
360 )
361 ),
362 )
363 ),
364 'warnings' => new external_warnings(),
365 )
366 );
367 }
291645f7
JL
368
369 /**
370 * Describes the parameters for view_workshop.
371 *
372 * @return external_function_parameters
373 * @since Moodle 3.4
374 */
375 public static function view_workshop_parameters() {
376 return new external_function_parameters (
377 array(
378 'workshopid' => new external_value(PARAM_INT, 'Workshop instance id'),
379 )
380 );
381 }
382
383 /**
384 * Trigger the course module viewed event and update the module completion status.
385 *
386 * @param int $workshopid workshop instance id
387 * @return array of warnings and status result
388 * @since Moodle 3.4
389 * @throws moodle_exception
390 */
391 public static function view_workshop($workshopid) {
392
393 $params = array('workshopid' => $workshopid);
394 $params = self::validate_parameters(self::view_workshop_parameters(), $params);
395 $warnings = array();
396
397 list($workshop, $course, $cm, $context) = self::validate_workshop($params['workshopid']);
398
399 $workshop->set_module_viewed();
400
401 $result = array(
402 'status' => true,
403 'warnings' => $warnings,
404 );
405 return $result;
406 }
407
408 /**
409 * Describes the view_workshop return value.
410 *
411 * @return external_single_structure
412 * @since Moodle 3.4
413 */
414 public static function view_workshop_returns() {
415 return new external_single_structure(
416 array(
417 'status' => new external_value(PARAM_BOOL, 'status: true if success'),
418 'warnings' => new external_warnings(),
419 )
420 );
421 }
9f1ab2db 422}