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