[Summary view] [Print] [Text view]

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