Search moodle.org's
Developer Documentation

See Release Notes
Long Term Support Release

  • Bug fixes for general core bugs in 4.1.x will end 13 November 2023 (12 months).
  • Bug fixes for security issues in 4.1.x will end 10 November 2025 (36 months).
  • PHP version: minimum PHP 7.4.0 Note: minimum PHP version has increased since Moodle 4.0. PHP 8.0.x is supported too.

Differences Between: [Versions 310 and 401] [Versions 311 and 401] [Versions 39 and 401] [Versions 401 and 402] [Versions 401 and 403]

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