MDL-65153 competencies: Urls course competencies
[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 core_cohort\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 core_course\external\course_module_summary_exporter;
50 use core_course\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_user\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             'cangradecompetencies' => new external_value(PARAM_BOOL, 'User can grade competencies.'),
408             'settings' => course_competency_settings_exporter::get_read_structure(),
409             'statistics' => course_competency_statistics_exporter::get_read_structure(),
410             'competencies' => new external_multiple_structure(new external_single_structure(array(
411                 'competency' => competency_exporter::get_read_structure(),
412                 'coursecompetency' => course_competency_exporter::get_read_structure(),
413                 'coursemodules' => new external_multiple_structure(course_module_summary_exporter::get_read_structure()),
414                 'usercompetencycourse' => $ucc,
415                 'ruleoutcomeoptions' => new external_multiple_structure(
416                     new external_single_structure(array(
417                         'value' => new external_value(PARAM_INT, 'The option value'),
418                         'text' => new external_value(PARAM_NOTAGS, 'The name of the option'),
419                         'selected' => new external_value(PARAM_BOOL, 'If this is the currently selected option'),
420                     ))
421                 ),
422                 'comppath' => competency_path_exporter::get_read_structure(),
423                 'plans' => new external_multiple_structure(
424                     plan_exporter::get_read_structure()
425                 ),
426             ))),
427             'manageurl' => new external_value(PARAM_LOCALURL, 'Url to the manage competencies page.'),
428             'pluginbaseurl' => new external_value(PARAM_LOCALURL, 'Url to the course competencies page.'),
429         ));
431     }
433     /**
434      * Returns description of data_for_templates_manage_page() parameters.
435      *
436      * @return \external_function_parameters
437      */
438     public static function data_for_templates_manage_page_parameters() {
439         $params = array('pagecontext' => self::get_context_parameters());
440         return new external_function_parameters($params);
441     }
443     /**
444      * Loads the data required to render the templates_manage_page template.
445      *
446      * @param array $pagecontext The page context info.
447      * @return boolean
448      */
449     public static function data_for_templates_manage_page($pagecontext) {
450         global $PAGE;
452         $params = self::validate_parameters(self::data_for_templates_manage_page_parameters(), array(
453             'pagecontext' => $pagecontext
454         ));
455         $context = self::get_context_from_params($params['pagecontext']);
456         self::validate_context($context);
458         $renderable = new output\manage_templates_page($context);
459         $renderer = $PAGE->get_renderer('tool_lp');
461         $data = $renderable->export_for_template($renderer);
463         return $data;
464     }
466     /**
467      * Returns description of data_for_templates_manage_page() result value.
468      *
469      * @return \external_description
470      */
471     public static function data_for_templates_manage_page_returns() {
472         return new external_single_structure(array (
473             'templates' => new external_multiple_structure(
474                 template_exporter::get_read_structure()
475             ),
476             'pluginbaseurl' => new external_value(PARAM_LOCALURL, 'Url to the tool_lp plugin folder on this Moodle site'),
477             'navigation' => new external_multiple_structure(
478                 new external_value(PARAM_RAW, 'HTML for a navigation item that should be on this page')
479             ),
480             'pagecontextid' => new external_value(PARAM_INT, 'The page context id'),
481             'canmanage' => new external_value(PARAM_BOOL, 'Whether the user manage the templates')
482         ));
484     }
486     /**
487      * Returns description of data_for_template_competenies_page() parameters.
488      *
489      * @return \external_function_parameters
490      */
491     public static function data_for_template_competencies_page_parameters() {
492         $templateid = new external_value(
493             PARAM_INT,
494             'The template id',
495             VALUE_REQUIRED
496         );
497         $params = array('templateid' => $templateid, 'pagecontext' => self::get_context_parameters());
498         return new external_function_parameters($params);
499     }
501     /**
502      * Loads the data required to render the template_competencies_page template.
503      *
504      * @param int $templateid Template id.
505      * @param array $pagecontext The page context info.
506      * @return boolean
507      */
508     public static function data_for_template_competencies_page($templateid, $pagecontext) {
509         global $PAGE;
510         $params = self::validate_parameters(self::data_for_template_competencies_page_parameters(), array(
511             'templateid' => $templateid,
512             'pagecontext' => $pagecontext
513         ));
515         $context = self::get_context_from_params($params['pagecontext']);
516         self::validate_context($context);
518         $template = api::read_template($params['templateid']);
519         $renderable = new output\template_competencies_page($template, $context);
520         $renderer = $PAGE->get_renderer('tool_lp');
522         $data = $renderable->export_for_template($renderer);
524         return $data;
525     }
527     /**
528      * Returns description of data_for_template_competencies_page() result value.
529      *
530      * @return \external_description
531      */
532     public static function data_for_template_competencies_page_returns() {
533         return new external_single_structure(array (
534             'template' => template_exporter::get_read_structure(),
535             'pagecontextid' => new external_value(PARAM_INT, 'Context ID'),
536             'canmanagecompetencyframeworks' => new external_value(PARAM_BOOL, 'User can manage competency frameworks'),
537             'canmanagetemplatecompetencies' => new external_value(PARAM_BOOL, 'User can manage learning plan templates'),
538             'competencies' => new external_multiple_structure(
539                 competency_summary_exporter::get_read_structure()
540             ),
541             'manageurl' => new external_value(PARAM_LOCALURL, 'Url to the manage competencies page.'),
542             'pluginbaseurl' => new external_value(PARAM_LOCALURL, 'Base URL of the plugin.'),
543             'statistics' => template_statistics_exporter::get_read_structure()
544         ));
546     }
548     /**
549      * Returns description of data_for_plan_competenies_page() parameters.
550      *
551      * @return \external_function_parameters
552      */
553     public static function data_for_plan_page_parameters() {
554         $planid = new external_value(
555             PARAM_INT,
556             'The plan id',
557             VALUE_REQUIRED
558         );
559         $params = array('planid' => $planid);
560         return new external_function_parameters($params);
561     }
563     /**
564      * Loads the data required to render the plan_page template.
565      *
566      * @param int $planid Learning Plan id.
567      * @return boolean
568      */
569     public static function data_for_plan_page($planid) {
570         global $PAGE;
571         $params = self::validate_parameters(self::data_for_plan_page_parameters(), array(
572             'planid' => $planid
573         ));
574         $plan = api::read_plan($params['planid']);
575         self::validate_context($plan->get_context());
577         $renderable = new output\plan_page($plan);
578         $renderer = $PAGE->get_renderer('tool_lp');
580         $data = $renderable->export_for_template($renderer);
582         return $data;
583     }
585     /**
586      * Returns description of data_for_plan_page() result value.
587      *
588      * @return \external_description
589      */
590     public static function data_for_plan_page_returns() {
591         $uc = user_competency_exporter::get_read_structure();
592         $ucp = user_competency_plan_exporter::get_read_structure();
594         $uc->required = VALUE_OPTIONAL;
595         $ucp->required = VALUE_OPTIONAL;
597         return new external_single_structure(array (
598             'plan' => plan_exporter::get_read_structure(),
599             'contextid' => new external_value(PARAM_INT, 'Context ID.'),
600             'pluginbaseurl' => new external_value(PARAM_URL, 'Plugin base URL.'),
601             'competencies' => new external_multiple_structure(
602                 new external_single_structure(array(
603                     'competency' => competency_exporter::get_read_structure(),
604                     'comppath' => competency_path_exporter::get_read_structure(),
605                     'usercompetency' => $uc,
606                     'usercompetencyplan' => $ucp
607                 ))
608             ),
609             'competencycount' => new external_value(PARAM_INT, 'Count of competencies'),
610             'proficientcompetencycount' => new external_value(PARAM_INT, 'Count of proficientcompetencies'),
611             'proficientcompetencypercentage' => new external_value(PARAM_FLOAT, 'Percentage of competencies proficient'),
612             'proficientcompetencypercentageformatted' => new external_value(PARAM_RAW, 'Displayable percentage'),
613         ));
614     }
616     /**
617      * Returns description of data_for_plans_page() parameters.
618      *
619      * @return \external_function_parameters
620      */
621     public static function data_for_plans_page_parameters() {
622         $userid = new external_value(
623             PARAM_INT,
624             'The user id',
625             VALUE_REQUIRED
626         );
627         $params = array('userid' => $userid);
628         return new external_function_parameters($params);
629     }
631     /**
632      * Loads the data required to render the plans_page template.
633      *
634      * @param int $userid User id.
635      * @return boolean
636      */
637     public static function data_for_plans_page($userid) {
638         global $PAGE;
640         $params = self::validate_parameters(self::data_for_plans_page_parameters(), array(
641             'userid' => $userid,
642         ));
644         $context = context_user::instance($params['userid']);
645         self::validate_context($context);
646         $output = $PAGE->get_renderer('tool_lp');
648         $renderable = new \tool_lp\output\plans_page($params['userid']);
650         return $renderable->export_for_template($output);
651     }
653     /**
654      * Returns description of data_for_plans_page() result value.
655      *
656      * @return \external_description
657      */
658     public static function data_for_plans_page_returns() {
659         return new external_single_structure(array (
660             'userid' => new external_value(PARAM_INT, 'The learning plan user id'),
661             'plans' => new external_multiple_structure(
662                 plan_exporter::get_read_structure()
663             ),
664             'pluginbaseurl' => new external_value(PARAM_LOCALURL, 'Url to the tool_lp plugin folder on this Moodle site'),
665             'navigation' => new external_multiple_structure(
666                 new external_value(PARAM_RAW, 'HTML for a navigation item that should be on this page')
667             ),
668             'canreaduserevidence' => new external_value(PARAM_BOOL, 'Can the current user view the user\'s evidence'),
669             'canmanageuserplans' => new external_value(PARAM_BOOL, 'Can the current user manage the user\'s plans'),
670         ));
671     }
673     /**
674      * Returns description of external function parameters.
675      *
676      * @return \external_function_parameters
677      */
678     public static function data_for_user_evidence_list_page_parameters() {
679         return new external_function_parameters(array(
680             'userid' => new external_value(PARAM_INT, 'The user ID')
681         ));
682     }
684     /**
685      * Loads the data required to render the user_evidence_list_page template.
686      *
687      * @param int $userid User id.
688      * @return boolean
689      */
690     public static function data_for_user_evidence_list_page($userid) {
691         global $PAGE;
692         $params = self::validate_parameters(self::data_for_user_evidence_list_page_parameters(),
693             array('userid' => $userid));
695         $context = context_user::instance($params['userid']);
696         self::validate_context($context);
697         $output = $PAGE->get_renderer('tool_lp');
699         $renderable = new \tool_lp\output\user_evidence_list_page($params['userid']);
700         return $renderable->export_for_template($output);
701     }
703     /**
704      * Returns description of external function result value.
705      *
706      * @return \external_description
707      */
708     public static function data_for_user_evidence_list_page_returns() {
709         return new external_single_structure(array (
710             'canmanage' => new external_value(PARAM_BOOL, 'Can the current user manage the user\'s evidence'),
711             'userid' => new external_value(PARAM_INT, 'The user ID'),
712             'pluginbaseurl' => new external_value(PARAM_LOCALURL, 'Url to the tool_lp plugin folder on this Moodle site'),
713             'evidence' => new external_multiple_structure(user_evidence_summary_exporter::get_read_structure()),
714             'navigation' => new external_multiple_structure(
715                 new external_value(PARAM_RAW, 'HTML for a navigation item that should be on this page')
716             ),
717         ));
718     }
720     /**
721      * Returns description of external function parameters.
722      *
723      * @return \external_function_parameters
724      */
725     public static function data_for_user_evidence_page_parameters() {
726         return new external_function_parameters(array(
727             'id' => new external_value(PARAM_INT, 'The user evidence ID')
728         ));
729     }
731     /**
732      * Loads the data required to render the user_evidence_page template.
733      *
734      * @param int $id User id.
735      * @return boolean
736      */
737     public static function data_for_user_evidence_page($id) {
738         global $PAGE;
739         $params = self::validate_parameters(self::data_for_user_evidence_page_parameters(),
740             array('id' => $id));
742         $userevidence = api::read_user_evidence($id);
743         self::validate_context($userevidence->get_context());
744         $output = $PAGE->get_renderer('tool_lp');
746         $renderable = new \tool_lp\output\user_evidence_page($userevidence);
747         return $renderable->export_for_template($output);
748     }
750     /**
751      * Returns description of external function result value.
752      *
753      * @return \external_description
754      */
755     public static function data_for_user_evidence_page_returns() {
756         return new external_single_structure(array(
757             'userevidence' => user_evidence_summary_exporter::get_read_structure(),
758             'pluginbaseurl' => new external_value(PARAM_LOCALURL, 'Url to the tool_lp plugin folder on this Moodle site')
759         ));
760     }
762     /**
763      * Returns the description of the data_for_related_competencies_section_parameters() parameters.
764      *
765      * @return external_function_parameters.
766      */
767     public static function data_for_related_competencies_section_parameters() {
768         $competencyid = new external_value(
769             PARAM_INT,
770             'The competency id',
771             VALUE_REQUIRED
772         );
773         return new external_function_parameters(array('competencyid' => $competencyid));
774     }
776     /**
777      * Data to render in the related competencies section.
778      *
779      * @param int $competencyid
780      * @return array Related competencies and whether to show delete action button or not.
781      */
782     public static function data_for_related_competencies_section($competencyid) {
783         global $PAGE;
785         $params = self::validate_parameters(self::data_for_related_competencies_section_parameters(), array(
786             'competencyid' => $competencyid,
787         ));
788         $competency = api::read_competency($params['competencyid']);
789         self::validate_context($competency->get_context());
791         $renderable = new \tool_lp\output\related_competencies($params['competencyid']);
792         $renderer = $PAGE->get_renderer('tool_lp');
794         return $renderable->export_for_template($renderer);
795     }
797     /**
798      * Returns description of data_for_related_competencies_section_returns() result value.
799      *
800      * @return external_description
801      */
802     public static function data_for_related_competencies_section_returns() {
803         return new external_single_structure(array(
804             'relatedcompetencies' => new external_multiple_structure(competency_exporter::get_read_structure()),
805             'showdeleterelatedaction' => new external_value(PARAM_BOOL, 'Whether to show the delete relation link or not')
806         ));
807     }
809     /**
810      * Returns the description of external function parameters.
811      *
812      * @return external_function_parameters.
813      */
814     public static function search_users_parameters() {
815         $query = new external_value(
816             PARAM_RAW,
817             'Query string'
818         );
819         $capability = new external_value(
820             PARAM_RAW,
821             'Required capability'
822         );
823         $limitfrom = new external_value(
824             PARAM_INT,
825             'Number of records to skip',
826             VALUE_DEFAULT,
827             0
828         );
829         $limitnum = new external_value(
830             PARAM_RAW,
831             'Number of records to fetch',
832             VALUE_DEFAULT,
833             100
834         );
835         return new external_function_parameters(array(
836             'query' => $query,
837             'capability' => $capability,
838             'limitfrom' => $limitfrom,
839             'limitnum' => $limitnum
840         ));
841     }
843     /**
844      * Search users.
845      *
846      * @param string $query
847      * @param string $capability
848      * @param int $limitfrom
849      * @param int $limitnum
850      * @return array
851      */
852     public static function search_users($query, $capability = '', $limitfrom = 0, $limitnum = 100) {
853         global $DB, $CFG, $PAGE, $USER;
855         $params = self::validate_parameters(self::search_users_parameters(), array(
856             'query' => $query,
857             'capability' => $capability,
858             'limitfrom' => $limitfrom,
859             'limitnum' => $limitnum,
860         ));
861         $query = $params['query'];
862         $cap = $params['capability'];
863         $limitfrom = $params['limitfrom'];
864         $limitnum = $params['limitnum'];
866         $context = context_system::instance();
867         self::validate_context($context);
868         $output = $PAGE->get_renderer('tool_lp');
870         list($filtercapsql, $filtercapparams) = api::filter_users_with_capability_on_user_context_sql($cap,
871             $USER->id, SQL_PARAMS_NAMED);
873         $extrasearchfields = array();
874         if (!empty($CFG->showuseridentity) && has_capability('moodle/site:viewuseridentity', $context)) {
875             $extrasearchfields = explode(',', $CFG->showuseridentity);
876         }
877         $fields = \user_picture::fields('u', $extrasearchfields);
879         list($wheresql, $whereparams) = users_search_sql($query, 'u', true, $extrasearchfields);
880         list($sortsql, $sortparams) = users_order_by_sql('u', $query, $context);
882         $countsql = "SELECT COUNT('x') FROM {user} u WHERE $wheresql AND u.id $filtercapsql";
883         $countparams = $whereparams + $filtercapparams;
884         $sql = "SELECT $fields FROM {user} u WHERE $wheresql AND u.id $filtercapsql ORDER BY $sortsql";
885         $params = $whereparams + $filtercapparams + $sortparams;
887         $count = $DB->count_records_sql($countsql, $countparams);
888         $result = $DB->get_recordset_sql($sql, $params, $limitfrom, $limitnum);
890         $users = array();
891         foreach ($result as $key => $user) {
892             // Make sure all required fields are set.
893             foreach (user_summary_exporter::define_properties() as $propertykey => $definition) {
894                 if (empty($user->$propertykey) || !in_array($propertykey, $extrasearchfields)) {
895                     if ($propertykey != 'id') {
896                         $user->$propertykey = '';
897                     }
898                 }
899             }
900             $exporter = new user_summary_exporter($user);
901             $newuser = $exporter->export($output);
903             $users[$key] = $newuser;
904         }
905         $result->close();
907         return array(
908             'users' => $users,
909             'count' => $count
910         );
911     }
913     /**
914      * Returns description of external function result value.
915      *
916      * @return external_description
917      */
918     public static function search_users_returns() {
919         global $CFG;
920         require_once($CFG->dirroot . '/user/externallib.php');
921         return new external_single_structure(array(
922             'users' => new external_multiple_structure(user_summary_exporter::get_read_structure()),
923             'count' => new external_value(PARAM_INT, 'Total number of results.')
924         ));
925     }
927     /**
928      * Returns description of external function.
929      *
930      * @return \external_function_parameters
931      */
932     public static function data_for_user_competency_summary_parameters() {
933         $userid = new external_value(
934             PARAM_INT,
935             'Data base record id for the user',
936             VALUE_REQUIRED
937         );
938         $competencyid = new external_value(
939             PARAM_INT,
940             'Data base record id for the competency',
941             VALUE_REQUIRED
942         );
943         $params = array(
944             'userid' => $userid,
945             'competencyid' => $competencyid,
946         );
947         return new external_function_parameters($params);
948     }
950     /**
951      * Data for user competency summary.
952      *
953      * @param int $userid The user ID
954      * @param int $competencyid The competency ID
955      * @return \stdClass
956      */
957     public static function data_for_user_competency_summary($userid, $competencyid) {
958         global $PAGE;
959         $params = self::validate_parameters(self::data_for_user_competency_summary_parameters(), array(
960             'userid' => $userid,
961             'competencyid' => $competencyid,
962         ));
964         $uc = api::get_user_competency($params['userid'], $params['competencyid']);
965         self::validate_context($uc->get_context());
966         $output = $PAGE->get_renderer('tool_lp');
968         $renderable = new \tool_lp\output\user_competency_summary($uc);
969         return $renderable->export_for_template($output);
970     }
972     /**
973      * Returns description of external function.
974      *
975      * @return \external_description
976      */
977     public static function data_for_user_competency_summary_returns() {
978         return user_competency_summary_exporter::get_read_structure();
979     }
981     /**
982      * Returns description of data_for_user_competency_summary_in_plan() parameters.
983      *
984      * @return \external_function_parameters
985      */
986     public static function data_for_user_competency_summary_in_plan_parameters() {
987         $competencyid = new external_value(
988             PARAM_INT,
989             'Data base record id for the competency',
990             VALUE_REQUIRED
991         );
992         $planid = new external_value(
993             PARAM_INT,
994             'Data base record id for the plan',
995             VALUE_REQUIRED
996         );
998         $params = array(
999             'competencyid' => $competencyid,
1000             'planid' => $planid,
1001         );
1002         return new external_function_parameters($params);
1003     }
1005     /**
1006      * Read a user competency summary.
1007      *
1008      * @param int $competencyid The competency id
1009      * @param int $planid The plan id
1010      * @return \stdClass
1011      */
1012     public static function data_for_user_competency_summary_in_plan($competencyid, $planid) {
1013         global $PAGE;
1014         $params = self::validate_parameters(self::data_for_user_competency_summary_in_plan_parameters(), array(
1015             'competencyid' => $competencyid,
1016             'planid' => $planid
1017         ));
1019         $plan = api::read_plan($params['planid']);
1020         $context = $plan->get_context();
1021         self::validate_context($context);
1022         $output = $PAGE->get_renderer('tool_lp');
1024         $renderable = new user_competency_summary_in_plan($params['competencyid'], $params['planid']);
1025         return $renderable->export_for_template($output);
1026     }
1028     /**
1029      * Returns description of data_for_user_competency_summary_in_plan() result value.
1030      *
1031      * @return \external_description
1032      */
1033     public static function data_for_user_competency_summary_in_plan_returns() {
1034         return user_competency_summary_in_plan_exporter::get_read_structure();
1035     }
1037     /**
1038      * Returns description of data_for_user_competency_summary_in_course() parameters.
1039      *
1040      * @return \external_function_parameters
1041      */
1042     public static function data_for_user_competency_summary_in_course_parameters() {
1043         $userid = new external_value(
1044             PARAM_INT,
1045             'Data base record id for the user',
1046             VALUE_REQUIRED
1047         );
1048         $competencyid = new external_value(
1049             PARAM_INT,
1050             'Data base record id for the competency',
1051             VALUE_REQUIRED
1052         );
1053         $courseid = new external_value(
1054             PARAM_INT,
1055             'Data base record id for the course',
1056             VALUE_REQUIRED
1057         );
1059         $params = array(
1060             'userid' => $userid,
1061             'competencyid' => $competencyid,
1062             'courseid' => $courseid,
1063         );
1064         return new external_function_parameters($params);
1065     }
1067     /**
1068      * Read a user competency summary.
1069      *
1070      * @param int $userid The user id
1071      * @param int $competencyid The competency id
1072      * @param int $courseid The course id
1073      * @return \stdClass
1074      */
1075     public static function data_for_user_competency_summary_in_course($userid, $competencyid, $courseid) {
1076         global $PAGE;
1077         $params = self::validate_parameters(self::data_for_user_competency_summary_in_course_parameters(), array(
1078             'userid' => $userid,
1079             'competencyid' => $competencyid,
1080             'courseid' => $courseid
1081         ));
1082         $context = context_user::instance($params['userid']);
1083         self::validate_context($context);
1084         $output = $PAGE->get_renderer('tool_lp');
1086         $renderable = new user_competency_summary_in_course($params['userid'], $params['competencyid'], $params['courseid']);
1087         return $renderable->export_for_template($output);
1088     }
1090     /**
1091      * Returns description of data_for_user_competency_summary_in_course() result value.
1092      *
1093      * @return \external_description
1094      */
1095     public static function data_for_user_competency_summary_in_course_returns() {
1096         return user_competency_summary_in_course_exporter::get_read_structure();
1097     }