MDL-53700 competency: Migrating tests to core
[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;
d629323f 44use grade_scale;
767f66c0 45use core_competency\api;
72018c0a
FM
46use core_competency\competency;
47use core_competency\competency_framework;
48use core_competency\course_competency;
49use core_competency\course_competency_settings;
50use core_competency\course_module_competency;
51use core_competency\evidence;
52use core_competency\plan;
53use core_competency\plan_competency;
54use core_competency\related_competency;
55use core_competency\template;
56use core_competency\template_cohort;
57use core_competency\template_competency;
58use core_competency\user_competency;
59use core_competency\user_competency_course;
60use core_competency\user_competency_plan;
61use core_competency\user_evidence;
62use core_competency\user_evidence_competency;
51247ea0 63use tool_lp\external\cohort_summary_exporter;
72018c0a
FM
64use core_competency\external\competency_exporter;
65use core_competency\external\competency_framework_exporter;
66use tool_lp\external\competency_path_exporter;
67use tool_lp\external\competency_summary_exporter;
68use core_competency\external\course_competency_exporter;
69use core_competency\external\course_competency_settings_exporter;
70use tool_lp\external\course_competency_statistics_exporter;
71use tool_lp\external\course_module_summary_exporter;
72use tool_lp\external\course_summary_exporter;
73use core_competency\external\evidence_exporter;
74use core_competency\external\plan_exporter;
75use core_competency\external\template_exporter;
3edcd295 76use tool_lp\external\template_statistics_exporter;
72018c0a
FM
77use core_competency\external\user_competency_exporter;
78use core_competency\external\user_competency_plan_exporter;
3c659fc2 79use tool_lp\external\user_competency_summary_exporter;
e1964c90 80use tool_lp\external\user_competency_summary_in_course_exporter;
0845a3a0 81use tool_lp\external\user_competency_summary_in_plan_exporter;
72018c0a
FM
82use core_competency\external\user_evidence_competency_exporter;
83use core_competency\external\user_evidence_exporter;
71cb304a 84use tool_lp\external\user_evidence_summary_exporter;
72018c0a 85use core_competency\external\user_summary_exporter;
65a67e23
DW
86use tool_lp\output\user_competency_summary_in_plan;
87use tool_lp\output\user_competency_summary_in_course;
d9a39950
DW
88
89/**
90 * This is the external API for this tool.
91 *
92 * @copyright 2015 Damyon Wiese
93 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
94 */
95class external extends external_api {
96
97 /**
98 * Returns description of a generic list() parameters.
99 *
e90c24d0 100 * @return \external_function_parameters
d9a39950
DW
101 */
102 protected static function list_parameters_structure() {
103 $filters = new external_multiple_structure(new external_single_structure(
104 array(
105 'column' => new external_value(PARAM_ALPHANUMEXT, 'Column name to filter by'),
106 'value' => new external_value(PARAM_TEXT, 'Value to filter by. Must be exact match')
107 )
108 ));
109 $sort = new external_value(
110 PARAM_ALPHANUMEXT,
111 'Column to sort by.',
112 VALUE_DEFAULT,
113 ''
114 );
115 $order = new external_value(
116 PARAM_ALPHA,
117 'Sort direction. Should be either ASC or DESC',
118 VALUE_DEFAULT,
119 ''
120 );
121 $skip = new external_value(
122 PARAM_INT,
123 'Skip this number of records before returning results',
124 VALUE_DEFAULT,
125 0
126 );
127 $limit = new external_value(
128 PARAM_INT,
129 'Return this number of records at most.',
130 VALUE_DEFAULT,
131 0
132 );
133
134 $params = array(
135 'filters' => $filters,
136 'sort' => $sort,
137 'order' => $order,
138 'skip' => $skip,
139 'limit' => $limit
140 );
141 return new external_function_parameters($params);
142 }
143
2de75345
FM
144 /**
145 * Returns a prepared structure to use a context parameters.
146 * @return external_single_structure
147 */
148 protected static function get_context_parameters() {
149 $id = new external_value(
150 PARAM_INT,
151 'Context ID. Either use this value, or level and instanceid.',
152 VALUE_DEFAULT,
153 0
154 );
155 $level = new external_value(
156 PARAM_ALPHA,
157 'Context level. To be used with instanceid.',
158 VALUE_DEFAULT,
159 ''
160 );
161 $instanceid = new external_value(
162 PARAM_INT,
163 'Context instance ID. To be used with level',
164 VALUE_DEFAULT,
165 0
166 );
167 return new external_single_structure(array(
168 'contextid' => $id,
169 'contextlevel' => $level,
170 'instanceid' => $instanceid,
171 ));
172 }
173
d9a39950
DW
174 /**
175 * Returns description of a generic count_x() parameters.
176 *
e90c24d0 177 * @return \external_function_parameters
d9a39950
DW
178 */
179 public static function count_parameters_structure() {
180 $filters = new external_multiple_structure(new external_single_structure(
181 array(
182 'column' => new external_value(PARAM_ALPHANUMEXT, 'Column name to filter by'),
183 'value' => new external_value(PARAM_TEXT, 'Value to filter by. Must be exact match')
184 )
185 ));
186
187 $params = array(
188 'filters' => $filters,
189 );
190 return new external_function_parameters($params);
191 }
192
d9a39950
DW
193 /**
194 * Returns description of create_competency_framework() parameters.
195 *
e90c24d0 196 * @return \external_function_parameters
d9a39950
DW
197 */
198 public static function create_competency_framework_parameters() {
578e61c1 199 $structure = competency_framework_exporter::get_create_structure();
8ec5f810 200 $params = array('competencyframework' => $structure);
d9a39950
DW
201 return new external_function_parameters($params);
202 }
203
d9a39950
DW
204 /**
205 * Create a new competency framework
206 *
8ec5f810 207 * @param array $competencyframework A single param with all the fields for a competency framework.
b17d3d10 208 * @return \stdClass The new record
d9a39950 209 */
8ec5f810 210 public static function create_competency_framework($competencyframework) {
86938d06
DW
211 global $PAGE;
212
d9a39950 213 $params = self::validate_parameters(self::create_competency_framework_parameters(),
8ec5f810 214 array('competencyframework' => $competencyframework));
d9a39950 215
8ec5f810
DW
216 $params = $params['competencyframework'];
217
218 $context = self::get_context_from_params($params);
2de75345 219 self::validate_context($context);
86938d06 220 $output = $PAGE->get_renderer('tool_lp');
2de75345 221
8ec5f810
DW
222 unset($params['contextlevel']);
223 unset($params['instanceid']);
2de75345
FM
224 $params['contextid'] = $context->id;
225
226 $params = (object) $params;
d9a39950 227 $result = api::create_framework($params);
86938d06 228 $exporter = new competency_framework_exporter($result);
5db5c22c 229 $record = $exporter->export($output);
b6070264 230 return $record;
d9a39950
DW
231 }
232
233 /**
234 * Returns description of create_competency_framework() result value.
235 *
e90c24d0 236 * @return \external_description
d9a39950
DW
237 */
238 public static function create_competency_framework_returns() {
578e61c1 239 return competency_framework_exporter::get_read_structure();
d9a39950
DW
240 }
241
242 /**
243 * Returns description of read_competency_framework() parameters.
244 *
e90c24d0 245 * @return \external_function_parameters
d9a39950
DW
246 */
247 public static function read_competency_framework_parameters() {
248 $id = new external_value(
249 PARAM_INT,
250 'Data base record id for the framework',
251 VALUE_REQUIRED
252 );
253
254 $params = array(
255 'id' => $id,
256 );
257 return new external_function_parameters($params);
258 }
259
d9a39950
DW
260 /**
261 * Read a competency framework by id.
262 *
263 * @param int $id The id of the framework.
b17d3d10 264 * @return \stdClass
d9a39950
DW
265 */
266 public static function read_competency_framework($id) {
86938d06
DW
267 global $PAGE;
268
d9a39950
DW
269 $params = self::validate_parameters(self::read_competency_framework_parameters(),
270 array(
271 'id' => $id,
272 ));
273
86938d06
DW
274 $framework = api::read_framework($params['id']);
275 self::validate_context($framework->get_context());
276 $output = $PAGE->get_renderer('tool_lp');
277 $exporter = new competency_framework_exporter($framework);
5db5c22c 278 $record = $exporter->export($output);
b6070264 279 return $record;
d9a39950
DW
280 }
281
282 /**
283 * Returns description of read_competency_framework() result value.
284 *
e90c24d0 285 * @return \external_description
d9a39950
DW
286 */
287 public static function read_competency_framework_returns() {
578e61c1 288 return competency_framework_exporter::get_read_structure();
d9a39950
DW
289 }
290
3e6a8e16
IT
291 /**
292 * Returns description of competency_viewed() parameters.
293 *
294 * @return \external_function_parameters
295 */
296 public static function competency_viewed_parameters() {
297 $id = new external_value(
298 PARAM_INT,
299 'The competency id',
300 VALUE_REQUIRED
301 );
302 $params = array(
303 'id' => $id
304 );
305 return new external_function_parameters($params);
306 }
307
308 /**
309 * Log event competency viewed.
310 *
311 * @param int $id The competency ID.
312 * @return boolean
313 */
314 public static function competency_viewed($id) {
315 $params = self::validate_parameters(self::competency_viewed_parameters(),
316 array(
317 'id' => $id
318 ));
319 return api::competency_viewed($params['id']);
320 }
321
322 /**
323 * Returns description of competency_viewed() result value.
324 *
325 * @return \external_description
326 */
327 public static function competency_viewed_returns() {
328 return new external_value(PARAM_BOOL, 'True if the event competency viewed was logged');
329 }
330
c61db7bb
IT
331 /**
332 * Returns description of duplicate_competency_framework() parameters.
333 *
334 * @return \external_function_parameters
335 */
336 public static function duplicate_competency_framework_parameters() {
337 $id = new external_value(
338 PARAM_INT,
339 'Data base record id for the framework',
340 VALUE_REQUIRED
341 );
342
343 $params = array(
344 'id' => $id,
345 );
346 return new external_function_parameters($params);
347 }
348
c61db7bb
IT
349 /**
350 * Duplicate a competency framework
351 *
352 * @param int $id The competency framework id
353 * @return boolean
354 */
355 public static function duplicate_competency_framework($id) {
37798262 356 global $PAGE;
c61db7bb
IT
357 $params = self::validate_parameters(self::duplicate_competency_framework_parameters(),
358 array(
359 'id' => $id,
360 ));
361
86938d06
DW
362 $framework = api::read_framework($params['id']);
363 self::validate_context($framework->get_context());
364
37798262
IT
365 $output = $PAGE->get_renderer('tool_lp');
366 $framework = api::duplicate_framework($params['id']);
367 $exporter = new competency_framework_exporter($framework);
368 $record = $exporter->export($output);
369 return $record;
c61db7bb
IT
370 }
371
372 /**
373 * Returns description of duplicate_competency_framework() result value.
374 *
375 * @return \external_description
376 */
377 public static function duplicate_competency_framework_returns() {
578e61c1 378 return competency_framework_exporter::get_read_structure();
c61db7bb
IT
379 }
380
d9a39950
DW
381 /**
382 * Returns description of delete_competency_framework() parameters.
383 *
e90c24d0 384 * @return \external_function_parameters
d9a39950
DW
385 */
386 public static function delete_competency_framework_parameters() {
387 $id = new external_value(
388 PARAM_INT,
389 'Data base record id for the framework',
390 VALUE_REQUIRED
391 );
392
393 $params = array(
394 'id' => $id,
395 );
396 return new external_function_parameters($params);
397 }
398
d9a39950
DW
399 /**
400 * Delete a competency framework
401 *
402 * @param int $id The competency framework id
403 * @return boolean
404 */
405 public static function delete_competency_framework($id) {
406 $params = self::validate_parameters(self::delete_competency_framework_parameters(),
407 array(
408 'id' => $id,
409 ));
410
86938d06
DW
411 $framework = api::read_framework($params['id']);
412 self::validate_context($framework->get_context());
413
d9a39950
DW
414 return api::delete_framework($params['id']);
415 }
416
417 /**
418 * Returns description of delete_competency_framework() result value.
419 *
e90c24d0 420 * @return \external_description
d9a39950
DW
421 */
422 public static function delete_competency_framework_returns() {
423 return new external_value(PARAM_BOOL, 'True if the delete was successful');
424 }
425
426 /**
427 * Returns description of update_competency_framework() parameters.
428 *
e90c24d0 429 * @return \external_function_parameters
d9a39950
DW
430 */
431 public static function update_competency_framework_parameters() {
578e61c1 432 $structure = competency_framework_exporter::get_update_structure();
8ec5f810 433 $params = array('competencyframework' => $structure);
d9a39950
DW
434 return new external_function_parameters($params);
435 }
436
d9a39950
DW
437 /**
438 * Update an existing competency framework
439 *
8ec5f810 440 * @param array $competencyframework An array with all the fields for a competency framework.
d9a39950
DW
441 * @return boolean
442 */
8ec5f810 443 public static function update_competency_framework($competencyframework) {
d9a39950
DW
444
445 $params = self::validate_parameters(self::update_competency_framework_parameters(),
446 array(
8ec5f810 447 'competencyframework' => $competencyframework
d9a39950 448 ));
3392a313 449
8ec5f810
DW
450 $params = $params['competencyframework'];
451
86938d06
DW
452 $framework = api::read_framework($params['id']);
453 self::validate_context($framework->get_context());
454
d9a39950
DW
455 $params = (object) $params;
456
457 return api::update_framework($params);
458 }
459
460 /**
461 * Returns description of update_competency_framework() result value.
462 *
e90c24d0 463 * @return \external_description
d9a39950
DW
464 */
465 public static function update_competency_framework_returns() {
466 return new external_value(PARAM_BOOL, 'True if the update was successful');
467 }
468
469 /**
470 * Returns description of list_competency_frameworks() parameters.
471 *
e90c24d0 472 * @return \external_function_parameters
d9a39950
DW
473 */
474 public static function list_competency_frameworks_parameters() {
2de75345
FM
475 $sort = new external_value(
476 PARAM_ALPHANUMEXT,
477 'Column to sort by.',
478 VALUE_DEFAULT,
0fe5aac7 479 'shortname'
2de75345
FM
480 );
481 $order = new external_value(
482 PARAM_ALPHA,
483 'Sort direction. Should be either ASC or DESC',
484 VALUE_DEFAULT,
485 ''
486 );
487 $skip = new external_value(
488 PARAM_INT,
489 'Skip this number of records before returning results',
490 VALUE_DEFAULT,
491 0
492 );
493 $limit = new external_value(
494 PARAM_INT,
495 'Return this number of records at most.',
496 VALUE_DEFAULT,
497 0
498 );
499 $includes = new external_value(
500 PARAM_ALPHA,
501 'What other contextes to fetch the frameworks from. (children, parents, self)',
502 VALUE_DEFAULT,
503 'children'
504 );
964afa98
IT
505 $onlyvisible = new external_value(
506 PARAM_BOOL,
507 'Only visible frameworks will be returned if visible true',
508 VALUE_DEFAULT,
509 false
510 );
0fe5aac7
FM
511 $query = new external_value(
512 PARAM_RAW,
513 'A query string to filter the results',
514 VALUE_DEFAULT,
515 ''
516 );
2de75345
FM
517
518 $params = array(
519 'sort' => $sort,
520 'order' => $order,
521 'skip' => $skip,
522 'limit' => $limit,
523 'context' => self::get_context_parameters(),
964afa98 524 'includes' => $includes,
0fe5aac7
FM
525 'onlyvisible' => $onlyvisible,
526 'query' => $query,
2de75345
FM
527 );
528 return new external_function_parameters($params);
d9a39950
DW
529 }
530
d9a39950
DW
531 /**
532 * List the existing competency frameworks
533 *
b17d3d10
AA
534 * @param int $sort
535 * @param string $order
536 * @param string $skip
537 * @param int $limit
2de75345
FM
538 * @param array $context
539 * @param bool $includes
964afa98 540 * @param bool $onlyvisible
0fe5aac7 541 * @param string $query
b17d3d10
AA
542 *
543 * @return array
544 * @throws \required_capability_exception
545 * @throws invalid_parameter_exception
d9a39950 546 */
0fe5aac7
FM
547 public static function list_competency_frameworks($sort, $order, $skip, $limit, $context, $includes, $onlyvisible,
548 $query = '') {
86938d06
DW
549 global $PAGE;
550
d9a39950
DW
551 $params = self::validate_parameters(self::list_competency_frameworks_parameters(),
552 array(
d9a39950
DW
553 'sort' => $sort,
554 'order' => $order,
555 'skip' => $skip,
2de75345
FM
556 'limit' => $limit,
557 'context' => $context,
964afa98 558 'includes' => $includes,
0fe5aac7
FM
559 'onlyvisible' => $onlyvisible,
560 'query' => $query,
d9a39950
DW
561 ));
562
2de75345
FM
563 $context = self::get_context_from_params($params['context']);
564 self::validate_context($context);
86938d06 565 $output = $PAGE->get_renderer('tool_lp');
2de75345 566
d9a39950
DW
567 if ($params['order'] !== '' && $params['order'] !== 'ASC' && $params['order'] !== 'DESC') {
568 throw new invalid_parameter_exception('Invalid order param. Must be ASC, DESC or empty.');
569 }
570
2de75345
FM
571 $results = api::list_frameworks($params['sort'],
572 $params['order'],
573 $params['skip'],
574 $params['limit'],
575 $context,
964afa98 576 $params['includes'],
0fe5aac7
FM
577 $params['onlyvisible'],
578 $params['query']);
d9a39950
DW
579 $records = array();
580 foreach ($results as $result) {
86938d06 581 $exporter = new competency_framework_exporter($result);
5db5c22c 582 $record = $exporter->export($output);
d9a39950
DW
583 array_push($records, $record);
584 }
585 return $records;
586 }
587
588 /**
589 * Returns description of list_competency_frameworks() result value.
590 *
e90c24d0 591 * @return \external_description
d9a39950
DW
592 */
593 public static function list_competency_frameworks_returns() {
578e61c1 594 return new external_multiple_structure(competency_framework_exporter::get_read_structure());
d9a39950
DW
595 }
596
597 /**
598 * Returns description of count_competency_frameworks() parameters.
599 *
e90c24d0 600 * @return \external_function_parameters
d9a39950
DW
601 */
602 public static function count_competency_frameworks_parameters() {
f610a957
FM
603 $includes = new external_value(
604 PARAM_ALPHA,
605 'What other contextes to fetch the frameworks from. (children, parents, self)',
606 VALUE_DEFAULT,
607 'children'
608 );
d9a39950
DW
609
610 $params = array(
f610a957
FM
611 'context' => self::get_context_parameters(),
612 'includes' => $includes
d9a39950
DW
613 );
614 return new external_function_parameters($params);
615 }
616
d9a39950
DW
617 /**
618 * Count the existing competency frameworks
619 *
96c2b847
FM
620 * @param array $context
621 * @param string $includes
622 * @return int
d9a39950 623 */
f610a957 624 public static function count_competency_frameworks($context, $includes) {
d9a39950
DW
625 $params = self::validate_parameters(self::count_competency_frameworks_parameters(),
626 array(
f610a957
FM
627 'context' => $context,
628 'includes' => $includes
d9a39950
DW
629 ));
630
f610a957
FM
631 $context = self::get_context_from_params($params['context']);
632 self::validate_context($context);
d9a39950 633
f610a957 634 return api::count_frameworks($context, $params['includes']);
d9a39950
DW
635 }
636
637 /**
638 * Returns description of count_competency_frameworks() result value.
639 *
e90c24d0 640 * @return \external_description
d9a39950
DW
641 */
642 public static function count_competency_frameworks_returns() {
643 return new external_value(PARAM_INT, 'The number of competency frameworks found.');
644 }
645
f73a29c1
IT
646 /**
647 * Returns description of competency_framework_viewed() parameters.
648 *
649 * @return \external_function_parameters
650 */
651 public static function competency_framework_viewed_parameters() {
652 $id = new external_value(
653 PARAM_INT,
654 'The competency framework id',
655 VALUE_REQUIRED
656 );
657
658 $params = array(
659 'id' => $id
660 );
661 return new external_function_parameters($params);
662 }
663
664 /**
665 * Log event competency framework viewed.
666 *
667 * @param int $id The competency framework ID.
668 * @return boolean
669 */
670 public static function competency_framework_viewed($id) {
671 $params = self::validate_parameters(self::competency_framework_viewed_parameters(),
672 array(
673 'id' => $id
674 ));
675 return api::competency_framework_viewed($params['id']);
676
677 }
678
679 /**
680 * Returns description of competency_framework_viewed() result value.
681 *
682 * @return \external_description
683 */
684 public static function competency_framework_viewed_returns() {
685 return new external_value(PARAM_BOOL, 'True if the event competency framework was logged');
686 }
687
d9a39950
DW
688 /**
689 * Returns description of data_for_competency_frameworks_manage_page() parameters.
690 *
e90c24d0 691 * @return \external_function_parameters
d9a39950
DW
692 */
693 public static function data_for_competency_frameworks_manage_page_parameters() {
2de75345 694 $params = array('pagecontext' => self::get_context_parameters());
d9a39950
DW
695 return new external_function_parameters($params);
696 }
697
d9a39950
DW
698 /**
699 * Loads the data required to render the competency_frameworks_manage_page template.
700 *
37798262
IT
701 * @param context $pagecontext The page context
702 * @return \stdClass
d9a39950 703 */
2de75345 704 public static function data_for_competency_frameworks_manage_page($pagecontext) {
d9a39950
DW
705 global $PAGE;
706
2de75345
FM
707 $params = self::validate_parameters(
708 self::data_for_competency_frameworks_manage_page_parameters(),
709 array(
710 'pagecontext' => $pagecontext
711 )
712 );
713 $context = self::get_context_from_params($params['pagecontext']);
714 self::validate_context($context);
715
716 $renderable = new output\manage_competency_frameworks_page($context);
d9a39950
DW
717 $renderer = $PAGE->get_renderer('tool_lp');
718
719 $data = $renderable->export_for_template($renderer);
720
721 return $data;
722 }
723
724 /**
725 * Returns description of data_for_competency_frameworks_manage_page() result value.
726 *
e90c24d0 727 * @return \external_description
d9a39950
DW
728 */
729 public static function data_for_competency_frameworks_manage_page_returns() {
730 return new external_single_structure(array (
d9a39950 731 'competencyframeworks' => new external_multiple_structure(
578e61c1 732 competency_framework_exporter::get_read_structure()
d9a39950
DW
733 ),
734 'pluginbaseurl' => new external_value(PARAM_LOCALURL, 'Url to the tool_lp plugin folder on this Moodle site'),
735 'navigation' => new external_multiple_structure(
736 new external_value(PARAM_RAW, 'HTML for a navigation item that should be on this page')
37798262
IT
737 ),
738 'pagecontextid' => new external_value(PARAM_INT, 'The page context id')
d9a39950
DW
739 ));
740
741 }
742
d9a39950
DW
743 /**
744 * Returns description of create_competency() parameters.
745 *
e90c24d0 746 * @return \external_function_parameters
d9a39950
DW
747 */
748 public static function create_competency_parameters() {
578e61c1 749 $structure = competency_exporter::get_create_structure();
8ec5f810 750 $params = array('competency' => $structure);
d9a39950
DW
751 return new external_function_parameters($params);
752 }
753
754 /**
8ec5f810 755 * Create a new competency
d9a39950 756 *
8ec5f810
DW
757 * @param array $competency All the fields for a competency record (including id)
758 * @return array the competency
759 */
760 public static function create_competency($competency) {
86938d06
DW
761 global $PAGE;
762
d9a39950 763 $params = self::validate_parameters(self::create_competency_parameters(),
8ec5f810 764 array('competency' => $competency));
d9a39950 765
8ec5f810 766 $params = $params['competency'];
86938d06
DW
767 $framework = api::read_framework($params['competencyframeworkid']);
768 $context = $framework->get_context();
769 self::validate_context($context);
770 $output = $PAGE->get_renderer('tool_lp');
771
772 $params = (object) $params;
d9a39950 773 $result = api::create_competency($params);
86938d06 774 $exporter = new competency_exporter($result, array('context' => $context));
5db5c22c 775 $record = $exporter->export($output);
c27113d9 776 return $record;
d9a39950
DW
777 }
778
779 /**
780 * Returns description of create_competency() result value.
781 *
e90c24d0 782 * @return \external_description
d9a39950
DW
783 */
784 public static function create_competency_returns() {
578e61c1 785 return competency_exporter::get_read_structure();
d9a39950
DW
786 }
787
788 /**
789 * Returns description of read_competency() parameters.
790 *
e90c24d0 791 * @return \external_function_parameters
d9a39950
DW
792 */
793 public static function read_competency_parameters() {
794 $id = new external_value(
795 PARAM_INT,
796 'Data base record id for the competency',
797 VALUE_REQUIRED
798 );
799
800 $params = array(
801 'id' => $id,
802 );
803 return new external_function_parameters($params);
804 }
805
d9a39950
DW
806 /**
807 * Read a competency by id.
808 *
809 * @param int $id The id of the competency
b17d3d10 810 * @return \stdClass
d9a39950
DW
811 */
812 public static function read_competency($id) {
86938d06
DW
813 global $PAGE;
814
d9a39950
DW
815 $params = self::validate_parameters(self::read_competency_parameters(),
816 array(
817 'id' => $id,
818 ));
819
86938d06 820 $competency = api::read_competency($params['id']);
a214d35e 821 $context = $competency->get_context();
86938d06
DW
822 self::validate_context($context);
823 $output = $PAGE->get_renderer('tool_lp');
824 $exporter = new competency_exporter($competency, array('context' => $context));
5db5c22c 825 $record = $exporter->export($output);
c27113d9 826 return $record;
d9a39950
DW
827 }
828
829 /**
830 * Returns description of read_competency() result value.
831 *
e90c24d0 832 * @return \external_description
d9a39950
DW
833 */
834 public static function read_competency_returns() {
578e61c1 835 return competency_exporter::get_read_structure();
d9a39950
DW
836 }
837
838 /**
839 * Returns description of delete_competency() parameters.
840 *
e90c24d0 841 * @return \external_function_parameters
d9a39950
DW
842 */
843 public static function delete_competency_parameters() {
844 $id = new external_value(
845 PARAM_INT,
846 'Data base record id for the competency',
847 VALUE_REQUIRED
848 );
849
850 $params = array(
851 'id' => $id,
852 );
853 return new external_function_parameters($params);
854 }
855
d9a39950
DW
856 /**
857 * Delete a competency
858 *
859 * @param int $id The competency id
860 * @return boolean
861 */
862 public static function delete_competency($id) {
8ec5f810
DW
863 $params = self::validate_parameters(self::delete_competency_parameters(),
864 array(
865 'id' => $id,
866 ));
d9a39950 867
8ec5f810
DW
868 $competency = api::read_competency($params['id']);
869 $context = $competency->get_context();
870 self::validate_context($context);
871
872 return api::delete_competency($params['id']);
873 }
874
875 /**
876 * Returns description of delete_competency() result value.
877 *
878 * @return \external_description
879 */
880 public static function delete_competency_returns() {
881 return new external_value(PARAM_BOOL, 'True if the delete was successful');
882 }
883
884 /**
885 * Returns description of update_competency() parameters.
886 *
887 * @return \external_function_parameters
888 */
889 public static function update_competency_parameters() {
578e61c1 890 $structure = competency_exporter::get_update_structure();
8ec5f810 891 $params = array('competency' => $structure);
d9a39950
DW
892 return new external_function_parameters($params);
893 }
894
d9a39950
DW
895 /**
896 * Update an existing competency
897 *
8ec5f810 898 * @param array $competency The array of competency fields (id is required).
d9a39950
DW
899 * @return boolean
900 */
8ec5f810 901 public static function update_competency($competency) {
d9a39950
DW
902
903 $params = self::validate_parameters(self::update_competency_parameters(),
8ec5f810
DW
904 array('competency' => $competency));
905 $params = $params['competency'];
86938d06
DW
906
907 $competency = api::read_competency($params['id']);
a214d35e 908 self::validate_context($competency->get_context());
86938d06 909
d9a39950
DW
910 $params = (object) $params;
911
912 return api::update_competency($params);
913 }
914
915 /**
916 * Returns description of update_competency_framework() result value.
917 *
e90c24d0 918 * @return \external_description
d9a39950
DW
919 */
920 public static function update_competency_returns() {
921 return new external_value(PARAM_BOOL, 'True if the update was successful');
922 }
923
924 /**
925 * Returns description of list_competencies() parameters.
926 *
e90c24d0 927 * @return \external_function_parameters
d9a39950
DW
928 */
929 public static function list_competencies_parameters() {
930 return self::list_parameters_structure();
931 }
932
d9a39950 933 /**
b17d3d10 934 * List the existing competency.
d9a39950 935 *
b17d3d10
AA
936 * @param string $filters
937 * @param int $sort
938 * @param string $order
939 * @param string $skip
940 * @param int $limit
941 *
942 * @return array
943 * @throws \required_capability_exception
944 * @throws invalid_parameter_exception
d9a39950
DW
945 */
946 public static function list_competencies($filters, $sort, $order, $skip, $limit) {
86938d06
DW
947 global $PAGE;
948
d9a39950
DW
949 $params = self::validate_parameters(self::list_competencies_parameters(),
950 array(
951 'filters' => $filters,
952 'sort' => $sort,
953 'order' => $order,
954 'skip' => $skip,
955 'limit' => $limit
956 ));
957
958 if ($params['order'] !== '' && $params['order'] !== 'ASC' && $params['order'] !== 'DESC') {
959 throw new invalid_parameter_exception('Invalid order param. Must be ASC, DESC or empty.');
960 }
961
962 $safefilters = array();
b17d3d10 963 $validcolumns = array('id', 'shortname', 'description', 'sortorder',
964afa98 964 'idnumber', 'parentid', 'competencyframeworkid');
d9a39950
DW
965 foreach ($params['filters'] as $filter) {
966 if (!in_array($filter->column, $validcolumns)) {
967 throw new invalid_parameter_exception('Filter column was invalid');
968 }
969 $safefilters[$filter->column] = $filter->value;
970 }
971
86938d06
DW
972 $context = null;
973 if (isset($safefilters['competencyframeworkid'])) {
974 $framework = api::read_framework($safefilters['competencyframeworkid']);
975 $context = $framework->get_context();
976 } else {
977 $context = context_system::instance();
978 }
979
980 self::validate_context($context);
981 $output = $PAGE->get_renderer('tool_lp');
982
8ec5f810
DW
983 $results = api::list_competencies(
984 $safefilters,
985 $params['sort'],
986 $params['order'],
987 $params['skip'],
988 $params['limit']
989 );
990
d9a39950
DW
991 $records = array();
992 foreach ($results as $result) {
86938d06 993 $exporter = new competency_exporter($result, array('context' => $context));
5db5c22c 994 $record = $exporter->export($output);
d9a39950
DW
995 array_push($records, $record);
996 }
997 return $records;
998 }
999
1000 /**
1001 * Returns description of list_competencies() result value.
1002 *
e90c24d0 1003 * @return \external_description
d9a39950
DW
1004 */
1005 public static function list_competencies_returns() {
578e61c1 1006 return new external_multiple_structure(competency_exporter::get_read_structure());
d9a39950
DW
1007 }
1008
1009 /**
1010 * Returns description of search_competencies() parameters.
1011 *
e90c24d0 1012 * @return \external_function_parameters
d9a39950
DW
1013 */
1014 public static function search_competencies_parameters() {
1015 $searchtext = new external_value(
1016 PARAM_RAW,
1017 'Text to search for',
1018 VALUE_REQUIRED
1019 );
1020 $frameworkid = new external_value(
1021 PARAM_INT,
1022 'Competency framework id',
1023 VALUE_REQUIRED
1024 );
1025
1026 $params = array(
1027 'searchtext' => $searchtext,
8ec5f810 1028 'competencyframeworkid' => $frameworkid
d9a39950
DW
1029 );
1030 return new external_function_parameters($params);
1031 }
1032
b17d3d10
AA
1033 /**
1034 * List the existing competency frameworks
1035 *
1036 * @param string $searchtext Text to search.
1037 * @param int $competencyframeworkid Framework id.
1038 *
1039 * @return array
1040 */
8ec5f810 1041 public static function search_competencies($searchtext, $competencyframeworkid) {
86938d06
DW
1042 global $PAGE;
1043
d9a39950
DW
1044 $params = self::validate_parameters(self::search_competencies_parameters(),
1045 array(
1046 'searchtext' => $searchtext,
8ec5f810 1047 'competencyframeworkid' => $competencyframeworkid
d9a39950
DW
1048 ));
1049
86938d06
DW
1050 $framework = api::read_framework($params['competencyframeworkid']);
1051 $context = $framework->get_context();
1052 self::validate_context($context);
1053 $output = $PAGE->get_renderer('tool_lp');
1054
aec5363e 1055 $results = api::search_competencies($params['searchtext'], $params['competencyframeworkid']);
d9a39950
DW
1056 $records = array();
1057 foreach ($results as $result) {
86938d06 1058 $exporter = new competency_exporter($result, array('context' => $context));
5db5c22c 1059 $record = $exporter->export($output);
aec5363e 1060
d9a39950
DW
1061 array_push($records, $record);
1062 }
4f815459 1063
aec5363e 1064 return $records;
d9a39950
DW
1065 }
1066
1067 /**
1068 * Returns description of search_competencies() result value.
1069 *
e90c24d0 1070 * @return \external_description
d9a39950
DW
1071 */
1072 public static function search_competencies_returns() {
578e61c1 1073 return new external_multiple_structure(competency_exporter::get_read_structure());
d9a39950
DW
1074 }
1075
d9a39950
DW
1076 /**
1077 * Returns description of count_competencies() parameters.
1078 *
e90c24d0 1079 * @return \external_function_parameters
d9a39950
DW
1080 */
1081 public static function count_competencies_parameters() {
1082 return self::count_parameters_structure();
1083 }
1084
d9a39950 1085 /**
b17d3d10 1086 * Count the existing competency frameworks.
d9a39950 1087 *
b17d3d10 1088 * @param string $filters Filters to use.
d9a39950
DW
1089 * @return boolean
1090 */
1091 public static function count_competencies($filters) {
1092 $params = self::validate_parameters(self::count_competencies_parameters(),
1093 array(
1094 'filters' => $filters
1095 ));
1096
1097 $safefilters = array();
b17d3d10 1098 $validcolumns = array('id', 'shortname', 'description', 'sortorder', 'idnumber',
964afa98 1099 'parentid', 'competencyframeworkid');
d9a39950 1100 foreach ($params['filters'] as $filter) {
2327fe75 1101 if (!in_array($filter['column'], $validcolumns)) {
d9a39950
DW
1102 throw new invalid_parameter_exception('Filter column was invalid');
1103 }
2327fe75 1104 $safefilters[$filter['column']] = $filter['value'];
d9a39950
DW
1105 }
1106
86938d06
DW
1107 $context = null;
1108 if (isset($safefilters['competencyframeworkid'])) {
1109 $framework = api::read_framework($safefilters['competencyframeworkid']);
1110 $context = $framework->get_context();
1111 } else {
1112 $context = context_system::instance();
1113 }
1114
1115 self::validate_context($context);
1116
d9a39950
DW
1117 return api::count_competencies($safefilters);
1118 }
1119
1120 /**
1121 * Returns description of count_competencies() result value.
1122 *
e90c24d0 1123 * @return \external_description
d9a39950
DW
1124 */
1125 public static function count_competencies_returns() {
1126 return new external_value(PARAM_INT, 'The number of competencies found.');
1127 }
1128
1129 /**
1130 * Returns description of data_for_competencies_manage_page() parameters.
1131 *
e90c24d0 1132 * @return \external_function_parameters
d9a39950
DW
1133 */
1134 public static function data_for_competencies_manage_page_parameters() {
1135 $competencyframeworkid = new external_value(
1136 PARAM_INT,
1137 'The competency framework id',
1138 VALUE_REQUIRED
1139 );
1140 $search = new external_value(
1141 PARAM_RAW,
1142 'A search string',
1143 VALUE_DEFAULT,
1144 ''
1145 );
1146 $params = array(
1147 'competencyframeworkid' => $competencyframeworkid,
1148 'search' => $search
1149 );
1150 return new external_function_parameters($params);
1151 }
1152
d9a39950
DW
1153 /**
1154 * Loads the data required to render the competencies_manage_page template.
1155 *
b17d3d10
AA
1156 * @param int $competencyframeworkid Framework id.
1157 * @param string $search Text to search.
1158 *
d9a39950
DW
1159 * @return boolean
1160 */
1161 public static function data_for_competencies_manage_page($competencyframeworkid, $search) {
1162 global $PAGE;
86938d06 1163
d9a39950
DW
1164 $params = self::validate_parameters(self::data_for_competencies_manage_page_parameters(),
1165 array(
1166 'competencyframeworkid' => $competencyframeworkid,
1167 'search' => $search
1168 ));
1169
86938d06
DW
1170 $framework = api::read_framework($params['competencyframeworkid']);
1171 self::validate_context($framework->get_context());
1172 $output = $PAGE->get_renderer('tool_lp');
d9a39950 1173
2de75345 1174 $renderable = new output\manage_competencies_page($framework, $params['search'], $framework->get_context());
d9a39950 1175
86938d06 1176 $data = $renderable->export_for_template($output);
d9a39950
DW
1177
1178 return $data;
1179 }
1180
1181 /**
1182 * Returns description of data_for_competencies_manage_page() result value.
1183 *
e90c24d0 1184 * @return \external_description
d9a39950
DW
1185 */
1186 public static function data_for_competencies_manage_page_returns() {
1187 return new external_single_structure(array (
578e61c1 1188 'framework' => competency_framework_exporter::get_read_structure(),
d9a39950 1189 'canmanage' => new external_value(PARAM_BOOL, 'True if this user has permission to manage competency frameworks'),
60bf8bb0 1190 'pagecontextid' => new external_value(PARAM_INT, 'Context id for the framework'),
1896274f 1191 'search' => new external_value(PARAM_RAW, 'Current search string'),
a4f1b030
IT
1192 'rulesmodules' => new external_value(PARAM_RAW, 'JSON encoded data for rules'),
1193 'pluginbaseurl' => new external_value(PARAM_RAW, 'Plugin base url')
d9a39950
DW
1194 ));
1195
1196 }
1197
2e90c62f
IT
1198 /**
1199 * Returns description of data_for_competency_summary() parameters.
1200 *
1201 * @return \external_function_parameters
1202 */
1203 public static function data_for_competency_summary_parameters() {
1204 $competencyid = new external_value(
1205 PARAM_INT,
1206 'The competency id',
1207 VALUE_REQUIRED
1208 );
1209 $includerelated = new external_value(
1210 PARAM_BOOL,
1211 'Include or not related competencies',
1212 VALUE_DEFAULT,
1213 false
1214 );
1215 $includecourses = new external_value(
1216 PARAM_BOOL,
1217 'Include or not competency courses',
1218 VALUE_DEFAULT,
1219 false
1220 );
1221 $params = array(
1222 'competencyid' => $competencyid,
1223 'includerelated' => $includerelated,
1224 'includecourses' => $includecourses
1225 );
1226 return new external_function_parameters($params);
1227 }
1228
1229 /**
1230 * Loads the data required to render the competency_page template.
1231 *
1232 * @param int $competencyid Competency id.
1233 * @param boolean $includerelated Include or not related competencies.
1234 * @param boolean $includecourses Include or not competency courses.
1235 *
1236 * @return \stdClass
1237 */
1238 public static function data_for_competency_summary($competencyid, $includerelated = false, $includecourses = false) {
1239 global $PAGE;
1240 $params = self::validate_parameters(self::data_for_competency_summary_parameters(),
1241 array(
1242 'competencyid' => $competencyid,
1243 'includerelated' => $includerelated,
1244 'includecourses' => $includecourses
1245 ));
1246
1247 $competency = api::read_competency($params['competencyid']);
1248 $framework = api::read_framework($competency->get_competencyframeworkid());
1249 $renderable = new output\competency_summary($competency, $framework, $params['includerelated'], $params['includecourses']);
1250 $renderer = $PAGE->get_renderer('tool_lp');
1251
1252 $data = $renderable->export_for_template($renderer);
1253
1254 return $data;
1255 }
1256
1257 /**
1258 * Returns description of data_for_competency_summary_() result value.
1259 *
1260 * @return \external_description
1261 */
1262 public static function data_for_competency_summary_returns() {
49c5b8b4 1263 return competency_summary_exporter::get_read_structure();
2e90c62f
IT
1264 }
1265
d9a39950
DW
1266 /**
1267 * Returns description of set_parent_competency() parameters.
1268 *
e90c24d0 1269 * @return \external_function_parameters
d9a39950
DW
1270 */
1271 public static function set_parent_competency_parameters() {
1272 $competencyid = new external_value(
1273 PARAM_INT,
1274 'The competency id',
1275 VALUE_REQUIRED
1276 );
1277 $parentid = new external_value(
1278 PARAM_INT,
1279 'The new competency parent id',
1280 VALUE_REQUIRED
1281 );
1282 $params = array(
1283 'competencyid' => $competencyid,
1284 'parentid' => $parentid
1285 );
1286 return new external_function_parameters($params);
1287 }
1288
d9a39950
DW
1289 /**
1290 * Move the competency to a new parent.
1291 *
b17d3d10
AA
1292 * @param int $competencyid Competency id.
1293 * @param int $parentid Parent id.
1294 *
1295 * @return bool
d9a39950
DW
1296 */
1297 public static function set_parent_competency($competencyid, $parentid) {
d9a39950
DW
1298 $params = self::validate_parameters(self::set_parent_competency_parameters(),
1299 array(
1300 'competencyid' => $competencyid,
1301 'parentid' => $parentid
1302 ));
1303
86938d06 1304 $competency = api::read_competency($params['competencyid']);
a214d35e 1305 self::validate_context($competency->get_context());
86938d06
DW
1306
1307 return api::set_parent_competency($params['competencyid'], $params['parentid']);
d9a39950
DW
1308 }
1309
1310 /**
1311 * Returns description of set_parent_competency() result value.
1312 *
e90c24d0 1313 * @return \external_description
d9a39950
DW
1314 */
1315 public static function set_parent_competency_returns() {
1316 return new external_value(PARAM_BOOL, 'True if the update was successful');
1317 }
1318
1319 /**
1320 * Returns description of move_up_competency() parameters.
1321 *
e90c24d0 1322 * @return \external_function_parameters
d9a39950
DW
1323 */
1324 public static function move_up_competency_parameters() {
1325 $competencyid = new external_value(
1326 PARAM_INT,
1327 'The competency id',
1328 VALUE_REQUIRED
1329 );
1330 $params = array(
1331 'id' => $competencyid,
1332 );
1333 return new external_function_parameters($params);
1334 }
1335
d9a39950
DW
1336 /**
1337 * Change the sort order of a competency.
1338 *
b17d3d10 1339 * @param int $competencyid Competency id.
d9a39950
DW
1340 * @return boolean
1341 */
1342 public static function move_up_competency($competencyid) {
d9a39950
DW
1343 $params = self::validate_parameters(self::move_up_competency_parameters(),
1344 array(
1345 'id' => $competencyid,
1346 ));
1347
86938d06 1348 $competency = api::read_competency($params['id']);
a214d35e 1349 self::validate_context($competency->get_context());
86938d06 1350
d9a39950
DW
1351 return api::move_up_competency($params['id']);
1352 }
1353
1354 /**
1355 * Returns description of move_up_competency() result value.
1356 *
e90c24d0 1357 * @return \external_description
d9a39950
DW
1358 */
1359 public static function move_up_competency_returns() {
1360 return new external_value(PARAM_BOOL, 'True if the update was successful');
1361 }
1362
1363 /**
1364 * Returns description of move_down_competency() parameters.
1365 *
e90c24d0 1366 * @return \external_function_parameters
d9a39950
DW
1367 */
1368 public static function move_down_competency_parameters() {
1369 $competencyid = new external_value(
1370 PARAM_INT,
1371 'The competency id',
1372 VALUE_REQUIRED
1373 );
1374 $params = array(
1375 'id' => $competencyid,
1376 );
1377 return new external_function_parameters($params);
1378 }
1379
d9a39950
DW
1380 /**
1381 * Change the sort order of a competency.
1382 *
b17d3d10 1383 * @param int $competencyid Competency id.
d9a39950
DW
1384 * @return boolean
1385 */
1386 public static function move_down_competency($competencyid) {
d9a39950
DW
1387 $params = self::validate_parameters(self::move_down_competency_parameters(),
1388 array(
1389 'id' => $competencyid,
1390 ));
1391
86938d06 1392 $competency = api::read_competency($params['id']);
a214d35e 1393 self::validate_context($competency->get_context());
86938d06 1394
d9a39950
DW
1395 return api::move_down_competency($params['id']);
1396 }
1397
1398 /**
1399 * Returns description of move_down_competency() result value.
1400 *
e90c24d0 1401 * @return \external_description
d9a39950
DW
1402 */
1403 public static function move_down_competency_returns() {
1404 return new external_value(PARAM_BOOL, 'True if the update was successful');
1405 }
1406
1407 /**
1408 * Returns description of count_courses_using_competency() parameters.
1409 *
e90c24d0 1410 * @return \external_function_parameters
d9a39950
DW
1411 */
1412 public static function count_courses_using_competency_parameters() {
1413 $competencyid = new external_value(
1414 PARAM_INT,
1415 'The competency id',
1416 VALUE_REQUIRED
1417 );
1418 $params = array(
1419 'id' => $competencyid,
1420 );
1421 return new external_function_parameters($params);
1422 }
1423
d9a39950
DW
1424 /**
1425 * Count the courses (visible to this user) that use this competency.
1426 *
b17d3d10 1427 * @param int $competencyid Competency id.
d9a39950
DW
1428 * @return int
1429 */
1430 public static function count_courses_using_competency($competencyid) {
d9a39950
DW
1431 $params = self::validate_parameters(self::count_courses_using_competency_parameters(),
1432 array(
1433 'id' => $competencyid,
1434 ));
1435
86938d06 1436 $competency = api::read_competency($params['id']);
a214d35e 1437 self::validate_context($competency->get_context());
86938d06 1438
d9a39950
DW
1439 return api::count_courses_using_competency($params['id']);
1440 }
1441
1442 /**
1443 * Returns description of count_courses_using_competency() result value.
1444 *
e90c24d0 1445 * @return \external_description
d9a39950
DW
1446 */
1447 public static function count_courses_using_competency_returns() {
1448 return new external_value(PARAM_INT, 'The number of courses using this competency');
1449 }
1450
1451 /**
1452 * Returns description of list_courses_using_competency() parameters.
1453 *
e90c24d0 1454 * @return \external_function_parameters
d9a39950
DW
1455 */
1456 public static function list_courses_using_competency_parameters() {
1457 $competencyid = new external_value(
1458 PARAM_INT,
1459 'The competency id',
1460 VALUE_REQUIRED
1461 );
1462 $params = array(
1463 'id' => $competencyid,
1464 );
1465 return new external_function_parameters($params);
1466 }
1467
d9a39950
DW
1468 /**
1469 * Count the courses (visible to this user) that use this competency.
1470 *
b17d3d10 1471 * @param int $competencyid Competency id.
d9a39950
DW
1472 * @return array
1473 */
1474 public static function list_courses_using_competency($competencyid) {
c80630da
DW
1475 global $PAGE;
1476
d9a39950
DW
1477 $params = self::validate_parameters(self::list_courses_using_competency_parameters(),
1478 array(
1479 'id' => $competencyid,
1480 ));
1481
86938d06 1482 $competency = api::read_competency($params['id']);
a214d35e 1483 self::validate_context($competency->get_context());
c80630da 1484 $output = $PAGE->get_renderer('tool_lp');
86938d06 1485
c80630da
DW
1486 $results = array();
1487 $courses = api::list_courses_using_competency($params['id']);
1488 foreach ($courses as $course) {
1489 $context = context_course::instance($course->id);
1490 $exporter = new course_summary_exporter($course, array('context' => $context));
1491 $result = $exporter->export($output);
1492 array_push($results, $result);
1493 }
1494 return $results;
d9a39950
DW
1495 }
1496
1497 /**
1498 * Returns description of list_courses_using_competency() result value.
1499 *
e90c24d0 1500 * @return \external_description
d9a39950
DW
1501 */
1502 public static function list_courses_using_competency_returns() {
c80630da 1503 return new external_multiple_structure(course_summary_exporter::get_read_structure());
d9a39950
DW
1504 }
1505
1506 /**
1507 * Returns description of count_competencies_in_course() parameters.
1508 *
e90c24d0 1509 * @return \external_function_parameters
d9a39950
DW
1510 */
1511 public static function count_competencies_in_course_parameters() {
1512 $courseid = new external_value(
1513 PARAM_INT,
1514 'The course id',
1515 VALUE_REQUIRED
1516 );
1517 $params = array(
1518 'id' => $courseid,
1519 );
1520 return new external_function_parameters($params);
1521 }
1522
d9a39950
DW
1523 /**
1524 * Count the competencies (visible to this user) in this course.
1525 *
b17d3d10 1526 * @param int $courseid The course id to check.
d9a39950
DW
1527 * @return int
1528 */
1529 public static function count_competencies_in_course($courseid) {
d9a39950
DW
1530 $params = self::validate_parameters(self::count_competencies_in_course_parameters(),
1531 array(
1532 'id' => $courseid,
1533 ));
1534
86938d06
DW
1535 self::validate_context(context_course::instance($params['id']));
1536
d9a39950
DW
1537 return api::count_competencies_in_course($params['id']);
1538 }
1539
1540 /**
1541 * Returns description of count_competencies_in_course() result value.
1542 *
e90c24d0 1543 * @return \external_description
d9a39950
DW
1544 */
1545 public static function count_competencies_in_course_returns() {
1546 return new external_value(PARAM_INT, 'The number of competencies in this course.');
1547 }
1548
db650737
DW
1549 /**
1550 * Returns description of list_course_module_competencies() parameters.
1551 *
1552 * @return \external_function_parameters
1553 */
1554 public static function list_course_module_competencies_parameters() {
1555 $cmid = new external_value(
1556 PARAM_INT,
1557 'The course module id',
1558 VALUE_REQUIRED
1559 );
1560 $params = array(
1561 'cmid' => $cmid
1562 );
1563 return new external_function_parameters($params);
1564 }
1565
1566 /**
1567 * List the course modules using this competency (visible to this user) in this course.
1568 *
1569 * @param int $cmid The course module id to check.
1570 * @return array
1571 */
1572 public static function list_course_module_competencies($cmid) {
1573 global $PAGE;
1574
1575 $params = self::validate_parameters(self::list_course_module_competencies_parameters(),
1576 array(
1577 'cmid' => $cmid
1578 ));
1579
f446b2e1 1580 $context = context_module::instance($params['cmid']);
db650737
DW
1581 self::validate_context($context);
1582
1583 $output = $PAGE->get_renderer('tool_lp');
1584
1585 $apiresult = api::list_course_module_competencies($params['cmid']);
1586 $result = array();
1587
1588 foreach ($apiresult as $cmrecord) {
d846a535 1589 $one = new \stdClass();
db650737
DW
1590 $exporter = new competency_exporter($cmrecord['competency']);
1591 $one->competency = $exporter->export($output);
1592 $exporter = new course_module_competency_exporter($cmrecord['coursemodulecompetency']);
1593 $one->coursemodulecompetency = $exporter->export($output);
1594
1595 $result[] = (array) $one;
1596 }
1597
1598 return $result;
1599 }
1600
1601 /**
1602 * Returns description of list_course_module_competencies() result value.
1603 *
1604 * @return \external_description
1605 */
1606 public static function list_course_module_competencies_returns() {
1607 return new external_multiple_structure(
1608 new external_single_structure(array(
1609 'competency' => competency_exporter::get_read_structure(),
1610 'coursemodulecompetency' => course_module_competency_exporter::get_read_structure()
1611 ))
1612 );
1613 }
1614
1615 /**
1616 * Returns description of list_course_modules_using_competency() parameters.
1617 *
1618 * @return \external_function_parameters
1619 */
1620 public static function list_course_modules_using_competency_parameters() {
1621 $competencyid = new external_value(
1622 PARAM_INT,
1623 'The competency id',
1624 VALUE_REQUIRED
1625 );
1626 $courseid = new external_value(
1627 PARAM_INT,
1628 'The course id',
1629 VALUE_REQUIRED
1630 );
1631 $params = array(
1632 'competencyid' => $competencyid,
1633 'courseid' => $courseid,
1634 );
1635 return new external_function_parameters($params);
1636 }
1637
1638 /**
1639 * List the course modules using this competency (visible to this user) in this course.
1640 *
1641 * @param int $competencyid The competency id to check.
1642 * @param int $courseid The course id to check.
1643 * @return array
1644 */
1645 public static function list_course_modules_using_competency($competencyid, $courseid) {
1646 global $PAGE;
1647
1f769953
FM
1648 $params = self::validate_parameters(self::list_course_modules_using_competency_parameters(), array(
1649 'competencyid' => $competencyid,
1650 'courseid' => $courseid,
1651 ));
db650737
DW
1652
1653 $coursecontext = context_course::instance($params['courseid']);
1654 self::validate_context($coursecontext);
1655
1656 $output = $PAGE->get_renderer('tool_lp');
1657
1658 $coursemodules = api::list_course_modules_using_competency($params['competencyid'], $params['courseid']);
1659 $result = array();
1660
1f769953 1661 $fastmodinfo = get_fast_modinfo($params['courseid']);
24fc4e30 1662
f446b2e1 1663 foreach ($coursemodules as $cmid) {
24fc4e30
DW
1664 $cminfo = $fastmodinfo->cms[$cmid];
1665 $exporter = new course_module_summary_exporter(null, array('cm' => $cminfo));
db650737
DW
1666 $coursemodulesummary = $exporter->export($output);
1667
1668 $result[] = $coursemodulesummary;
1669 }
1670
1671 return $result;
1672 }
1673
1674 /**
1675 * Returns description of list_course_modules_using_competency() result value.
1676 *
1677 * @return \external_description
1678 */
1679 public static function list_course_modules_using_competency_returns() {
1680 return new external_multiple_structure(course_module_summary_exporter::get_read_structure());
1681 }
1682
d9a39950 1683 /**
d4c0a2f6 1684 * Returns description of list_course_competencies() parameters.
d9a39950 1685 *
e90c24d0 1686 * @return \external_function_parameters
d9a39950 1687 */
d4c0a2f6 1688 public static function list_course_competencies_parameters() {
d9a39950
DW
1689 $courseid = new external_value(
1690 PARAM_INT,
1691 'The course id',
1692 VALUE_REQUIRED
1693 );
1694 $params = array(
1695 'id' => $courseid,
1696 );
1697 return new external_function_parameters($params);
1698 }
1699
d9a39950
DW
1700 /**
1701 * List the competencies (visible to this user) in this course.
1702 *
b17d3d10 1703 * @param int $courseid The course id to check.
d9a39950
DW
1704 * @return array
1705 */
d4c0a2f6 1706 public static function list_course_competencies($courseid) {
86938d06
DW
1707 global $PAGE;
1708
d4c0a2f6 1709 $params = self::validate_parameters(self::list_course_competencies_parameters(),
d9a39950
DW
1710 array(
1711 'id' => $courseid,
1712 ));
1713
e1964c90
DW
1714 $coursecontext = context_course::instance($params['id']);
1715 self::validate_context($coursecontext);
1716
86938d06
DW
1717 $output = $PAGE->get_renderer('tool_lp');
1718
d4c0a2f6
SG
1719 $competencies = api::list_course_competencies($params['id']);
1720 $result = array();
86938d06
DW
1721
1722 $contextcache = array();
d9a39950 1723 foreach ($competencies as $competency) {
d4c0a2f6
SG
1724 if (!isset($contextcache[$competency['competency']->get_competencyframeworkid()])) {
1725 $contextcache[$competency['competency']->get_competencyframeworkid()] = $competency['competency']->get_context();
86938d06 1726 }
d4c0a2f6
SG
1727 $context = $contextcache[$competency['competency']->get_competencyframeworkid()];
1728 $exporter = new competency_exporter($competency['competency'], array('context' => $context));
1729 $competencyrecord = $exporter->export($output);
1730 $exporter = new course_competency_exporter($competency['coursecompetency'], array('context' => $context));
1731 $coursecompetencyrecord = $exporter->export($output);
e1964c90 1732
d4c0a2f6
SG
1733 $result[] = array(
1734 'competency' => $competencyrecord,
1735 'coursecompetency' => $coursecompetencyrecord
1736 );
d9a39950 1737 }
d4c0a2f6
SG
1738
1739 return $result;
d9a39950
DW
1740 }
1741
1742 /**
d4c0a2f6 1743 * Returns description of list_course_competencies() result value.
d9a39950 1744 *
e90c24d0 1745 * @return \external_description
d9a39950 1746 */
d4c0a2f6 1747 public static function list_course_competencies_returns() {
d4c0a2f6
SG
1748 return new external_multiple_structure(
1749 new external_single_structure(array(
1750 'competency' => competency_exporter::get_read_structure(),
1751 'coursecompetency' => course_competency_exporter::get_read_structure()
1752 ))
1753 );
1754
d9a39950
DW
1755 }
1756
1757 /**
1758 * Returns description of add_competency_to_course() parameters.
1759 *
e90c24d0 1760 * @return \external_function_parameters
d9a39950
DW
1761 */
1762 public static function add_competency_to_course_parameters() {
1763 $courseid = new external_value(
1764 PARAM_INT,
1765 'The course id',
1766 VALUE_REQUIRED
1767 );
1768 $competencyid = new external_value(
1769 PARAM_INT,
1770 'The competency id',
1771 VALUE_REQUIRED
1772 );
1773 $params = array(
1774 'courseid' => $courseid,
1775 'competencyid' => $competencyid,
1776 );
1777 return new external_function_parameters($params);
1778 }
1779
d9a39950
DW
1780 /**
1781 * Count the competencies (visible to this user) in this course.
1782 *
b17d3d10
AA
1783 * @param int $courseid The course id to check.
1784 * @param int $competencyid Competency id.
d9a39950
DW
1785 * @return int
1786 */
1787 public static function add_competency_to_course($courseid, $competencyid) {
d9a39950
DW
1788 $params = self::validate_parameters(self::add_competency_to_course_parameters(),
1789 array(
1790 'courseid' => $courseid,
1791 'competencyid' => $competencyid,
1792 ));
1793
86938d06
DW
1794 self::validate_context(context_course::instance($params['courseid']));
1795
d9a39950
DW
1796 return api::add_competency_to_course($params['courseid'], $params['competencyid']);
1797 }
1798
1799 /**
1800 * Returns description of add_competency_to_course() result value.
1801 *
e90c24d0 1802 * @return \external_description
d9a39950
DW
1803 */
1804 public static function add_competency_to_course_returns() {
1805 return new external_value(PARAM_BOOL, 'True if successful.');
1806 }
1807
1808 /**
1809 * Returns description of remove_competency_from_course() parameters.
1810 *
e90c24d0 1811 * @return \external_function_parameters
d9a39950
DW
1812 */
1813 public static function remove_competency_from_course_parameters() {
1814 $courseid = new external_value(
1815 PARAM_INT,
1816 'The course id',
1817 VALUE_REQUIRED
1818 );
1819 $competencyid = new external_value(
1820 PARAM_INT,
1821 'The competency id',
1822 VALUE_REQUIRED
1823 );
1824 $params = array(
1825 'courseid' => $courseid,
1826 'competencyid' => $competencyid,
1827 );
1828 return new external_function_parameters($params);
1829 }
1830
d9a39950
DW
1831 /**
1832 * Count the competencies (visible to this user) in this course.
1833 *
b17d3d10
AA
1834 * @param int $courseid The course id to check.
1835 * @param int $competencyid Competency id.
d9a39950
DW
1836 * @return int
1837 */
1838 public static function remove_competency_from_course($courseid, $competencyid) {
1839 $params = self::validate_parameters(self::remove_competency_from_course_parameters(),
1840 array(
1841 'courseid' => $courseid,
1842 'competencyid' => $competencyid,
1843 ));
1844
86938d06
DW
1845 self::validate_context(context_course::instance($params['courseid']));
1846
d9a39950
DW
1847 return api::remove_competency_from_course($params['courseid'], $params['competencyid']);
1848 }
1849
1850 /**
1851 * Returns description of remove_competency_from_course() result value.
1852 *
e90c24d0 1853 * @return \external_description
d9a39950
DW
1854 */
1855 public static function remove_competency_from_course_returns() {
1856 return new external_value(PARAM_BOOL, 'True if successful.');
1857 }
1858
1859 /**
1860 * Returns description of data_for_course_competenies_page() parameters.
1861 *
e90c24d0 1862 * @return \external_function_parameters
d9a39950
DW
1863 */
1864 public static function data_for_course_competencies_page_parameters() {
1865 $courseid = new external_value(
1866 PARAM_INT,
1867 'The course id',
1868 VALUE_REQUIRED
1869 );
1870 $params = array('courseid' => $courseid);
1871 return new external_function_parameters($params);
1872 }
1873
d9a39950
DW
1874 /**
1875 * Loads the data required to render the course_competencies_page template.
1876 *
b17d3d10 1877 * @param int $courseid The course id to check.
d9a39950
DW
1878 * @return boolean
1879 */
1880 public static function data_for_course_competencies_page($courseid) {
1881 global $PAGE;
1882 $params = self::validate_parameters(self::data_for_course_competencies_page_parameters(),
1883 array(
1884 'courseid' => $courseid,
1885 ));
86938d06 1886 self::validate_context(context_course::instance($params['courseid']));
d9a39950 1887
b17d3d10 1888 $renderable = new output\course_competencies_page($params['courseid']);
d9a39950
DW
1889 $renderer = $PAGE->get_renderer('tool_lp');
1890
1891 $data = $renderable->export_for_template($renderer);
1892
1893 return $data;
1894 }
1895
1896 /**
1897 * Returns description of data_for_course_competencies_page() result value.
1898 *
e90c24d0 1899 * @return \external_description
d9a39950
DW
1900 */
1901 public static function data_for_course_competencies_page_returns() {
96f4d771
DW
1902 $ucc = user_competency_course_exporter::get_read_structure();
1903 $ucc->required = VALUE_OPTIONAL;
e1964c90 1904
d9a39950
DW
1905 return new external_single_structure(array (
1906 'courseid' => new external_value(PARAM_INT, 'The current course id'),
d660824b 1907 'pagecontextid' => new external_value(PARAM_INT, 'The current page context ID.'),
e1964c90 1908 'gradableuserid' => new external_value(PARAM_INT, 'Current user id, if the user is a gradable user.', VALUE_OPTIONAL),
d9a39950
DW
1909 'canmanagecompetencyframeworks' => new external_value(PARAM_BOOL, 'User can manage competency frameworks'),
1910 'canmanagecoursecompetencies' => new external_value(PARAM_BOOL, 'User can manage linked course competencies'),
7ba07487 1911 'canconfigurecoursecompetencies' => new external_value(PARAM_BOOL, 'User can configure course competency settings'),
eb0d340c 1912 'settings' => course_competency_settings_exporter::get_read_structure(),
f1979b60 1913 'statistics' => course_competency_statistics_exporter::get_read_structure(),
d660824b
FM
1914 'competencies' => new external_multiple_structure(new external_single_structure(array(
1915 'competency' => competency_exporter::get_read_structure(),
72181303 1916 'coursecompetency' => course_competency_exporter::get_read_structure(),
db650737 1917 'coursemodules' => new external_multiple_structure(course_module_summary_exporter::get_read_structure()),
96f4d771 1918 'usercompetencycourse' => $ucc,
72181303
DW
1919 'ruleoutcomeoptions' => new external_multiple_structure(
1920 new external_single_structure(array(
1921 'value' => new external_value(PARAM_INT, 'The option value'),
1922 'text' => new external_value(PARAM_NOTAGS, 'The name of the option'),
1923 'selected' => new external_value(PARAM_BOOL, 'If this is the currently selected option'),
8c9cb5ec
IT
1924 ))),
1925 'comppath' => competency_path_exporter::get_read_structure(),
d660824b 1926 ))),
d9a39950
DW
1927 'manageurl' => new external_value(PARAM_LOCALURL, 'Url to the manage competencies page.'),
1928 ));
1929
1930 }
1931
1932 /**
1933 * Returns description of reorder_course_competency() parameters.
1934 *
e90c24d0 1935 * @return \external_function_parameters
d9a39950
DW
1936 */
1937 public static function reorder_course_competency_parameters() {
1938 $courseid = new external_value(
1939 PARAM_INT,
1940 'The course id',
1941 VALUE_REQUIRED
1942 );
1943 $competencyidfrom = new external_value(
1944 PARAM_INT,
1945 'The competency id we are moving',
1946 VALUE_REQUIRED
1947 );
1948 $competencyidto = new external_value(
1949 PARAM_INT,
1950 'The competency id we are moving to',
1951 VALUE_REQUIRED
1952 );
1953 $params = array(
1954 'courseid' => $courseid,
1955 'competencyidfrom' => $competencyidfrom,
1956 'competencyidto' => $competencyidto,
1957 );
1958 return new external_function_parameters($params);
1959 }
1960
d9a39950
DW
1961 /**
1962 * Change the order of course competencies.
1963 *
1964 * @param int $courseid The course id
1965 * @param int $competencyidfrom The competency to move.
1966 * @param int $competencyidto The competency to move to.
1967 * @return bool
1968 */
1969 public static function reorder_course_competency($courseid, $competencyidfrom, $competencyidto) {
1970 $params = self::validate_parameters(self::reorder_course_competency_parameters(),
1971 array(
1972 'courseid' => $courseid,
1973 'competencyidfrom' => $competencyidfrom,
1974 'competencyidto' => $competencyidto,
1975 ));
86938d06 1976 self::validate_context(context_course::instance($params['courseid']));
d9a39950
DW
1977
1978 return api::reorder_course_competency($params['courseid'], $params['competencyidfrom'], $params['competencyidto']);
1979 }
1980
1981 /**
1982 * Returns description of reorder_course_competency() result value.
1983 *
e90c24d0 1984 * @return \external_description
d9a39950
DW
1985 */
1986 public static function reorder_course_competency_returns() {
1987 return new external_value(PARAM_BOOL, 'True if successful.');
54c5a739
MN
1988 }
1989
1990 /**
1991 * Returns description of reorder_template_competency() parameters.
1992 *
e90c24d0 1993 * @return \external_function_parameters
54c5a739
MN
1994 */
1995 public static function reorder_template_competency_parameters() {
1996 $templateid = new external_value(
1997 PARAM_INT,
1998 'The template id',
1999 VALUE_REQUIRED
2000 );
2001 $competencyidfrom = new external_value(
2002 PARAM_INT,
2003 'The competency id we are moving',
2004 VALUE_REQUIRED
2005 );
2006 $competencyidto = new external_value(
2007 PARAM_INT,
2008 'The competency id we are moving to',
2009 VALUE_REQUIRED
2010 );
2011 $params = array(
2012 'templateid' => $templateid,
2013 'competencyidfrom' => $competencyidfrom,
2014 'competencyidto' => $competencyidto,
2015 );
2016 return new external_function_parameters($params);
2017 }
2018
54c5a739
MN
2019 /**
2020 * Change the order of template competencies.
2021 *
2022 * @param int $templateid The template id
2023 * @param int $competencyidfrom The competency to move.
2024 * @param int $competencyidto The competency to move to.
2025 * @return bool
2026 */
2027 public static function reorder_template_competency($templateid, $competencyidfrom, $competencyidto) {
2028 $params = self::validate_parameters(self::reorder_template_competency_parameters(),
2029 array(
2030 'templateid' => $templateid,
2031 'competencyidfrom' => $competencyidfrom,
2032 'competencyidto' => $competencyidto,
2033 ));
2034
86938d06
DW
2035 $template = api::read_template($params['templateid']);
2036 self::validate_context($template->get_context());
2037
54c5a739
MN
2038 return api::reorder_template_competency($params['templateid'], $params['competencyidfrom'], $params['competencyidto']);
2039 }
2040
2041 /**
2042 * Returns description of reorder_template_competency() result value.
2043 *
e90c24d0 2044 * @return \external_description
54c5a739
MN
2045 */
2046 public static function reorder_template_competency_returns() {
2047 return new external_value(PARAM_BOOL, 'True if successful.');
d9a39950
DW
2048 }
2049
d9a39950
DW
2050 /**
2051 * Returns description of create_template() parameters.
2052 *
e90c24d0 2053 * @return \external_function_parameters
d9a39950
DW
2054 */
2055 public static function create_template_parameters() {
578e61c1 2056 $structure = template_exporter::get_create_structure();
8ec5f810 2057 $params = array('template' => $structure);
d9a39950
DW
2058 return new external_function_parameters($params);
2059 }
2060
d9a39950
DW
2061 /**
2062 * Create a new learning plan template
2063 *
8ec5f810 2064 * @param array $template The list of fields for the template.
b17d3d10 2065 * @return \stdClass Record of new template.
d9a39950 2066 */
8ec5f810 2067 public static function create_template($template) {
86938d06
DW
2068 global $PAGE;
2069
d9a39950 2070 $params = self::validate_parameters(self::create_template_parameters(),
8ec5f810
DW
2071 array('template' => $template));
2072 $params = $params['template'];
2073 $context = self::get_context_from_params($params);
f0da26a4 2074 self::validate_context($context);
86938d06 2075 $output = $PAGE->get_renderer('tool_lp');
d9a39950 2076
8ec5f810
DW
2077 unset($params['contextlevel']);
2078 unset($params['instanceid']);
d9a39950 2079 $params = (object) $params;
f0da26a4 2080 $params->contextid = $context->id;
d9a39950
DW
2081
2082 $result = api::create_template($params);
86938d06 2083 $exporter = new template_exporter($result);
5db5c22c 2084 $record = $exporter->export($output);
cda17bd9 2085 return $record;
d9a39950
DW
2086 }
2087
2088 /**
2089 * Returns description of create_template() result value.
2090 *
e90c24d0 2091 * @return \external_description
d9a39950
DW
2092 */
2093 public static function create_template_returns() {
578e61c1 2094 return template_exporter::get_read_structure();
d9a39950
DW
2095 }
2096
2097 /**
2098 * Returns description of read_template() parameters.
2099 *
e90c24d0 2100 * @return \external_function_parameters
d9a39950
DW
2101 */
2102 public static function read_template_parameters() {
2103 $id = new external_value(
2104 PARAM_INT,
2105 'Data base record id for the template',
2106 VALUE_REQUIRED
2107 );
2108
2109 $params = array(
2110 'id' => $id,
2111 );
2112 return new external_function_parameters($params);
2113 }
2114
d9a39950
DW
2115 /**
2116 * Read a learning plan template by id.
2117 *
2118 * @param int $id The id of the template.
b17d3d10 2119 * @return \stdClass
d9a39950
DW
2120 */
2121 public static function read_template($id) {
86938d06
DW
2122 global $PAGE;
2123
d9a39950
DW
2124 $params = self::validate_parameters(self::read_template_parameters(),
2125 array(
2126 'id' => $id,
2127 ));
2128
86938d06
DW
2129 $template = api::read_template($params['id']);
2130 self::validate_context($template->get_context());
2131 $output = $PAGE->get_renderer('tool_lp');
2132
2133 $exporter = new template_exporter($template);
5db5c22c 2134 $record = $exporter->export($output);
cda17bd9 2135 return $record;
d9a39950
DW
2136 }
2137
2138 /**
2139 * Returns description of read_template() result value.
2140 *
e90c24d0 2141 * @return \external_description
d9a39950
DW
2142 */
2143 public static function read_template_returns() {
578e61c1 2144 return template_exporter::get_read_structure();
d9a39950
DW
2145 }
2146
2147 /**
2148 * Returns description of delete_template() parameters.
2149 *
e90c24d0 2150 * @return \external_function_parameters
d9a39950
DW
2151 */
2152 public static function delete_template_parameters() {
2153 $id = new external_value(
2154 PARAM_INT,
2155 'Data base record id for the template',
2156 VALUE_REQUIRED
2157 );
2158
8fabc738
SG
2159 $deleteplans = new external_value(
2160 PARAM_BOOL,
2161 'Boolean to indicate if plans must be deleted',
2162 VALUE_REQUIRED
2163 );
2164
d9a39950
DW
2165 $params = array(
2166 'id' => $id,
8fabc738 2167 'deleteplans' => $deleteplans
d9a39950
DW
2168 );
2169 return new external_function_parameters($params);
2170 }
2171
d9a39950
DW
2172 /**
2173 * Delete a learning plan template
2174 *
2175 * @param int $id The learning plan template id
8fabc738 2176 * @param boolean $deleteplans True to delete the plans associated to template or false to unlink them
d9a39950
DW
2177 * @return boolean
2178 */
8fabc738 2179 public static function delete_template($id, $deleteplans = true) {
d9a39950
DW
2180 $params = self::validate_parameters(self::delete_template_parameters(),
2181 array(
2182 'id' => $id,
8fabc738 2183 'deleteplans' => $deleteplans,
d9a39950
DW
2184 ));
2185
86938d06
DW
2186 $template = api::read_template($params['id']);
2187 self::validate_context($template->get_context());
2188
8fabc738 2189 return api::delete_template($params['id'], $params['deleteplans']);
d9a39950
DW
2190 }
2191
2192 /**
2193 * Returns description of delete_template() result value.
2194 *
e90c24d0 2195 * @return \external_description
d9a39950
DW
2196 */
2197 public static function delete_template_returns() {
2198 return new external_value(PARAM_BOOL, 'True if the delete was successful');
2199 }
2200
2201 /**
2202 * Returns description of update_template() parameters.
2203 *
e90c24d0 2204 * @return \external_function_parameters
d9a39950
DW
2205 */
2206 public static function update_template_parameters() {
578e61c1 2207 $structure = template_exporter::get_update_structure();
8ec5f810 2208 $params = array('template' => $structure);
d9a39950
DW
2209 return new external_function_parameters($params);
2210 }
2211
d9a39950
DW
2212 /**
2213 * Update an existing learning plan template
2214 *
8ec5f810 2215 * @param array $template The list of fields for the template.
d9a39950
DW
2216 * @return boolean
2217 */
8ec5f810 2218 public static function update_template($template) {
d9a39950
DW
2219
2220 $params = self::validate_parameters(self::update_template_parameters(),
8ec5f810
DW
2221 array('template' => $template));
2222 $params = $params['template'];
86938d06
DW
2223 $template = api::read_template($params['id']);
2224 self::validate_context($template->get_context());
2225
d9a39950
DW
2226 $params = (object) $params;
2227
2228 return api::update_template($params);
2229 }
2230
2231 /**
2232 * Returns description of update_template() result value.
2233 *
e90c24d0 2234 * @return \external_description
d9a39950
DW
2235 */
2236 public static function update_template_returns() {
2237 return new external_value(PARAM_BOOL, 'True if the update was successful');
2238 }
2239
76c107ea
IT
2240 /**
2241 * Returns description of duplicate_template() parameters.
2242 *
2243 * @return \external_function_parameters
2244 */
2245 public static function duplicate_template_parameters() {
2246 $templateid = new external_value(
2247 PARAM_INT,
2248 'The template id',
2249 VALUE_REQUIRED
2250 );
2251
2252 $params = array(
2253 'id' => $templateid
2254 );
2255 return new external_function_parameters($params);
2256 }
2257
76c107ea
IT
2258 /**
2259 * Duplicate a learning plan template.
2260 *
2261 * @param int $id the id of the learning plan template to duplicate
2262 * @return boolean Record of new template.
2263 */
2264 public static function duplicate_template($id) {
86938d06
DW
2265 global $PAGE;
2266
76c107ea
IT
2267 $params = self::validate_parameters(self::duplicate_template_parameters(),
2268 array(
2269 'id' => $id,
2270 ));
2271
86938d06
DW
2272 $template = api::read_template($params['id']);
2273 self::validate_context($template->get_context());
2274 $output = $PAGE->get_renderer('tool_lp');
2275
76c107ea 2276 $result = api::duplicate_template($params['id']);
86938d06 2277 $exporter = new template_exporter($result);
5db5c22c 2278 return $exporter->export($output);
76c107ea
IT
2279 }
2280
2281 /**
2282 * Returns description of duplicate_template() result value.
2283 *
2284 * @return \external_description
2285 */
2286 public static function duplicate_template_returns() {
578e61c1 2287 return template_exporter::get_read_structure();
76c107ea
IT
2288 }
2289
d9a39950
DW
2290 /**
2291 * Returns description of list_templates() parameters.
2292 *
e90c24d0 2293 * @return \external_function_parameters
d9a39950
DW
2294 */
2295 public static function list_templates_parameters() {
3392a313 2296 $sort = new external_value(
f0da26a4
FM
2297 PARAM_ALPHANUMEXT,
2298 'Column to sort by.',
2299 VALUE_DEFAULT,
2300 ''
2301 );
2302 $order = new external_value(
2303 PARAM_ALPHA,
2304 'Sort direction. Should be either ASC or DESC',
2305 VALUE_DEFAULT,
2306 ''
2307 );
2308 $skip = new external_value(
2309 PARAM_INT,
2310 'Skip this number of records before returning results',
2311 VALUE_DEFAULT,
2312 0
2313 );
2314 $limit = new external_value(
2315 PARAM_INT,
2316 'Return this number of records at most.',
2317 VALUE_DEFAULT,
2318 0
2319 );
2320 $includes = new external_value(
2321 PARAM_ALPHA,
2322 'What other contexts to fetch the templates from. (children, parents, self)',
2323 VALUE_DEFAULT,
2324 'children'
2325 );
964afa98
IT
2326 $onlyvisible = new external_value(
2327 PARAM_BOOL,
2328 'If should list only visible templates',
2329 VALUE_DEFAULT,
2330 false
2331 );
f0da26a4
FM
2332
2333 $params = array(
2334 'sort' => $sort,
2335 'order' => $order,
2336 'skip' => $skip,
2337 'limit' => $limit,
2338 'context' => self::get_context_parameters(),
964afa98
IT
2339 'includes' => $includes,
2340 'onlyvisible' => $onlyvisible
f0da26a4
FM
2341 );
2342 return new external_function_parameters($params);
d9a39950
DW
2343 }
2344
d9a39950
DW
2345 /**
2346 * List the existing learning plan templates
2347 *
b17d3d10
AA
2348 * @param string $sort Field to sort by.
2349 * @param string $order Sort order.
2350 * @param int $skip Limitstart.
2351 * @param int $limit Number of rows to return.
f0da26a4
FM
2352 * @param array $context
2353 * @param bool $includes
964afa98 2354 * @param bool $onlyvisible
b17d3d10
AA
2355 *
2356 * @return array
d9a39950 2357 */
964afa98 2358 public static function list_templates($sort, $order, $skip, $limit, $context, $includes, $onlyvisible) {
86938d06
DW
2359 global $PAGE;
2360
d9a39950
DW
2361 $params = self::validate_parameters(self::list_templates_parameters(),
2362 array(
d9a39950
DW
2363 'sort' => $sort,
2364 'order' => $order,
2365 'skip' => $skip,
f0da26a4
FM
2366 'limit' => $limit,
2367 'context' => $context,
964afa98
IT
2368 'includes' => $includes,
2369 'onlyvisible' => $onlyvisible
d9a39950
DW
2370 ));
2371
f0da26a4
FM
2372 $context = self::get_context_from_params($params['context']);
2373 self::validate_context($context);
86938d06 2374 $output = $PAGE->get_renderer('tool_lp');
f0da26a4 2375
d9a39950
DW
2376 if ($params['order'] !== '' && $params['order'] !== 'ASC' && $params['order'] !== 'DESC') {
2377 throw new invalid_parameter_exception('Invalid order param. Must be ASC, DESC or empty.');
2378 }
2379
f0da26a4
FM
2380 $results = api::list_templates($params['sort'],
2381 $params['order'],
2382 $params['skip'],
2383 $params['limit'],
2384 $context,
964afa98
IT
2385 $params['includes'],
2386 $params['onlyvisible']);
d9a39950
DW
2387 $records = array();
2388 foreach ($results as $result) {
86938d06 2389 $exporter = new template_exporter($result);
5db5c22c 2390 $record = $exporter->export($output);
d9a39950
DW
2391 array_push($records, $record);
2392 }
2393 return $records;
2394 }
2395
2396 /**
2397 * Returns description of list_templates() result value.
2398 *
e90c24d0 2399 * @return \external_description
d9a39950
DW
2400 */
2401 public static function list_templates_returns() {
578e61c1 2402 return new external_multiple_structure(template_exporter::get_read_structure());
d9a39950
DW
2403 }
2404
2405 /**
2406 * Returns description of count_templates() parameters.
2407 *
e90c24d0 2408 * @return \external_function_parameters
d9a39950
DW
2409 */
2410 public static function count_templates_parameters() {
f0da26a4
FM
2411 $includes = new external_value(
2412 PARAM_ALPHA,
2413 'What other contextes to fetch the frameworks from. (children, parents, self)',
2414 VALUE_DEFAULT,
2415 'children'
2416 );
d9a39950
DW
2417
2418 $params = array(
f0da26a4
FM
2419 'context' => self::get_context_parameters(),
2420 'includes' => $includes
d9a39950
DW
2421 );
2422 return new external_function_parameters($params);
2423 }
2424
d9a39950
DW
2425 /**
2426 * Count the existing learning plan templates
2427 *
96c2b847
FM
2428 * @param array $context
2429 * @param string $includes
2430 * @return int
d9a39950 2431 */
f0da26a4 2432 public static function count_templates($context, $includes) {
d9a39950
DW
2433 $params = self::validate_parameters(self::count_templates_parameters(),
2434 array(
f0da26a4
FM
2435 'context' => $context,
2436 'includes' => $includes
d9a39950 2437 ));
f0da26a4
FM
2438 $context = self::get_context_from_params($params['context']);
2439 self::validate_context($context);
d9a39950 2440
f0da26a4 2441 return api::count_templates($context, $includes);
d9a39950
DW
2442 }
2443
2444 /**
2445 * Returns description of count_templates() result value.
2446 *
e90c24d0 2447 * @return \external_description
d9a39950
DW
2448 */
2449 public static function count_templates_returns() {
2450 return new external_value(PARAM_INT, 'The number of learning plan templates found.');
2451 }
2452
d9a39950
DW
2453 /**
2454 * Returns description of data_for_templates_manage_page() parameters.
2455 *
e90c24d0 2456 * @return \external_function_parameters
d9a39950
DW
2457 */
2458 public static function data_for_templates_manage_page_parameters() {
f0da26a4 2459 $params = array('pagecontext' => self::get_context_parameters());
d9a39950
DW
2460 return new external_function_parameters($params);
2461 }
2462
d9a39950
DW
2463 /**
2464 * Loads the data required to render the templates_manage_page template.
2465 *
f0da26a4 2466 * @param array $pagecontext The page context info.
d9a39950
DW
2467 * @return boolean
2468 */
f0da26a4 2469 public static function data_for_templates_manage_page($pagecontext) {
d9a39950
DW
2470 global $PAGE;
2471
f0da26a4
FM
2472 $params = self::validate_parameters(self::data_for_templates_manage_page_parameters(), array(
2473 'pagecontext' => $pagecontext
2474 ));
2475 $context = self::get_context_from_params($params['pagecontext']);
2476 self::validate_context($context);
2477
2478 $renderable = new output\manage_templates_page($context);
d9a39950
DW
2479 $renderer = $PAGE->get_renderer('tool_lp');
2480
2481 $data = $renderable->export_for_template($renderer);
2482
2483 return $data;
2484 }
2485
2486 /**
2487 * Returns description of data_for_templates_manage_page() result value.
2488 *
e90c24d0 2489 * @return \external_description
d9a39950
DW
2490 */
2491 public static function data_for_templates_manage_page_returns() {
2492 return new external_single_structure(array (
d9a39950 2493 'templates' => new external_multiple_structure(
578e61c1 2494 template_exporter::get_read_structure()
d9a39950
DW
2495 ),
2496 'pluginbaseurl' => new external_value(PARAM_LOCALURL, 'Url to the tool_lp plugin folder on this Moodle site'),
2497 'navigation' => new external_multiple_structure(
2498 new external_value(PARAM_RAW, 'HTML for a navigation item that should be on this page')
37798262 2499 ),
29530d63
FM
2500 'pagecontextid' => new external_value(PARAM_INT, 'The page context id'),
2501 'canmanage' => new external_value(PARAM_BOOL, 'Whether the user manage the templates')
d9a39950
DW
2502 ));
2503
2504 }
2505
2506 /**
2507 * Returns description of count_templates_using_competency() parameters.
2508 *
e90c24d0 2509 * @return \external_function_parameters
d9a39950
DW
2510 */
2511 public static function count_templates_using_competency_parameters() {
2512 $competencyid = new external_value(
2513 PARAM_INT,
2514 'The competency id',
2515 VALUE_REQUIRED
2516 );
2517 $params = array(
2518 'id' => $competencyid,
2519 );
2520 return new external_function_parameters($params);
2521 }
2522
d9a39950
DW
2523 /**
2524 * Count the learning plan templates (visible to this user) that use this competency.
2525 *
b17d3d10 2526 * @param int $competencyid Competency id.
d9a39950
DW
2527 * @return int
2528 */
2529 public static function count_templates_using_competency($competencyid) {
d9a39950
DW
2530 $params = self::validate_parameters(self::count_templates_using_competency_parameters(),
2531 array(
2532 'id' => $competencyid,
2533 ));
2534
86938d06 2535 $competency = api::read_competency($params['id']);
a214d35e 2536 self::validate_context($competency->get_context());
86938d06 2537
d9a39950
DW
2538 return api::count_templates_using_competency($params['id']);
2539 }
2540
2541 /**
2542 * Returns description of count_templates_using_competency() result value.
2543 *
e90c24d0 2544 * @return \external_description
d9a39950
DW
2545 */
2546 public static function count_templates_using_competency_returns() {
2547 return new external_value(PARAM_INT, 'The number of learning plan templates using this competency');
2548 }
2549
2550 /**
2551 * Returns description of list_templates_using_competency() parameters.
2552 *
e90c24d0 2553 * @return \external_function_parameters
d9a39950
DW
2554 */
2555 public static function list_templates_using_competency_parameters() {
2556 $competencyid = new external_value(
2557 PARAM_INT,
2558 'The competency id',
2559 VALUE_REQUIRED
2560 );
2561 $params = array(
2562 'id' => $competencyid,
2563 );
2564 return new external_function_parameters($params);
2565 }
2566
d9a39950
DW
2567 /**
2568 * List the learning plan templates (visible to this user) that use this competency.
2569 *
b17d3d10 2570 * @param int $competencyid Competency id.
d9a39950
DW
2571 * @return array
2572 */
2573 public static function list_templates_using_competency($competencyid) {
2574 global $PAGE;
86938d06 2575
d9a39950
DW
2576 $params = self::validate_parameters(self::list_templates_using_competency_parameters(),
2577 array(
2578 'id' => $competencyid,
2579 ));
2580
86938d06 2581 $competency = api::read_competency($params['id']);
a214d35e 2582 self::validate_context($competency->get_context());
86938d06
DW
2583 $output = $PAGE->get_renderer('tool_lp');
2584
2585 $templates = api::list_templates_using_competency($params['id']);
2586 $records = array();
2587
2588 foreach ($templates as $template) {
2589 $exporter = new template_exporter($template);
5db5c22c 2590 $record = $exporter->export($output);
86938d06
DW
2591 $records[] = $record;
2592 }
5b224627
IT
2593
2594 return $records;
d9a39950
DW
2595 }
2596
2597 /**
2598 * Returns description of list_templates_using_competency() result value.
2599 *
e90c24d0 2600 * @return \external_description
d9a39950
DW
2601 */
2602 public static function list_templates_using_competency_returns() {
578e61c1 2603 return new external_multiple_structure(template_exporter::get_read_structure());
d9a39950
DW
2604 }
2605
2606 /**
2607 * Returns description of count_competencies_in_template() parameters.
2608 *
e90c24d0 2609 * @return \external_function_parameters
d9a39950
DW
2610 */
2611 public static function count_competencies_in_template_parameters() {
2612 $templateid = new external_value(
2613 PARAM_INT,
2614 'The template id',
2615 VALUE_REQUIRED
2616 );
2617 $params = array(
2618 'id' => $templateid,
2619 );
2620 return new external_function_parameters($params);
2621 }
2622
d9a39950
DW
2623 /**
2624 * Count the competencies (visible to this user) in this learning plan template.
2625 *
2626 * @param int $templateid The template id to check
2627 * @return int
2628 */
2629 public static function count_competencies_in_template($templateid) {
d9a39950
DW
2630 $params = self::validate_parameters(self::count_competencies_in_template_parameters(),
2631 array(
2632 'id' => $templateid,
2633 ));
86938d06
DW
2634 $template = api::read_template($params['id']);
2635 self::validate_context($template->get_context());
d9a39950
DW
2636
2637 return api::count_competencies_in_template($params['id']);
2638 }
2639
2640 /**
2641 * Returns description of count_competencies_in_template() result value.
2642 *
e90c24d0 2643 * @return \external_description
d9a39950
DW
2644 */
2645 public static function count_competencies_in_template_returns() {
2646 return new external_value(PARAM_INT, 'The number of competencies in this learning plan template.');
2647 }
2648
2649 /**
2650 * Returns description of list_competencies_in_template() parameters.
2651 *
e90c24d0 2652 * @return \external_function_parameters
d9a39950
DW
2653 */
2654 public static function list_competencies_in_template_parameters() {
2655 $templateid = new external_value(
2656 PARAM_INT,
2657 'The template id',
2658 VALUE_REQUIRED
2659 );
2660 $params = array(
e90c24d0 2661 'id' => $templateid,
d9a39950
DW
2662 );
2663 return new external_function_parameters($params);
2664 }
2665
d9a39950
DW
2666 /**
2667 * List the competencies (visible to this user) in this learning plan template.
2668 *
b17d3d10 2669 * @param int $templateid Template id.
d9a39950
DW
2670 * @return array
2671 */
2672 public static function list_competencies_in_template($templateid) {
2673 global $PAGE;
86938d06 2674
d9a39950
DW
2675 $params = self::validate_parameters(self::list_competencies_in_template_parameters(),
2676 array(
2677 'id' => $templateid,
2678 ));
2679
86938d06
DW
2680 $template = api::read_template($params['id']);
2681 self::validate_context($template->get_context());
2682 $output = $PAGE->get_renderer('tool_lp');
2683
d9a39950
DW
2684 $competencies = api::list_competencies_in_template($params['id']);
2685 $results = array();
86938d06
DW
2686 $contextcache = array();
2687
d9a39950 2688 foreach ($competencies as $competency) {
86938d06 2689 if (!isset($contextcache[$competency->get_competencyframeworkid()])) {
a214d35e 2690 $contextcache[$competency->get_competencyframeworkid()] = $competency->get_context();
86938d06
DW
2691 }
2692 $context = $contextcache[$competency->get_competencyframeworkid()];
2693 $exporter = new competency_exporter($competency, array('context' => $context));
5db5c22c 2694 $record = $exporter->export($output);
d9a39950
DW
2695 array_push($results, $record);
2696 }
2697 return $results;
2698 }
2699
2700 /**
2701 * Returns description of list_competencies_in_template() result value.
2702 *
e90c24d0 2703 * @return \external_description
d9a39950
DW
2704 */
2705 public static function list_competencies_in_template_returns() {
578e61c1 2706 return new external_multiple_structure(competency_exporter::get_read_structure());
d9a39950
DW
2707 }
2708
2709 /**
2710 * Returns description of add_competency_to_template() parameters.
2711 *
e90c24d0 2712 * @return \external_function_parameters
d9a39950
DW
2713 */
2714 public static function add_competency_to_template_parameters() {
2715 $templateid = new external_value(
2716 PARAM_INT,
2717 'The template id',
2718 VALUE_REQUIRED
2719 );
2720 $competencyid = new external_value(
2721 PARAM_INT,
2722 'The competency id',
2723 VALUE_REQUIRED
2724 );
2725 $params = array(
2726 'templateid' => $templateid,
2727 'competencyid' => $competencyid,
2728 );
2729 return new external_function_parameters($params);
2730 }
2731
d9a39950
DW
2732 /**
2733 * Count the competencies (visible to this user) in this template.
2734 *
b17d3d10
AA
2735 * @param int $templateid Template id.
2736 * @param int $competencyid Competency id.
d9a39950
DW
2737 * @return int
2738 */
2739 public static function add_competency_to_template($templateid, $competencyid) {
2740 global $PAGE;
2741 $params = self::validate_parameters(self::add_competency_to_template_parameters(),
2742 array(
2743 'templateid' => $templateid,
2744 'competencyid' => $competencyid,
2745 ));
2746
86938d06
DW
2747 $template = api::read_template($params['templateid']);
2748 self::validate_context($template->get_context());
2749
d9a39950
DW
2750 return api::add_competency_to_template($params['templateid'], $params['competencyid']);
2751 }
2752
2753 /**
2754 * Returns description of add_competency_to_template() result value.
2755 *
e90c24d0 2756 * @return \external_description
d9a39950
DW
2757 */
2758 public static function add_competency_to_template_returns() {
2759 return new external_value(PARAM_BOOL, 'True if successful.');
2760 }
2761
554b369b
IT
2762 /**
2763 * Returns description of add_competency_to_plan() parameters.
2764 *
2765 * @return \external_function_parameters
2766 */
2767 public static function add_competency_to_plan_parameters() {
2768 $planid = new external_value(
2769 PARAM_INT,
2770 'The plan id',
2771 VALUE_REQUIRED
2772 );
2773 $competencyid = new external_value(
2774 PARAM_INT,
2775 'The competency id',
2776 VALUE_REQUIRED
2777 );
2778 $params = array(
2779 'planid' => $planid,
2780 'competencyid' => $competencyid,
2781 );
2782 return new external_function_parameters($params);
2783 }
2784
2785 /**
2786 * add competency to a learning plan.
2787 *
2788 * @param int $planid Plan id.
2789 * @param int $competencyid Competency id.
2790 * @return int
2791 */
2792 public static function add_competency_to_plan($planid, $competencyid) {
2793 $params = self::validate_parameters(self::add_competency_to_plan_parameters(),
2794 array(
2795 'planid' => $planid,
2796 'competencyid' => $competencyid,
2797 ));
2798
86938d06
DW
2799 $plan = api::read_plan($params['planid']);
2800 self::validate_context($plan->get_context());
2801
554b369b
IT
2802 return api::add_competency_to_plan($params['planid'], $params['competencyid']);
2803 }
2804
2805 /**
2806 * Returns description of add_competency_to_plan() result value.
2807 *
2808 * @return \external_description
2809 */
2810 public static function add_competency_to_plan_returns() {
2811 return new external_value(PARAM_BOOL, 'True if successful.');
2812 }
2813
2814 /**
2815 * Returns description of remove_competency_from_plan() parameters.
2816 *
2817 * @return \external_function_parameters
2818 */
2819 public static function remove_competency_from_plan_parameters() {
2820 $planid = new external_value(
2821 PARAM_INT,
2822 'The plan id',
2823 VALUE_REQUIRED
2824 );
2825 $competencyid = new external_value(
2826 PARAM_INT,
2827 'The competency id',
2828 VALUE_REQUIRED
2829 );
2830 $params = array(
2831 'planid' => $planid,
2832 'competencyid' => $competencyid,
2833 );
2834 return new external_function_parameters($params);
2835 }
2836
2837 /**
2838 * Remove a competency from plan.
2839 *
2840 * @param int $planid Plan id.
2841 * @param int $competencyid Competency id.
2842 * @return int
2843 */
2844 public static function remove_competency_from_plan($planid, $competencyid) {
2845 $params = self::validate_parameters(self::remove_competency_from_plan_parameters(),
2846 array(
2847 'planid' => $planid,
2848 'competencyid' => $competencyid,
2849 ));
86938d06
DW
2850 $plan = api::read_plan($params['planid']);
2851 self::validate_context($plan->get_context());
554b369b
IT
2852
2853 return api::remove_competency_from_plan($params['planid'], $params['competencyid']);
2854 }
2855
2856 /**
2857 * Returns description of remove_competency_from_plan() result value.
2858 *
2859 * @return \external_description
2860 */
2861 public static function remove_competency_from_plan_returns() {
2862 return new external_value(PARAM_BOOL, 'True if successful.');
2863 }
2864
d9a39950
DW
2865 /**
2866 * Returns description of remove_competency_from_template() parameters.
2867 *
e90c24d0 2868 * @return \external_function_parameters
d9a39950
DW
2869 */
2870 public static function remove_competency_from_template_parameters() {
2871 $templateid = new external_value(
2872 PARAM_INT,
2873 'The template id',
2874 VALUE_REQUIRED
2875 );
2876 $competencyid = new external_value(
2877 PARAM_INT,
2878 'The competency id',
2879 VALUE_REQUIRED
2880 );
2881 $params = array(
2882 'templateid' => $templateid,
2883 'competencyid' => $competencyid,
2884 );
2885 return new external_function_parameters($params);
2886 }
2887
554b369b
IT
2888 /**
2889 * Returns description of reorder_plan_competency() parameters.
2890 *
2891 * @return \external_function_parameters
2892 */
2893 public static function reorder_plan_competency_parameters() {
2894 $planid = new external_value(
2895 PARAM_INT,
2896 'The plan id',
2897 VALUE_REQUIRED
2898 );
2899 $competencyidfrom = new external_value(
2900 PARAM_INT,
2901 'The competency id we are moving',
2902 VALUE_REQUIRED
2903 );
2904 $competencyidto = new external_value(
2905 PARAM_INT,
2906 'The competency id we are moving to',
2907 VALUE_REQUIRED
2908 );
2909 $params = array(
2910 'planid' => $planid,
2911 'competencyidfrom' => $competencyidfrom,
2912 'competencyidto' => $competencyidto,
2913 );
2914 return new external_function_parameters($params);
2915 }
2916
2917 /**
2918 * Change the order of plan competencies.
2919 *
2920 * @param int $planid The plan id
2921 * @param int $competencyidfrom The competency to move.
2922 * @param int $competencyidto The competency to move to.
2923 * @return bool
2924 */
2925 public static function reorder_plan_competency($planid, $competencyidfrom, $competencyidto) {
2926 $params = self::validate_parameters(self::reorder_plan_competency_parameters(),
2927 array(
2928 'planid' => $planid,
2929 'competencyidfrom' => $competencyidfrom,
2930 'competencyidto' => $competencyidto,
2931 ));
2932
86938d06
DW
2933 $plan = api::read_plan($params['planid']);
2934 self::validate_context($plan->get_context());
2935
554b369b
IT
2936 return api::reorder_plan_competency($params['planid'], $params['competencyidfrom'], $params['competencyidto']);
2937 }
2938
2939 /**
2940 * Returns description of reorder_plan_competency() result value.
2941 *
2942 * @return \external_description
2943 */
2944 public static function reorder_plan_competency_returns() {
2945 return new external_value(PARAM_BOOL, 'True if successful.');
2946 }
2947
c008e92d
FM
2948 /**
2949 * Returns description of external function parameters.
2950 *
2951 * @return \external_function_parameters
2952 */
2953 public static function user_competency_cancel_review_request_parameters() {
2954 return new external_function_parameters(array(
2955 'userid' => new external_value(PARAM_INT, 'The user ID'),
2956 'competencyid' => new external_value(PARAM_INT, 'The competency ID'),
2957 ));
2958 }
2959
2960 /**
2961 * External function user_competency_cancel_review_request.
2962 *
96c2b847
FM
2963 * @param int $userid The user ID.
2964 * @param int $competencyid The competency ID.
c008e92d
FM
2965 * @return boolean
2966 */
2967 public static function user_competency_cancel_review_request($userid, $competencyid) {
71cb304a 2968 $params = self::validate_parameters(self::user_competency_cancel_review_request_parameters(), array(
c008e92d
FM
2969 'userid' => $userid,
2970 'competencyid' => $competencyid
2971 ));
2972
2973 $context = context_user::instance($params['userid']);
2974 self::validate_context($context);
2975
2976 return api::user_competency_cancel_review_request($userid, $competencyid);
2977 }
2978
2979 /**
2980 * Returns description of external function result value.
2981 *
2982 * @return \external_function_parameters
2983 */
2984 public static function user_competency_cancel_review_request_returns() {
182f6092 2985 return new external_value(PARAM_BOOL, 'The success');
c008e92d
FM
2986 }
2987
2988 /**
2989 * Returns description of external function parameters.
2990 *
2991 * @return \external_function_parameters
2992 */
2993 public static function user_competency_request_review_parameters() {
2994 return new external_function_parameters(array(
2995 'userid' => new external_value(PARAM_INT, 'The user ID'),
2996 'competencyid' => new external_value(PARAM_INT, 'The competency ID'),
2997 ));
2998 }
2999
3000 /**
3001 * External function user_competency_request_review.
3002 *
3003 * @param int $userid The user ID.
3004 * @param int $competencyid The competency ID.
3005 * @return boolean
3006 */
1f586188 3007 public static function user_competency_request_review($userid, $competencyid) {
c008e92d
FM
3008 $params = self::validate_parameters(self::user_competency_request_review_parameters(), array(
3009 'userid' => $userid,
71cb304a 3010 'competencyid' => $competencyid,
c008e92d
FM
3011 ));
3012
3013 $context = context_user::instance($params['userid']);
3014 self::validate_context($context);
3015
1f586188 3016 return api::user_competency_request_review($userid, $competencyid);
c008e92d
FM
3017 }
3018
3019 /**
3020 * Returns description of external function result value.
3021 *
3022 * @return \external_function_parameters
3023 */
3024 public static function user_competency_request_review_returns() {
182f6092 3025 return new external_value(PARAM_BOOL, 'The success');
c008e92d
FM
3026 }
3027
3028 /**
3029 * Returns description of external function parameters.
3030 *
3031 * @return \external_function_parameters
3032 */
3033 public static function user_competency_start_review_parameters() {
3034 return new external_function_parameters(array(
3035 'userid' => new external_value(PARAM_INT, 'The user ID'),
3036 'competencyid' => new external_value(PARAM_INT, 'The competency ID'),
3037 ));
3038 }
3039
3040 /**
3041 * External function user_competency_start_review.
3042 *
96c2b847
FM
3043 * @param int $userid The user ID.
3044 * @param int $competencyid The competency ID.
c008e92d
FM
3045 * @return boolean
3046 */
3047 public static function user_competency_start_review($userid, $competencyid) {
71cb304a 3048 $params = self::validate_parameters(self::user_competency_start_review_parameters(), array(
c008e92d
FM
3049 'userid' => $userid,
3050 'competencyid' => $competencyid
3051 ));
3052
3053 $context = context_user::instance($params['userid']);
3054 self::validate_context($context);
3055
3056 return api::user_competency_start_review($userid, $competencyid);
3057 }
3058
3059 /**
3060 * Returns description of external function result value.
3061 *
3062 * @return \external_function_parameters
3063 */
3064 public static function user_competency_start_review_returns() {
182f6092 3065 return new external_value(PARAM_BOOL, 'The success');
c008e92d
FM
3066 }
3067
3068 /**
3069 * Returns description of external function parameters.
3070 *
3071 * @return \external_function_parameters
3072 */
3073 public static function user_competency_stop_review_parameters() {
3074 return new external_function_parameters(array(
3075 'userid' => new external_value(PARAM_INT, 'The user ID'),
3076 'competencyid' => new external_value(PARAM_INT, 'The competency ID'),
3077 ));
3078 }
3079
3080 /**
3081 * External function user_competency_stop_review.
3082 *
96c2b847
FM
3083 * @param int $userid The user ID.
3084 * @param int $competencyid The competency ID.
c008e92d
FM
3085 * @return boolean
3086 */
3087 public static function user_competency_stop_review($userid, $competencyid) {
71cb304a 3088 $params = self::validate_parameters(self::user_competency_stop_review_parameters(), array(
c008e92d
FM
3089 'userid' => $userid,
3090 'competencyid' => $competencyid
3091 ));
3092
3093 $context = context_user::instance($params['userid']);
3094 self::validate_context($context);
3095
3096 return api::user_competency_stop_review($userid, $competencyid);
3097 }
3098
3099 /**
3100 * Returns description of external function result value.
3101 *
3102 * @return \external_function_parameters
3103 */
3104 public static function user_competency_stop_review_returns() {
182f6092 3105 return new external_value(PARAM_BOOL, 'The success');
c008e92d
FM
3106 }
3107
8fabc738
SG
3108 /**
3109 * Returns description of template_has_related_data() parameters.
3110 *
3111 * @return \external_function_parameters
3112 */
3113 public static function template_has_related_data_parameters() {
3114 $templateid = new external_value(
3115 PARAM_INT,
3116 'The template id',
3117 VALUE_REQUIRED
3118 );
3119 $params = array(
3120 'id' => $templateid,
3121 );
3122 return new external_function_parameters($params);
3123 }
3124
3125 /**
3126 * Check if template has related data.
3127 *
3128 * @param int $templateid Template id.
3129 * @return boolean
3130 */
3131 public static function template_has_related_data($templateid) {
3132 $params = self::validate_parameters(self::template_has_related_data_parameters(),
3133 array(
3134 'id' => $templateid,
3135 ));
3136
3137 $template = api::read_template($params['id']);
3138 self::validate_context($template->get_context());
3139
3140 return api::template_has_related_data($params['id']);
3141 }
3142
3143 /**
3144 * Returns description of template_has_related_data() result value.
3145 *
3146 * @return \external_description
3147 */
3148 public static function template_has_related_data_returns() {
3149 return new external_value(PARAM_BOOL, 'True if the template has related data');
3150 }
3151
d9a39950
DW
3152 /**
3153 * Count the competencies (visible to this user) in this learning plan template.
3154 *
b17d3d10
AA
3155 * @param int $templateid Template id.
3156 * @param int $competencyid Competency id.
d9a39950
DW
3157 * @return int
3158 */
3159 public static function remove_competency_from_template($templateid, $competencyid) {
3160 $params = self::validate_parameters(self::remove_competency_from_template_parameters(),
3161 array(
3162 'templateid' => $templateid,
3163 'competencyid' => $competencyid,
3164 ));
86938d06
DW
3165 $template = api::read_template($params['templateid']);
3166 self::validate_context($template->get_context());
d9a39950
DW
3167
3168 return api::remove_competency_from_template($params['templateid'], $params['competencyid']);
3169 }
3170
3171 /**
3172 * Returns description of remove_competency_from_template() result value.
3173 *
e90c24d0 3174 * @return \external_description
d9a39950
DW
3175 */
3176 public static function remove_competency_from_template_returns() {
3177 return new external_value(PARAM_BOOL, 'True if successful.');
3178 }
3179
3180 /**
3181 * Returns description of data_for_template_competenies_page() parameters.
3182 *
e90c24d0 3183 * @return \external_function_parameters
d9a39950
DW
3184 */
3185 public static function data_for_template_competencies_page_parameters() {
3186 $templateid = new external_value(
3187 PARAM_INT,
3188 'The template id',
3189 VALUE_REQUIRED
3190 );
f0da26a4 3191 $params = array('templateid' => $templateid, 'pagecontext' => self::get_context_parameters());
d9a39950
DW
3192 return new external_function_parameters($params);
3193 }
3194
d9a39950
DW
3195 /**
3196 * Loads the data required to render the template_competencies_page template.
3197 *
b17d3d10 3198 * @param int $templateid Template id.
f0da26a4 3199 * @param array $pagecontext The page context info.
d9a39950
DW
3200 * @return boolean
3201 */
f0da26a4 3202 public static function data_for_template_competencies_page($templateid, $pagecontext) {
d9a39950
DW
3203 global $PAGE;
3204 $params = self::validate_parameters(self::data_for_template_competencies_page_parameters(),
3205 array(
3206 'templateid' => $templateid,
f0da26a4 3207 'pagecontext' => $pagecontext
d9a39950
DW
3208 ));
3209
f0da26a4
FM
3210 $context = self::get_context_from_params($params['pagecontext']);
3211 self::validate_context($context);
3212
f864aa4c
FM
3213 $template = api::read_template($params['templateid']);
3214 $renderable = new output\template_competencies_page($template, $context);
d9a39950
DW
3215 $renderer = $PAGE->get_renderer('tool_lp');
3216
3217 $data = $renderable->export_for_template($renderer);
3218
3219 return $data;
3220 }
3221
3222 /**
3223 * Returns description of data_for_template_competencies_page() result value.
3224 *
e90c24d0 3225 * @return \external_description
d9a39950
DW
3226 */
3227 public static function data_for_template_competencies_page_returns() {
3228 return new external_single_structure(array (
f864aa4c 3229 'template' => template_exporter::get_read_structure(),
72181303 3230 'pagecontextid' => new external_value(PARAM_INT, 'Context ID'),
d9a39950 3231 'canmanagecompetencyframeworks' => new external_value(PARAM_BOOL, 'User can manage competency frameworks'),
72181303 3232 'canmanagetemplatecompetencies' => new external_value(PARAM_BOOL, 'User can manage learning plan templates'),
d9a39950 3233 'competencies' => new external_multiple_structure(
c80630da 3234 competency_summary_exporter::get_read_structure()
d9a39950
DW
3235 ),
3236 'manageurl' => new external_value(PARAM_LOCALURL, 'Url to the manage competencies page.'),
f864aa4c 3237 'pluginbaseurl' => new external_value(PARAM_LOCALURL, 'Base URL of the plugin.'),
3edcd295 3238 'statistics' => template_statistics_exporter::get_read_structure()
d9a39950
DW
3239 ));