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/>.
  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  */
  24 namespace tool_lp;
  25 defined('MOODLE_INTERNAL') || die();
  26
  27 require_once("$CFG->libdir/externallib.php");
  28 require_once("$CFG->libdir/grade/grade_scale.php");
  29
  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;
  44
  45 use tool_lp\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 tool_lp\external\course_module_summary_exporter;
  50 use tool_lp\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;
  58
  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_competency\external\user_summary_exporter;
  70
  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 {
  78
  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
 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     }
 118
 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;
 127
 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);
 136
 137         $renderable = new output\manage_competency_frameworks_page($context);
 138         $renderer = $PAGE->get_renderer('tool_lp');
 139
 140         $data = $renderable->export_for_template($renderer);
 141
 142         return $data;
 143     }
 144
 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         ));
 161
 162     }
 163
 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     }
 187
 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;
 198
 199         $params = self::validate_parameters(self::data_for_competencies_manage_page_parameters(), array(
 200             'competencyframeworkid' => $competencyframeworkid,
 201             'search' => $search
 202         ));
 203
 204         $framework = api::read_framework($params['competencyframeworkid']);
 205         self::validate_context($framework->get_context());
 206         $output = $PAGE->get_renderer('tool_lp');
 207
 208         $renderable = new output\manage_competencies_page($framework, $params['search'], $framework->get_context());
 209
 210         $data = $renderable->export_for_template($output);
 211
 212         return $data;
 213     }
 214
 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         ));
 229
 230     }
 231
 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     }
 262
 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         ));
 279
 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');
 285
 286         $data = $renderable->export_for_template($renderer);
 287
 288         return $data;
 289     }
 290
 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     }
 299
 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     }
 316
 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;
 325
 326         $params = self::validate_parameters(self::list_courses_using_competency_parameters(), array(
 327             'id' => $competencyid,
 328         ));
 329
 330         $competency = api::read_competency($params['id']);
 331         self::validate_context($competency->get_context());
 332         $output = $PAGE->get_renderer('tool_lp');
 333
 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     }
 344
 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     }
 353
 354
 355     /**
 356      * Returns description of data_for_course_competenies_page() parameters.
 357      *
 358      * @return \external_function_parameters
 359      */
 360     public static function data_for_course_competencies_page_parameters() {
 361         $courseid = new external_value(
 362             PARAM_INT,
 363             'The course id',
 364             VALUE_REQUIRED
 365         );
 366         $params = array('courseid' => $courseid);
 367         return new external_function_parameters($params);
 368     }
 369
 370     /**
 371      * Loads the data required to render the course_competencies_page template.
 372      *
 373      * @param int $courseid The course id to check.
 374      * @return boolean
 375      */
 376     public static function data_for_course_competencies_page($courseid) {
 377         global $PAGE;
 378         $params = self::validate_parameters(self::data_for_course_competencies_page_parameters(), array(
 379             'courseid' => $courseid,
 380         ));
 381         self::validate_context(context_course::instance($params['courseid']));
 382
 383         $renderable = new output\course_competencies_page($params['courseid']);
 384         $renderer = $PAGE->get_renderer('tool_lp');
 385
 386         $data = $renderable->export_for_template($renderer);
 387
 388         return $data;
 389     }
 390
 391     /**
 392      * Returns description of data_for_course_competencies_page() result value.
 393      *
 394      * @return \external_description
 395      */
 396     public static function data_for_course_competencies_page_returns() {
 397         $ucc = user_competency_course_exporter::get_read_structure();
 398         $ucc->required = VALUE_OPTIONAL;
 399
 400         return new external_single_structure(array (
 401             'courseid' => new external_value(PARAM_INT, 'The current course id'),
 402             'pagecontextid' => new external_value(PARAM_INT, 'The current page context ID.'),
 403             'gradableuserid' => new external_value(PARAM_INT, 'Current user id, if the user is a gradable user.', VALUE_OPTIONAL),
 404             'canmanagecompetencyframeworks' => new external_value(PARAM_BOOL, 'User can manage competency frameworks'),
 405             'canmanagecoursecompetencies' => new external_value(PARAM_BOOL, 'User can manage linked course competencies'),
 406             'canconfigurecoursecompetencies' => new external_value(PARAM_BOOL, 'User can configure course competency settings'),
 407             'settings' => course_competency_settings_exporter::get_read_structure(),
 408             'statistics' => course_competency_statistics_exporter::get_read_structure(),
 409             'competencies' => new external_multiple_structure(new external_single_structure(array(
 410                 'competency' => competency_exporter::get_read_structure(),
 411                 'coursecompetency' => course_competency_exporter::get_read_structure(),
 412                 'coursemodules' => new external_multiple_structure(course_module_summary_exporter::get_read_structure()),
 413                 'usercompetencycourse' => $ucc,
 414                 'ruleoutcomeoptions' => new external_multiple_structure(
 415                     new external_single_structure(array(
 416                         'value' => new external_value(PARAM_INT, 'The option value'),
 417                         'text' => new external_value(PARAM_NOTAGS, 'The name of the option'),
 418                         'selected' => new external_value(PARAM_BOOL, 'If this is the currently selected option'),
 419                     ))
 420                 ),
 421                 'comppath' => competency_path_exporter::get_read_structure(),
 422             ))),
 423             'manageurl' => new external_value(PARAM_LOCALURL, 'Url to the manage competencies page.'),
 424         ));
 425
 426     }
 427
 428     /**
 429      * Returns description of data_for_templates_manage_page() parameters.
 430      *
 431      * @return \external_function_parameters
 432      */
 433     public static function data_for_templates_manage_page_parameters() {
 434         $params = array('pagecontext' => self::get_context_parameters());
 435         return new external_function_parameters($params);
 436     }
 437
 438     /**
 439      * Loads the data required to render the templates_manage_page template.
 440      *
 441      * @param array $pagecontext The page context info.
 442      * @return boolean
 443      */
 444     public static function data_for_templates_manage_page($pagecontext) {
 445         global $PAGE;
 446
 447         $params = self::validate_parameters(self::data_for_templates_manage_page_parameters(), array(
 448             'pagecontext' => $pagecontext
 449         ));
 450         $context = self::get_context_from_params($params['pagecontext']);
 451         self::validate_context($context);
 452
 453         $renderable = new output\manage_templates_page($context);
 454         $renderer = $PAGE->get_renderer('tool_lp');
 455
 456         $data = $renderable->export_for_template($renderer);
 457
 458         return $data;
 459     }
 460
 461     /**
 462      * Returns description of data_for_templates_manage_page() result value.
 463      *
 464      * @return \external_description
 465      */
 466     public static function data_for_templates_manage_page_returns() {
 467         return new external_single_structure(array (
 468             'templates' => new external_multiple_structure(
 469                 template_exporter::get_read_structure()
 470             ),
 471             'pluginbaseurl' => new external_value(PARAM_LOCALURL, 'Url to the tool_lp plugin folder on this Moodle site'),
 472             'navigation' => new external_multiple_structure(
 473                 new external_value(PARAM_RAW, 'HTML for a navigation item that should be on this page')
 474             ),
 475             'pagecontextid' => new external_value(PARAM_INT, 'The page context id'),
 476             'canmanage' => new external_value(PARAM_BOOL, 'Whether the user manage the templates')
 477         ));
 478
 479     }
 480
 481     /**
 482      * Returns description of data_for_template_competenies_page() parameters.
 483      *
 484      * @return \external_function_parameters
 485      */
 486     public static function data_for_template_competencies_page_parameters() {
 487         $templateid = new external_value(
 488             PARAM_INT,
 489             'The template id',
 490             VALUE_REQUIRED
 491         );
 492         $params = array('templateid' => $templateid, 'pagecontext' => self::get_context_parameters());
 493         return new external_function_parameters($params);
 494     }
 495
 496     /**
 497      * Loads the data required to render the template_competencies_page template.
 498      *
 499      * @param int $templateid Template id.
 500      * @param array $pagecontext The page context info.
 501      * @return boolean
 502      */
 503     public static function data_for_template_competencies_page($templateid, $pagecontext) {
 504         global $PAGE;
 505         $params = self::validate_parameters(self::data_for_template_competencies_page_parameters(), array(
 506             'templateid' => $templateid,
 507             'pagecontext' => $pagecontext
 508         ));
 509
 510         $context = self::get_context_from_params($params['pagecontext']);
 511         self::validate_context($context);
 512
 513         $template = api::read_template($params['templateid']);
 514         $renderable = new output\template_competencies_page($template, $context);
 515         $renderer = $PAGE->get_renderer('tool_lp');
 516
 517         $data = $renderable->export_for_template($renderer);
 518
 519         return $data;
 520     }
 521
 522     /**
 523      * Returns description of data_for_template_competencies_page() result value.
 524      *
 525      * @return \external_description
 526      */
 527     public static function data_for_template_competencies_page_returns() {
 528         return new external_single_structure(array (
 529             'template' => template_exporter::get_read_structure(),
 530             'pagecontextid' => new external_value(PARAM_INT, 'Context ID'),
 531             'canmanagecompetencyframeworks' => new external_value(PARAM_BOOL, 'User can manage competency frameworks'),
 532             'canmanagetemplatecompetencies' => new external_value(PARAM_BOOL, 'User can manage learning plan templates'),
 533             'competencies' => new external_multiple_structure(
 534                 competency_summary_exporter::get_read_structure()
 535             ),
 536             'manageurl' => new external_value(PARAM_LOCALURL, 'Url to the manage competencies page.'),
 537             'pluginbaseurl' => new external_value(PARAM_LOCALURL, 'Base URL of the plugin.'),
 538             'statistics' => template_statistics_exporter::get_read_structure()
 539         ));
 540
 541     }
 542
 543     /**
 544      * Returns description of data_for_plan_competenies_page() parameters.
 545      *
 546      * @return \external_function_parameters
 547      */
 548     public static function data_for_plan_page_parameters() {
 549         $planid = new external_value(
 550             PARAM_INT,
 551             'The plan id',
 552             VALUE_REQUIRED
 553         );
 554         $params = array('planid' => $planid);
 555         return new external_function_parameters($params);
 556     }
 557
 558     /**
 559      * Loads the data required to render the plan_page template.
 560      *
 561      * @param int $planid Learning Plan id.
 562      * @return boolean
 563      */
 564     public static function data_for_plan_page($planid) {
 565         global $PAGE;
 566         $params = self::validate_parameters(self::data_for_plan_page_parameters(), array(
 567             'planid' => $planid
 568         ));
 569         $plan = api::read_plan($params['planid']);
 570         self::validate_context($plan->get_context());
 571
 572         $renderable = new output\plan_page($plan);
 573         $renderer = $PAGE->get_renderer('tool_lp');
 574
 575         $data = $renderable->export_for_template($renderer);
 576
 577         return $data;
 578     }
 579
 580     /**
 581      * Returns description of data_for_plan_page() result value.
 582      *
 583      * @return \external_description
 584      */
 585     public static function data_for_plan_page_returns() {
 586         $uc = user_competency_exporter::get_read_structure();
 587         $ucp = user_competency_plan_exporter::get_read_structure();
 588
 589         $uc->required = VALUE_OPTIONAL;
 590         $ucp->required = VALUE_OPTIONAL;
 591
 592         return new external_single_structure(array (
 593             'plan' => plan_exporter::get_read_structure(),
 594             'contextid' => new external_value(PARAM_INT, 'Context ID.'),
 595             'pluginbaseurl' => new external_value(PARAM_URL, 'Plugin base URL.'),
 596             'competencies' => new external_multiple_structure(
 597                 new external_single_structure(array(
 598                     'competency' => competency_exporter::get_read_structure(),
 599                     'comppath' => competency_path_exporter::get_read_structure(),
 600                     'usercompetency' => $uc,
 601                     'usercompetencyplan' => $ucp
 602                 ))
 603             ),
 604             'competencycount' => new external_value(PARAM_INT, 'Count of competencies'),
 605             'proficientcompetencycount' => new external_value(PARAM_INT, 'Count of proficientcompetencies'),
 606             'proficientcompetencypercentage' => new external_value(PARAM_FLOAT, 'Percentage of competencies proficient'),
 607             'proficientcompetencypercentageformatted' => new external_value(PARAM_RAW, 'Displayable percentage'),
 608         ));
 609     }
 610
 611     /**
 612      * Returns description of data_for_plans_page() parameters.
 613      *
 614      * @return \external_function_parameters
 615      */
 616     public static function data_for_plans_page_parameters() {
 617         $userid = new external_value(
 618             PARAM_INT,
 619             'The user id',
 620             VALUE_REQUIRED
 621         );
 622         $params = array('userid' => $userid);
 623         return new external_function_parameters($params);
 624     }
 625
 626     /**
 627      * Loads the data required to render the plans_page template.
 628      *
 629      * @param int $userid User id.
 630      * @return boolean
 631      */
 632     public static function data_for_plans_page($userid) {
 633         global $PAGE;
 634
 635         $params = self::validate_parameters(self::data_for_plans_page_parameters(), array(
 636             'userid' => $userid,
 637         ));
 638
 639         $context = context_user::instance($params['userid']);
 640         self::validate_context($context);
 641         $output = $PAGE->get_renderer('tool_lp');
 642
 643         $renderable = new \tool_lp\output\plans_page($params['userid']);
 644
 645         return $renderable->export_for_template($output);
 646     }
 647
 648     /**
 649      * Returns description of data_for_plans_page() result value.
 650      *
 651      * @return \external_description
 652      */
 653     public static function data_for_plans_page_returns() {
 654         return new external_single_structure(array (
 655             'userid' => new external_value(PARAM_INT, 'The learning plan user id'),
 656             'plans' => new external_multiple_structure(
 657                 plan_exporter::get_read_structure()
 658             ),
 659             'pluginbaseurl' => new external_value(PARAM_LOCALURL, 'Url to the tool_lp plugin folder on this Moodle site'),
 660             'navigation' => new external_multiple_structure(
 661                 new external_value(PARAM_RAW, 'HTML for a navigation item that should be on this page')
 662             ),
 663             'canreaduserevidence' => new external_value(PARAM_BOOL, 'Can the current user view the user\'s evidence'),
 664             'canmanageuserplans' => new external_value(PARAM_BOOL, 'Can the current user manage the user\'s plans'),
 665         ));
 666     }
 667
 668     /**
 669      * Returns description of external function parameters.
 670      *
 671      * @return \external_function_parameters
 672      */
 673     public static function data_for_user_evidence_list_page_parameters() {
 674         return new external_function_parameters(array(
 675             'userid' => new external_value(PARAM_INT, 'The user ID')
 676         ));
 677     }
 678
 679     /**
 680      * Loads the data required to render the user_evidence_list_page template.
 681      *
 682      * @param int $userid User id.
 683      * @return boolean
 684      */
 685     public static function data_for_user_evidence_list_page($userid) {
 686         global $PAGE;
 687         $params = self::validate_parameters(self::data_for_user_evidence_list_page_parameters(),
 688             array('userid' => $userid));
 689
 690         $context = context_user::instance($params['userid']);
 691         self::validate_context($context);
 692         $output = $PAGE->get_renderer('tool_lp');
 693
 694         $renderable = new \tool_lp\output\user_evidence_list_page($params['userid']);
 695         return $renderable->export_for_template($output);
 696     }
 697
 698     /**
 699      * Returns description of external function result value.
 700      *
 701      * @return \external_description
 702      */
 703     public static function data_for_user_evidence_list_page_returns() {
 704         return new external_single_structure(array (
 705             'canmanage' => new external_value(PARAM_BOOL, 'Can the current user manage the user\'s evidence'),
 706             'userid' => new external_value(PARAM_INT, 'The user ID'),
 707             'pluginbaseurl' => new external_value(PARAM_LOCALURL, 'Url to the tool_lp plugin folder on this Moodle site'),
 708             'evidence' => new external_multiple_structure(user_evidence_summary_exporter::get_read_structure()),
 709             'navigation' => new external_multiple_structure(
 710                 new external_value(PARAM_RAW, 'HTML for a navigation item that should be on this page')
 711             ),
 712         ));
 713     }
 714
 715     /**
 716      * Returns description of external function parameters.
 717      *
 718      * @return \external_function_parameters
 719      */
 720     public static function data_for_user_evidence_page_parameters() {
 721         return new external_function_parameters(array(
 722             'id' => new external_value(PARAM_INT, 'The user evidence ID')
 723         ));
 724     }
 725
 726     /**
 727      * Loads the data required to render the user_evidence_page template.
 728      *
 729      * @param int $id User id.
 730      * @return boolean
 731      */
 732     public static function data_for_user_evidence_page($id) {
 733         global $PAGE;
 734         $params = self::validate_parameters(self::data_for_user_evidence_page_parameters(),
 735             array('id' => $id));
 736
 737         $userevidence = api::read_user_evidence($id);
 738         self::validate_context($userevidence->get_context());
 739         $output = $PAGE->get_renderer('tool_lp');
 740
 741         $renderable = new \tool_lp\output\user_evidence_page($userevidence);
 742         return $renderable->export_for_template($output);
 743     }
 744
 745     /**
 746      * Returns description of external function result value.
 747      *
 748      * @return \external_description
 749      */
 750     public static function data_for_user_evidence_page_returns() {
 751         return new external_single_structure(array(
 752             'userevidence' => user_evidence_summary_exporter::get_read_structure(),
 753             'pluginbaseurl' => new external_value(PARAM_LOCALURL, 'Url to the tool_lp plugin folder on this Moodle site')
 754         ));
 755     }
 756
 757     /**
 758      * Returns the description of the data_for_related_competencies_section_parameters() parameters.
 759      *
 760      * @return external_function_parameters.
 761      */
 762     public static function data_for_related_competencies_section_parameters() {
 763         $competencyid = new external_value(
 764             PARAM_INT,
 765             'The competency id',
 766             VALUE_REQUIRED
 767         );
 768         return new external_function_parameters(array('competencyid' => $competencyid));
 769     }
 770
 771     /**
 772      * Data to render in the related competencies section.
 773      *
 774      * @param int $competencyid
 775      * @return array Related competencies and whether to show delete action button or not.
 776      */
 777     public static function data_for_related_competencies_section($competencyid) {
 778         global $PAGE;
 779
 780         $params = self::validate_parameters(self::data_for_related_competencies_section_parameters(), array(
 781             'competencyid' => $competencyid,
 782         ));
 783         $competency = api::read_competency($params['competencyid']);
 784         self::validate_context($competency->get_context());
 785
 786         $renderable = new \tool_lp\output\related_competencies($params['competencyid']);
 787         $renderer = $PAGE->get_renderer('tool_lp');
 788
 789         return $renderable->export_for_template($renderer);
 790     }
 791
 792     /**
 793      * Returns description of data_for_related_competencies_section_returns() result value.
 794      *
 795      * @return external_description
 796      */
 797     public static function data_for_related_competencies_section_returns() {
 798         return new external_single_structure(array(
 799             'relatedcompetencies' => new external_multiple_structure(competency_exporter::get_read_structure()),
 800             'showdeleterelatedaction' => new external_value(PARAM_BOOL, 'Whether to show the delete relation link or not')
 801         ));
 802     }
 803
 804     /**
 805      * Returns the description of external function parameters.
 806      *
 807      * @return external_function_parameters.
 808      */
 809     public static function search_users_parameters() {
 810         $query = new external_value(
 811             PARAM_RAW,
 812             'Query string'
 813         );
 814         $capability = new external_value(
 815             PARAM_RAW,
 816             'Required capability'
 817         );
 818         $limitfrom = new external_value(
 819             PARAM_INT,
 820             'Number of records to skip',
 821             VALUE_DEFAULT,
 822             0
 823         );
 824         $limitnum = new external_value(
 825             PARAM_RAW,
 826             'Number of records to fetch',
 827             VALUE_DEFAULT,
 828             100
 829         );
 830         return new external_function_parameters(array(
 831             'query' => $query,
 832             'capability' => $capability,
 833             'limitfrom' => $limitfrom,
 834             'limitnum' => $limitnum
 835         ));
 836     }
 837
 838     /**
 839      * Search users.
 840      *
 841      * @param string $query
 842      * @param string $capability
 843      * @param int $limitfrom
 844      * @param int $limitnum
 845      * @return array
 846      */
 847     public static function search_users($query, $capability = '', $limitfrom = 0, $limitnum = 100) {
 848         global $DB, $CFG, $PAGE, $USER;
 849
 850         $params = self::validate_parameters(self::search_users_parameters(), array(
 851             'query' => $query,
 852             'capability' => $capability,
 853             'limitfrom' => $limitfrom,
 854             'limitnum' => $limitnum,
 855         ));
 856         $query = $params['query'];
 857         $cap = $params['capability'];
 858         $limitfrom = $params['limitfrom'];
 859         $limitnum = $params['limitnum'];
 860
 861         $context = context_system::instance();
 862         self::validate_context($context);
 863         $output = $PAGE->get_renderer('tool_lp');
 864
 865         list($filtercapsql, $filtercapparams) = api::filter_users_with_capability_on_user_context_sql($cap,
 866             $USER->id, SQL_PARAMS_NAMED);
 867
 868         $extrasearchfields = array();
 869         if (!empty($CFG->showuseridentity) && has_capability('moodle/site:viewuseridentity', $context)) {
 870             $extrasearchfields = explode(',', $CFG->showuseridentity);
 871         }
 872         $fields = \user_picture::fields('u', $extrasearchfields);
 873
 874         list($wheresql, $whereparams) = users_search_sql($query, 'u', true, $extrasearchfields);
 875         list($sortsql, $sortparams) = users_order_by_sql('u', $query, $context);
 876
 877         $countsql = "SELECT COUNT('x') FROM {user} u WHERE $wheresql AND u.id $filtercapsql";
 878         $countparams = $whereparams + $filtercapparams;
 879         $sql = "SELECT $fields FROM {user} u WHERE $wheresql AND u.id $filtercapsql ORDER BY $sortsql";
 880         $params = $whereparams + $filtercapparams + $sortparams;
 881
 882         $count = $DB->count_records_sql($countsql, $countparams);
 883         $result = $DB->get_recordset_sql($sql, $params, $limitfrom, $limitnum);
 884
 885         $users = array();
 886         foreach ($result as $key => $user) {
 887             // Make sure all required fields are set.
 888             foreach (user_summary_exporter::define_properties() as $propertykey => $definition) {
 889                 if (empty($user->$propertykey) || !in_array($propertykey, $extrasearchfields)) {
 890                     if ($propertykey != 'id') {
 891                         $user->$propertykey = '';
 892                     }
 893                 }
 894             }
 895             $exporter = new user_summary_exporter($user);
 896             $newuser = $exporter->export($output);
 897
 898             $users[$key] = $newuser;
 899         }
 900         $result->close();
 901
 902         return array(
 903             'users' => $users,
 904             'count' => $count
 905         );
 906     }
 907
 908     /**
 909      * Returns description of external function result value.
 910      *
 911      * @return external_description
 912      */
 913     public static function search_users_returns() {
 914         global $CFG;
 915         require_once($CFG->dirroot . '/user/externallib.php');
 916         return new external_single_structure(array(
 917             'users' => new external_multiple_structure(user_summary_exporter::get_read_structure()),
 918             'count' => new external_value(PARAM_INT, 'Total number of results.')
 919         ));
 920     }
 921
 922     /**
 923      * Returns the description of external function parameters.
 924      *
 925      * @return external_function_parameters
 926      */
 927     public static function search_cohorts_parameters() {
 928         $query = new external_value(
 929             PARAM_RAW,
 930             'Query string'
 931         );
 932         $includes = new external_value(
 933             PARAM_ALPHA,
 934             'What other contexts to fetch the frameworks from. (all, parents, self)',
 935             VALUE_DEFAULT,
 936             'parents'
 937         );
 938         $limitfrom = new external_value(
 939             PARAM_INT,
 940             'limitfrom we are fetching the records from',
 941             VALUE_DEFAULT,
 942             0
 943         );
 944         $limitnum = new external_value(
 945             PARAM_INT,
 946             'Number of records to fetch',
 947             VALUE_DEFAULT,
 948             25
 949         );
 950         return new external_function_parameters(array(
 951             'query' => $query,
 952             'context' => self::get_context_parameters(),
 953             'includes' => $includes,
 954             'limitfrom' => $limitfrom,
 955             'limitnum' => $limitnum
 956         ));
 957     }
 958
 959     /**
 960      * Search cohorts.
 961      * TODO: MDL-52243 Move this function to cohorts/externallib.php
 962      *
 963      * @param string $query
 964      * @param array $context
 965      * @param string $includes
 966      * @param int $limitfrom
 967      * @param int $limitnum
 968      * @return array
 969      */
 970     public static function search_cohorts($query, $context, $includes = 'parents', $limitfrom = 0, $limitnum = 25) {
 971         global $DB, $CFG, $PAGE;
 972         require_once($CFG->dirroot . '/cohort/lib.php');
 973
 974         $params = self::validate_parameters(self::search_cohorts_parameters(), array(
 975             'query' => $query,
 976             'context' => $context,
 977             'includes' => $includes,
 978             'limitfrom' => $limitfrom,
 979             'limitnum' => $limitnum,
 980         ));
 981         $query = $params['query'];
 982         $includes = $params['includes'];
 983         $context = self::get_context_from_params($params['context']);
 984         $limitfrom = $params['limitfrom'];
 985         $limitnum = $params['limitnum'];
 986
 987         self::validate_context($context);
 988         $output = $PAGE->get_renderer('tool_lp');
 989
 990         $manager = has_capability('moodle/cohort:manage', $context);
 991         if (!$manager) {
 992             require_capability('moodle/cohort:view', $context);
 993         }
 994
 995         // TODO Make this more efficient.
 996         if ($includes == 'self') {
 997             $results = cohort_get_cohorts($context->id, $limitfrom, $limitnum, $query);
 998             $results = $results['cohorts'];
 999         } else if ($includes == 'parents') {
1000             $results = cohort_get_cohorts($context->id, $limitfrom, $limitnum, $query);
1001             $results = $results['cohorts'];
1002             if (!$context instanceof context_system) {
1003                 $results = array_merge($results, cohort_get_available_cohorts($context, COHORT_ALL, $limitfrom, $limitnum, $query));
1004             }
1005         } else if ($includes == 'all') {
1006             $results = cohort_get_all_cohorts($limitfrom, $limitnum, $query);
1007             $results = $results['cohorts'];
1008         } else {
1009             throw new coding_exception('Invalid parameter value for \'includes\'.');
1010         }
1011
1012         $cohorts = array();
1013         foreach ($results as $key => $cohort) {
1014             $cohortcontext = context::instance_by_id($cohort->contextid);
1015             $exporter = new cohort_summary_exporter($cohort, array('context' => $cohortcontext));
1016             $newcohort = $exporter->export($output);
1017
1018             $cohorts[$key] = $newcohort;
1019         }
1020
1021         return array('cohorts' => $cohorts);
1022     }
1023
1024     /**
1025      * Returns description of external function result value.
1026      *
1027      * @return external_description
1028      */
1029     public static function search_cohorts_returns() {
1030         return new external_single_structure(array(
1031             'cohorts' => new external_multiple_structure(cohort_summary_exporter::get_read_structure())
1032         ));
1033     }
1034
1035     /**
1036      * Returns description of external function.
1037      *
1038      * @return \external_function_parameters
1039      */
1040     public static function data_for_user_competency_summary_parameters() {
1041         $userid = new external_value(
1042             PARAM_INT,
1043             'Data base record id for the user',
1044             VALUE_REQUIRED
1045         );
1046         $competencyid = new external_value(
1047             PARAM_INT,
1048             'Data base record id for the competency',
1049             VALUE_REQUIRED
1050         );
1051         $params = array(
1052             'userid' => $userid,
1053             'competencyid' => $competencyid,
1054         );
1055         return new external_function_parameters($params);
1056     }
1057
1058     /**
1059      * Data for user competency summary.
1060      *
1061      * @param int $userid The user ID
1062      * @param int $competencyid The competency ID
1063      * @return \stdClass
1064      */
1065     public static function data_for_user_competency_summary($userid, $competencyid) {
1066         global $PAGE;
1067         $params = self::validate_parameters(self::data_for_user_competency_summary_parameters(), array(
1068             'userid' => $userid,
1069             'competencyid' => $competencyid,
1070         ));
1071
1072         $uc = api::get_user_competency($params['userid'], $params['competencyid']);
1073         self::validate_context($uc->get_context());
1074         $output = $PAGE->get_renderer('tool_lp');
1075
1076         $renderable = new \tool_lp\output\user_competency_summary($uc);
1077         return $renderable->export_for_template($output);
1078     }
1079
1080     /**
1081      * Returns description of external function.
1082      *
1083      * @return \external_description
1084      */
1085     public static function data_for_user_competency_summary_returns() {
1086         return user_competency_summary_exporter::get_read_structure();
1087     }
1088
1089     /**
1090      * Returns description of data_for_user_competency_summary_in_plan() parameters.
1091      *
1092      * @return \external_function_parameters
1093      */
1094     public static function data_for_user_competency_summary_in_plan_parameters() {
1095         $competencyid = new external_value(
1096             PARAM_INT,
1097             'Data base record id for the competency',
1098             VALUE_REQUIRED
1099         );
1100         $planid = new external_value(
1101             PARAM_INT,
1102             'Data base record id for the plan',
1103             VALUE_REQUIRED
1104         );
1105
1106         $params = array(
1107             'competencyid' => $competencyid,
1108             'planid' => $planid,
1109         );
1110         return new external_function_parameters($params);
1111     }
1112
1113     /**
1114      * Read a user competency summary.
1115      *
1116      * @param int $competencyid The competency id
1117      * @param int $planid The plan id
1118      * @return \stdClass
1119      */
1120     public static function data_for_user_competency_summary_in_plan($competencyid, $planid) {
1121         global $PAGE;
1122         $params = self::validate_parameters(self::data_for_user_competency_summary_in_plan_parameters(), array(
1123             'competencyid' => $competencyid,
1124             'planid' => $planid
1125         ));
1126
1127         $plan = api::read_plan($params['planid']);
1128         $context = $plan->get_context();
1129         self::validate_context($context);
1130         $output = $PAGE->get_renderer('tool_lp');
1131
1132         $renderable = new user_competency_summary_in_plan($params['competencyid'], $params['planid']);
1133         return $renderable->export_for_template($output);
1134     }
1135
1136     /**
1137      * Returns description of data_for_user_competency_summary_in_plan() result value.
1138      *
1139      * @return \external_description
1140      */
1141     public static function data_for_user_competency_summary_in_plan_returns() {
1142         return user_competency_summary_in_plan_exporter::get_read_structure();
1143     }
1144
1145     /**
1146      * Returns description of data_for_user_competency_summary_in_course() parameters.
1147      *
1148      * @return \external_function_parameters
1149      */
1150     public static function data_for_user_competency_summary_in_course_parameters() {
1151         $userid = new external_value(
1152             PARAM_INT,
1153             'Data base record id for the user',
1154             VALUE_REQUIRED
1155         );
1156         $competencyid = new external_value(
1157             PARAM_INT,
1158             'Data base record id for the competency',
1159             VALUE_REQUIRED
1160         );
1161         $courseid = new external_value(
1162             PARAM_INT,
1163             'Data base record id for the course',
1164             VALUE_REQUIRED
1165         );
1166
1167         $params = array(
1168             'userid' => $userid,
1169             'competencyid' => $competencyid,
1170             'courseid' => $courseid,
1171         );
1172         return new external_function_parameters($params);
1173     }
1174
1175     /**
1176      * Read a user competency summary.
1177      *
1178      * @param int $userid The user id
1179      * @param int $competencyid The competency id
1180      * @param int $courseid The course id
1181      * @return \stdClass
1182      */
1183     public static function data_for_user_competency_summary_in_course($userid, $competencyid, $courseid) {
1184         global $PAGE;
1185         $params = self::validate_parameters(self::data_for_user_competency_summary_in_course_parameters(), array(
1186             'userid' => $userid,
1187             'competencyid' => $competencyid,
1188             'courseid' => $courseid
1189         ));
1190         $context = context_user::instance($params['userid']);
1191         self::validate_context($context);
1192         $output = $PAGE->get_renderer('tool_lp');
1193
1194         $renderable = new user_competency_summary_in_course($params['userid'], $params['competencyid'], $params['courseid']);
1195         return $renderable->export_for_template($output);
1196     }
1197
1198     /**
1199      * Returns description of data_for_user_competency_summary_in_course() result value.
1200      *
1201      * @return \external_description
1202      */
1203     public static function data_for_user_competency_summary_in_course_returns() {
1204         return user_competency_summary_in_course_exporter::get_read_structure();
1205     }
1206
1207 }