MDL-53773 tool_lp: Missing validate_context call in external function
[moodle.git] / admin / tool / lp / classes / external.php
CommitLineData
d9a39950
DW
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 * This is the external API for this tool.
19 *
20 * @package tool_lp
21 * @copyright 2015 Damyon Wiese
22 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
23 */
24namespace tool_lp;
dd1ce763 25defined('MOODLE_INTERNAL') || die();
d9a39950
DW
26
27require_once("$CFG->libdir/externallib.php");
d629323f 28require_once("$CFG->libdir/grade/grade_scale.php");
d9a39950 29
2de75345 30use context;
b6070264 31use context_system;
86938d06 32use context_course;
940235b7 33use context_helper;
86938d06 34use context_user;
80583e0d 35use coding_exception;
d9a39950
DW
36use external_api;
37use external_function_parameters;
38use external_value;
39use external_format_value;
40use external_single_structure;
41use external_multiple_structure;
42use invalid_parameter_exception;
dd1df082 43use required_capability_exception;
81de839f 44
51247ea0 45use tool_lp\external\cohort_summary_exporter;
72018c0a
FM
46use tool_lp\external\competency_path_exporter;
47use tool_lp\external\competency_summary_exporter;
72018c0a
FM
48use tool_lp\external\course_competency_statistics_exporter;
49use tool_lp\external\course_module_summary_exporter;
50use tool_lp\external\course_summary_exporter;
3edcd295 51use tool_lp\external\template_statistics_exporter;
3c659fc2 52use tool_lp\external\user_competency_summary_exporter;
e1964c90 53use tool_lp\external\user_competency_summary_in_course_exporter;
0845a3a0 54use tool_lp\external\user_competency_summary_in_plan_exporter;
71cb304a 55use tool_lp\external\user_evidence_summary_exporter;
65a67e23
DW
56use tool_lp\output\user_competency_summary_in_plan;
57use tool_lp\output\user_competency_summary_in_course;
d9a39950 58
81de839f
FM
59use core_competency\api;
60use core_competency\external\competency_exporter;
61use core_competency\external\competency_framework_exporter;
62use core_competency\external\course_competency_exporter;
63use core_competency\external\course_competency_settings_exporter;
64use core_competency\external\plan_exporter;
65use core_competency\external\template_exporter;
66use core_competency\external\user_competency_course_exporter;
67use core_competency\external\user_competency_exporter;
68use core_competency\external\user_competency_plan_exporter;
69use core_competency\external\user_summary_exporter;
70
d9a39950
DW
71/**
72 * This is the external API for this tool.
73 *
74 * @copyright 2015 Damyon Wiese
75 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
76 */
77class external extends external_api {
78
2de75345
FM
79 /**
80 * Returns a prepared structure to use a context parameters.
81 * @return external_single_structure
82 */
83 protected static function get_context_parameters() {
84 $id = new external_value(
85 PARAM_INT,
86 'Context ID. Either use this value, or level and instanceid.',
87 VALUE_DEFAULT,
88 0
89 );
90 $level = new external_value(
91 PARAM_ALPHA,
92 'Context level. To be used with instanceid.',
93 VALUE_DEFAULT,
94 ''
95 );
96 $instanceid = new external_value(
97 PARAM_INT,
98 'Context instance ID. To be used with level',
99 VALUE_DEFAULT,
100 0
101 );
102 return new external_single_structure(array(
103 'contextid' => $id,
104 'contextlevel' => $level,
105 'instanceid' => $instanceid,
106 ));
107 }
108
d9a39950 109 /**
81de839f 110 * Returns description of data_for_competency_frameworks_manage_page() parameters.
d9a39950 111 *
e90c24d0 112 * @return \external_function_parameters
d9a39950 113 */
81de839f
FM
114 public static function data_for_competency_frameworks_manage_page_parameters() {
115 $params = array('pagecontext' => self::get_context_parameters());
d9a39950
DW
116 return new external_function_parameters($params);
117 }
118
d9a39950 119 /**
81de839f 120 * Loads the data required to render the competency_frameworks_manage_page template.
d9a39950 121 *
81de839f
FM
122 * @param context $pagecontext The page context
123 * @return \stdClass
d9a39950 124 */
81de839f 125 public static function data_for_competency_frameworks_manage_page($pagecontext) {
86938d06
DW
126 global $PAGE;
127
81de839f
FM
128 $params = self::validate_parameters(
129 self::data_for_competency_frameworks_manage_page_parameters(),
130 array(
131 'pagecontext' => $pagecontext
132 )
133 );
134 $context = self::get_context_from_params($params['pagecontext']);
2de75345
FM
135 self::validate_context($context);
136
81de839f
FM
137 $renderable = new output\manage_competency_frameworks_page($context);
138 $renderer = $PAGE->get_renderer('tool_lp');
139
140 $data = $renderable->export_for_template($renderer);
2de75345 141
81de839f 142 return $data;
d9a39950
DW
143 }
144
145 /**
81de839f 146 * Returns description of data_for_competency_frameworks_manage_page() result value.
d9a39950 147 *
e90c24d0 148 * @return \external_description
d9a39950 149 */
81de839f
FM
150 public static function data_for_competency_frameworks_manage_page_returns() {
151 return new external_single_structure(array (
152 'competencyframeworks' => new external_multiple_structure(
153 competency_framework_exporter::get_read_structure()
154 ),
155 'pluginbaseurl' => new external_value(PARAM_LOCALURL, 'Url to the tool_lp plugin folder on this Moodle site'),
156 'navigation' => new external_multiple_structure(
157 new external_value(PARAM_RAW, 'HTML for a navigation item that should be on this page')
158 ),
159 'pagecontextid' => new external_value(PARAM_INT, 'The page context id')
160 ));
161
d9a39950
DW
162 }
163
164 /**
81de839f 165 * Returns description of data_for_competencies_manage_page() parameters.
d9a39950 166 *
e90c24d0 167 * @return \external_function_parameters
d9a39950 168 */
81de839f
FM
169 public static function data_for_competencies_manage_page_parameters() {
170 $competencyframeworkid = new external_value(
d9a39950 171 PARAM_INT,
81de839f 172 'The competency framework id',
d9a39950
DW
173 VALUE_REQUIRED
174 );
81de839f
FM
175 $search = new external_value(
176 PARAM_RAW,
177 'A search string',
178 VALUE_DEFAULT,
179 ''
180 );
d9a39950 181 $params = array(
81de839f
FM
182 'competencyframeworkid' => $competencyframeworkid,
183 'search' => $search
d9a39950
DW
184 );
185 return new external_function_parameters($params);
186 }
187
d9a39950 188 /**
81de839f 189 * Loads the data required to render the competencies_manage_page template.
d9a39950 190 *
81de839f
FM
191 * @param int $competencyframeworkid Framework id.
192 * @param string $search Text to search.
193 *
194 * @return boolean
d9a39950 195 */
81de839f 196 public static function data_for_competencies_manage_page($competencyframeworkid, $search) {
86938d06
DW
197 global $PAGE;
198
91e54642
FM
199 $params = self::validate_parameters(self::data_for_competencies_manage_page_parameters(), array(
200 'competencyframeworkid' => $competencyframeworkid,
201 'search' => $search
202 ));
d9a39950 203
81de839f 204 $framework = api::read_framework($params['competencyframeworkid']);
86938d06
DW
205 self::validate_context($framework->get_context());
206 $output = $PAGE->get_renderer('tool_lp');
81de839f
FM
207
208 $renderable = new output\manage_competencies_page($framework, $params['search'], $framework->get_context());
209
210 $data = $renderable->export_for_template($output);
211
212 return $data;
d9a39950
DW
213 }
214
215 /**
81de839f 216 * Returns description of data_for_competencies_manage_page() result value.
d9a39950 217 *
e90c24d0 218 * @return \external_description
d9a39950 219 */
81de839f
FM
220 public static function data_for_competencies_manage_page_returns() {
221 return new external_single_structure(array (
222 'framework' => competency_framework_exporter::get_read_structure(),
223 'canmanage' => new external_value(PARAM_BOOL, 'True if this user has permission to manage competency frameworks'),
224 'pagecontextid' => new external_value(PARAM_INT, 'Context id for the framework'),
225 'search' => new external_value(PARAM_RAW, 'Current search string'),
226 'rulesmodules' => new external_value(PARAM_RAW, 'JSON encoded data for rules'),
227 'pluginbaseurl' => new external_value(PARAM_RAW, 'Plugin base url')
228 ));
229
d9a39950
DW
230 }
231
3e6a8e16 232 /**
81de839f 233 * Returns description of data_for_competency_summary() parameters.
3e6a8e16
IT
234 *
235 * @return \external_function_parameters
236 */
81de839f
FM
237 public static function data_for_competency_summary_parameters() {
238 $competencyid = new external_value(
3e6a8e16
IT
239 PARAM_INT,
240 'The competency id',
241 VALUE_REQUIRED
242 );
81de839f
FM
243 $includerelated = new external_value(
244 PARAM_BOOL,
245 'Include or not related competencies',
246 VALUE_DEFAULT,
247 false
248 );
249 $includecourses = new external_value(
250 PARAM_BOOL,
251 'Include or not competency courses',
252 VALUE_DEFAULT,
253 false
254 );
3e6a8e16 255 $params = array(
81de839f
FM
256 'competencyid' => $competencyid,
257 'includerelated' => $includerelated,
258 'includecourses' => $includecourses
3e6a8e16
IT
259 );
260 return new external_function_parameters($params);
261 }
262
263 /**
81de839f 264 * Loads the data required to render the competency_page template.
3e6a8e16 265 *
81de839f
FM
266 * @param int $competencyid Competency id.
267 * @param boolean $includerelated Include or not related competencies.
268 * @param boolean $includecourses Include or not competency courses.
269 *
270 * @return \stdClass
3e6a8e16 271 */
81de839f
FM
272 public static function data_for_competency_summary($competencyid, $includerelated = false, $includecourses = false) {
273 global $PAGE;
91e54642
FM
274 $params = self::validate_parameters(self::data_for_competency_summary_parameters(), array(
275 'competencyid' => $competencyid,
276 'includerelated' => $includerelated,
277 'includecourses' => $includecourses
278 ));
81de839f
FM
279
280 $competency = api::read_competency($params['competencyid']);
281 $framework = api::read_framework($competency->get_competencyframeworkid());
5aa9ded5 282 self::validate_context($framework->get_context());
81de839f
FM
283 $renderable = new output\competency_summary($competency, $framework, $params['includerelated'], $params['includecourses']);
284 $renderer = $PAGE->get_renderer('tool_lp');
285
286 $data = $renderable->export_for_template($renderer);
287
288 return $data;
3e6a8e16
IT
289 }
290
291 /**
81de839f 292 * Returns description of data_for_competency_summary_() result value.
3e6a8e16
IT
293 *
294 * @return \external_description
295 */
81de839f
FM
296 public static function data_for_competency_summary_returns() {
297 return competency_summary_exporter::get_read_structure();
3e6a8e16
IT
298 }
299
c61db7bb 300 /**
81de839f 301 * Returns description of list_courses_using_competency() parameters.
c61db7bb
IT
302 *
303 * @return \external_function_parameters
304 */
81de839f
FM
305 public static function list_courses_using_competency_parameters() {
306 $competencyid = new external_value(
c61db7bb 307 PARAM_INT,
81de839f 308 'The competency id',
c61db7bb
IT
309 VALUE_REQUIRED
310 );
c61db7bb 311 $params = array(
81de839f 312 'id' => $competencyid,
c61db7bb
IT
313 );
314 return new external_function_parameters($params);
315 }
316
c61db7bb 317 /**
81de839f 318 * Count the courses (visible to this user) that use this competency.
c61db7bb 319 *
81de839f
FM
320 * @param int $competencyid Competency id.
321 * @return array
c61db7bb 322 */
81de839f 323 public static function list_courses_using_competency($competencyid) {
37798262 324 global $PAGE;
c61db7bb 325
81de839f
FM
326 $params = self::validate_parameters(self::list_courses_using_competency_parameters(), array(
327 'id' => $competencyid,
328 ));
86938d06 329
81de839f
FM
330 $competency = api::read_competency($params['id']);
331 self::validate_context($competency->get_context());
37798262 332 $output = $PAGE->get_renderer('tool_lp');
81de839f
FM
333
334 $results = array();
335 $courses = api::list_courses_using_competency($params['id']);
336 foreach ($courses as $course) {
337 $context = context_course::instance($course->id);
338 $exporter = new course_summary_exporter($course, array('context' => $context));
339 $result = $exporter->export($output);
340 array_push($results, $result);
341 }
342 return $results;
c61db7bb
IT
343 }
344
345 /**
81de839f 346 * Returns description of list_courses_using_competency() result value.
c61db7bb
IT
347 *
348 * @return \external_description
349 */
81de839f
FM
350 public static function list_courses_using_competency_returns() {
351 return new external_multiple_structure(course_summary_exporter::get_read_structure());
c61db7bb
IT
352 }
353
81de839f 354
d9a39950 355 /**
81de839f 356 * Returns description of data_for_course_competenies_page() parameters.
d9a39950 357 *
e90c24d0 358 * @return \external_function_parameters
d9a39950 359 */
81de839f
FM
360 public static function data_for_course_competencies_page_parameters() {
361 $courseid = new external_value(
d9a39950 362 PARAM_INT,
81de839f 363 'The course id',
d9a39950
DW
364 VALUE_REQUIRED
365 );
81de839f 366 $params = array('courseid' => $courseid);
d9a39950
DW
367 return new external_function_parameters($params);
368 }
369
d9a39950 370 /**
81de839f 371 * Loads the data required to render the course_competencies_page template.
d9a39950 372 *
81de839f 373 * @param int $courseid The course id to check.
d9a39950
DW
374 * @return boolean
375 */
81de839f
FM
376 public static function data_for_course_competencies_page($courseid) {
377 global $PAGE;
91e54642
FM
378 $params = self::validate_parameters(self::data_for_course_competencies_page_parameters(), array(
379 'courseid' => $courseid,
380 ));
81de839f 381 self::validate_context(context_course::instance($params['courseid']));
d9a39950 382
81de839f
FM
383 $renderable = new output\course_competencies_page($params['courseid']);
384 $renderer = $PAGE->get_renderer('tool_lp');
d9a39950 385
81de839f 386 $data = $renderable->export_for_template($renderer);
d9a39950 387
81de839f 388 return $data;
d9a39950
DW
389 }
390
d9a39950 391 /**
81de839f 392 * Returns description of data_for_course_competencies_page() result value.
d9a39950 393 *
81de839f 394 * @return \external_description
d9a39950 395 */
81de839f
FM
396 public static function data_for_course_competencies_page_returns() {
397 $ucc = user_competency_course_exporter::get_read_structure();
398 $ucc->required = VALUE_OPTIONAL;
d9a39950 399
81de839f
FM
400 return new external_single_structure(array (
401 'courseid' => new external_value(PARAM_INT, 'The current course id'),
402 'pagecontextid' => new external_value(PARAM_INT, 'The current page context ID.'),
403 'gradableuserid' => new external_value(PARAM_INT, 'Current user id, if the user is a gradable user.', VALUE_OPTIONAL),
404 'canmanagecompetencyframeworks' => new external_value(PARAM_BOOL, 'User can manage competency frameworks'),
405 'canmanagecoursecompetencies' => new external_value(PARAM_BOOL, 'User can manage linked course competencies'),
406 'canconfigurecoursecompetencies' => new external_value(PARAM_BOOL, 'User can configure course competency settings'),
407 'settings' => course_competency_settings_exporter::get_read_structure(),
408 'statistics' => course_competency_statistics_exporter::get_read_structure(),
409 'competencies' => new external_multiple_structure(new external_single_structure(array(
410 'competency' => competency_exporter::get_read_structure(),
411 'coursecompetency' => course_competency_exporter::get_read_structure(),
412 'coursemodules' => new external_multiple_structure(course_module_summary_exporter::get_read_structure()),
413 'usercompetencycourse' => $ucc,
414 'ruleoutcomeoptions' => new external_multiple_structure(
415 new external_single_structure(array(
416 'value' => new external_value(PARAM_INT, 'The option value'),
417 'text' => new external_value(PARAM_NOTAGS, 'The name of the option'),
418 'selected' => new external_value(PARAM_BOOL, 'If this is the currently selected option'),
91e54642
FM
419 ))
420 ),
81de839f
FM
421 'comppath' => competency_path_exporter::get_read_structure(),
422 ))),
423 'manageurl' => new external_value(PARAM_LOCALURL, 'Url to the manage competencies page.'),
424 ));
d9a39950 425
d9a39950
DW
426 }
427
428 /**
81de839f 429 * Returns description of data_for_templates_manage_page() parameters.
d9a39950 430 *
e90c24d0 431 * @return \external_function_parameters
d9a39950 432 */
81de839f
FM
433 public static function data_for_templates_manage_page_parameters() {
434 $params = array('pagecontext' => self::get_context_parameters());
2de75345 435 return new external_function_parameters($params);
d9a39950
DW
436 }
437
d9a39950 438 /**
81de839f 439 * Loads the data required to render the templates_manage_page template.
b17d3d10 440 *
81de839f
FM
441 * @param array $pagecontext The page context info.
442 * @return boolean
d9a39950 443 */
81de839f 444 public static function data_for_templates_manage_page($pagecontext) {
86938d06
DW
445 global $PAGE;
446
81de839f
FM
447 $params = self::validate_parameters(self::data_for_templates_manage_page_parameters(), array(
448 'pagecontext' => $pagecontext
449 ));
450 $context = self::get_context_from_params($params['pagecontext']);
2de75345
FM
451 self::validate_context($context);
452
81de839f
FM
453 $renderable = new output\manage_templates_page($context);
454 $renderer = $PAGE->get_renderer('tool_lp');
d9a39950 455
81de839f
FM
456 $data = $renderable->export_for_template($renderer);
457
458 return $data;
d9a39950
DW
459 }
460
461 /**
81de839f 462 * Returns description of data_for_templates_manage_page() result value.
d9a39950 463 *
e90c24d0 464 * @return \external_description
d9a39950 465 */
81de839f
FM
466 public static function data_for_templates_manage_page_returns() {
467 return new external_single_structure(array (
468 'templates' => new external_multiple_structure(
469 template_exporter::get_read_structure()
470 ),
471 'pluginbaseurl' => new external_value(PARAM_LOCALURL, 'Url to the tool_lp plugin folder on this Moodle site'),
472 'navigation' => new external_multiple_structure(
473 new external_value(PARAM_RAW, 'HTML for a navigation item that should be on this page')
474 ),
475 'pagecontextid' => new external_value(PARAM_INT, 'The page context id'),
476 'canmanage' => new external_value(PARAM_BOOL, 'Whether the user manage the templates')
477 ));
478
d9a39950
DW
479 }
480
481 /**
81de839f 482 * Returns description of data_for_template_competenies_page() parameters.
d9a39950 483 *
e90c24d0 484 * @return \external_function_parameters
d9a39950 485 */
81de839f
FM
486 public static function data_for_template_competencies_page_parameters() {
487 $templateid = new external_value(
488 PARAM_INT,
489 'The template id',
490 VALUE_REQUIRED
d9a39950 491 );
81de839f 492 $params = array('templateid' => $templateid, 'pagecontext' => self::get_context_parameters());
d9a39950
DW
493 return new external_function_parameters($params);
494 }
495
d9a39950 496 /**
81de839f 497 * Loads the data required to render the template_competencies_page template.
d9a39950 498 *
81de839f
FM
499 * @param int $templateid Template id.
500 * @param array $pagecontext The page context info.
501 * @return boolean
d9a39950 502 */
81de839f
FM
503 public static function data_for_template_competencies_page($templateid, $pagecontext) {
504 global $PAGE;
91e54642
FM
505 $params = self::validate_parameters(self::data_for_template_competencies_page_parameters(), array(
506 'templateid' => $templateid,
507 'pagecontext' => $pagecontext
508 ));
d9a39950 509
81de839f 510 $context = self::get_context_from_params($params['pagecontext']);
f610a957 511 self::validate_context($context);
d9a39950 512
81de839f
FM
513 $template = api::read_template($params['templateid']);
514 $renderable = new output\template_competencies_page($template, $context);
515 $renderer = $PAGE->get_renderer('tool_lp');
516
517 $data = $renderable->export_for_template($renderer);
518
519 return $data;
d9a39950
DW
520 }
521
522 /**
81de839f 523 * Returns description of data_for_template_competencies_page() result value.
d9a39950 524 *
e90c24d0 525 * @return \external_description
d9a39950 526 */
81de839f
FM
527 public static function data_for_template_competencies_page_returns() {
528 return new external_single_structure(array (
529 'template' => template_exporter::get_read_structure(),
530 'pagecontextid' => new external_value(PARAM_INT, 'Context ID'),
531 'canmanagecompetencyframeworks' => new external_value(PARAM_BOOL, 'User can manage competency frameworks'),
532 'canmanagetemplatecompetencies' => new external_value(PARAM_BOOL, 'User can manage learning plan templates'),
533 'competencies' => new external_multiple_structure(
534 competency_summary_exporter::get_read_structure()
535 ),
536 'manageurl' => new external_value(PARAM_LOCALURL, 'Url to the manage competencies page.'),
537 'pluginbaseurl' => new external_value(PARAM_LOCALURL, 'Base URL of the plugin.'),
538 'statistics' => template_statistics_exporter::get_read_structure()
539 ));
540
d9a39950
DW
541 }
542
f73a29c1 543 /**
81de839f 544 * Returns description of data_for_plan_competenies_page() parameters.
f73a29c1
IT
545 *
546 * @return \external_function_parameters
547 */
81de839f
FM
548 public static function data_for_plan_page_parameters() {
549 $planid = new external_value(
f73a29c1 550 PARAM_INT,
81de839f 551 'The plan id',
f73a29c1
IT
552 VALUE_REQUIRED
553 );
81de839f 554 $params = array('planid' => $planid);
f73a29c1
IT
555 return new external_function_parameters($params);
556 }
557
558 /**
81de839f 559 * Loads the data required to render the plan_page template.
f73a29c1 560 *
81de839f 561 * @param int $planid Learning Plan id.
f73a29c1
IT
562 * @return boolean
563 */
81de839f
FM
564 public static function data_for_plan_page($planid) {
565 global $PAGE;
91e54642
FM
566 $params = self::validate_parameters(self::data_for_plan_page_parameters(), array(
567 'planid' => $planid
568 ));
81de839f
FM
569 $plan = api::read_plan($params['planid']);
570 self::validate_context($plan->get_context());
571
572 $renderable = new output\plan_page($plan);
573 $renderer = $PAGE->get_renderer('tool_lp');
f73a29c1 574
81de839f
FM
575 $data = $renderable->export_for_template($renderer);
576
577 return $data;
f73a29c1
IT
578 }
579
580 /**
81de839f 581 * Returns description of data_for_plan_page() result value.
f73a29c1
IT
582 *
583 * @return \external_description
584 */
81de839f
FM
585 public static function data_for_plan_page_returns() {
586 $uc = user_competency_exporter::get_read_structure();
587 $ucp = user_competency_plan_exporter::get_read_structure();
588
589 $uc->required = VALUE_OPTIONAL;
590 $ucp->required = VALUE_OPTIONAL;
591
592 return new external_single_structure(array (
593 'plan' => plan_exporter::get_read_structure(),
594 'contextid' => new external_value(PARAM_INT, 'Context ID.'),
595 'pluginbaseurl' => new external_value(PARAM_URL, 'Plugin base URL.'),
596 'competencies' => new external_multiple_structure(
597 new external_single_structure(array(
598 'competency' => competency_exporter::get_read_structure(),
599 'comppath' => competency_path_exporter::get_read_structure(),
600 'usercompetency' => $uc,
601 'usercompetencyplan' => $ucp
602 ))
603 ),
604 'competencycount' => new external_value(PARAM_INT, 'Count of competencies'),
605 'proficientcompetencycount' => new external_value(PARAM_INT, 'Count of proficientcompetencies'),
606 'proficientcompetencypercentage' => new external_value(PARAM_FLOAT, 'Percentage of competencies proficient'),
607 'proficientcompetencypercentageformatted' => new external_value(PARAM_RAW, 'Displayable percentage'),
608 ));
f73a29c1
IT
609 }
610
d9a39950 611 /**
81de839f 612 * Returns description of data_for_plans_page() parameters.
d9a39950 613 *
e90c24d0 614 * @return \external_function_parameters
d9a39950 615 */
81de839f
FM
616 public static function data_for_plans_page_parameters() {
617 $userid = new external_value(
618 PARAM_INT,
619 'The user id',
620 VALUE_REQUIRED
621 );
622 $params = array('userid' => $userid);
d9a39950
DW
623 return new external_function_parameters($params);
624 }
625
d9a39950 626 /**
81de839f 627 * Loads the data required to render the plans_page template.
d9a39950 628 *
81de839f
FM
629 * @param int $userid User id.
630 * @return boolean
d9a39950 631 */
81de839f 632 public static function data_for_plans_page($userid) {
d9a39950
DW
633 global $PAGE;
634
91e54642
FM
635 $params = self::validate_parameters(self::data_for_plans_page_parameters(), array(
636 'userid' => $userid,
637 ));
2de75345 638
81de839f
FM
639 $context = context_user::instance($params['userid']);
640 self::validate_context($context);
641 $output = $PAGE->get_renderer('tool_lp');
d9a39950 642
81de839f 643 $renderable = new \tool_lp\output\plans_page($params['userid']);
d9a39950 644
81de839f 645 return $renderable->export_for_template($output);
d9a39950
DW
646 }
647
648 /**
81de839f 649 * Returns description of data_for_plans_page() result value.
d9a39950 650 *
e90c24d0 651 * @return \external_description
d9a39950 652 */
81de839f 653 public static function data_for_plans_page_returns() {
d9a39950 654 return new external_single_structure(array (
81de839f
FM
655 'userid' => new external_value(PARAM_INT, 'The learning plan user id'),
656 'plans' => new external_multiple_structure(
657 plan_exporter::get_read_structure()
d9a39950
DW
658 ),
659 'pluginbaseurl' => new external_value(PARAM_LOCALURL, 'Url to the tool_lp plugin folder on this Moodle site'),
660 'navigation' => new external_multiple_structure(
661 new external_value(PARAM_RAW, 'HTML for a navigation item that should be on this page')
37798262 662 ),
81de839f
FM
663 'canreaduserevidence' => new external_value(PARAM_BOOL, 'Can the current user view the user\'s evidence'),
664 'canmanageuserplans' => new external_value(PARAM_BOOL, 'Can the current user manage the user\'s plans'),
d9a39950 665 ));
d9a39950
DW
666 }
667
d9a39950 668 /**
81de839f 669 * Returns description of external function parameters.
d9a39950 670 *
e90c24d0 671 * @return \external_function_parameters
d9a39950 672 */
81de839f
FM
673 public static function data_for_user_evidence_list_page_parameters() {
674 return new external_function_parameters(array(
675 'userid' => new external_value(PARAM_INT, 'The user ID')
676 ));
d9a39950
DW
677 }
678
679 /**
81de839f 680 * Loads the data required to render the user_evidence_list_page template.
d9a39950 681 *
81de839f
FM
682 * @param int $userid User id.
683 * @return boolean
8ec5f810 684 */
81de839f 685 public static function data_for_user_evidence_list_page($userid) {
86938d06 686 global $PAGE;
81de839f
FM
687 $params = self::validate_parameters(self::data_for_user_evidence_list_page_parameters(),
688 array('userid' => $userid));
86938d06 689
81de839f 690 $context = context_user::instance($params['userid']);
86938d06
DW
691 self::validate_context($context);
692 $output = $PAGE->get_renderer('tool_lp');
693
81de839f
FM
694 $renderable = new \tool_lp\output\user_evidence_list_page($params['userid']);
695 return $renderable->export_for_template($output);
d9a39950
DW
696 }
697
698 /**
81de839f 699 * Returns description of external function result value.
d9a39950 700 *
e90c24d0 701 * @return \external_description
d9a39950 702 */
81de839f
FM
703 public static function data_for_user_evidence_list_page_returns() {
704 return new external_single_structure(array (
705 'canmanage' => new external_value(PARAM_BOOL, 'Can the current user manage the user\'s evidence'),
706 'userid' => new external_value(PARAM_INT, 'The user ID'),
707 'pluginbaseurl' => new external_value(PARAM_LOCALURL, 'Url to the tool_lp plugin folder on this Moodle site'),
708 'evidence' => new external_multiple_structure(user_evidence_summary_exporter::get_read_structure()),
709 'navigation' => new external_multiple_structure(
710 new external_value(PARAM_RAW, 'HTML for a navigation item that should be on this page')
711 ),
712 ));
d9a39950
DW
713 }
714
715 /**
81de839f 716 * Returns description of external function parameters.
d9a39950 717 *
e90c24d0 718 * @return \external_function_parameters
d9a39950 719 */
81de839f
FM
720 public static function data_for_user_evidence_page_parameters() {
721 return new external_function_parameters(array(
722 'id' => new external_value(PARAM_INT, 'The user evidence ID')
723 ));
d9a39950
DW
724 }
725
d9a39950 726 /**
81de839f 727 * Loads the data required to render the user_evidence_page template.
d9a39950 728 *
81de839f
FM
729 * @param int $id User id.
730 * @return boolean
d9a39950 731 */
81de839f 732 public static function data_for_user_evidence_page($id) {
86938d06 733 global $PAGE;
81de839f
FM
734 $params = self::validate_parameters(self::data_for_user_evidence_page_parameters(),
735 array('id' => $id));
86938d06 736
81de839f
FM
737 $userevidence = api::read_user_evidence($id);
738 self::validate_context($userevidence->get_context());
86938d06 739 $output = $PAGE->get_renderer('tool_lp');
81de839f
FM
740
741 $renderable = new \tool_lp\output\user_evidence_page($userevidence);
742 return $renderable->export_for_template($output);
d9a39950
DW
743 }
744
745 /**
81de839f 746 * Returns description of external function result value.
d9a39950 747 *
e90c24d0 748 * @return \external_description
d9a39950 749 */
81de839f
FM
750 public static function data_for_user_evidence_page_returns() {
751 return new external_single_structure(array(
752 'userevidence' => user_evidence_summary_exporter::get_read_structure(),
753 'pluginbaseurl' => new external_value(PARAM_LOCALURL, 'Url to the tool_lp plugin folder on this Moodle site')
754 ));
d9a39950
DW
755 }
756
757 /**
81de839f 758 * Returns the description of the data_for_related_competencies_section_parameters() parameters.
d9a39950 759 *
81de839f 760 * @return external_function_parameters.
d9a39950 761 */
81de839f
FM
762 public static function data_for_related_competencies_section_parameters() {
763 $competencyid = new external_value(
d9a39950 764 PARAM_INT,
81de839f 765 'The competency id',
d9a39950
DW
766 VALUE_REQUIRED
767 );
81de839f 768 return new external_function_parameters(array('competencyid' => $competencyid));
d9a39950
DW
769 }
770
d9a39950 771 /**
81de839f 772 * Data to render in the related competencies section.
b17d3d10 773 *
81de839f
FM
774 * @param int $competencyid
775 * @return array Related competencies and whether to show delete action button or not.
d9a39950 776 */
81de839f 777 public static function data_for_related_competencies_section($competencyid) {
86938d06
DW
778 global $PAGE;
779
91e54642
FM
780 $params = self::validate_parameters(self::data_for_related_competencies_section_parameters(), array(
781 'competencyid' => $competencyid,
782 ));
81de839f
FM
783 $competency = api::read_competency($params['competencyid']);
784 self::validate_context($competency->get_context());
d9a39950 785
81de839f
FM
786 $renderable = new \tool_lp\output\related_competencies($params['competencyid']);
787 $renderer = $PAGE->get_renderer('tool_lp');
8ec5f810 788
81de839f 789 return $renderable->export_for_template($renderer);
d9a39950
DW
790 }
791
792 /**
81de839f 793 * Returns description of data_for_related_competencies_section_returns() result value.
d9a39950 794 *
81de839f 795 * @return external_description
d9a39950 796 */
81de839f
FM
797 public static function data_for_related_competencies_section_returns() {
798 return new external_single_structure(array(
799 'relatedcompetencies' => new external_multiple_structure(competency_exporter::get_read_structure()),
800 'showdeleterelatedaction' => new external_value(PARAM_BOOL, 'Whether to show the delete relation link or not')
801 ));
d9a39950
DW
802 }
803
804 /**
81de839f 805 * Returns the description of external function parameters.
d9a39950 806 *
81de839f 807 * @return external_function_parameters.
d9a39950 808 */
81de839f
FM
809 public static function search_users_parameters() {
810 $query = new external_value(
d9a39950 811 PARAM_RAW,
81de839f
FM
812 'Query string'
813 );
814 $capability = new external_value(
815 PARAM_RAW,
816 'Required capability'
d9a39950 817 );
81de839f 818 $limitfrom = new external_value(
d9a39950 819 PARAM_INT,
81de839f
FM
820 'Number of records to skip',
821 VALUE_DEFAULT,
822 0
d9a39950 823 );
81de839f
FM
824 $limitnum = new external_value(
825 PARAM_RAW,
826 'Number of records to fetch',
827 VALUE_DEFAULT,
828 100
d9a39950 829 );
81de839f
FM
830 return new external_function_parameters(array(
831 'query' => $query,
832 'capability' => $capability,
833 'limitfrom' => $limitfrom,
834 'limitnum' => $limitnum
835 ));
d9a39950
DW
836 }
837
b17d3d10 838 /**
81de839f 839 * Search users.
b17d3d10 840 *
81de839f
FM
841 * @param string $query
842 * @param string $capability
843 * @param int $limitfrom
844 * @param int $limitnum
b17d3d10
AA
845 * @return array
846 */
81de839f
FM
847 public static function search_users($query, $capability = '', $limitfrom = 0, $limitnum = 100) {
848 global $DB, $CFG, $PAGE, $USER;
86938d06 849
91e54642
FM
850 $params = self::validate_parameters(self::search_users_parameters(), array(
851 'query' => $query,
852 'capability' => $capability,
853 'limitfrom' => $limitfrom,
854 'limitnum' => $limitnum,
855 ));
81de839f
FM
856 $query = $params['query'];
857 $cap = $params['capability'];
858 $limitfrom = $params['limitfrom'];
859 $limitnum = $params['limitnum'];
d9a39950 860
81de839f 861 $context = context_system::instance();
86938d06
DW
862 self::validate_context($context);
863 $output = $PAGE->get_renderer('tool_lp');
864
81de839f
FM
865 list($filtercapsql, $filtercapparams) = api::filter_users_with_capability_on_user_context_sql($cap,
866 $USER->id, SQL_PARAMS_NAMED);
aec5363e 867
81de839f
FM
868 $extrasearchfields = array();
869 if (!empty($CFG->showuseridentity) && has_capability('moodle/site:viewuseridentity', $context)) {
870 $extrasearchfields = explode(',', $CFG->showuseridentity);
d9a39950 871 }
81de839f 872 $fields = \user_picture::fields('u', $extrasearchfields);
4f815459 873
81de839f
FM
874 list($wheresql, $whereparams) = users_search_sql($query, 'u', true, $extrasearchfields);
875 list($sortsql, $sortparams) = users_order_by_sql('u', $query, $context);
d9a39950 876
81de839f
FM
877 $countsql = "SELECT COUNT('x') FROM {user} u WHERE $wheresql AND u.id $filtercapsql";
878 $countparams = $whereparams + $filtercapparams;
879 $sql = "SELECT $fields FROM {user} u WHERE $wheresql AND u.id $filtercapsql ORDER BY $sortsql";
880 $params = $whereparams + $filtercapparams + $sortparams;
d9a39950 881
81de839f
FM
882 $count = $DB->count_records_sql($countsql, $countparams);
883 $result = $DB->get_recordset_sql($sql, $params, $limitfrom, $limitnum);
d9a39950 884
81de839f
FM
885 $users = array();
886 foreach ($result as $key => $user) {
887 // Make sure all required fields are set.
888 foreach (user_summary_exporter::define_properties() as $propertykey => $definition) {
889 if (empty($user->$propertykey) || !in_array($propertykey, $extrasearchfields)) {
890 if ($propertykey != 'id') {
891 $user->$propertykey = '';
892 }
893 }
894 }
895 $exporter = new user_summary_exporter($user);
896 $newuser = $exporter->export($output);
64020153 897
81de839f
FM
898 $users[$key] = $newuser;
899 }
900 $result->close();
64020153 901
81de839f
FM
902 return array(
903 'users' => $users,
904 'count' => $count
905 );
64020153
IT
906 }
907
908 /**
81de839f 909 * Returns description of external function result value.
64020153 910 *
81de839f 911 * @return external_description
64020153 912 */
81de839f
FM
913 public static function search_users_returns() {
914 global $CFG;
915 require_once($CFG->dirroot . '/user/externallib.php');
916 return new external_single_structure(array(
917 'users' => new external_multiple_structure(user_summary_exporter::get_read_structure()),
918 'count' => new external_value(PARAM_INT, 'Total number of results.')
919 ));
64020153
IT
920 }
921
922 /**
81de839f 923 * Returns the description of external function parameters.
64020153 924 *
81de839f 925 * @return external_function_parameters
64020153 926 */
81de839f
FM
927 public static function search_cohorts_parameters() {
928 $query = new external_value(
929 PARAM_RAW,
930 'Query string'
64020153 931 );
81de839f
FM
932 $includes = new external_value(
933 PARAM_ALPHA,
934 'What other contexts to fetch the frameworks from. (all, parents, self)',
935 VALUE_DEFAULT,
936 'parents'
64020153 937 );
81de839f 938 $limitfrom = new external_value(
64020153 939 PARAM_INT,
81de839f
FM
940 'limitfrom we are fetching the records from',
941 VALUE_DEFAULT,
942 0
64020153 943 );
81de839f
FM
944 $limitnum = new external_value(
945 PARAM_INT,
946 'Number of records to fetch',
947 VALUE_DEFAULT,
948 25
64020153 949 );
81de839f
FM
950 return new external_function_parameters(array(
951 'query' => $query,
952 'context' => self::get_context_parameters(),
953 'includes' => $includes,
954 'limitfrom' => $limitfrom,
955 'limitnum' => $limitnum
956 ));
64020153
IT
957 }
958
959 /**
81de839f
FM
960 * Search cohorts.
961 * TODO: MDL-52243 Move this function to cohorts/externallib.php
64020153 962 *
81de839f
FM
963 * @param string $query
964 * @param array $context
965 * @param string $includes
966 * @param int $limitfrom
967 * @param int $limitnum
968 * @return array
64020153 969 */
81de839f
FM
970 public static function search_cohorts($query, $context, $includes = 'parents', $limitfrom = 0, $limitnum = 25) {
971 global $DB, $CFG, $PAGE;
972 require_once($CFG->dirroot . '/cohort/lib.php');
973
91e54642
FM
974 $params = self::validate_parameters(self::search_cohorts_parameters(), array(
975 'query' => $query,
976 'context' => $context,
977 'includes' => $includes,
978 'limitfrom' => $limitfrom,
979 'limitnum' => $limitnum,
980 ));
81de839f
FM
981 $query = $params['query'];
982 $includes = $params['includes'];
983 $context = self::get_context_from_params($params['context']);
984 $limitfrom = $params['limitfrom'];
985 $limitnum = $params['limitnum'];
986
987 self::validate_context($context);
988 $output = $PAGE->get_renderer('tool_lp');
989
990 $manager = has_capability('moodle/cohort:manage', $context);
991 if (!$manager) {
992 require_capability('moodle/cohort:view', $context);
993 }
994
995 // TODO Make this more efficient.
996 if ($includes == 'self') {
997 $results = cohort_get_cohorts($context->id, $limitfrom, $limitnum, $query);
998 $results = $results['cohorts'];
999 } else if ($includes == 'parents') {
1000 $results = cohort_get_cohorts($context->id, $limitfrom, $limitnum, $query);
1001 $results = $results['cohorts'];
1002 if (!$context instanceof context_system) {
1003 $results = array_merge($results, cohort_get_available_cohorts($context, COHORT_ALL, $limitfrom, $limitnum, $query));
1004 }
1005 } else if ($includes == 'all') {
1006 $results = cohort_get_all_cohorts($limitfrom, $limitnum, $query);
1007 $results = $results['cohorts'];
1008 } else {
1009 throw new coding_exception('Invalid parameter value for \'includes\'.');
1010 }
1011
1012 $cohorts = array();
1013 foreach ($results as $key => $cohort) {
1014 $cohortcontext = context::instance_by_id($cohort->contextid);
1015 $exporter = new cohort_summary_exporter($cohort, array('context' => $cohortcontext));
1016 $newcohort = $exporter->export($output);
64020153 1017
81de839f
FM
1018 $cohorts[$key] = $newcohort;
1019 }
1020
1021 return array('cohorts' => $cohorts);
64020153
IT
1022 }
1023
1024 /**
81de839f 1025 * Returns description of external function result value.
64020153 1026 *
81de839f 1027 * @return external_description
64020153 1028 */
81de839f
FM
1029 public static function search_cohorts_returns() {
1030 return new external_single_structure(array(
1031 'cohorts' => new external_multiple_structure(cohort_summary_exporter::get_read_structure())
1032 ));
64020153
IT
1033 }
1034
e1964c90 1035 /**
81de839f 1036 * Returns description of external function.
e1964c90
DW
1037 *
1038 * @return \external_function_parameters
1039 */
81de839f 1040 public static function data_for_user_competency_summary_parameters() {
e1964c90
DW
1041 $userid = new external_value(
1042 PARAM_INT,
81de839f 1043 'Data base record id for the user',
e1964c90
DW
1044 VALUE_REQUIRED
1045 );
1046 $competencyid = new external_value(
1047 PARAM_INT,
81de839f 1048 'Data base record id for the competency',
e1964c90
DW
1049 VALUE_REQUIRED
1050 );
e1964c90 1051 $params = array(
e1964c90
DW
1052 'userid' => $userid,
1053 'competencyid' => $competencyid,
e1964c90
DW
1054 );
1055 return new external_function_parameters($params);
1056 }
1057
1058 /**
81de839f 1059 * Data for user competency summary.
e1964c90 1060 *
81de839f
FM
1061 * @param int $userid The user ID
1062 * @param int $competencyid The competency ID
1063 * @return \stdClass
e1964c90 1064 */
81de839f
FM
1065 public static function data_for_user_competency_summary($userid, $competencyid) {
1066 global $PAGE;
1067 $params = self::validate_parameters(self::data_for_user_competency_summary_parameters(), array(
1068 'userid' => $userid,
1069 'competencyid' => $competencyid,
1070 ));
e1964c90 1071
81de839f
FM
1072 $uc = api::get_user_competency($params['userid'], $params['competencyid']);
1073 self::validate_context($uc->get_context());
e1964c90
DW
1074 $output = $PAGE->get_renderer('tool_lp');
1075
81de839f
FM
1076 $renderable = new \tool_lp\output\user_competency_summary($uc);
1077 return $renderable->export_for_template($output);
e1964c90
DW
1078 }
1079
1080 /**
81de839f 1081 * Returns description of external function.
e1964c90 1082 *
81de839f 1083 * @return \external_description
e1964c90 1084 */
81de839f
FM
1085 public static function data_for_user_competency_summary_returns() {
1086 return user_competency_summary_exporter::get_read_structure();
e1964c90
DW
1087 }
1088
a8902ee2 1089 /**
81de839f 1090 * Returns description of data_for_user_competency_summary_in_plan() parameters.
a8902ee2
SG
1091 *
1092 * @return \external_function_parameters
1093 */
81de839f
FM
1094 public static function data_for_user_competency_summary_in_plan_parameters() {
1095 $competencyid = new external_value(
1096 PARAM_INT,
1097 'Data base record id for the competency',
1098 VALUE_REQUIRED
1099 );
a8902ee2
SG
1100 $planid = new external_value(
1101 PARAM_INT,
1102 'Data base record id for the plan',
1103 VALUE_REQUIRED
1104 );
1105
1106 $params = array(
81de839f 1107 'competencyid' => $competencyid,
a8902ee2
SG
1108 'planid' => $planid,
1109 );
1110 return new external_function_parameters($params);
1111 }
1112
1113 /**
81de839f 1114 * Read a user competency summary.
a8902ee2 1115 *
81de839f 1116 * @param int $competencyid The competency id
a8902ee2 1117 * @param int $planid The plan id
81de839f 1118 * @return \stdClass
a8902ee2 1119 */
81de839f
FM
1120 public static function data_for_user_competency_summary_in_plan($competencyid, $planid) {
1121 global $PAGE;
91e54642
FM
1122 $params = self::validate_parameters(self::data_for_user_competency_summary_in_plan_parameters(), array(
1123 'competencyid' => $competencyid,
1124 'planid' => $planid
1125 ));
a8902ee2 1126
81de839f
FM
1127 $plan = api::read_plan($params['planid']);
1128 $context = $plan->get_context();
1129 self::validate_context($context);
1130 $output = $PAGE->get_renderer('tool_lp');
a8902ee2 1131
81de839f
FM
1132 $renderable = new user_competency_summary_in_plan($params['competencyid'], $params['planid']);
1133 return $renderable->export_for_template($output);
a8902ee2
SG
1134 }
1135
1136 /**
81de839f 1137 * Returns description of data_for_user_competency_summary_in_plan() result value.
a8902ee2 1138 *
81de839f 1139 * @return \external_description
a8902ee2 1140 */
81de839f
FM
1141 public static function data_for_user_competency_summary_in_plan_returns() {
1142 return user_competency_summary_in_plan_exporter::get_read_structure();
a8902ee2
SG
1143 }
1144
305eaf38 1145 /**
81de839f 1146 * Returns description of data_for_user_competency_summary_in_course() parameters.
305eaf38
SG
1147 *
1148 * @return \external_function_parameters
1149 */
81de839f
FM
1150 public static function data_for_user_competency_summary_in_course_parameters() {
1151 $userid = new external_value(
305eaf38 1152 PARAM_INT,
81de839f 1153 'Data base record id for the user',
305eaf38
SG
1154 VALUE_REQUIRED
1155 );
81de839f 1156 $competencyid = new external_value(
7ba07487 1157 PARAM_INT,
81de839f 1158 'Data base record id for the competency',
7ba07487
DW
1159 VALUE_REQUIRED
1160 );
81de839f
FM
1161 $courseid = new external_value(
1162 PARAM_INT,
1163 'Data base record id for the course',
7ba07487
DW
1164 VALUE_REQUIRED
1165 );
81de839f 1166
7ba07487 1167 $params = array(
81de839f
FM
1168 'userid' => $userid,
1169 'competencyid' => $competencyid,
7ba07487 1170 'courseid' => $courseid,
7ba07487
DW
1171 );
1172 return new external_function_parameters($params);
1173 }
1174
1175 /**
81de839f 1176 * Read a user competency summary.
7ba07487 1177 *
81de839f
FM
1178 * @param int $userid The user id
1179 * @param int $competencyid The competency id
1180 * @param int $courseid The course id
1181 * @return \stdClass
7ba07487 1182 */
81de839f
FM
1183 public static function data_for_user_competency_summary_in_course($userid, $competencyid, $courseid) {
1184 global $PAGE;
91e54642
FM
1185 $params = self::validate_parameters(self::data_for_user_competency_summary_in_course_parameters(), array(
1186 'userid' => $userid,
1187 'competencyid' => $competencyid,
1188 'courseid' => $courseid
1189 ));
81de839f 1190 $context = context_user::instance($params['userid']);
7ba07487 1191 self::validate_context($context);
81de839f 1192 $output = $PAGE->get_renderer('tool_lp');
7ba07487 1193
81de839f
FM
1194 $renderable = new user_competency_summary_in_course($params['userid'], $params['competencyid'], $params['courseid']);
1195 return $renderable->export_for_template($output);
7ba07487
DW
1196 }
1197
1198 /**
81de839f 1199 * Returns description of data_for_user_competency_summary_in_course() result value.
7ba07487 1200 *
81de839f 1201 * @return \external_description
7ba07487 1202 */
81de839f
FM
1203 public static function data_for_user_competency_summary_in_course_returns() {
1204 return user_competency_summary_in_course_exporter::get_read_structure();
7ba07487 1205 }
81de839f 1206
d9a39950 1207}