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