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