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