Search moodle.org's
Developer Documentation

  • Bug fixes for general core bugs in 3.11.x will end 9 May 2022 (12 months).
  • Bug fixes for security issues in 3.11.x will end 14 November 2022 (18 months).
  • PHP version: minimum PHP 7.3.0 Note: minimum PHP version has increased since Moodle 3.10. PHP 7.4.x is supported too.
  • Differences Between: [Versions 310 and 311] [Versions 35 and 311] [Versions 36 and 311] [Versions 37 and 311] [Versions 38 and 311] [Versions 39 and 311]

       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  }