f5bde03285f516cd5aa54be563fc6d61345b2302
[moodle.git] / admin / tool / lp / classes / external.php
1 <?php
2 // This file is part of Moodle - http://moodle.org/
3 //
4 // Moodle is free software: you can redistribute it and/or modify
5 // it under the terms of the GNU General Public License as published by
6 // the Free Software Foundation, either version 3 of the License, or
7 // (at your option) any later version.
8 //
9 // Moodle is distributed in the hope that it will be useful,
10 // but WITHOUT ANY WARRANTY; without even the implied warranty of
11 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
12 // GNU General Public License for more details.
13 //
14 // You should have received a copy of the GNU General Public License
15 // along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
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  */
24 namespace tool_lp;
25 defined('MOODLE_INTERNAL') || die();
27 require_once("$CFG->libdir/externallib.php");
28 require_once("$CFG->libdir/grade/grade_scale.php");
30 use context;
31 use context_system;
32 use context_course;
33 use context_helper;
34 use context_user;
35 use coding_exception;
36 use external_api;
37 use external_function_parameters;
38 use external_value;
39 use external_format_value;
40 use external_single_structure;
41 use external_multiple_structure;
42 use invalid_parameter_exception;
43 use required_capability_exception;
44 use grade_scale;
45 use tool_lp\external\competency_framework_exporter;
46 use tool_lp\external\competency_summary_exporter;
47 use tool_lp\external\competency_path_exporter;
48 use tool_lp\external\cohort_summary_exporter;
49 use tool_lp\external\template_statistics_exporter;
50 use tool_lp\external\user_summary_exporter;
51 use tool_lp\external\user_competency_exporter;
52 use tool_lp\external\user_competency_plan_exporter;
53 use tool_lp\external\user_competency_summary_exporter;
54 use tool_lp\external\user_competency_summary_in_course_exporter;
55 use tool_lp\external\user_competency_summary_in_plan_exporter;
56 use tool_lp\external\user_evidence_exporter;
57 use tool_lp\external\user_evidence_summary_exporter;
58 use tool_lp\external\user_evidence_competency_exporter;
59 use tool_lp\external\competency_exporter;
60 use tool_lp\external\course_competency_exporter;
61 use tool_lp\external\course_summary_exporter;
62 use tool_lp\external\course_module_summary_exporter;
63 use tool_lp\external\plan_exporter;
64 use tool_lp\external\template_exporter;
65 use tool_lp\external\evidence_exporter;
66 use tool_lp\output\user_competency_summary_in_plan;
67 use tool_lp\output\user_competency_summary_in_course;
69 /**
70  * This is the external API for this tool.
71  *
72  * @copyright  2015 Damyon Wiese
73  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
74  */
75 class external extends external_api {
77     /**
78      * Returns description of a generic list() parameters.
79      *
80      * @return \external_function_parameters
81      */
82     protected static function list_parameters_structure() {
83         $filters = new external_multiple_structure(new external_single_structure(
84             array(
85                 'column' => new external_value(PARAM_ALPHANUMEXT, 'Column name to filter by'),
86                 'value' => new external_value(PARAM_TEXT, 'Value to filter by. Must be exact match')
87             )
88         ));
89         $sort = new external_value(
90             PARAM_ALPHANUMEXT,
91             'Column to sort by.',
92             VALUE_DEFAULT,
93             ''
94         );
95         $order = new external_value(
96             PARAM_ALPHA,
97             'Sort direction. Should be either ASC or DESC',
98             VALUE_DEFAULT,
99             ''
100         );
101         $skip = new external_value(
102             PARAM_INT,
103             'Skip this number of records before returning results',
104             VALUE_DEFAULT,
105             0
106         );
107         $limit = new external_value(
108             PARAM_INT,
109             'Return this number of records at most.',
110             VALUE_DEFAULT,
111             0
112         );
114         $params = array(
115             'filters' => $filters,
116             'sort' => $sort,
117             'order' => $order,
118             'skip' => $skip,
119             'limit' => $limit
120         );
121         return new external_function_parameters($params);
122     }
124     /**
125      * Returns a prepared structure to use a context parameters.
126      * @return external_single_structure
127      */
128     protected static function get_context_parameters() {
129         $id = new external_value(
130             PARAM_INT,
131             'Context ID. Either use this value, or level and instanceid.',
132             VALUE_DEFAULT,
133             0
134         );
135         $level = new external_value(
136             PARAM_ALPHA,
137             'Context level. To be used with instanceid.',
138             VALUE_DEFAULT,
139             ''
140         );
141         $instanceid = new external_value(
142             PARAM_INT,
143             'Context instance ID. To be used with level',
144             VALUE_DEFAULT,
145             0
146         );
147         return new external_single_structure(array(
148             'contextid' => $id,
149             'contextlevel' => $level,
150             'instanceid' => $instanceid,
151         ));
152     }
154     /**
155      * Returns description of a generic count_x() parameters.
156      *
157      * @return \external_function_parameters
158      */
159     public static function count_parameters_structure() {
160         $filters = new external_multiple_structure(new external_single_structure(
161             array(
162                 'column' => new external_value(PARAM_ALPHANUMEXT, 'Column name to filter by'),
163                 'value' => new external_value(PARAM_TEXT, 'Value to filter by. Must be exact match')
164             )
165         ));
167         $params = array(
168             'filters' => $filters,
169         );
170         return new external_function_parameters($params);
171     }
173     /**
174      * Returns description of create_competency_framework() parameters.
175      *
176      * @return \external_function_parameters
177      */
178     public static function create_competency_framework_parameters() {
179         $structure = competency_framework_exporter::get_create_structure();
180         $params = array('competencyframework' => $structure);
181         return new external_function_parameters($params);
182     }
184     /**
185      * Create a new competency framework
186      *
187      * @param array $competencyframework A single param with all the fields for a competency framework.
188      * @return \stdClass The new record
189      */
190     public static function create_competency_framework($competencyframework) {
191         global $PAGE;
193         $params = self::validate_parameters(self::create_competency_framework_parameters(),
194                                             array('competencyframework' => $competencyframework));
196         $params = $params['competencyframework'];
198         $context = self::get_context_from_params($params);
199         self::validate_context($context);
200         $output = $PAGE->get_renderer('tool_lp');
202         unset($params['contextlevel']);
203         unset($params['instanceid']);
204         $params['contextid'] = $context->id;
206         $params = (object) $params;
207         $result = api::create_framework($params);
208         $exporter = new competency_framework_exporter($result);
209         $record = $exporter->export($output);
210         return $record;
211     }
213     /**
214      * Returns description of create_competency_framework() result value.
215      *
216      * @return \external_description
217      */
218     public static function create_competency_framework_returns() {
219         return competency_framework_exporter::get_read_structure();
220     }
222     /**
223      * Returns description of read_competency_framework() parameters.
224      *
225      * @return \external_function_parameters
226      */
227     public static function read_competency_framework_parameters() {
228         $id = new external_value(
229             PARAM_INT,
230             'Data base record id for the framework',
231             VALUE_REQUIRED
232         );
234         $params = array(
235             'id' => $id,
236         );
237         return new external_function_parameters($params);
238     }
240     /**
241      * Read a competency framework by id.
242      *
243      * @param int $id The id of the framework.
244      * @return \stdClass
245      */
246     public static function read_competency_framework($id) {
247         global $PAGE;
249         $params = self::validate_parameters(self::read_competency_framework_parameters(),
250                                             array(
251                                                 'id' => $id,
252                                             ));
254         $framework = api::read_framework($params['id']);
255         self::validate_context($framework->get_context());
256         $output = $PAGE->get_renderer('tool_lp');
257         $exporter = new competency_framework_exporter($framework);
258         $record = $exporter->export($output);
259         return $record;
260     }
262     /**
263      * Returns description of read_competency_framework() result value.
264      *
265      * @return \external_description
266      */
267     public static function read_competency_framework_returns() {
268         return competency_framework_exporter::get_read_structure();
269     }
271     /**
272      * Returns description of competency_viewed() parameters.
273      *
274      * @return \external_function_parameters
275      */
276     public static function competency_viewed_parameters() {
277         $id = new external_value(
278             PARAM_INT,
279             'The competency id',
280             VALUE_REQUIRED
281         );
282         $params = array(
283             'id' => $id
284         );
285         return new external_function_parameters($params);
286     }
288     /**
289      * Log event competency viewed.
290      *
291      * @param int $id The competency ID.
292      * @return boolean
293      */
294     public static function competency_viewed($id) {
295         $params = self::validate_parameters(self::competency_viewed_parameters(),
296                                             array(
297                                                 'id' => $id
298                                             ));
299         return api::competency_viewed($params['id']);
300     }
302     /**
303      * Returns description of competency_viewed() result value.
304      *
305      * @return \external_description
306      */
307     public static function competency_viewed_returns() {
308         return new external_value(PARAM_BOOL, 'True if the event competency viewed was logged');
309     }
311     /**
312      * Returns description of duplicate_competency_framework() parameters.
313      *
314      * @return \external_function_parameters
315      */
316     public static function duplicate_competency_framework_parameters() {
317         $id = new external_value(
318             PARAM_INT,
319             'Data base record id for the framework',
320             VALUE_REQUIRED
321         );
323         $params = array(
324             'id' => $id,
325         );
326         return new external_function_parameters($params);
327     }
329     /**
330      * Duplicate a competency framework
331      *
332      * @param int $id The competency framework id
333      * @return boolean
334      */
335     public static function duplicate_competency_framework($id) {
336         global $PAGE;
337         $params = self::validate_parameters(self::duplicate_competency_framework_parameters(),
338                                             array(
339                                                 'id' => $id,
340                                             ));
342         $framework = api::read_framework($params['id']);
343         self::validate_context($framework->get_context());
345         $output = $PAGE->get_renderer('tool_lp');
346         $framework = api::duplicate_framework($params['id']);
347         $exporter = new competency_framework_exporter($framework);
348         $record = $exporter->export($output);
349         return $record;
350     }
352     /**
353      * Returns description of duplicate_competency_framework() result value.
354      *
355      * @return \external_description
356      */
357     public static function duplicate_competency_framework_returns() {
358         return competency_framework_exporter::get_read_structure();
359     }
361     /**
362      * Returns description of delete_competency_framework() parameters.
363      *
364      * @return \external_function_parameters
365      */
366     public static function delete_competency_framework_parameters() {
367         $id = new external_value(
368             PARAM_INT,
369             'Data base record id for the framework',
370             VALUE_REQUIRED
371         );
373         $params = array(
374             'id' => $id,
375         );
376         return new external_function_parameters($params);
377     }
379     /**
380      * Delete a competency framework
381      *
382      * @param int $id The competency framework id
383      * @return boolean
384      */
385     public static function delete_competency_framework($id) {
386         $params = self::validate_parameters(self::delete_competency_framework_parameters(),
387                                             array(
388                                                 'id' => $id,
389                                             ));
391         $framework = api::read_framework($params['id']);
392         self::validate_context($framework->get_context());
394         return api::delete_framework($params['id']);
395     }
397     /**
398      * Returns description of delete_competency_framework() result value.
399      *
400      * @return \external_description
401      */
402     public static function delete_competency_framework_returns() {
403         return new external_value(PARAM_BOOL, 'True if the delete was successful');
404     }
406     /**
407      * Returns description of update_competency_framework() parameters.
408      *
409      * @return \external_function_parameters
410      */
411     public static function update_competency_framework_parameters() {
412         $structure = competency_framework_exporter::get_update_structure();
413         $params = array('competencyframework' => $structure);
414         return new external_function_parameters($params);
415     }
417     /**
418      * Update an existing competency framework
419      *
420      * @param array $competencyframework An array with all the fields for a competency framework.
421      * @return boolean
422      */
423     public static function update_competency_framework($competencyframework) {
425         $params = self::validate_parameters(self::update_competency_framework_parameters(),
426                                             array(
427                                                 'competencyframework' => $competencyframework
428                                             ));
430         $params = $params['competencyframework'];
432         $framework = api::read_framework($params['id']);
433         self::validate_context($framework->get_context());
435         $params = (object) $params;
437         return api::update_framework($params);
438     }
440     /**
441      * Returns description of update_competency_framework() result value.
442      *
443      * @return \external_description
444      */
445     public static function update_competency_framework_returns() {
446         return new external_value(PARAM_BOOL, 'True if the update was successful');
447     }
449     /**
450      * Returns description of list_competency_frameworks() parameters.
451      *
452      * @return \external_function_parameters
453      */
454     public static function list_competency_frameworks_parameters() {
455         $sort = new external_value(
456             PARAM_ALPHANUMEXT,
457             'Column to sort by.',
458             VALUE_DEFAULT,
459             'shortname'
460         );
461         $order = new external_value(
462             PARAM_ALPHA,
463             'Sort direction. Should be either ASC or DESC',
464             VALUE_DEFAULT,
465             ''
466         );
467         $skip = new external_value(
468             PARAM_INT,
469             'Skip this number of records before returning results',
470             VALUE_DEFAULT,
471             0
472         );
473         $limit = new external_value(
474             PARAM_INT,
475             'Return this number of records at most.',
476             VALUE_DEFAULT,
477             0
478         );
479         $includes = new external_value(
480             PARAM_ALPHA,
481             'What other contextes to fetch the frameworks from. (children, parents, self)',
482             VALUE_DEFAULT,
483             'children'
484         );
485         $onlyvisible = new external_value(
486             PARAM_BOOL,
487             'Only visible frameworks will be returned if visible true',
488             VALUE_DEFAULT,
489             false
490         );
491         $query = new external_value(
492             PARAM_RAW,
493             'A query string to filter the results',
494             VALUE_DEFAULT,
495             ''
496         );
498         $params = array(
499             'sort' => $sort,
500             'order' => $order,
501             'skip' => $skip,
502             'limit' => $limit,
503             'context' => self::get_context_parameters(),
504             'includes' => $includes,
505             'onlyvisible' => $onlyvisible,
506             'query' => $query,
507         );
508         return new external_function_parameters($params);
509     }
511     /**
512      * List the existing competency frameworks
513      *
514      * @param int $sort
515      * @param string $order
516      * @param string $skip
517      * @param int $limit
518      * @param array $context
519      * @param bool $includes
520      * @param bool $onlyvisible
521      * @param string $query
522      *
523      * @return array
524      * @throws \required_capability_exception
525      * @throws invalid_parameter_exception
526      */
527     public static function list_competency_frameworks($sort, $order, $skip, $limit, $context, $includes, $onlyvisible,
528             $query = '') {
529         global $PAGE;
531         $params = self::validate_parameters(self::list_competency_frameworks_parameters(),
532                                             array(
533                                                 'sort' => $sort,
534                                                 'order' => $order,
535                                                 'skip' => $skip,
536                                                 'limit' => $limit,
537                                                 'context' => $context,
538                                                 'includes' => $includes,
539                                                 'onlyvisible' => $onlyvisible,
540                                                 'query' => $query,
541                                             ));
543         $context = self::get_context_from_params($params['context']);
544         self::validate_context($context);
545         $output = $PAGE->get_renderer('tool_lp');
547         if ($params['order'] !== '' && $params['order'] !== 'ASC' && $params['order'] !== 'DESC') {
548             throw new invalid_parameter_exception('Invalid order param. Must be ASC, DESC or empty.');
549         }
551         $results = api::list_frameworks($params['sort'],
552                                        $params['order'],
553                                        $params['skip'],
554                                        $params['limit'],
555                                        $context,
556                                        $params['includes'],
557                                        $params['onlyvisible'],
558                                        $params['query']);
559         $records = array();
560         foreach ($results as $result) {
561             $exporter = new competency_framework_exporter($result);
562             $record = $exporter->export($output);
563             array_push($records, $record);
564         }
565         return $records;
566     }
568     /**
569      * Returns description of list_competency_frameworks() result value.
570      *
571      * @return \external_description
572      */
573     public static function list_competency_frameworks_returns() {
574         return new external_multiple_structure(competency_framework_exporter::get_read_structure());
575     }
577     /**
578      * Returns description of count_competency_frameworks() parameters.
579      *
580      * @return \external_function_parameters
581      */
582     public static function count_competency_frameworks_parameters() {
583         $includes = new external_value(
584             PARAM_ALPHA,
585             'What other contextes to fetch the frameworks from. (children, parents, self)',
586             VALUE_DEFAULT,
587             'children'
588         );
590         $params = array(
591             'context' => self::get_context_parameters(),
592             'includes' => $includes
593         );
594         return new external_function_parameters($params);
595     }
597     /**
598      * Count the existing competency frameworks
599      *
600      * @param array $context
601      * @param string $includes
602      * @return int
603      */
604     public static function count_competency_frameworks($context, $includes) {
605         $params = self::validate_parameters(self::count_competency_frameworks_parameters(),
606                                             array(
607                                                 'context' => $context,
608                                                 'includes' => $includes
609                                             ));
611         $context = self::get_context_from_params($params['context']);
612         self::validate_context($context);
614         return api::count_frameworks($context, $params['includes']);
615     }
617     /**
618      * Returns description of count_competency_frameworks() result value.
619      *
620      * @return \external_description
621      */
622     public static function count_competency_frameworks_returns() {
623         return new external_value(PARAM_INT, 'The number of competency frameworks found.');
624     }
626     /**
627      * Returns description of competency_framework_viewed() parameters.
628      *
629      * @return \external_function_parameters
630      */
631     public static function competency_framework_viewed_parameters() {
632         $id = new external_value(
633             PARAM_INT,
634             'The competency framework id',
635             VALUE_REQUIRED
636         );
638         $params = array(
639             'id' => $id
640         );
641         return new external_function_parameters($params);
642     }
644     /**
645      * Log event competency framework viewed.
646      *
647      * @param int $id The competency framework ID.
648      * @return boolean
649      */
650     public static function competency_framework_viewed($id) {
651         $params = self::validate_parameters(self::competency_framework_viewed_parameters(),
652                                             array(
653                                                 'id' => $id
654                                             ));
655         return api::competency_framework_viewed($params['id']);
657     }
659     /**
660      * Returns description of competency_framework_viewed() result value.
661      *
662      * @return \external_description
663      */
664     public static function competency_framework_viewed_returns() {
665         return new external_value(PARAM_BOOL, 'True if the event competency framework was logged');
666     }
668     /**
669      * Returns description of data_for_competency_frameworks_manage_page() parameters.
670      *
671      * @return \external_function_parameters
672      */
673     public static function data_for_competency_frameworks_manage_page_parameters() {
674         $params = array('pagecontext' => self::get_context_parameters());
675         return new external_function_parameters($params);
676     }
678     /**
679      * Loads the data required to render the competency_frameworks_manage_page template.
680      *
681      * @param context $pagecontext The page context
682      * @return \stdClass
683      */
684     public static function data_for_competency_frameworks_manage_page($pagecontext) {
685         global $PAGE;
687         $params = self::validate_parameters(
688             self::data_for_competency_frameworks_manage_page_parameters(),
689             array(
690                 'pagecontext' => $pagecontext
691             )
692         );
693         $context = self::get_context_from_params($params['pagecontext']);
694         self::validate_context($context);
696         $renderable = new output\manage_competency_frameworks_page($context);
697         $renderer = $PAGE->get_renderer('tool_lp');
699         $data = $renderable->export_for_template($renderer);
701         return $data;
702     }
704     /**
705      * Returns description of data_for_competency_frameworks_manage_page() result value.
706      *
707      * @return \external_description
708      */
709     public static function data_for_competency_frameworks_manage_page_returns() {
710         return new external_single_structure(array (
711             'competencyframeworks' => new external_multiple_structure(
712                 competency_framework_exporter::get_read_structure()
713             ),
714             'pluginbaseurl' => new external_value(PARAM_LOCALURL, 'Url to the tool_lp plugin folder on this Moodle site'),
715             'navigation' => new external_multiple_structure(
716                 new external_value(PARAM_RAW, 'HTML for a navigation item that should be on this page')
717             ),
718             'pagecontextid' => new external_value(PARAM_INT, 'The page context id')
719         ));
721     }
723     /**
724      * Returns description of create_competency() parameters.
725      *
726      * @return \external_function_parameters
727      */
728     public static function create_competency_parameters() {
729         $structure = competency_exporter::get_create_structure();
730         $params = array('competency' => $structure);
731         return new external_function_parameters($params);
732     }
734     /**
735      * Create a new competency
736      *
737      * @param array $competency All the fields for a competency record (including id)
738      * @return array the competency
739      */
740     public static function create_competency($competency) {
741         global $PAGE;
743         $params = self::validate_parameters(self::create_competency_parameters(),
744                                             array('competency' => $competency));
746         $params = $params['competency'];
747         $framework = api::read_framework($params['competencyframeworkid']);
748         $context = $framework->get_context();
749         self::validate_context($context);
750         $output = $PAGE->get_renderer('tool_lp');
752         $params = (object) $params;
753         $result = api::create_competency($params);
754         $exporter = new competency_exporter($result, array('context' => $context));
755         $record = $exporter->export($output);
756         return $record;
757     }
759     /**
760      * Returns description of create_competency() result value.
761      *
762      * @return \external_description
763      */
764     public static function create_competency_returns() {
765         return competency_exporter::get_read_structure();
766     }
768     /**
769      * Returns description of read_competency() parameters.
770      *
771      * @return \external_function_parameters
772      */
773     public static function read_competency_parameters() {
774         $id = new external_value(
775             PARAM_INT,
776             'Data base record id for the competency',
777             VALUE_REQUIRED
778         );
780         $params = array(
781             'id' => $id,
782         );
783         return new external_function_parameters($params);
784     }
786     /**
787      * Read a competency by id.
788      *
789      * @param int $id The id of the competency
790      * @return \stdClass
791      */
792     public static function read_competency($id) {
793         global $PAGE;
795         $params = self::validate_parameters(self::read_competency_parameters(),
796                                             array(
797                                                 'id' => $id,
798                                             ));
800         $competency = api::read_competency($params['id']);
801         $context = $competency->get_context();
802         self::validate_context($context);
803         $output = $PAGE->get_renderer('tool_lp');
804         $exporter = new competency_exporter($competency, array('context' => $context));
805         $record = $exporter->export($output);
806         return $record;
807     }
809     /**
810      * Returns description of read_competency() result value.
811      *
812      * @return \external_description
813      */
814     public static function read_competency_returns() {
815         return competency_exporter::get_read_structure();
816     }
818     /**
819      * Returns description of delete_competency() parameters.
820      *
821      * @return \external_function_parameters
822      */
823     public static function delete_competency_parameters() {
824         $id = new external_value(
825             PARAM_INT,
826             'Data base record id for the competency',
827             VALUE_REQUIRED
828         );
830         $params = array(
831             'id' => $id,
832         );
833         return new external_function_parameters($params);
834     }
836     /**
837      * Delete a competency
838      *
839      * @param int $id The competency id
840      * @return boolean
841      */
842     public static function delete_competency($id) {
843         $params = self::validate_parameters(self::delete_competency_parameters(),
844                                             array(
845                                                 'id' => $id,
846                                             ));
848         $competency = api::read_competency($params['id']);
849         $context = $competency->get_context();
850         self::validate_context($context);
852         return api::delete_competency($params['id']);
853     }
855     /**
856      * Returns description of delete_competency() result value.
857      *
858      * @return \external_description
859      */
860     public static function delete_competency_returns() {
861         return new external_value(PARAM_BOOL, 'True if the delete was successful');
862     }
864     /**
865      * Returns description of update_competency() parameters.
866      *
867      * @return \external_function_parameters
868      */
869     public static function update_competency_parameters() {
870         $structure = competency_exporter::get_update_structure();
871         $params = array('competency' => $structure);
872         return new external_function_parameters($params);
873     }
875     /**
876      * Update an existing competency
877      *
878      * @param array $competency The array of competency fields (id is required).
879      * @return boolean
880      */
881     public static function update_competency($competency) {
883         $params = self::validate_parameters(self::update_competency_parameters(),
884                                             array('competency' => $competency));
885         $params = $params['competency'];
887         $competency = api::read_competency($params['id']);
888         self::validate_context($competency->get_context());
890         $params = (object) $params;
892         return api::update_competency($params);
893     }
895     /**
896      * Returns description of update_competency_framework() result value.
897      *
898      * @return \external_description
899      */
900     public static function update_competency_returns() {
901         return new external_value(PARAM_BOOL, 'True if the update was successful');
902     }
904     /**
905      * Returns description of list_competencies() parameters.
906      *
907      * @return \external_function_parameters
908      */
909     public static function list_competencies_parameters() {
910         return self::list_parameters_structure();
911     }
913     /**
914      * List the existing competency.
915      *
916      * @param string $filters
917      * @param int $sort
918      * @param string $order
919      * @param string $skip
920      * @param int $limit
921      *
922      * @return array
923      * @throws \required_capability_exception
924      * @throws invalid_parameter_exception
925      */
926     public static function list_competencies($filters, $sort, $order, $skip, $limit) {
927         global $PAGE;
929         $params = self::validate_parameters(self::list_competencies_parameters(),
930                                             array(
931                                                 'filters' => $filters,
932                                                 'sort' => $sort,
933                                                 'order' => $order,
934                                                 'skip' => $skip,
935                                                 'limit' => $limit
936                                             ));
938         if ($params['order'] !== '' && $params['order'] !== 'ASC' && $params['order'] !== 'DESC') {
939             throw new invalid_parameter_exception('Invalid order param. Must be ASC, DESC or empty.');
940         }
942         $safefilters = array();
943         $validcolumns = array('id', 'shortname', 'description', 'sortorder',
944                               'idnumber', 'parentid', 'competencyframeworkid');
945         foreach ($params['filters'] as $filter) {
946             if (!in_array($filter->column, $validcolumns)) {
947                 throw new invalid_parameter_exception('Filter column was invalid');
948             }
949             $safefilters[$filter->column] = $filter->value;
950         }
952         $context = null;
953         if (isset($safefilters['competencyframeworkid'])) {
954             $framework = api::read_framework($safefilters['competencyframeworkid']);
955             $context = $framework->get_context();
956         } else {
957             $context = context_system::instance();
958         }
960         self::validate_context($context);
961         $output = $PAGE->get_renderer('tool_lp');
963         $results = api::list_competencies(
964             $safefilters,
965             $params['sort'],
966             $params['order'],
967             $params['skip'],
968             $params['limit']
969         );
971         $records = array();
972         foreach ($results as $result) {
973             $exporter = new competency_exporter($result, array('context' => $context));
974             $record = $exporter->export($output);
975             array_push($records, $record);
976         }
977         return $records;
978     }
980     /**
981      * Returns description of list_competencies() result value.
982      *
983      * @return \external_description
984      */
985     public static function list_competencies_returns() {
986         return new external_multiple_structure(competency_exporter::get_read_structure());
987     }
989     /**
990      * Returns description of search_competencies() parameters.
991      *
992      * @return \external_function_parameters
993      */
994     public static function search_competencies_parameters() {
995         $searchtext = new external_value(
996             PARAM_RAW,
997             'Text to search for',
998             VALUE_REQUIRED
999         );
1000         $frameworkid = new external_value(
1001             PARAM_INT,
1002             'Competency framework id',
1003             VALUE_REQUIRED
1004         );
1006         $params = array(
1007             'searchtext' => $searchtext,
1008             'competencyframeworkid' => $frameworkid
1009         );
1010         return new external_function_parameters($params);
1011     }
1013     /**
1014      * List the existing competency frameworks
1015      *
1016      * @param string $searchtext Text to search.
1017      * @param int $competencyframeworkid Framework id.
1018      *
1019      * @return array
1020      */
1021     public static function search_competencies($searchtext, $competencyframeworkid) {
1022         global $PAGE;
1024         $params = self::validate_parameters(self::search_competencies_parameters(),
1025                                             array(
1026                                                 'searchtext' => $searchtext,
1027                                                 'competencyframeworkid' => $competencyframeworkid
1028                                             ));
1030         $framework = api::read_framework($params['competencyframeworkid']);
1031         $context = $framework->get_context();
1032         self::validate_context($context);
1033         $output = $PAGE->get_renderer('tool_lp');
1035         $results = api::search_competencies($params['searchtext'], $params['competencyframeworkid']);
1036         $records = array();
1037         foreach ($results as $result) {
1038             $exporter = new competency_exporter($result, array('context' => $context));
1039             $record = $exporter->export($output);
1041             array_push($records, $record);
1042         }
1044         return $records;
1045     }
1047     /**
1048      * Returns description of search_competencies() result value.
1049      *
1050      * @return \external_description
1051      */
1052     public static function search_competencies_returns() {
1053         return new external_multiple_structure(competency_exporter::get_read_structure());
1054     }
1056     /**
1057      * Returns description of count_competencies() parameters.
1058      *
1059      * @return \external_function_parameters
1060      */
1061     public static function count_competencies_parameters() {
1062         return self::count_parameters_structure();
1063     }
1065     /**
1066      * Count the existing competency frameworks.
1067      *
1068      * @param string $filters Filters to use.
1069      * @return boolean
1070      */
1071     public static function count_competencies($filters) {
1072         $params = self::validate_parameters(self::count_competencies_parameters(),
1073                                             array(
1074                                                 'filters' => $filters
1075                                             ));
1077         $safefilters = array();
1078         $validcolumns = array('id', 'shortname', 'description', 'sortorder', 'idnumber',
1079                               'parentid', 'competencyframeworkid');
1080         foreach ($params['filters'] as $filter) {
1081             if (!in_array($filter['column'], $validcolumns)) {
1082                 throw new invalid_parameter_exception('Filter column was invalid');
1083             }
1084             $safefilters[$filter['column']] = $filter['value'];
1085         }
1087         $context = null;
1088         if (isset($safefilters['competencyframeworkid'])) {
1089             $framework = api::read_framework($safefilters['competencyframeworkid']);
1090             $context = $framework->get_context();
1091         } else {
1092             $context = context_system::instance();
1093         }
1095         self::validate_context($context);
1097         return api::count_competencies($safefilters);
1098     }
1100     /**
1101      * Returns description of count_competencies() result value.
1102      *
1103      * @return \external_description
1104      */
1105     public static function count_competencies_returns() {
1106         return new external_value(PARAM_INT, 'The number of competencies found.');
1107     }
1109     /**
1110      * Returns description of data_for_competencies_manage_page() parameters.
1111      *
1112      * @return \external_function_parameters
1113      */
1114     public static function data_for_competencies_manage_page_parameters() {
1115         $competencyframeworkid = new external_value(
1116             PARAM_INT,
1117             'The competency framework id',
1118             VALUE_REQUIRED
1119         );
1120         $search = new external_value(
1121             PARAM_RAW,
1122             'A search string',
1123             VALUE_DEFAULT,
1124             ''
1125         );
1126         $params = array(
1127             'competencyframeworkid' => $competencyframeworkid,
1128             'search' => $search
1129         );
1130         return new external_function_parameters($params);
1131     }
1133     /**
1134      * Loads the data required to render the competencies_manage_page template.
1135      *
1136      * @param int $competencyframeworkid Framework id.
1137      * @param string $search Text to search.
1138      *
1139      * @return boolean
1140      */
1141     public static function data_for_competencies_manage_page($competencyframeworkid, $search) {
1142         global $PAGE;
1144         $params = self::validate_parameters(self::data_for_competencies_manage_page_parameters(),
1145                                             array(
1146                                                 'competencyframeworkid' => $competencyframeworkid,
1147                                                 'search' => $search
1148                                             ));
1150         $framework = api::read_framework($params['competencyframeworkid']);
1151         self::validate_context($framework->get_context());
1152         $output = $PAGE->get_renderer('tool_lp');
1154         $renderable = new output\manage_competencies_page($framework, $params['search'], $framework->get_context());
1156         $data = $renderable->export_for_template($output);
1158         return $data;
1159     }
1161     /**
1162      * Returns description of data_for_competencies_manage_page() result value.
1163      *
1164      * @return \external_description
1165      */
1166     public static function data_for_competencies_manage_page_returns() {
1167         return new external_single_structure(array (
1168             'framework' => competency_framework_exporter::get_read_structure(),
1169             'canmanage' => new external_value(PARAM_BOOL, 'True if this user has permission to manage competency frameworks'),
1170             'pagecontextid' => new external_value(PARAM_INT, 'Context id for the framework'),
1171             'search' => new external_value(PARAM_RAW, 'Current search string'),
1172             'rulesmodules' => new external_value(PARAM_RAW, 'JSON encoded data for rules')
1173         ));
1175     }
1177     /**
1178      * Returns description of data_for_competency_summary() parameters.
1179      *
1180      * @return \external_function_parameters
1181      */
1182     public static function data_for_competency_summary_parameters() {
1183         $competencyid = new external_value(
1184             PARAM_INT,
1185             'The competency id',
1186             VALUE_REQUIRED
1187         );
1188         $includerelated = new external_value(
1189             PARAM_BOOL,
1190             'Include or not related competencies',
1191             VALUE_DEFAULT,
1192             false
1193         );
1194         $includecourses = new external_value(
1195             PARAM_BOOL,
1196             'Include or not competency courses',
1197             VALUE_DEFAULT,
1198             false
1199         );
1200         $params = array(
1201             'competencyid' => $competencyid,
1202             'includerelated' => $includerelated,
1203             'includecourses' => $includecourses
1204         );
1205         return new external_function_parameters($params);
1206     }
1208     /**
1209      * Loads the data required to render the competency_page template.
1210      *
1211      * @param int $competencyid Competency id.
1212      * @param boolean $includerelated Include or not related competencies.
1213      * @param boolean $includecourses Include or not competency courses.
1214      *
1215      * @return \stdClass
1216      */
1217     public static function data_for_competency_summary($competencyid, $includerelated = false, $includecourses = false) {
1218         global $PAGE;
1219         $params = self::validate_parameters(self::data_for_competency_summary_parameters(),
1220                                             array(
1221                                                 'competencyid' => $competencyid,
1222                                                 'includerelated' => $includerelated,
1223                                                 'includecourses' => $includecourses
1224                                             ));
1226         $competency = api::read_competency($params['competencyid']);
1227         $framework = api::read_framework($competency->get_competencyframeworkid());
1228         $renderable = new output\competency_summary($competency, $framework, $params['includerelated'], $params['includecourses']);
1229         $renderer = $PAGE->get_renderer('tool_lp');
1231         $data = $renderable->export_for_template($renderer);
1233         return $data;
1234     }
1236     /**
1237      * Returns description of data_for_competency_summary_() result value.
1238      *
1239      * @return \external_description
1240      */
1241     public static function data_for_competency_summary_returns() {
1242         return competency_summary_exporter::get_read_structure();
1243     }
1245     /**
1246      * Returns description of set_parent_competency() parameters.
1247      *
1248      * @return \external_function_parameters
1249      */
1250     public static function set_parent_competency_parameters() {
1251         $competencyid = new external_value(
1252             PARAM_INT,
1253             'The competency id',
1254             VALUE_REQUIRED
1255         );
1256         $parentid = new external_value(
1257             PARAM_INT,
1258             'The new competency parent id',
1259             VALUE_REQUIRED
1260         );
1261         $params = array(
1262             'competencyid' => $competencyid,
1263             'parentid' => $parentid
1264         );
1265         return new external_function_parameters($params);
1266     }
1268     /**
1269      * Move the competency to a new parent.
1270      *
1271      * @param int $competencyid Competency id.
1272      * @param int $parentid Parent id.
1273      *
1274      * @return bool
1275      */
1276     public static function set_parent_competency($competencyid, $parentid) {
1277         $params = self::validate_parameters(self::set_parent_competency_parameters(),
1278                                             array(
1279                                                 'competencyid' => $competencyid,
1280                                                 'parentid' => $parentid
1281                                             ));
1283         $competency = api::read_competency($params['competencyid']);
1284         self::validate_context($competency->get_context());
1286         return api::set_parent_competency($params['competencyid'], $params['parentid']);
1287     }
1289     /**
1290      * Returns description of set_parent_competency() result value.
1291      *
1292      * @return \external_description
1293      */
1294     public static function set_parent_competency_returns() {
1295         return new external_value(PARAM_BOOL, 'True if the update was successful');
1296     }
1298     /**
1299      * Returns description of move_up_competency() parameters.
1300      *
1301      * @return \external_function_parameters
1302      */
1303     public static function move_up_competency_parameters() {
1304         $competencyid = new external_value(
1305             PARAM_INT,
1306             'The competency id',
1307             VALUE_REQUIRED
1308         );
1309         $params = array(
1310             'id' => $competencyid,
1311         );
1312         return new external_function_parameters($params);
1313     }
1315     /**
1316      * Change the sort order of a competency.
1317      *
1318      * @param int $competencyid Competency id.
1319      * @return boolean
1320      */
1321     public static function move_up_competency($competencyid) {
1322         $params = self::validate_parameters(self::move_up_competency_parameters(),
1323                                             array(
1324                                                 'id' => $competencyid,
1325                                             ));
1327         $competency = api::read_competency($params['id']);
1328         self::validate_context($competency->get_context());
1330         return api::move_up_competency($params['id']);
1331     }
1333     /**
1334      * Returns description of move_up_competency() result value.
1335      *
1336      * @return \external_description
1337      */
1338     public static function move_up_competency_returns() {
1339         return new external_value(PARAM_BOOL, 'True if the update was successful');
1340     }
1342     /**
1343      * Returns description of move_down_competency() parameters.
1344      *
1345      * @return \external_function_parameters
1346      */
1347     public static function move_down_competency_parameters() {
1348         $competencyid = new external_value(
1349             PARAM_INT,
1350             'The competency id',
1351             VALUE_REQUIRED
1352         );
1353         $params = array(
1354             'id' => $competencyid,
1355         );
1356         return new external_function_parameters($params);
1357     }
1359     /**
1360      * Change the sort order of a competency.
1361      *
1362      * @param int $competencyid Competency id.
1363      * @return boolean
1364      */
1365     public static function move_down_competency($competencyid) {
1366         $params = self::validate_parameters(self::move_down_competency_parameters(),
1367                                             array(
1368                                                 'id' => $competencyid,
1369                                             ));
1371         $competency = api::read_competency($params['id']);
1372         self::validate_context($competency->get_context());
1374         return api::move_down_competency($params['id']);
1375     }
1377     /**
1378      * Returns description of move_down_competency() result value.
1379      *
1380      * @return \external_description
1381      */
1382     public static function move_down_competency_returns() {
1383         return new external_value(PARAM_BOOL, 'True if the update was successful');
1384     }
1386     /**
1387      * Returns description of count_courses_using_competency() parameters.
1388      *
1389      * @return \external_function_parameters
1390      */
1391     public static function count_courses_using_competency_parameters() {
1392         $competencyid = new external_value(
1393             PARAM_INT,
1394             'The competency id',
1395             VALUE_REQUIRED
1396         );
1397         $params = array(
1398             'id' => $competencyid,
1399         );
1400         return new external_function_parameters($params);
1401     }
1403     /**
1404      * Count the courses (visible to this user) that use this competency.
1405      *
1406      * @param int $competencyid Competency id.
1407      * @return int
1408      */
1409     public static function count_courses_using_competency($competencyid) {
1410         $params = self::validate_parameters(self::count_courses_using_competency_parameters(),
1411                                             array(
1412                                                 'id' => $competencyid,
1413                                             ));
1415         $competency = api::read_competency($params['id']);
1416         self::validate_context($competency->get_context());
1418         return api::count_courses_using_competency($params['id']);
1419     }
1421     /**
1422      * Returns description of count_courses_using_competency() result value.
1423      *
1424      * @return \external_description
1425      */
1426     public static function count_courses_using_competency_returns() {
1427         return new external_value(PARAM_INT, 'The number of courses using this competency');
1428     }
1430     /**
1431      * Returns description of list_courses_using_competency() parameters.
1432      *
1433      * @return \external_function_parameters
1434      */
1435     public static function list_courses_using_competency_parameters() {
1436         $competencyid = new external_value(
1437             PARAM_INT,
1438             'The competency id',
1439             VALUE_REQUIRED
1440         );
1441         $params = array(
1442             'id' => $competencyid,
1443         );
1444         return new external_function_parameters($params);
1445     }
1447     /**
1448      * Count the courses (visible to this user) that use this competency.
1449      *
1450      * @param int $competencyid Competency id.
1451      * @return array
1452      */
1453     public static function list_courses_using_competency($competencyid) {
1454         global $PAGE;
1456         $params = self::validate_parameters(self::list_courses_using_competency_parameters(),
1457                                             array(
1458                                                 'id' => $competencyid,
1459                                             ));
1461         $competency = api::read_competency($params['id']);
1462         self::validate_context($competency->get_context());
1463         $output = $PAGE->get_renderer('tool_lp');
1465         $results = array();
1466         $courses = api::list_courses_using_competency($params['id']);
1467         foreach ($courses as $course) {
1468             $context = context_course::instance($course->id);
1469             $exporter = new course_summary_exporter($course, array('context' => $context));
1470             $result = $exporter->export($output);
1471             array_push($results, $result);
1472         }
1473         return $results;
1474     }
1476     /**
1477      * Returns description of list_courses_using_competency() result value.
1478      *
1479      * @return \external_description
1480      */
1481     public static function list_courses_using_competency_returns() {
1482         return new external_multiple_structure(course_summary_exporter::get_read_structure());
1483     }
1485     /**
1486      * Returns description of count_competencies_in_course() parameters.
1487      *
1488      * @return \external_function_parameters
1489      */
1490     public static function count_competencies_in_course_parameters() {
1491         $courseid = new external_value(
1492             PARAM_INT,
1493             'The course id',
1494             VALUE_REQUIRED
1495         );
1496         $params = array(
1497             'id' => $courseid,
1498         );
1499         return new external_function_parameters($params);
1500     }
1502     /**
1503      * Count the competencies (visible to this user) in this course.
1504      *
1505      * @param int $courseid The course id to check.
1506      * @return int
1507      */
1508     public static function count_competencies_in_course($courseid) {
1509         $params = self::validate_parameters(self::count_competencies_in_course_parameters(),
1510                                             array(
1511                                                 'id' => $courseid,
1512                                             ));
1514         self::validate_context(context_course::instance($params['id']));
1516         return api::count_competencies_in_course($params['id']);
1517     }
1519     /**
1520      * Returns description of count_competencies_in_course() result value.
1521      *
1522      * @return \external_description
1523      */
1524     public static function count_competencies_in_course_returns() {
1525         return new external_value(PARAM_INT, 'The number of competencies in this course.');
1526     }
1528     /**
1529      * Returns description of list_course_module_competencies() parameters.
1530      *
1531      * @return \external_function_parameters
1532      */
1533     public static function list_course_module_competencies_parameters() {
1534         $cmid = new external_value(
1535             PARAM_INT,
1536             'The course module id',
1537             VALUE_REQUIRED
1538         );
1539         $params = array(
1540             'cmid' => $cmid
1541         );
1542         return new external_function_parameters($params);
1543     }
1545     /**
1546      * List the course modules using this competency (visible to this user) in this course.
1547      *
1548      * @param int $cmid The course module id to check.
1549      * @return array
1550      */
1551     public static function list_course_module_competencies($cmid) {
1552         global $PAGE;
1554         $params = self::validate_parameters(self::list_course_module_competencies_parameters(),
1555                                             array(
1556                                                 'cmid' => $cmid
1557                                             ));
1559         $context = context_module::instance($params['cmid']);
1560         self::validate_context($context);
1562         $output = $PAGE->get_renderer('tool_lp');
1564         $apiresult = api::list_course_module_competencies($params['cmid']);
1565         $result = array();
1567         foreach ($apiresult as $cmrecord) {
1568             $one = new stdClass();
1569             $exporter = new competency_exporter($cmrecord['competency']);
1570             $one->competency = $exporter->export($output);
1571             $exporter = new course_module_competency_exporter($cmrecord['coursemodulecompetency']);
1572             $one->coursemodulecompetency = $exporter->export($output);
1574             $result[] = (array) $one;
1575         }
1577         return $result;
1578     }
1580     /**
1581      * Returns description of list_course_module_competencies() result value.
1582      *
1583      * @return \external_description
1584      */
1585     public static function list_course_module_competencies_returns() {
1586         return new external_multiple_structure(
1587             new external_single_structure(array(
1588                 'competency' => competency_exporter::get_read_structure(),
1589                 'coursemodulecompetency' => course_module_competency_exporter::get_read_structure()
1590             ))
1591         );
1592     }
1594     /**
1595      * Returns description of list_course_modules_using_competency() parameters.
1596      *
1597      * @return \external_function_parameters
1598      */
1599     public static function list_course_modules_using_competency_parameters() {
1600         $competencyid = new external_value(
1601             PARAM_INT,
1602             'The competency id',
1603             VALUE_REQUIRED
1604         );
1605         $courseid = new external_value(
1606             PARAM_INT,
1607             'The course id',
1608             VALUE_REQUIRED
1609         );
1610         $params = array(
1611             'competencyid' => $competencyid,
1612             'courseid' => $courseid,
1613         );
1614         return new external_function_parameters($params);
1615     }
1617     /**
1618      * List the course modules using this competency (visible to this user) in this course.
1619      *
1620      * @param int $competencyid The competency id to check.
1621      * @param int $courseid The course id to check.
1622      * @return array
1623      */
1624     public static function list_course_modules_using_competency($competencyid, $courseid) {
1625         global $PAGE;
1627         $params = self::validate_parameters(self::list_course_modules_using_competency_parameters(),
1628                                             array(
1629                                                 'competencyid' => $competencyid,
1630                                                 'courseid' => $courseid,
1631                                             ));
1633         $coursecontext = context_course::instance($params['courseid']);
1634         self::validate_context($coursecontext);
1636         $output = $PAGE->get_renderer('tool_lp');
1638         $coursemodules = api::list_course_modules_using_competency($params['competencyid'], $params['courseid']);
1639         $result = array();
1641         $fastmodinfo = get_fast_modinfo($cm->course);
1643         foreach ($coursemodules as $cmid) {
1644             $cminfo = $fastmodinfo->cms[$cmid];
1645             $exporter = new course_module_summary_exporter(null, array('cm' => $cminfo));
1646             $coursemodulesummary = $exporter->export($output);
1648             $result[] = $coursemodulesummary;
1649         }
1651         return $result;
1652     }
1654     /**
1655      * Returns description of list_course_modules_using_competency() result value.
1656      *
1657      * @return \external_description
1658      */
1659     public static function list_course_modules_using_competency_returns() {
1660         return new external_multiple_structure(course_module_summary_exporter::get_read_structure());
1661     }
1663     /**
1664      * Returns description of list_course_competencies() parameters.
1665      *
1666      * @return \external_function_parameters
1667      */
1668     public static function list_course_competencies_parameters() {
1669         $courseid = new external_value(
1670             PARAM_INT,
1671             'The course id',
1672             VALUE_REQUIRED
1673         );
1674         $params = array(
1675             'id' => $courseid,
1676         );
1677         return new external_function_parameters($params);
1678     }
1680     /**
1681      * List the competencies (visible to this user) in this course.
1682      *
1683      * @param int $courseid The course id to check.
1684      * @return array
1685      */
1686     public static function list_course_competencies($courseid) {
1687         global $PAGE;
1689         $params = self::validate_parameters(self::list_course_competencies_parameters(),
1690                                             array(
1691                                                 'id' => $courseid,
1692                                             ));
1694         $coursecontext = context_course::instance($params['id']);
1695         self::validate_context($coursecontext);
1697         $output = $PAGE->get_renderer('tool_lp');
1699         $competencies = api::list_course_competencies($params['id']);
1700         $result = array();
1702         $contextcache = array();
1703         foreach ($competencies as $competency) {
1704             if (!isset($contextcache[$competency['competency']->get_competencyframeworkid()])) {
1705                 $contextcache[$competency['competency']->get_competencyframeworkid()] = $competency['competency']->get_context();
1706             }
1707             $context = $contextcache[$competency['competency']->get_competencyframeworkid()];
1708             $exporter = new competency_exporter($competency['competency'], array('context' => $context));
1709             $competencyrecord = $exporter->export($output);
1710             $exporter = new course_competency_exporter($competency['coursecompetency'], array('context' => $context));
1711             $coursecompetencyrecord = $exporter->export($output);
1713             $result[] = array(
1714                 'competency' => $competencyrecord,
1715                 'coursecompetency' => $coursecompetencyrecord
1716             );
1717         }
1719         return $result;
1720     }
1722     /**
1723      * Returns description of list_course_competencies() result value.
1724      *
1725      * @return \external_description
1726      */
1727     public static function list_course_competencies_returns() {
1728         return new external_multiple_structure(
1729             new external_single_structure(array(
1730                 'competency' => competency_exporter::get_read_structure(),
1731                 'coursecompetency' => course_competency_exporter::get_read_structure()
1732             ))
1733         );
1735     }
1737     /**
1738      * Returns description of add_competency_to_course() parameters.
1739      *
1740      * @return \external_function_parameters
1741      */
1742     public static function add_competency_to_course_parameters() {
1743         $courseid = new external_value(
1744             PARAM_INT,
1745             'The course id',
1746             VALUE_REQUIRED
1747         );
1748         $competencyid = new external_value(
1749             PARAM_INT,
1750             'The competency id',
1751             VALUE_REQUIRED
1752         );
1753         $params = array(
1754             'courseid' => $courseid,
1755             'competencyid' => $competencyid,
1756         );
1757         return new external_function_parameters($params);
1758     }
1760     /**
1761      * Count the competencies (visible to this user) in this course.
1762      *
1763      * @param int $courseid The course id to check.
1764      * @param int $competencyid Competency id.
1765      * @return int
1766      */
1767     public static function add_competency_to_course($courseid, $competencyid) {
1768         $params = self::validate_parameters(self::add_competency_to_course_parameters(),
1769                                             array(
1770                                                 'courseid' => $courseid,
1771                                                 'competencyid' => $competencyid,
1772                                             ));
1774         self::validate_context(context_course::instance($params['courseid']));
1776         return api::add_competency_to_course($params['courseid'], $params['competencyid']);
1777     }
1779     /**
1780      * Returns description of add_competency_to_course() result value.
1781      *
1782      * @return \external_description
1783      */
1784     public static function add_competency_to_course_returns() {
1785         return new external_value(PARAM_BOOL, 'True if successful.');
1786     }
1788     /**
1789      * Returns description of remove_competency_from_course() parameters.
1790      *
1791      * @return \external_function_parameters
1792      */
1793     public static function remove_competency_from_course_parameters() {
1794         $courseid = new external_value(
1795             PARAM_INT,
1796             'The course id',
1797             VALUE_REQUIRED
1798         );
1799         $competencyid = new external_value(
1800             PARAM_INT,
1801             'The competency id',
1802             VALUE_REQUIRED
1803         );
1804         $params = array(
1805             'courseid' => $courseid,
1806             'competencyid' => $competencyid,
1807         );
1808         return new external_function_parameters($params);
1809     }
1811     /**
1812      * Count the competencies (visible to this user) in this course.
1813      *
1814      * @param int $courseid The course id to check.
1815      * @param int $competencyid Competency id.
1816      * @return int
1817      */
1818     public static function remove_competency_from_course($courseid, $competencyid) {
1819         $params = self::validate_parameters(self::remove_competency_from_course_parameters(),
1820                                             array(
1821                                                 'courseid' => $courseid,
1822                                                 'competencyid' => $competencyid,
1823                                             ));
1825         self::validate_context(context_course::instance($params['courseid']));
1827         return api::remove_competency_from_course($params['courseid'], $params['competencyid']);
1828     }
1830     /**
1831      * Returns description of remove_competency_from_course() result value.
1832      *
1833      * @return \external_description
1834      */
1835     public static function remove_competency_from_course_returns() {
1836         return new external_value(PARAM_BOOL, 'True if successful.');
1837     }
1839     /**
1840      * Returns description of data_for_course_competenies_page() parameters.
1841      *
1842      * @return \external_function_parameters
1843      */
1844     public static function data_for_course_competencies_page_parameters() {
1845         $courseid = new external_value(
1846             PARAM_INT,
1847             'The course id',
1848             VALUE_REQUIRED
1849         );
1850         $params = array('courseid' => $courseid);
1851         return new external_function_parameters($params);
1852     }
1854     /**
1855      * Loads the data required to render the course_competencies_page template.
1856      *
1857      * @param int $courseid The course id to check.
1858      * @return boolean
1859      */
1860     public static function data_for_course_competencies_page($courseid) {
1861         global $PAGE;
1862         $params = self::validate_parameters(self::data_for_course_competencies_page_parameters(),
1863                                             array(
1864                                                 'courseid' => $courseid,
1865                                             ));
1866         self::validate_context(context_course::instance($params['courseid']));
1868         $renderable = new output\course_competencies_page($params['courseid']);
1869         $renderer = $PAGE->get_renderer('tool_lp');
1871         $data = $renderable->export_for_template($renderer);
1873         return $data;
1874     }
1876     /**
1877      * Returns description of data_for_course_competencies_page() result value.
1878      *
1879      * @return \external_description
1880      */
1881     public static function data_for_course_competencies_page_returns() {
1882         $uc = user_competency_exporter::get_read_structure();
1883         $uc->required = VALUE_OPTIONAL;
1885         return new external_single_structure(array (
1886             'courseid' => new external_value(PARAM_INT, 'The current course id'),
1887             'pagecontextid' => new external_value(PARAM_INT, 'The current page context ID.'),
1888             'gradableuserid' => new external_value(PARAM_INT, 'Current user id, if the user is a gradable user.', VALUE_OPTIONAL),
1889             'canmanagecompetencyframeworks' => new external_value(PARAM_BOOL, 'User can manage competency frameworks'),
1890             'canmanagecoursecompetencies' => new external_value(PARAM_BOOL, 'User can manage linked course competencies'),
1891             'competencies' => new external_multiple_structure(new external_single_structure(array(
1892                 'competency' => competency_exporter::get_read_structure(),
1893                 'coursecompetency' => course_competency_exporter::get_read_structure(),
1894                 'coursemodules' => new external_multiple_structure(course_module_summary_exporter::get_read_structure()),
1895                 'usercompetency' => $uc,
1896                 'ruleoutcomeoptions' => new external_multiple_structure(
1897                     new external_single_structure(array(
1898                         'value' => new external_value(PARAM_INT, 'The option value'),
1899                         'text' => new external_value(PARAM_NOTAGS, 'The name of the option'),
1900                         'selected' => new external_value(PARAM_BOOL, 'If this is the currently selected option'),
1901                 ))),
1902                 'comppath' => competency_path_exporter::get_read_structure(),
1903             ))),
1904             'manageurl' => new external_value(PARAM_LOCALURL, 'Url to the manage competencies page.'),
1905         ));
1907     }
1909     /**
1910      * Returns description of reorder_course_competency() parameters.
1911      *
1912      * @return \external_function_parameters
1913      */
1914     public static function reorder_course_competency_parameters() {
1915         $courseid = new external_value(
1916             PARAM_INT,
1917             'The course id',
1918             VALUE_REQUIRED
1919         );
1920         $competencyidfrom = new external_value(
1921             PARAM_INT,
1922             'The competency id we are moving',
1923             VALUE_REQUIRED
1924         );
1925         $competencyidto = new external_value(
1926             PARAM_INT,
1927             'The competency id we are moving to',
1928             VALUE_REQUIRED
1929         );
1930         $params = array(
1931             'courseid' => $courseid,
1932             'competencyidfrom' => $competencyidfrom,
1933             'competencyidto' => $competencyidto,
1934         );
1935         return new external_function_parameters($params);
1936     }
1938     /**
1939      * Change the order of course competencies.
1940      *
1941      * @param int $courseid The course id
1942      * @param int $competencyidfrom The competency to move.
1943      * @param int $competencyidto The competency to move to.
1944      * @return bool
1945      */
1946     public static function reorder_course_competency($courseid, $competencyidfrom, $competencyidto) {
1947         $params = self::validate_parameters(self::reorder_course_competency_parameters(),
1948                                             array(
1949                                                 'courseid' => $courseid,
1950                                                 'competencyidfrom' => $competencyidfrom,
1951                                                 'competencyidto' => $competencyidto,
1952                                             ));
1953         self::validate_context(context_course::instance($params['courseid']));
1955         return api::reorder_course_competency($params['courseid'], $params['competencyidfrom'], $params['competencyidto']);
1956     }
1958     /**
1959      * Returns description of reorder_course_competency() result value.
1960      *
1961      * @return \external_description
1962      */
1963     public static function reorder_course_competency_returns() {
1964         return new external_value(PARAM_BOOL, 'True if successful.');
1965     }
1967     /**
1968      * Returns description of reorder_template_competency() parameters.
1969      *
1970      * @return \external_function_parameters
1971      */
1972     public static function reorder_template_competency_parameters() {
1973         $templateid = new external_value(
1974             PARAM_INT,
1975             'The template id',
1976             VALUE_REQUIRED
1977         );
1978         $competencyidfrom = new external_value(
1979             PARAM_INT,
1980             'The competency id we are moving',
1981             VALUE_REQUIRED
1982         );
1983         $competencyidto = new external_value(
1984             PARAM_INT,
1985             'The competency id we are moving to',
1986             VALUE_REQUIRED
1987         );
1988         $params = array(
1989             'templateid' => $templateid,
1990             'competencyidfrom' => $competencyidfrom,
1991             'competencyidto' => $competencyidto,
1992         );
1993         return new external_function_parameters($params);
1994     }
1996     /**
1997      * Change the order of template competencies.
1998      *
1999      * @param int $templateid The template id
2000      * @param int $competencyidfrom The competency to move.
2001      * @param int $competencyidto The competency to move to.
2002      * @return bool
2003      */
2004     public static function reorder_template_competency($templateid, $competencyidfrom, $competencyidto) {
2005         $params = self::validate_parameters(self::reorder_template_competency_parameters(),
2006             array(
2007                 'templateid' => $templateid,
2008                 'competencyidfrom' => $competencyidfrom,
2009                 'competencyidto' => $competencyidto,
2010             ));
2012         $template = api::read_template($params['templateid']);
2013         self::validate_context($template->get_context());
2015         return api::reorder_template_competency($params['templateid'], $params['competencyidfrom'], $params['competencyidto']);
2016     }
2018     /**
2019      * Returns description of reorder_template_competency() result value.
2020      *
2021      * @return \external_description
2022      */
2023     public static function reorder_template_competency_returns() {
2024         return new external_value(PARAM_BOOL, 'True if successful.');
2025     }
2027     /**
2028      * Returns description of create_template() parameters.
2029      *
2030      * @return \external_function_parameters
2031      */
2032     public static function create_template_parameters() {
2033         $structure = template_exporter::get_create_structure();
2034         $params = array('template' => $structure);
2035         return new external_function_parameters($params);
2036     }
2038     /**
2039      * Create a new learning plan template
2040      *
2041      * @param array $template The list of fields for the template.
2042      * @return \stdClass Record of new template.
2043      */
2044     public static function create_template($template) {
2045         global $PAGE;
2047         $params = self::validate_parameters(self::create_template_parameters(),
2048                                             array('template' => $template));
2049         $params = $params['template'];
2050         $context = self::get_context_from_params($params);
2051         self::validate_context($context);
2052         $output = $PAGE->get_renderer('tool_lp');
2054         unset($params['contextlevel']);
2055         unset($params['instanceid']);
2056         $params = (object) $params;
2057         $params->contextid = $context->id;
2059         $result = api::create_template($params);
2060         $exporter = new template_exporter($result);
2061         $record = $exporter->export($output);
2062         return $record;
2063     }
2065     /**
2066      * Returns description of create_template() result value.
2067      *
2068      * @return \external_description
2069      */
2070     public static function create_template_returns() {
2071         return template_exporter::get_read_structure();
2072     }
2074     /**
2075      * Returns description of read_template() parameters.
2076      *
2077      * @return \external_function_parameters
2078      */
2079     public static function read_template_parameters() {
2080         $id = new external_value(
2081             PARAM_INT,
2082             'Data base record id for the template',
2083             VALUE_REQUIRED
2084         );
2086         $params = array(
2087             'id' => $id,
2088         );
2089         return new external_function_parameters($params);
2090     }
2092     /**
2093      * Read a learning plan template by id.
2094      *
2095      * @param int $id The id of the template.
2096      * @return \stdClass
2097      */
2098     public static function read_template($id) {
2099         global $PAGE;
2101         $params = self::validate_parameters(self::read_template_parameters(),
2102                                             array(
2103                                                 'id' => $id,
2104                                             ));
2106         $template = api::read_template($params['id']);
2107         self::validate_context($template->get_context());
2108         $output = $PAGE->get_renderer('tool_lp');
2110         $exporter = new template_exporter($template);
2111         $record = $exporter->export($output);
2112         return $record;
2113     }
2115     /**
2116      * Returns description of read_template() result value.
2117      *
2118      * @return \external_description
2119      */
2120     public static function read_template_returns() {
2121         return template_exporter::get_read_structure();
2122     }
2124     /**
2125      * Returns description of delete_template() parameters.
2126      *
2127      * @return \external_function_parameters
2128      */
2129     public static function delete_template_parameters() {
2130         $id = new external_value(
2131             PARAM_INT,
2132             'Data base record id for the template',
2133             VALUE_REQUIRED
2134         );
2136         $deleteplans = new external_value(
2137             PARAM_BOOL,
2138             'Boolean to indicate if plans must be deleted',
2139             VALUE_REQUIRED
2140         );
2142         $params = array(
2143             'id' => $id,
2144             'deleteplans' => $deleteplans
2145         );
2146         return new external_function_parameters($params);
2147     }
2149     /**
2150      * Delete a learning plan template
2151      *
2152      * @param int $id The learning plan template id
2153      * @param boolean $deleteplans True to delete the plans associated to template or false to unlink them
2154      * @return boolean
2155      */
2156     public static function delete_template($id, $deleteplans = true) {
2157         $params = self::validate_parameters(self::delete_template_parameters(),
2158                                             array(
2159                                                 'id' => $id,
2160                                                 'deleteplans' => $deleteplans,
2161                                             ));
2163         $template = api::read_template($params['id']);
2164         self::validate_context($template->get_context());
2166         return api::delete_template($params['id'], $params['deleteplans']);
2167     }
2169     /**
2170      * Returns description of delete_template() result value.
2171      *
2172      * @return \external_description
2173      */
2174     public static function delete_template_returns() {
2175         return new external_value(PARAM_BOOL, 'True if the delete was successful');
2176     }
2178     /**
2179      * Returns description of update_template() parameters.
2180      *
2181      * @return \external_function_parameters
2182      */
2183     public static function update_template_parameters() {
2184         $structure = template_exporter::get_update_structure();
2185         $params = array('template' => $structure);
2186         return new external_function_parameters($params);
2187     }
2189     /**
2190      * Update an existing learning plan template
2191      *
2192      * @param array $template The list of fields for the template.
2193      * @return boolean
2194      */
2195     public static function update_template($template) {
2197         $params = self::validate_parameters(self::update_template_parameters(),
2198                                             array('template' => $template));
2199         $params = $params['template'];
2200         $template = api::read_template($params['id']);
2201         self::validate_context($template->get_context());
2203         $params = (object) $params;
2205         return api::update_template($params);
2206     }
2208     /**
2209      * Returns description of update_template() result value.
2210      *
2211      * @return \external_description
2212      */
2213     public static function update_template_returns() {
2214         return new external_value(PARAM_BOOL, 'True if the update was successful');
2215     }
2217     /**
2218      * Returns description of duplicate_template() parameters.
2219      *
2220      * @return \external_function_parameters
2221      */
2222     public static function duplicate_template_parameters() {
2223         $templateid = new external_value(
2224             PARAM_INT,
2225             'The template id',
2226             VALUE_REQUIRED
2227         );
2229         $params = array(
2230             'id' => $templateid
2231         );
2232         return new external_function_parameters($params);
2233     }
2235     /**
2236      * Duplicate a learning plan template.
2237      *
2238      * @param int $id the id of the learning plan template to duplicate
2239      * @return boolean Record of new template.
2240      */
2241     public static function duplicate_template($id) {
2242         global $PAGE;
2244         $params = self::validate_parameters(self::duplicate_template_parameters(),
2245                                             array(
2246                                                 'id' => $id,
2247                                             ));
2249         $template = api::read_template($params['id']);
2250         self::validate_context($template->get_context());
2251         $output = $PAGE->get_renderer('tool_lp');
2253         $result = api::duplicate_template($params['id']);
2254         $exporter = new template_exporter($result);
2255         return $exporter->export($output);
2256     }
2258     /**
2259      * Returns description of duplicate_template() result value.
2260      *
2261      * @return \external_description
2262      */
2263     public static function duplicate_template_returns() {
2264         return template_exporter::get_read_structure();
2265     }
2267     /**
2268      * Returns description of list_templates() parameters.
2269      *
2270      * @return \external_function_parameters
2271      */
2272     public static function list_templates_parameters() {
2273         $sort = new external_value(
2274             PARAM_ALPHANUMEXT,
2275             'Column to sort by.',
2276             VALUE_DEFAULT,
2277             ''
2278         );
2279         $order = new external_value(
2280             PARAM_ALPHA,
2281             'Sort direction. Should be either ASC or DESC',
2282             VALUE_DEFAULT,
2283             ''
2284         );
2285         $skip = new external_value(
2286             PARAM_INT,
2287             'Skip this number of records before returning results',
2288             VALUE_DEFAULT,
2289             0
2290         );
2291         $limit = new external_value(
2292             PARAM_INT,
2293             'Return this number of records at most.',
2294             VALUE_DEFAULT,
2295             0
2296         );
2297         $includes = new external_value(
2298             PARAM_ALPHA,
2299             'What other contexts to fetch the templates from. (children, parents, self)',
2300             VALUE_DEFAULT,
2301             'children'
2302         );
2303         $onlyvisible = new external_value(
2304             PARAM_BOOL,
2305             'If should list only visible templates',
2306             VALUE_DEFAULT,
2307             false
2308         );
2310         $params = array(
2311             'sort' => $sort,
2312             'order' => $order,
2313             'skip' => $skip,
2314             'limit' => $limit,
2315             'context' => self::get_context_parameters(),
2316             'includes' => $includes,
2317             'onlyvisible' => $onlyvisible
2318         );
2319         return new external_function_parameters($params);
2320     }
2322     /**
2323      * List the existing learning plan templates
2324      *
2325      * @param string $sort Field to sort by.
2326      * @param string $order Sort order.
2327      * @param int $skip Limitstart.
2328      * @param int $limit Number of rows to return.
2329      * @param array $context
2330      * @param bool $includes
2331      * @param bool $onlyvisible
2332      *
2333      * @return array
2334      */
2335     public static function list_templates($sort, $order, $skip, $limit, $context, $includes, $onlyvisible) {
2336         global $PAGE;
2338         $params = self::validate_parameters(self::list_templates_parameters(),
2339                                             array(
2340                                                 'sort' => $sort,
2341                                                 'order' => $order,
2342                                                 'skip' => $skip,
2343                                                 'limit' => $limit,
2344                                                 'context' => $context,
2345                                                 'includes' => $includes,
2346                                                 'onlyvisible' => $onlyvisible
2347                                             ));
2349         $context = self::get_context_from_params($params['context']);
2350         self::validate_context($context);
2351         $output = $PAGE->get_renderer('tool_lp');
2353         if ($params['order'] !== '' && $params['order'] !== 'ASC' && $params['order'] !== 'DESC') {
2354             throw new invalid_parameter_exception('Invalid order param. Must be ASC, DESC or empty.');
2355         }
2357         $results = api::list_templates($params['sort'],
2358                                        $params['order'],
2359                                        $params['skip'],
2360                                        $params['limit'],
2361                                        $context,
2362                                        $params['includes'],
2363                                        $params['onlyvisible']);
2364         $records = array();
2365         foreach ($results as $result) {
2366             $exporter = new template_exporter($result);
2367             $record = $exporter->export($output);
2368             array_push($records, $record);
2369         }
2370         return $records;
2371     }
2373     /**
2374      * Returns description of list_templates() result value.
2375      *
2376      * @return \external_description
2377      */
2378     public static function list_templates_returns() {
2379         return new external_multiple_structure(template_exporter::get_read_structure());
2380     }
2382     /**
2383      * Returns description of count_templates() parameters.
2384      *
2385      * @return \external_function_parameters
2386      */
2387     public static function count_templates_parameters() {
2388         $includes = new external_value(
2389             PARAM_ALPHA,
2390             'What other contextes to fetch the frameworks from. (children, parents, self)',
2391             VALUE_DEFAULT,
2392             'children'
2393         );
2395         $params = array(
2396             'context' => self::get_context_parameters(),
2397             'includes' => $includes
2398         );
2399         return new external_function_parameters($params);
2400     }
2402     /**
2403      * Count the existing learning plan templates
2404      *
2405      * @param array $context
2406      * @param string $includes
2407      * @return int
2408      */
2409     public static function count_templates($context, $includes) {
2410         $params = self::validate_parameters(self::count_templates_parameters(),
2411                                             array(
2412                                                 'context' => $context,
2413                                                 'includes' => $includes
2414                                             ));
2415         $context = self::get_context_from_params($params['context']);
2416         self::validate_context($context);
2418         return api::count_templates($context, $includes);
2419     }
2421     /**
2422      * Returns description of count_templates() result value.
2423      *
2424      * @return \external_description
2425      */
2426     public static function count_templates_returns() {
2427         return new external_value(PARAM_INT, 'The number of learning plan templates found.');
2428     }
2430     /**
2431      * Returns description of data_for_templates_manage_page() parameters.
2432      *
2433      * @return \external_function_parameters
2434      */
2435     public static function data_for_templates_manage_page_parameters() {
2436         $params = array('pagecontext' => self::get_context_parameters());
2437         return new external_function_parameters($params);
2438     }
2440     /**
2441      * Loads the data required to render the templates_manage_page template.
2442      *
2443      * @param array $pagecontext The page context info.
2444      * @return boolean
2445      */
2446     public static function data_for_templates_manage_page($pagecontext) {
2447         global $PAGE;
2449         $params = self::validate_parameters(self::data_for_templates_manage_page_parameters(), array(
2450             'pagecontext' => $pagecontext
2451         ));
2452         $context = self::get_context_from_params($params['pagecontext']);
2453         self::validate_context($context);
2455         $renderable = new output\manage_templates_page($context);
2456         $renderer = $PAGE->get_renderer('tool_lp');
2458         $data = $renderable->export_for_template($renderer);
2460         return $data;
2461     }
2463     /**
2464      * Returns description of data_for_templates_manage_page() result value.
2465      *
2466      * @return \external_description
2467      */
2468     public static function data_for_templates_manage_page_returns() {
2469         return new external_single_structure(array (
2470             'templates' => new external_multiple_structure(
2471                 template_exporter::get_read_structure()
2472             ),
2473             'pluginbaseurl' => new external_value(PARAM_LOCALURL, 'Url to the tool_lp plugin folder on this Moodle site'),
2474             'navigation' => new external_multiple_structure(
2475                 new external_value(PARAM_RAW, 'HTML for a navigation item that should be on this page')
2476             ),
2477             'pagecontextid' => new external_value(PARAM_INT, 'The page context id'),
2478             'canmanage' => new external_value(PARAM_BOOL, 'Whether the user manage the templates')
2479         ));
2481     }
2483     /**
2484      * Returns description of count_templates_using_competency() parameters.
2485      *
2486      * @return \external_function_parameters
2487      */
2488     public static function count_templates_using_competency_parameters() {
2489         $competencyid = new external_value(
2490             PARAM_INT,
2491             'The competency id',
2492             VALUE_REQUIRED
2493         );
2494         $params = array(
2495             'id' => $competencyid,
2496         );
2497         return new external_function_parameters($params);
2498     }
2500     /**
2501      * Count the learning plan templates (visible to this user) that use this competency.
2502      *
2503      * @param int $competencyid Competency id.
2504      * @return int
2505      */
2506     public static function count_templates_using_competency($competencyid) {
2507         $params = self::validate_parameters(self::count_templates_using_competency_parameters(),
2508                                             array(
2509                                                 'id' => $competencyid,
2510                                             ));
2512         $competency = api::read_competency($params['id']);
2513         self::validate_context($competency->get_context());
2515         return api::count_templates_using_competency($params['id']);
2516     }
2518     /**
2519      * Returns description of count_templates_using_competency() result value.
2520      *
2521      * @return \external_description
2522      */
2523     public static function count_templates_using_competency_returns() {
2524         return new external_value(PARAM_INT, 'The number of learning plan templates using this competency');
2525     }
2527     /**
2528      * Returns description of list_templates_using_competency() parameters.
2529      *
2530      * @return \external_function_parameters
2531      */
2532     public static function list_templates_using_competency_parameters() {
2533         $competencyid = new external_value(
2534             PARAM_INT,
2535             'The competency id',
2536             VALUE_REQUIRED
2537         );
2538         $params = array(
2539             'id' => $competencyid,
2540         );
2541         return new external_function_parameters($params);
2542     }
2544     /**
2545      * List the learning plan templates (visible to this user) that use this competency.
2546      *
2547      * @param int $competencyid Competency id.
2548      * @return array
2549      */
2550     public static function list_templates_using_competency($competencyid) {
2551         global $PAGE;
2553         $params = self::validate_parameters(self::list_templates_using_competency_parameters(),
2554                                             array(
2555                                                 'id' => $competencyid,
2556                                             ));
2558         $competency = api::read_competency($params['id']);
2559         self::validate_context($competency->get_context());
2560         $output = $PAGE->get_renderer('tool_lp');
2562         $templates = api::list_templates_using_competency($params['id']);
2563         $records = array();
2565         foreach ($templates as $template) {
2566             $exporter = new template_exporter($template);
2567             $record = $exporter->export($output);
2568             $records[] = $record;
2569         }
2571         return $records;
2572     }
2574     /**
2575      * Returns description of list_templates_using_competency() result value.
2576      *
2577      * @return \external_description
2578      */
2579     public static function list_templates_using_competency_returns() {
2580         return new external_multiple_structure(template_exporter::get_read_structure());
2581     }
2583     /**
2584      * Returns description of count_competencies_in_template() parameters.
2585      *
2586      * @return \external_function_parameters
2587      */
2588     public static function count_competencies_in_template_parameters() {
2589         $templateid = new external_value(
2590             PARAM_INT,
2591             'The template id',
2592             VALUE_REQUIRED
2593         );
2594         $params = array(
2595             'id' => $templateid,
2596         );
2597         return new external_function_parameters($params);
2598     }
2600     /**
2601      * Count the competencies (visible to this user) in this learning plan template.
2602      *
2603      * @param int $templateid The template id to check
2604      * @return int
2605      */
2606     public static function count_competencies_in_template($templateid) {
2607         global $PAGE;
2608         $params = self::validate_parameters(self::count_competencies_in_template_parameters(),
2609                                             array(
2610                                                 'id' => $templateid,
2611                                             ));
2612         $template = api::read_template($params['id']);
2613         self::validate_context($template->get_context());
2615         return api::count_competencies_in_template($params['id']);
2616     }
2618     /**
2619      * Returns description of count_competencies_in_template() result value.
2620      *
2621      * @return \external_description
2622      */
2623     public static function count_competencies_in_template_returns() {
2624         return new external_value(PARAM_INT, 'The number of competencies in this learning plan template.');
2625     }
2627     /**
2628      * Returns description of list_competencies_in_template() parameters.
2629      *
2630      * @return \external_function_parameters
2631      */
2632     public static function list_competencies_in_template_parameters() {
2633         $templateid = new external_value(
2634             PARAM_INT,
2635             'The template id',
2636             VALUE_REQUIRED
2637         );
2638         $params = array(
2639             'id' => $templateid,
2640         );
2641         return new external_function_parameters($params);
2642     }
2644     /**
2645      * List the competencies (visible to this user) in this learning plan template.
2646      *
2647      * @param int $templateid Template id.
2648      * @return array
2649      */
2650     public static function list_competencies_in_template($templateid) {
2651         global $PAGE;
2653         $params = self::validate_parameters(self::list_competencies_in_template_parameters(),
2654                                             array(
2655                                                 'id' => $templateid,
2656                                             ));
2658         $template = api::read_template($params['id']);
2659         self::validate_context($template->get_context());
2660         $output = $PAGE->get_renderer('tool_lp');
2662         $competencies = api::list_competencies_in_template($params['id']);
2663         $results = array();
2664         $contextcache = array();
2666         foreach ($competencies as $competency) {
2667             if (!isset($contextcache[$competency->get_competencyframeworkid()])) {
2668                 $contextcache[$competency->get_competencyframeworkid()] = $competency->get_context();
2669             }
2670             $context = $contextcache[$competency->get_competencyframeworkid()];
2671             $exporter = new competency_exporter($competency, array('context' => $context));
2672             $record = $exporter->export($output);
2673             array_push($results, $record);
2674         }
2675         return $results;
2676     }
2678     /**
2679      * Returns description of list_competencies_in_template() result value.
2680      *
2681      * @return \external_description
2682      */
2683     public static function list_competencies_in_template_returns() {
2684         return new external_multiple_structure(competency_exporter::get_read_structure());
2685     }
2687     /**
2688      * Returns description of add_competency_to_template() parameters.
2689      *
2690      * @return \external_function_parameters
2691      */
2692     public static function add_competency_to_template_parameters() {
2693         $templateid = new external_value(
2694             PARAM_INT,
2695             'The template id',
2696             VALUE_REQUIRED
2697         );
2698         $competencyid = new external_value(
2699             PARAM_INT,
2700             'The competency id',
2701             VALUE_REQUIRED
2702         );
2703         $params = array(
2704             'templateid' => $templateid,
2705             'competencyid' => $competencyid,
2706         );
2707         return new external_function_parameters($params);
2708     }
2710     /**
2711      * Count the competencies (visible to this user) in this template.
2712      *
2713      * @param int $templateid Template id.
2714      * @param int $competencyid Competency id.
2715      * @return int
2716      */
2717     public static function add_competency_to_template($templateid, $competencyid) {
2718         global $PAGE;
2719         $params = self::validate_parameters(self::add_competency_to_template_parameters(),
2720                                             array(
2721                                                 'templateid' => $templateid,
2722                                                 'competencyid' => $competencyid,
2723                                             ));
2725         $template = api::read_template($params['templateid']);
2726         self::validate_context($template->get_context());
2728         return api::add_competency_to_template($params['templateid'], $params['competencyid']);
2729     }
2731     /**
2732      * Returns description of add_competency_to_template() result value.
2733      *
2734      * @return \external_description
2735      */
2736     public static function add_competency_to_template_returns() {
2737         return new external_value(PARAM_BOOL, 'True if successful.');
2738     }
2740     /**
2741      * Returns description of add_competency_to_plan() parameters.
2742      *
2743      * @return \external_function_parameters
2744      */
2745     public static function add_competency_to_plan_parameters() {
2746         $planid = new external_value(
2747             PARAM_INT,
2748             'The plan id',
2749             VALUE_REQUIRED
2750         );
2751         $competencyid = new external_value(
2752             PARAM_INT,
2753             'The competency id',
2754             VALUE_REQUIRED
2755         );
2756         $params = array(
2757             'planid' => $planid,
2758             'competencyid' => $competencyid,
2759         );
2760         return new external_function_parameters($params);
2761     }
2763     /**
2764      * add competency to a learning plan.
2765      *
2766      * @param int $planid Plan id.
2767      * @param int $competencyid Competency id.
2768      * @return int
2769      */
2770     public static function add_competency_to_plan($planid, $competencyid) {
2771         $params = self::validate_parameters(self::add_competency_to_plan_parameters(),
2772                                             array(
2773                                                 'planid' => $planid,
2774                                                 'competencyid' => $competencyid,
2775                                             ));
2777         $plan = api::read_plan($params['planid']);
2778         self::validate_context($plan->get_context());
2780         return api::add_competency_to_plan($params['planid'], $params['competencyid']);
2781     }
2783     /**
2784      * Returns description of add_competency_to_plan() result value.
2785      *
2786      * @return \external_description
2787      */
2788     public static function add_competency_to_plan_returns() {
2789         return new external_value(PARAM_BOOL, 'True if successful.');
2790     }
2792     /**
2793      * Returns description of remove_competency_from_plan() parameters.
2794      *
2795      * @return \external_function_parameters
2796      */
2797     public static function remove_competency_from_plan_parameters() {
2798         $planid = new external_value(
2799             PARAM_INT,
2800             'The plan id',
2801             VALUE_REQUIRED
2802         );
2803         $competencyid = new external_value(
2804             PARAM_INT,
2805             'The competency id',
2806             VALUE_REQUIRED
2807         );
2808         $params = array(
2809             'planid' => $planid,
2810             'competencyid' => $competencyid,
2811         );
2812         return new external_function_parameters($params);
2813     }
2815     /**
2816      * Remove a competency from plan.
2817      *
2818      * @param int $planid Plan id.
2819      * @param int $competencyid Competency id.
2820      * @return int
2821      */
2822     public static function remove_competency_from_plan($planid, $competencyid) {
2823         $params = self::validate_parameters(self::remove_competency_from_plan_parameters(),
2824                                             array(
2825                                                 'planid' => $planid,
2826                                                 'competencyid' => $competencyid,
2827                                             ));
2828         $plan = api::read_plan($params['planid']);
2829         self::validate_context($plan->get_context());
2831         return api::remove_competency_from_plan($params['planid'], $params['competencyid']);
2832     }
2834     /**
2835      * Returns description of remove_competency_from_plan() result value.
2836      *
2837      * @return \external_description
2838      */
2839     public static function remove_competency_from_plan_returns() {
2840         return new external_value(PARAM_BOOL, 'True if successful.');
2841     }
2843     /**
2844      * Returns description of remove_competency_from_template() parameters.
2845      *
2846      * @return \external_function_parameters
2847      */
2848     public static function remove_competency_from_template_parameters() {
2849         $templateid = new external_value(
2850             PARAM_INT,
2851             'The template id',
2852             VALUE_REQUIRED
2853         );
2854         $competencyid = new external_value(
2855             PARAM_INT,
2856             'The competency id',
2857             VALUE_REQUIRED
2858         );
2859         $params = array(
2860             'templateid' => $templateid,
2861             'competencyid' => $competencyid,
2862         );
2863         return new external_function_parameters($params);
2864     }
2866     /**
2867      * Returns description of reorder_plan_competency() parameters.
2868      *
2869      * @return \external_function_parameters
2870      */
2871     public static function reorder_plan_competency_parameters() {
2872         $planid = new external_value(
2873             PARAM_INT,
2874             'The plan id',
2875             VALUE_REQUIRED
2876         );
2877         $competencyidfrom = new external_value(
2878             PARAM_INT,
2879             'The competency id we are moving',
2880             VALUE_REQUIRED
2881         );
2882         $competencyidto = new external_value(
2883             PARAM_INT,
2884             'The competency id we are moving to',
2885             VALUE_REQUIRED
2886         );
2887         $params = array(
2888             'planid' => $planid,
2889             'competencyidfrom' => $competencyidfrom,
2890             'competencyidto' => $competencyidto,
2891         );
2892         return new external_function_parameters($params);
2893     }
2895     /**
2896      * Change the order of plan competencies.
2897      *
2898      * @param int $planid The plan id
2899      * @param int $competencyidfrom The competency to move.
2900      * @param int $competencyidto The competency to move to.
2901      * @return bool
2902      */
2903     public static function reorder_plan_competency($planid, $competencyidfrom, $competencyidto) {
2904         $params = self::validate_parameters(self::reorder_plan_competency_parameters(),
2905             array(
2906                 'planid' => $planid,
2907                 'competencyidfrom' => $competencyidfrom,
2908                 'competencyidto' => $competencyidto,
2909             ));
2911         $plan = api::read_plan($params['planid']);
2912         self::validate_context($plan->get_context());
2914         return api::reorder_plan_competency($params['planid'], $params['competencyidfrom'], $params['competencyidto']);
2915     }
2917     /**
2918      * Returns description of reorder_plan_competency() result value.
2919      *
2920      * @return \external_description
2921      */
2922     public static function reorder_plan_competency_returns() {
2923         return new external_value(PARAM_BOOL, 'True if successful.');
2924     }
2926     /**
2927      * Returns description of external function parameters.
2928      *
2929      * @return \external_function_parameters
2930      */
2931     public static function user_competency_cancel_review_request_parameters() {
2932         return new external_function_parameters(array(
2933             'userid' => new external_value(PARAM_INT, 'The user ID'),
2934             'competencyid' => new external_value(PARAM_INT, 'The competency ID'),
2935         ));
2936     }
2938     /**
2939      * External function user_competency_cancel_review_request.
2940      *
2941      * @param int $userid The user ID.
2942      * @param int $competencyid The competency ID.
2943      * @return boolean
2944      */
2945     public static function user_competency_cancel_review_request($userid, $competencyid) {
2946         $params = self::validate_parameters(self::user_competency_cancel_review_request_parameters(), array(
2947             'userid' => $userid,
2948             'competencyid' => $competencyid
2949         ));
2951         $context = context_user::instance($params['userid']);
2952         self::validate_context($context);
2954         return api::user_competency_cancel_review_request($userid, $competencyid);
2955     }
2957     /**
2958      * Returns description of external function result value.
2959      *
2960      * @return \external_function_parameters
2961      */
2962     public static function user_competency_cancel_review_request_returns() {
2963         return new external_value(PARAM_BOOL, 'The success');
2964     }
2966     /**
2967      * Returns description of external function parameters.
2968      *
2969      * @return \external_function_parameters
2970      */
2971     public static function user_competency_request_review_parameters() {
2972         return new external_function_parameters(array(
2973             'userid' => new external_value(PARAM_INT, 'The user ID'),
2974             'competencyid' => new external_value(PARAM_INT, 'The competency ID'),
2975         ));
2976     }
2978     /**
2979      * External function user_competency_request_review.
2980      *
2981      * @param int $userid The user ID.
2982      * @param int $competencyid The competency ID.
2983      * @return boolean
2984      */
2985     public static function user_competency_request_review($userid, $competencyid) {
2986         $params = self::validate_parameters(self::user_competency_request_review_parameters(), array(
2987             'userid' => $userid,
2988             'competencyid' => $competencyid,
2989         ));
2991         $context = context_user::instance($params['userid']);
2992         self::validate_context($context);
2994         return api::user_competency_request_review($userid, $competencyid);
2995     }
2997     /**
2998      * Returns description of external function result value.
2999      *
3000      * @return \external_function_parameters
3001      */
3002     public static function user_competency_request_review_returns() {
3003         return new external_value(PARAM_BOOL, 'The success');
3004     }
3006     /**
3007      * Returns description of external function parameters.
3008      *
3009      * @return \external_function_parameters
3010      */
3011     public static function user_competency_start_review_parameters() {
3012         return new external_function_parameters(array(
3013             'userid' => new external_value(PARAM_INT, 'The user ID'),
3014             'competencyid' => new external_value(PARAM_INT, 'The competency ID'),
3015         ));
3016     }
3018     /**
3019      * External function user_competency_start_review.
3020      *
3021      * @param int $userid The user ID.
3022      * @param int $competencyid The competency ID.
3023      * @return boolean
3024      */
3025     public static function user_competency_start_review($userid, $competencyid) {
3026         $params = self::validate_parameters(self::user_competency_start_review_parameters(), array(
3027             'userid' => $userid,
3028             'competencyid' => $competencyid
3029         ));
3031         $context = context_user::instance($params['userid']);
3032         self::validate_context($context);
3034         return api::user_competency_start_review($userid, $competencyid);
3035     }
3037     /**
3038      * Returns description of external function result value.
3039      *
3040      * @return \external_function_parameters
3041      */
3042     public static function user_competency_start_review_returns() {
3043         return new external_value(PARAM_BOOL, 'The success');
3044     }
3046     /**
3047      * Returns description of external function parameters.
3048      *
3049      * @return \external_function_parameters
3050      */
3051     public static function user_competency_stop_review_parameters() {
3052         return new external_function_parameters(array(
3053             'userid' => new external_value(PARAM_INT, 'The user ID'),
3054             'competencyid' => new external_value(PARAM_INT, 'The competency ID'),
3055         ));
3056     }
3058     /**
3059      * External function user_competency_stop_review.
3060      *
3061      * @param int $userid The user ID.
3062      * @param int $competencyid The competency ID.
3063      * @return boolean
3064      */
3065     public static function user_competency_stop_review($userid, $competencyid) {
3066         $params = self::validate_parameters(self::user_competency_stop_review_parameters(), array(
3067             'userid' => $userid,
3068             'competencyid' => $competencyid
3069         ));
3071         $context = context_user::instance($params['userid']);
3072         self::validate_context($context);
3074         return api::user_competency_stop_review($userid, $competencyid);
3075     }
3077     /**
3078      * Returns description of external function result value.
3079      *
3080      * @return \external_function_parameters
3081      */
3082     public static function user_competency_stop_review_returns() {
3083         return new external_value(PARAM_BOOL, 'The success');
3084     }
3086     /**
3087      * Returns description of template_has_related_data() parameters.
3088      *
3089      * @return \external_function_parameters
3090      */
3091     public static function template_has_related_data_parameters() {
3092         $templateid = new external_value(
3093             PARAM_INT,
3094             'The template id',
3095             VALUE_REQUIRED
3096         );
3097         $params = array(
3098             'id' => $templateid,
3099         );
3100         return new external_function_parameters($params);
3101     }
3103     /**
3104      * Check if template has related data.
3105      *
3106      * @param int $templateid Template id.
3107      * @return boolean
3108      */
3109     public static function template_has_related_data($templateid) {
3110         $params = self::validate_parameters(self::template_has_related_data_parameters(),
3111                                             array(
3112                                                 'id' => $templateid,
3113                                             ));
3115         $template = api::read_template($params['id']);
3116         self::validate_context($template->get_context());
3118         return api::template_has_related_data($params['id']);
3119     }
3121     /**
3122      * Returns description of template_has_related_data() result value.
3123      *
3124      * @return \external_description
3125      */
3126     public static function template_has_related_data_returns() {
3127         return new external_value(PARAM_BOOL, 'True if the template has related data');
3128     }
3130     /**
3131      * Count the competencies (visible to this user) in this learning plan template.
3132      *
3133      * @param int $templateid Template id.
3134      * @param int $competencyid Competency id.
3135      * @return int
3136      */
3137     public static function remove_competency_from_template($templateid, $competencyid) {
3138         $params = self::validate_parameters(self::remove_competency_from_template_parameters(),
3139                                             array(
3140                                                 'templateid' => $templateid,
3141                                                 'competencyid' => $competencyid,
3142                                             ));
3143         $template = api::read_template($params['templateid']);
3144         self::validate_context($template->get_context());
3146         return api::remove_competency_from_template($params['templateid'], $params['competencyid']);
3147     }
3149     /**
3150      * Returns description of remove_competency_from_template() result value.
3151      *
3152      * @return \external_description
3153      */
3154     public static function remove_competency_from_template_returns() {
3155         return new external_value(PARAM_BOOL, 'True if successful.');
3156     }
3158     /**
3159      * Returns description of data_for_template_competenies_page() parameters.
3160      *
3161      * @return \external_function_parameters
3162      */
3163     public static function data_for_template_competencies_page_parameters() {
3164         $templateid = new external_value(
3165             PARAM_INT,
3166             'The template id',
3167             VALUE_REQUIRED
3168         );
3169         $params = array('templateid' => $templateid, 'pagecontext' => self::get_context_parameters());
3170         return new external_function_parameters($params);
3171     }
3173     /**
3174      * Loads the data required to render the template_competencies_page template.
3175      *
3176      * @param int $templateid Template id.
3177      * @param array $pagecontext The page context info.
3178      * @return boolean
3179      */
3180     public static function data_for_template_competencies_page($templateid, $pagecontext) {
3181         global $PAGE;
3182         $params = self::validate_parameters(self::data_for_template_competencies_page_parameters(),
3183                                             array(
3184                                                 'templateid' => $templateid,
3185                                                 'pagecontext' => $pagecontext
3186                                             ));
3188         $context = self::get_context_from_params($params['pagecontext']);
3189         self::validate_context($context);
3191         $renderable = new output\template_competencies_page($params['templateid'], $context);
3192         $renderer = $PAGE->get_renderer('tool_lp');
3194         $data = $renderable->export_for_template($renderer);
3196         return $data;
3197     }
3199     /**
3200      * Returns description of data_for_template_competencies_page() result value.
3201      *
3202      * @return \external_description
3203      */
3204     public static function data_for_template_competencies_page_returns() {
3205         return new external_single_structure(array (
3206             'templateid' => new external_value(PARAM_INT, 'The current template id'),
3207             'pagecontextid' => new external_value(PARAM_INT, 'Context ID'),
3208             'canmanagecompetencyframeworks' => new external_value(PARAM_BOOL, 'User can manage competency frameworks'),
3209             'canmanagetemplatecompetencies' => new external_value(PARAM_BOOL, 'User can manage learning plan templates'),
3210             'competencies' => new external_multiple_structure(
3211                 competency_summary_exporter::get_read_structure()
3212             ),
3213             'manageurl' => new external_value(PARAM_LOCALURL, 'Url to the manage competencies page.'),
3214             'statistics' => template_statistics_exporter::get_read_structure()
3215         ));
3217     }
3219     /**
3220      * Returns description of data_for_plan_competenies_page() parameters.
3221      *
3222      * @return \external_function_parameters
3223      */
3224     public static function data_for_plan_page_parameters() {
3225         $planid = new external_value(
3226             PARAM_INT,
3227             'The plan id',
3228             VALUE_REQUIRED
3229         );
3230         $params = array('planid' => $planid);
3231         return new external_function_parameters($params);
3232     }
3234     /**
3235      * Loads the data required to render the plan_page template.
3236      *
3237      * @param int $planid Learning Plan id.
3238      * @return boolean
3239      */
3240     public static function data_for_plan_page($planid) {
3241         global $PAGE;
3242         $params = self::validate_parameters(self::data_for_plan_page_parameters(),
3243                                             array(
3244                                                 'planid' => $planid
3245                                             ));
3246         $plan = api::read_plan($params['planid']);
3247         self::validate_context($plan->get_context());
3249         $renderable = new output\plan_page($plan);
3250         $renderer = $PAGE->get_renderer('tool_lp');
3252         $data = $renderable->export_for_template($renderer);
3254         return $data;
3255     }
3257     /**
3258      * Returns description of data_for_plan_page() result value.
3259      *
3260      * @return \external_description
3261      */
3262     public static function data_for_plan_page_returns() {
3263         $uc = user_competency_exporter::get_read_structure();
3264         $ucp = user_competency_plan_exporter::get_read_structure();
3266         $uc->required = VALUE_OPTIONAL;
3267         $ucp->required = VALUE_OPTIONAL;
3269         return new external_single_structure(array (
3270             'plan' => plan_exporter::get_read_structure(),
3271             'contextid' => new external_value(PARAM_INT, 'Context ID.'),
3272             'pluginbaseurl' => new external_value(PARAM_URL, 'Plugin base URL.'),
3273             'competencies' => new external_multiple_structure(
3274                 new external_single_structure(array(
3275                     'competency' => competency_exporter::get_read_structure(),
3276                     'comppath' => competency_path_exporter::get_read_structure(),
3277                     'usercompetency' => $uc,
3278                     'usercompetencyplan' => $ucp
3279                 ))
3280             )
3281         ));
3282     }
3284     /**
3285      * Returns description of create_plan() parameters.
3286      *
3287      * @return \external_function_parameters
3288      */
3289     public static function create_plan_parameters() {
3290         $structure = plan_exporter::get_create_structure();
3291         $params = array('plan' => $structure);
3292         return new external_function_parameters($params);
3293     }
3295     /**
3296      * Create a new learning plan.
3297      *
3298      * @param array $plan List of fields for the plan.
3299      * @return array New plan record.
3300      */
3301     public static function create_plan($plan) {
3302         global $PAGE;
3304         $params = self::validate_parameters(self::create_plan_parameters(),
3305                                             array('plan' => $plan));
3306         $params = $params['plan'];
3308         $context = context_user::instance($params['userid']);
3309         self::validate_context($context);
3310         $output = $PAGE->get_renderer('tool_lp');
3312         $params = (object) $params;
3314         $result = api::create_plan($params);
3315         $exporter = new plan_exporter($result, array('template' => null));
3316         return $exporter->export($output);
3317     }
3319     /**
3320      * Returns description of create_plan() result value.
3321      *
3322      * @return \external_description
3323      */
3324     public static function create_plan_returns() {
3325         return plan_exporter::get_read_structure();
3326     }
3328     /**
3329      * Returns description of update_plan() parameters.
3330      *
3331      * @return \external_function_parameters
3332      */
3333     public static function update_plan_parameters() {
3334         $structure = plan_exporter::get_update_structure();
3335         $params = array('plan' => $structure);
3336         return new external_function_parameters($params);
3337     }
3339     /**
3340      * Updates a new learning plan.
3341      *
3342      * @param array $plan Fields for the plan (id is required)
3343      * @return mixed
3344      */
3345     public static function update_plan($plan) {
3346         global $PAGE;
3348         $params = self::validate_parameters(self::update_plan_parameters(),
3349                                             array('plan' => $plan));
3351         $params = $params['plan'];
3353         $plan = api::read_plan($params['id']);
3354         self::validate_context($plan->get_context());
3355         $output = $PAGE->get_renderer('tool_lp');
3357         $params = (object) $params;
3358         $result = api::update_plan($params);
3359         $exporter = plan_exporter($result);
3360         $record = $exporter->export($output);
3361         return external_api::clean_returnvalue(self::update_plan_returns(), $record);
3362     }
3364     /**
3365      * Returns description of update_plan() result value.
3366      *
3367      * @return \external_description
3368      */
3369     public static function update_plan_returns() {
3370         return plan_exporter::get_read_structure();
3371     }
3373     /**
3374      * Returns description of complete_plan() parameters.
3375      *
3376      * @return \external_function_parameters
3377      */
3378     public static function complete_plan_parameters() {
3379         $planid = new external_value(
3380             PARAM_INT,
3381             'The plan id',
3382             VALUE_REQUIRED
3383         );
3384         $params = array('planid' => $planid);
3385         return new external_function_parameters($params);
3386     }
3388     /**
3389      * Complete Learning plan.
3390      *
3391      * @param int $planid plan id (id is required)
3392      * @return boolean
3393      */
3394     public static function complete_plan($planid) {
3395         $params = self::validate_parameters(self::complete_plan_parameters(),
3396                                             array(
3397                                                 'planid' => $planid
3398                                             ));
3400         return api::complete_plan($params['planid']);
3401     }
3403     /**
3404      * Returns description of complete_plan() result value.
3405      *
3406      * @return \external_description
3407      */
3408     public static function complete_plan_returns() {
3409         return new external_value(PARAM_BOOL, 'True if completing learning plan was successful');
3410     }
3412     /**
3413      * Returns description of reopen_plan() parameters.
3414      *
3415      * @return \external_function_parameters
3416      */
3417     public static function reopen_plan_parameters() {
3418         $planid = new external_value(
3419             PARAM_INT,
3420             'The plan id',
3421             VALUE_REQUIRED
3422         );
3423         $params = array('planid' => $planid);
3424         return new external_function_parameters($params);
3425     }
3427     /**
3428      * Reopen Learning plan.
3429      *
3430      * @param int $planid plan id (id is required)
3431      * @return boolean
3432      */
3433     public static function reopen_plan($planid) {
3434         $params = self::validate_parameters(self::reopen_plan_parameters(),
3435                                             array(
3436                                                 'planid' => $planid
3437                                             ));
3439         return api::reopen_plan($params['planid']);
3440     }
3442     /**
3443      * Returns description of reopen_plan() result value.
3444      *
3445      * @return \external_description
3446      */
3447     public static function reopen_plan_returns() {
3448         return new external_value(PARAM_BOOL, 'True if reopening learning plan was successful');
3449     }
3451     /**
3452      * Returns description of read_plan() parameters.
3453      *
3454      * @return \external_function_parameters
3455      */
3456     public static function read_plan_parameters() {
3457         $id = new external_value(
3458             PARAM_INT,
3459             'Data base record id for the plan',
3460             VALUE_REQUIRED
3461         );
3462         return new external_function_parameters(array('id' => $id));
3463     }
3465     /**
3466      * Read a plan by id.
3467      *
3468      * @param int $id The id of the plan.
3469      * @return \stdClass
3470      */
3471     public static function read_plan($id) {
3472         global $PAGE;
3474         $params = self::validate_parameters(self::read_plan_parameters(),
3475                                             array(
3476                                                 'id' => $id,
3477                                             ));
3479         $plan = api::read_plan($params['id']);
3480         self::validate_context($plan->get_context());
3481         $output = $PAGE->get_renderer('tool_lp');
3483         $exporter = new plan_exporter($plan, array('template' => $plan->get_template()));
3484         $record = $exporter->export($output);
3485         return external_api::clean_returnvalue(self::read_plan_returns(), $record);
3486     }
3488     /**
3489      * Returns description of read_plan() result value.
3490      *
3491      * @return \external_description
3492      */
3493     public static function read_plan_returns() {
3494         return plan_exporter::get_read_structure();
3495     }
3497     /**
3498      * Returns description of delete_plan() parameters.
3499      *
3500      * @return \external_function_parameters
3501      */
3502     public static function delete_plan_parameters() {
3503         $id = new external_value(
3504             PARAM_INT,
3505             'Data base record id for the learning plan',
3506             VALUE_REQUIRED
3507         );
3509         $params = array(
3510             'id' => $id,
3511         );
3512         return new external_function_parameters($params);
3513     }
3515     /**
3516      * Delete a plan.
3517      *
3518      * @param int $id The plan id
3519      * @return boolean
3520      */
3521     public static function delete_plan($id) {
3522         $params = self::validate_parameters(self::delete_plan_parameters(),
3523                                             array(
3524                                                 'id' => $id,
3525                                             ));
3527         $plan = api::read_plan($params['id']);
3528         self::validate_context($plan->get_context());
3530         return external_api::clean_returnvalue(self::delete_plan_returns(), api::delete_plan($params['id']));
3531     }
3533     /**
3534      * Returns description of delete_plan() result value.
3535      *
3536      * @return \external_description
3537      */
3538     public static function delete_plan_returns() {
3539         return new external_value(PARAM_BOOL, 'True if the delete was successful');
3540     }
3542     /**
3543      * Returns description of external function parameters.
3544      *
3545      * @return \external_function_parameters
3546      */
3547     public static function plan_cancel_review_request_parameters() {
3548         return new external_function_parameters(array(
3549             'id' => new external_value(PARAM_INT, 'The plan ID'),
3550         ));
3551     }
3553     /**
3554      * External function plan_cancel_review_request.
3555      *
3556      * @param int $id The plan ID.
3557      * @return boolean
3558      */
3559     public static function plan_cancel_review_request($id) {
3560         $params = self::validate_parameters(self::plan_cancel_review_request_parameters(), array(
3561             'id' => $id
3562         ));
3564         $plan = api::read_plan($id);
3565         self::validate_context($plan->get_context());
3567         return api::plan_cancel_review_request($plan);
3568     }
3570     /**
3571      * Returns description of external function result value.
3572      *
3573      * @return \external_function_parameters
3574      */
3575     public static function plan_cancel_review_request_returns() {
3576         return new external_value(PARAM_BOOL, 'The success');
3577     }
3579     /**
3580      * Returns description of external function parameters.
3581      *
3582      * @return \external_function_parameters
3583      */
3584     public static function plan_request_review_parameters() {
3585         return new external_function_parameters(array(
3586             'id' => new external_value(PARAM_INT, 'The plan ID'),
3587         ));
3588     }
3590     /**
3591      * External function plan_request_review.
3592      *
3593      * @param int $id The plan ID.
3594      * @return boolean
3595      */
3596     public static function plan_request_review($id) {
3597         $params = self::validate_parameters(self::plan_request_review_parameters(), array(
3598             'id' => $id
3599         ));
3601         $plan = api::read_plan($id);
3602         self::validate_context($plan->get_context());
3604         return api::plan_request_review($plan);
3605     }
3607     /**
3608      * Returns description of external function result value.
3609      *
3610      * @return \external_function_parameters
3611      */
3612     public static function plan_request_review_returns() {
3613         return new external_value(PARAM_BOOL, 'The success');
3614     }
3616     /**
3617      * Returns description of external function parameters.
3618      *
3619      * @return \external_function_parameters
3620      */
3621     public static function plan_start_review_parameters() {
3622         return new external_function_parameters(array(
3623             'id' => new external_value(PARAM_INT, 'The plan ID'),
3624         ));
3625     }
3627     /**
3628      * External function plan_start_review.
3629      *
3630      * @param int $id The plan ID.
3631      * @return boolean
3632      */
3633     public static function plan_start_review($id) {
3634         $params = self::validate_parameters(self::plan_start_review_parameters(), array(
3635             'id' => $id
3636         ));
3638         $plan = api::read_plan($id);
3639         self::validate_context($plan->get_context());
3641         return api::plan_start_review($plan);
3642     }
3644     /**
3645      * Returns description of external function result value.
3646      *
3647      * @return \external_function_parameters
3648      */
3649     public static function plan_start_review_returns() {
3650         return new external_value(PARAM_BOOL, 'The success');
3651     }
3653     /**
3654      * Returns description of external function parameters.
3655      *
3656      * @return \external_function_parameters
3657      */
3658     public static function plan_stop_review_parameters() {
3659         return new external_function_parameters(array(
3660             'id' => new external_value(PARAM_INT, 'The plan ID'),
3661         ));
3662     }
3664     /**
3665      * External function plan_stop_review.
3666      *
3667      * @param int $id The plan ID.
3668      * @return boolean
3669      */
3670     public static function plan_stop_review($id) {
3671         $params = self::validate_parameters(self::plan_stop_review_parameters(), array(
3672             'id' => $id
3673         ));
3675         $plan = api::read_plan($id);
3676         self::validate_context($plan->get_context());
3678         return api::plan_stop_review($plan);
3679     }
3681     /**
3682      * Returns description of external function result value.
3683      *
3684      * @return \external_function_parameters
3685      */
3686     public static function plan_stop_review_returns() {
3687         return new external_value(PARAM_BOOL, 'The success');
3688     }
3690     /**
3691      * Returns description of external function parameters.
3692      *
3693      * @return \external_function_parameters
3694      */
3695     public static function approve_plan_parameters() {
3696         return new external_function_parameters(array(
3697             'id' => new external_value(PARAM_INT, 'The plan ID'),
3698         ));
3699     }
3701     /**
3702      * External function approve_plan.
3703      *
3704      * @param int $id The plan ID.
3705      * @return boolean
3706      */
3707     public static function approve_plan($id) {
3708         $params = self::validate_parameters(self::approve_plan_parameters(), array(
3709             'id' => $id,
3710         ));
3712         $plan = api::read_plan($id);
3713         self::validate_context($plan->get_context());
3715         return api::approve_plan($plan);
3716     }
3718     /**
3719      * Returns description of external function result value.
3720      *
3721      * @return \external_function_parameters
3722      */
3723     public static function approve_plan_returns() {
3724         return new external_value(PARAM_BOOL, 'The success');
3725     }
3727     /**
3728      * Returns description of external function parameters.
3729      *
3730      * @return \external_function_parameters
3731      */
3732     public static function unapprove_plan_parameters() {
3733         return new external_function_parameters(array(
3734             'id' => new external_value(PARAM_INT, 'The plan ID'),
3735         ));
3736     }
3738     /**
3739      * External function unapprove_plan.
3740      *
3741      * @param int $id The plan ID.
3742      * @return boolean
3743      */
3744     public static function unapprove_plan($id) {
3745         $params = self::validate_parameters(self::unapprove_plan_parameters(), array(
3746             'id' => $id,
3747         ));
3749         $plan = api::read_plan($id);
3750         self::validate_context($plan->get_context());
3752         return api::unapprove_plan($plan);
3753     }
3755     /**
3756      * Returns description of external function result value.
3757      *
3758      * @return \external_function_parameters
3759      */
3760     public static function unapprove_plan_returns() {
3761         return new external_value(PARAM_BOOL, 'The success');
3762     }
3764     /**
3765      * Returns description of data_for_plans_page() parameters.
3766      *
3767      * @return \external_function_parameters
3768      */
3769     public static function data_for_plans_page_parameters() {
3770         $userid = new external_value(
3771             PARAM_INT,
3772             'The user id',
3773             VALUE_REQUIRED
3774         );
3775         $params = array('userid' => $userid);
3776         return new external_function_parameters($params);
3777     }
3779     /**
3780      * Loads the data required to render the plans_page template.
3781      *
3782      * @param int $userid User id.
3783      * @return boolean
3784      */
3785     public static function data_for_plans_page($userid) {
3786         global $PAGE;
3788         $params = self::validate_parameters(self::data_for_plans_page_parameters(),
3789                                             array(
3790                                                 'userid' => $userid,
3791                                             ));
3793         $context = context_user::instance($params['userid']);
3794         self::validate_context($context);
3795         $output = $PAGE->get_renderer('tool_lp');
3797         $renderable = new \tool_lp\output\plans_page($params['userid']);
3799         return $renderable->export_for_template($output);
3800     }
3802     /**
3803      * Returns description of data_for_plans_page() result value.
3804      *
3805      * @return \external_description
3806      */
3807     public static function data_for_plans_page_returns() {
3808         return new external_single_structure(array (
3809             'userid' => new external_value(PARAM_INT, 'The learning plan user id'),
3810             'plans' => new external_multiple_structure(
3811                 plan_exporter::get_read_structure()
3812             ),
3813             'pluginbaseurl' => new external_value(PARAM_LOCALURL, 'Url to the tool_lp plugin folder on this Moodle site'),
3814             'navigation' => new external_multiple_structure(
3815                 new external_value(PARAM_RAW, 'HTML for a navigation item that should be on this page')
3816             ),
3817             'canreaduserevidence' => new external_value(PARAM_BOOL, 'Can the current user view the user\'s evidence'),
3818             'canmanageuserplans' => new external_value(PARAM_BOOL, 'Can the current user manage the user\'s plans'),
3819         ));
3820     }
3822     /**
3823      * External function parameters structure.
3824      *
3825      * @return \external_description
3826      */
3827     public static function list_plan_competencies_parameters() {
3828         return new external_function_parameters(array(
3829             'id' => new external_value(PARAM_INT, 'The plan ID.')
3830         ));
3831     }
3833     /**
3834      * List plan competencies.
3835      * @param  int $id The plan ID.
3836      * @return array
3837      */
3838     public static function list_plan_competencies($id) {
3839         global $PAGE;
3841         $params = self::validate_parameters(self::list_plan_competencies_parameters(), array('id' => $id));
3842         $id = $params['id'];
3843         $plan = api::read_plan($id);
3844         $usercontext = $plan->get_context();
3845         self::validate_context($usercontext);
3846         $output = $PAGE->get_renderer('tool_lp');
3848         $result = api::list_plan_competencies($plan);
3850         if ($plan->get_status() == plan::STATUS_COMPLETE) {
3851             $ucproperty = 'usercompetencyplan';
3852         } else {
3853             $ucproperty = 'usercompetency';
3854         }
3856         $contextcache = array();
3857         $scalecache = array();
3859         foreach ($result as $key => $r) {
3860             if (!isset($scalecache[$r->competency->get_competencyframeworkid()])) {
3861                 $scalecache[$r->competency->get_competencyframeworkid()] = $r->competency->get_framework()->get_scale();
3862             }
3863             $scale = $scalecache[$r->competency->get_competencyframeworkid()];
3865             if (!isset($contextcache[$r->competency->get_competencyframeworkid()])) {
3866                 $contextcache[$r->competency->get_competencyframeworkid()] = $r->competency->get_context();
3867             }
3868             $context = $contextcache[$r->competency->get_competencyframeworkid()];
3870             $exporter = new competency_exporter($r->competency, array('context' => $context));
3871             $r->competency = $exporter->export($output);
3873             if ($r->usercompetency) {
3874                 $exporter = new user_competency_exporter($r->usercompetency, array('scale' => $scale));
3875                 $r->usercompetency = $exporter->export($output);
3876                 unset($r->usercompetencyplan);
3877             } else {
3878                 $exporter = new user_competency_plan_exporter($r->usercompetencyplan, array('scale' => $scale));
3879                 $r->usercompetencyplan = $exporter->export($output);
3880                 unset($r->usercompetency);
3881             }
3882         }
3883         return $result;
3884     }
3886     /**
3887      * External function return structure.
3888      *
3889      * @return \external_description
3890      */
3891     public static function list_plan_competencies_returns() {
3892         $uc = user_competency_exporter::get_read_structure();
3893         $ucp = user_competency_plan_exporter::get_read_structure();
3895         $uc->required = VALUE_OPTIONAL;
3896         $ucp->required = VALUE_OPTIONAL;
3898         return new external_multiple_structure(
3899             new external_single_structure(array(
3900                 'competency' => competency_exporter::get_read_structure(),
3901                 'usercompetency' => $uc,
3902                 'usercompetencyplan' => $ucp
3903             ))
3904         );
3905     }
3907     /**
3908      * Returns description of external function parameters.
3909      *
3910      * @return \external_function_parameters
3911      */
3912     public static function list_user_plans_parameters() {
3913         return new external_function_parameters(array(
3914             'userid' => new external_value(PARAM_INT, 'The user ID'),
3915         ));
3916     }
3918     /**
3919      * External function list_user_plans.
3920      *
3921      * @param int $userid The user ID.
3922      * @return boolean
3923      */
3924     public static function list_user_plans($userid) {
3925         global $PAGE;
3926         $params = self::validate_parameters(self::list_user_plans_parameters(), array(
3927             'userid' => $userid
3928         ));
3930         $context = context_user::instance($params['userid']);
3931         self::validate_context($context);
3932         $output = $PAGE->get_renderer('tool_lp');
3934         $response = array();
3935         $plans = api::list_user_plans($params['userid']);
3936         foreach ($plans as $plan) {
3937             $exporter = new plan_exporter($plan, array('template' => $plan->get_template()));
3938             $response[] = $exporter->export($output);
3939         }
3941         return $response;
3942     }
3944     /**
3945      * Returns description of external function result value.
3946      *
3947      * @return \external_function_parameters
3948      */
3949     public static function list_user_plans_returns() {
3950         return new external_multiple_structure(
3951             plan_exporter::get_read_structure()
3952         );
3953     }
3955     /**
3956      * Returns description of external function parameters.
3957      *
3958      * @return \external_description
3959      */
3960     public static function read_user_evidence_parameters() {
3961         return new external_function_parameters(array(
3962             'id' => new external_value(PARAM_INT, 'The user evidence ID.'),
3963         ));
3964     }
3966     /**
3967      * Delete a user evidence.
3968      *
3969      * @param int $id The evidence id
3970      * @return boolean
3971      */
3972     public static function read_user_evidence($id) {
3973         global $PAGE;
3974         $params = self::validate_parameters(self::read_user_evidence_parameters(), array('id' => $id));
3976         $userevidence = api::read_user_evidence($params['id']);
3977         $context = $userevidence->get_context();
3978   &nb