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