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