admin/tool/lp/classes/external.php

   1 <?php
   2 // This file is part of Moodle - http://moodle.org/
   3 //
   4 // Moodle is free software: you can redistribute it and/or modify
   5 // it under the terms of the GNU General Public License as published by
   6 // the Free Software Foundation, either version 3 of the License, or
   7 // (at your option) any later version.
   8 //
   9 // Moodle is distributed in the hope that it will be useful,
  10 // but WITHOUT ANY WARRANTY; without even the implied warranty of
  11 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  12 // GNU General Public License for more details.
  13 //
  14 // You should have received a copy of the GNU General Public License
  15 // along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
  16
  17 /**
  18  * This is the external API for this tool.
  19  *
  20  * @package    tool_lp
  21  * @copyright  2015 Damyon Wiese
  22  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  23  */
  24 namespace tool_lp;
  25 defined('MOODLE_INTERNAL') || die();
  26
  27 require_once("$CFG->libdir/externallib.php");
  28 require_once("$CFG->libdir/grade/grade_scale.php");
  29
  30 use context;
  31 use context_system;
  32 use context_course;
  33 use context_helper;
  34 use context_user;
  35 use coding_exception;
  36 use external_api;
  37 use external_function_parameters;
  38 use external_value;
  39 use external_format_value;
  40 use external_single_structure;
  41 use external_multiple_structure;
  42 use invalid_parameter_exception;
  43 use required_capability_exception;
  44 use grade_scale;
  45 use tool_lp\external\competency_framework_exporter;
  46 use tool_lp\external\competency_summary_exporter;
  47 use tool_lp\external\competency_path_exporter;
  48 use tool_lp\external\cohort_summary_exporter;
  49 use tool_lp\external\template_statistics_exporter;
  50 use tool_lp\external\user_summary_exporter;
  51 use tool_lp\external\user_competency_exporter;
  52 use tool_lp\external\user_competency_plan_exporter;
  53 use tool_lp\external\user_competency_summary_exporter;
  54 use tool_lp\external\user_competency_summary_in_course_exporter;
  55 use tool_lp\external\user_competency_summary_in_plan_exporter;
  56 use tool_lp\external\user_evidence_exporter;
  57 use tool_lp\external\user_evidence_summary_exporter;
  58 use tool_lp\external\user_evidence_competency_exporter;
  59 use tool_lp\external\competency_exporter;
  60 use tool_lp\external\course_competency_exporter;
  61 use tool_lp\external\course_summary_exporter;
  62 use tool_lp\external\course_module_summary_exporter;
  63 use tool_lp\external\plan_exporter;
  64 use tool_lp\external\template_exporter;
  65 use tool_lp\external\evidence_exporter;
  66 use tool_lp\output\user_competency_summary_in_plan;
  67 use tool_lp\output\user_competency_summary_in_course;
  68
  69 /**
  70  * This is the external API for this tool.
  71  *
  72  * @copyright  2015 Damyon Wiese
  73  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  74  */
  75 class external extends external_api {
  76
  77     /**
  78      * Returns description of a generic list() parameters.
  79      *
  80      * @return \external_function_parameters
  81      */
  82     protected static function list_parameters_structure() {
  83         $filters = new external_multiple_structure(new external_single_structure(
  84             array(
  85                 'column' => new external_value(PARAM_ALPHANUMEXT, 'Column name to filter by'),
  86                 'value' => new external_value(PARAM_TEXT, 'Value to filter by. Must be exact match')
  87             )
  88         ));
  89         $sort = new external_value(
  90             PARAM_ALPHANUMEXT,
  91             'Column to sort by.',
  92             VALUE_DEFAULT,
  93             ''
  94         );
  95         $order = new external_value(
  96             PARAM_ALPHA,
  97             'Sort direction. Should be either ASC or DESC',
  98             VALUE_DEFAULT,
  99             ''
 100         );
 101         $skip = new external_value(
 102             PARAM_INT,
 103             'Skip this number of records before returning results',
 104             VALUE_DEFAULT,
 105             0
 106         );
 107         $limit = new external_value(
 108             PARAM_INT,
 109             'Return this number of records at most.',
 110             VALUE_DEFAULT,
 111             0
 112         );
 113
 114         $params = array(
 115             'filters' => $filters,
 116             'sort' => $sort,
 117             'order' => $order,
 118             'skip' => $skip,
 119             'limit' => $limit
 120         );
 121         return new external_function_parameters($params);
 122     }
 123
 124     /**
 125      * Returns a prepared structure to use a context parameters.
 126      * @return external_single_structure
 127      */
 128     protected static function get_context_parameters() {
 129         $id = new external_value(
 130             PARAM_INT,
 131             'Context ID. Either use this value, or level and instanceid.',
 132             VALUE_DEFAULT,
 133             0
 134         );
 135         $level = new external_value(
 136             PARAM_ALPHA,
 137             'Context level. To be used with instanceid.',
 138             VALUE_DEFAULT,
 139             ''
 140         );
 141         $instanceid = new external_value(
 142             PARAM_INT,
 143             'Context instance ID. To be used with level',
 144             VALUE_DEFAULT,
 145             0
 146         );
 147         return new external_single_structure(array(
 148             'contextid' => $id,
 149             'contextlevel' => $level,
 150             'instanceid' => $instanceid,
 151         ));
 152     }
 153
 154     /**
 155      * Returns description of a generic count_x() parameters.
 156      *
 157      * @return \external_function_parameters
 158      */
 159     public static function count_parameters_structure() {
 160         $filters = new external_multiple_structure(new external_single_structure(
 161             array(
 162                 'column' => new external_value(PARAM_ALPHANUMEXT, 'Column name to filter by'),
 163                 'value' => new external_value(PARAM_TEXT, 'Value to filter by. Must be exact match')
 164             )
 165         ));
 166
 167         $params = array(
 168             'filters' => $filters,
 169         );
 170         return new external_function_parameters($params);
 171     }
 172
 173     /**
 174      * Returns description of create_competency_framework() parameters.
 175      *
 176      * @return \external_function_parameters
 177      */
 178     public static function create_competency_framework_parameters() {
 179         $structure = competency_framework_exporter::get_create_structure();
 180         $params = array('competencyframework' => $structure);
 181         return new external_function_parameters($params);
 182     }
 183
 184     /**
 185      * Create a new competency framework
 186      *
 187      * @param array $competencyframework A single param with all the fields for a competency framework.
 188      * @return \stdClass The new record
 189      */
 190     public static function create_competency_framework($competencyframework) {
 191         global $PAGE;
 192
 193         $params = self::validate_parameters(self::create_competency_framework_parameters(),
 194                                             array('competencyframework' => $competencyframework));
 195
 196         $params = $params['competencyframework'];
 197
 198         $context = self::get_context_from_params($params);
 199         self::validate_context($context);
 200         $output = $PAGE->get_renderer('tool_lp');
 201
 202         unset($params['contextlevel']);
 203         unset($params['instanceid']);
 204         $params['contextid'] = $context->id;
 205
 206         $params = (object) $params;
 207         $result = api::create_framework($params);
 208         $exporter = new competency_framework_exporter($result);
 209         $record = $exporter->export($output);
 210         return $record;
 211     }
 212
 213     /**
 214      * Returns description of create_competency_framework() result value.
 215      *
 216      * @return \external_description
 217      */
 218     public static function create_competency_framework_returns() {
 219         return competency_framework_exporter::get_read_structure();
 220     }
 221
 222     /**
 223      * Returns description of read_competency_framework() parameters.
 224      *
 225      * @return \external_function_parameters
 226      */
 227     public static function read_competency_framework_parameters() {
 228         $id = new external_value(
 229             PARAM_INT,
 230             'Data base record id for the framework',
 231             VALUE_REQUIRED
 232         );
 233
 234         $params = array(
 235             'id' => $id,
 236         );
 237         return new external_function_parameters($params);
 238     }
 239
 240     /**
 241      * Read a competency framework by id.
 242      *
 243      * @param int $id The id of the framework.
 244      * @return \stdClass
 245      */
 246     public static function read_competency_framework($id) {
 247         global $PAGE;
 248
 249         $params = self::validate_parameters(self::read_competency_framework_parameters(),
 250                                             array(
 251                                                 'id' => $id,
 252                                             ));
 253
 254         $framework = api::read_framework($params['id']);
 255         self::validate_context($framework->get_context());
 256         $output = $PAGE->get_renderer('tool_lp');
 257         $exporter = new competency_framework_exporter($framework);
 258         $record = $exporter->export($output);
 259         return $record;
 260     }
 261
 262     /**
 263      * Returns description of read_competency_framework() result value.
 264      *
 265      * @return \external_description
 266      */
 267     public static function read_competency_framework_returns() {
 268         return competency_framework_exporter::get_read_structure();
 269     }
 270
 271     /**
 272      * Returns description of competency_viewed() parameters.
 273      *
 274      * @return \external_function_parameters
 275      */
 276     public static function competency_viewed_parameters() {
 277         $id = new external_value(
 278             PARAM_INT,
 279             'The competency id',
 280             VALUE_REQUIRED
 281         );
 282         $params = array(
 283             'id' => $id
 284         );
 285         return new external_function_parameters($params);
 286     }
 287
 288     /**
 289      * Log event competency viewed.
 290      *
 291      * @param int $id The competency ID.
 292      * @return boolean
 293      */
 294     public static function competency_viewed($id) {
 295         $params = self::validate_parameters(self::competency_viewed_parameters(),
 296                                             array(
 297                                                 'id' => $id
 298                                             ));
 299         return api::competency_viewed($params['id']);
 300     }
 301
 302     /**
 303      * Returns description of competency_viewed() result value.
 304      *
 305      * @return \external_description
 306      */
 307     public static function competency_viewed_returns() {
 308         return new external_value(PARAM_BOOL, 'True if the event competency viewed was logged');
 309     }
 310
 311     /**
 312      * Returns description of duplicate_competency_framework() parameters.
 313      *
 314      * @return \external_function_parameters
 315      */
 316     public static function duplicate_competency_framework_parameters() {
 317         $id = new external_value(
 318             PARAM_INT,
 319             'Data base record id for the framework',
 320             VALUE_REQUIRED
 321         );
 322
 323         $params = array(
 324             'id' => $id,
 325         );
 326         return new external_function_parameters($params);
 327     }
 328
 329     /**
 330      * Duplicate a competency framework
 331      *
 332      * @param int $id The competency framework id
 333      * @return boolean
 334      */
 335     public static function duplicate_competency_framework($id) {
 336         global $PAGE;
 337         $params = self::validate_parameters(self::duplicate_competency_framework_parameters(),
 338                                             array(
 339                                                 'id' => $id,
 340                                             ));
 341
 342         $framework = api::read_framework($params['id']);
 343         self::validate_context($framework->get_context());
 344
 345         $output = $PAGE->get_renderer('tool_lp');
 346         $framework = api::duplicate_framework($params['id']);
 347         $exporter = new competency_framework_exporter($framework);
 348         $record = $exporter->export($output);
 349         return $record;
 350     }
 351
 352     /**
 353      * Returns description of duplicate_competency_framework() result value.
 354      *
 355      * @return \external_description
 356      */
 357     public static function duplicate_competency_framework_returns() {
 358         return competency_framework_exporter::get_read_structure();
 359     }
 360
 361     /**
 362      * Returns description of delete_competency_framework() parameters.
 363      *
 364      * @return \external_function_parameters
 365      */
 366     public static function delete_competency_framework_parameters() {
 367         $id = new external_value(
 368             PARAM_INT,
 369             'Data base record id for the framework',
 370             VALUE_REQUIRED
 371         );
 372
 373         $params = array(
 374             'id' => $id,
 375         );
 376         return new external_function_parameters($params);
 377     }
 378
 379     /**
 380      * Delete a competency framework
 381      *
 382      * @param int $id The competency framework id
 383      * @return boolean
 384      */
 385     public static function delete_competency_framework($id) {
 386         $params = self::validate_parameters(self::delete_competency_framework_parameters(),
 387                                             array(
 388                                                 'id' => $id,
 389                                             ));
 390
 391         $framework = api::read_framework($params['id']);
 392         self::validate_context($framework->get_context());
 393
 394         return api::delete_framework($params['id']);
 395     }
 396
 397     /**
 398      * Returns description of delete_competency_framework() result value.
 399      *
 400      * @return \external_description
 401      */
 402     public static function delete_competency_framework_returns() {
 403         return new external_value(PARAM_BOOL, 'True if the delete was successful');
 404     }
 405
 406     /**
 407      * Returns description of update_competency_framework() parameters.
 408      *
 409      * @return \external_function_parameters
 410      */
 411     public static function update_competency_framework_parameters() {
 412         $structure = competency_framework_exporter::get_update_structure();
 413         $params = array('competencyframework' => $structure);
 414         return new external_function_parameters($params);
 415     }
 416
 417     /**
 418      * Update an existing competency framework
 419      *
 420      * @param array $competencyframework An array with all the fields for a competency framework.
 421      * @return boolean
 422      */
 423     public static function update_competency_framework($competencyframework) {
 424
 425         $params = self::validate_parameters(self::update_competency_framework_parameters(),
 426                                             array(
 427                                                 'competencyframework' => $competencyframework
 428                                             ));
 429
 430         $params = $params['competencyframework'];
 431
 432         $framework = api::read_framework($params['id']);
 433         self::validate_context($framework->get_context());
 434
 435         $params = (object) $params;
 436
 437         return api::update_framework($params);
 438     }
 439
 440     /**
 441      * Returns description of update_competency_framework() result value.
 442      *
 443      * @return \external_description
 444      */
 445     public static function update_competency_framework_returns() {
 446         return new external_value(PARAM_BOOL, 'True if the update was successful');
 447     }
 448
 449     /**
 450      * Returns description of list_competency_frameworks() parameters.
 451      *
 452      * @return \external_function_parameters
 453      */
 454     public static function list_competency_frameworks_parameters() {
 455         $sort = new external_value(
 456             PARAM_ALPHANUMEXT,
 457             'Column to sort by.',
 458             VALUE_DEFAULT,
 459             'shortname'
 460         );
 461         $order = new external_value(
 462             PARAM_ALPHA,
 463             'Sort direction. Should be either ASC or DESC',
 464             VALUE_DEFAULT,
 465             ''
 466         );
 467         $skip = new external_value(
 468             PARAM_INT,
 469             'Skip this number of records before returning results',
 470             VALUE_DEFAULT,
 471             0
 472         );
 473         $limit = new external_value(
 474             PARAM_INT,
 475             'Return this number of records at most.',
 476             VALUE_DEFAULT,
 477             0
 478         );
 479         $includes = new external_value(
 480             PARAM_ALPHA,
 481             'What other contextes to fetch the frameworks from. (children, parents, self)',
 482             VALUE_DEFAULT,
 483             'children'
 484         );
 485         $onlyvisible = new external_value(
 486             PARAM_BOOL,
 487             'Only visible frameworks will be returned if visible true',
 488             VALUE_DEFAULT,
 489             false
 490         );
 491         $query = new external_value(
 492             PARAM_RAW,
 493             'A query string to filter the results',
 494             VALUE_DEFAULT,
 495             ''
 496         );
 497
 498         $params = array(
 499             'sort' => $sort,
 500             'order' => $order,
 501             'skip' => $skip,
 502             'limit' => $limit,
 503             'context' => self::get_context_parameters(),
 504             'includes' => $includes,
 505             'onlyvisible' => $onlyvisible,
 506             'query' => $query,
 507         );
 508         return new external_function_parameters($params);
 509     }
 510
 511     /**
 512      * List the existing competency frameworks
 513      *
 514      * @param int $sort
 515      * @param string $order
 516      * @param string $skip
 517      * @param int $limit
 518      * @param array $context
 519      * @param bool $includes
 520      * @param bool $onlyvisible
 521      * @param string $query
 522      *
 523      * @return array
 524      * @throws \required_capability_exception
 525      * @throws invalid_parameter_exception
 526      */
 527     public static function list_competency_frameworks($sort, $order, $skip, $limit, $context, $includes, $onlyvisible,
 528             $query = '') {
 529         global $PAGE;
 530
 531         $params = self::validate_parameters(self::list_competency_frameworks_parameters(),
 532                                             array(
 533                                                 'sort' => $sort,
 534                                                 'order' => $order,
 535                                                 'skip' => $skip,
 536                                                 'limit' => $limit,
 537                                                 'context' => $context,
 538                                                 'includes' => $includes,
 539                                                 'onlyvisible' => $onlyvisible,
 540                                                 'query' => $query,
 541                                             ));
 542
 543         $context = self::get_context_from_params($params['context']);
 544         self::validate_context($context);
 545         $output = $PAGE->get_renderer('tool_lp');
 546
 547         if ($params['order'] !== '' && $params['order'] !== 'ASC' && $params['order'] !== 'DESC') {
 548             throw new invalid_parameter_exception('Invalid order param. Must be ASC, DESC or empty.');
 549         }
 550
 551         $results = api::list_frameworks($params['sort'],
 552                                        $params['order'],
 553                                        $params['skip'],
 554                                        $params['limit'],
 555                                        $context,
 556                                        $params['includes'],
 557                                        $params['onlyvisible'],
 558                                        $params['query']);
 559         $records = array();
 560         foreach ($results as $result) {
 561             $exporter = new competency_framework_exporter($result);
 562             $record = $exporter->export($output);
 563             array_push($records, $record);
 564         }
 565         return $records;
 566     }
 567
 568     /**
 569      * Returns description of list_competency_frameworks() result value.
 570      *
 571      * @return \external_description
 572      */
 573     public static function list_competency_frameworks_returns() {
 574         return new external_multiple_structure(competency_framework_exporter::get_read_structure());
 575     }
 576
 577     /**
 578      * Returns description of count_competency_frameworks() parameters.
 579      *
 580      * @return \external_function_parameters
 581      */
 582     public static function count_competency_frameworks_parameters() {
 583         $includes = new external_value(
 584             PARAM_ALPHA,
 585             'What other contextes to fetch the frameworks from. (children, parents, self)',
 586             VALUE_DEFAULT,
 587             'children'
 588         );
 589
 590         $params = array(
 591             'context' => self::get_context_parameters(),
 592             'includes' => $includes
 593         );
 594         return new external_function_parameters($params);
 595     }
 596
 597     /**
 598      * Count the existing competency frameworks
 599      *
 600      * @param array $context
 601      * @param string $includes
 602      * @return int
 603      */
 604     public static function count_competency_frameworks($context, $includes) {
 605         $params = self::validate_parameters(self::count_competency_frameworks_parameters(),
 606                                             array(
 607                                                 'context' => $context,
 608                                                 'includes' => $includes
 609                                             ));
 610
 611         $context = self::get_context_from_params($params['context']);
 612         self::validate_context($context);
 613
 614         return api::count_frameworks($context, $params['includes']);
 615     }
 616
 617     /**
 618      * Returns description of count_competency_frameworks() result value.
 619      *
 620      * @return \external_description
 621      */
 622     public static function count_competency_frameworks_returns() {
 623         return new external_value(PARAM_INT, 'The number of competency frameworks found.');
 624     }
 625
 626     /**
 627      * Returns description of competency_framework_viewed() parameters.
 628      *
 629      * @return \external_function_parameters
 630      */
 631     public static function competency_framework_viewed_parameters() {
 632         $id = new external_value(
 633             PARAM_INT,
 634             'The competency framework id',
 635             VALUE_REQUIRED
 636         );
 637
 638         $params = array(
 639             'id' => $id
 640         );
 641         return new external_function_parameters($params);
 642     }
 643
 644     /**
 645      * Log event competency framework viewed.
 646      *
 647      * @param int $id The competency framework ID.
 648      * @return boolean
 649      */
 650     public static function competency_framework_viewed($id) {
 651         $params = self::validate_parameters(self::competency_framework_viewed_parameters(),
 652                                             array(
 653                                                 'id' => $id
 654                                             ));
 655         return api::competency_framework_viewed($params['id']);
 656
 657     }
 658
 659     /**
 660      * Returns description of competency_framework_viewed() result value.
 661      *
 662      * @return \external_description
 663      */
 664     public static function competency_framework_viewed_returns() {
 665         return new external_value(PARAM_BOOL, 'True if the event competency framework was logged');
 666     }
 667
 668     /**
 669      * Returns description of data_for_competency_frameworks_manage_page() parameters.
 670      *
 671      * @return \external_function_parameters
 672      */
 673     public static function data_for_competency_frameworks_manage_page_parameters() {
 674         $params = array('pagecontext' => self::get_context_parameters());
 675         return new external_function_parameters($params);
 676     }
 677
 678     /**
 679      * Loads the data required to render the competency_frameworks_manage_page template.
 680      *
 681      * @param context $pagecontext The page context
 682      * @return \stdClass
 683      */
 684     public static function data_for_competency_frameworks_manage_page($pagecontext) {
 685         global $PAGE;
 686
 687         $params = self::validate_parameters(
 688             self::data_for_competency_frameworks_manage_page_parameters(),
 689             array(
 690                 'pagecontext' => $pagecontext
 691             )
 692         );
 693         $context = self::get_context_from_params($params['pagecontext']);
 694         self::validate_context($context);
 695
 696         $renderable = new output\manage_competency_frameworks_page($context);
 697         $renderer = $PAGE->get_renderer('tool_lp');
 698
 699         $data = $renderable->export_for_template($renderer);
 700
 701         return $data;
 702     }
 703
 704     /**
 705      * Returns description of data_for_competency_frameworks_manage_page() result value.
 706      *
 707      * @return \external_description
 708      */
 709     public static function data_for_competency_frameworks_manage_page_returns() {
 710         return new external_single_structure(array (
 711             'competencyframeworks' => new external_multiple_structure(
 712                 competency_framework_exporter::get_read_structure()
 713             ),
 714             'pluginbaseurl' => new external_value(PARAM_LOCALURL, 'Url to the tool_lp plugin folder on this Moodle site'),
 715             'navigation' => new external_multiple_structure(
 716                 new external_value(PARAM_RAW, 'HTML for a navigation item that should be on this page')
 717             ),
 718             'pagecontextid' => new external_value(PARAM_INT, 'The page context id')
 719         ));
 720
 721     }
 722
 723     /**
 724      * Returns description of create_competency() parameters.
 725      *
 726      * @return \external_function_parameters
 727      */
 728     public static function create_competency_parameters() {
 729         $structure = competency_exporter::get_create_structure();
 730         $params = array('competency' => $structure);
 731         return new external_function_parameters($params);
 732     }
 733
 734     /**
 735      * Create a new competency
 736      *
 737      * @param array $competency All the fields for a competency record (including id)
 738      * @return array the competency
 739      */
 740     public static function create_competency($competency) {
 741         global $PAGE;
 742
 743         $params = self::validate_parameters(self::create_competency_parameters(),
 744                                             array('competency' => $competency));
 745
 746         $params = $params['competency'];
 747         $framework = api::read_framework($params['competencyframeworkid']);
 748         $context = $framework->get_context();
 749         self::validate_context($context);
 750         $output = $PAGE->get_renderer('tool_lp');
 751
 752         $params = (object) $params;
 753         $result = api::create_competency($params);
 754         $exporter = new competency_exporter($result, array('context' => $context));
 755         $record = $exporter->export($output);
 756         return $record;
 757     }
 758
 759     /**
 760      * Returns description of create_competency() result value.
 761      *
 762      * @return \external_description
 763      */
 764     public static function create_competency_returns() {
 765         return competency_exporter::get_read_structure();
 766     }
 767
 768     /**
 769      * Returns description of read_competency() parameters.
 770      *
 771      * @return \external_function_parameters
 772      */
 773     public static function read_competency_parameters() {
 774         $id = new external_value(
 775             PARAM_INT,
 776             'Data base record id for the competency',
 777             VALUE_REQUIRED
 778         );
 779
 780         $params = array(
 781             'id' => $id,
 782         );
 783         return new external_function_parameters($params);
 784     }
 785
 786     /**
 787      * Read a competency by id.
 788      *
 789      * @param int $id The id of the competency
 790      * @return \stdClass
 791      */
 792     public static function read_competency($id) {
 793         global $PAGE;
 794
 795         $params = self::validate_parameters(self::read_competency_parameters(),
 796                                             array(
 797                                                 'id' => $id,
 798                                             ));
 799
 800         $competency = api::read_competency($params['id']);
 801         $context = $competency->get_context();
 802         self::validate_context($context);
 803         $output = $PAGE->get_renderer('tool_lp');
 804         $exporter = new competency_exporter($competency, array('context' => $context));
 805         $record = $exporter->export($output);
 806         return $record;
 807     }
 808
 809     /**
 810      * Returns description of read_competency() result value.
 811      *
 812      * @return \external_description
 813      */
 814     public static function read_competency_returns() {
 815         return competency_exporter::get_read_structure();
 816     }
 817
 818     /**
 819      * Returns description of delete_competency() parameters.
 820      *
 821      * @return \external_function_parameters
 822      */
 823     public static function delete_competency_parameters() {
 824         $id = new external_value(
 825             PARAM_INT,
 826             'Data base record id for the competency',
 827             VALUE_REQUIRED
 828         );
 829
 830         $params = array(
 831             'id' => $id,
 832         );
 833         return new external_function_parameters($params);
 834     }
 835
 836     /**
 837      * Delete a competency
 838      *
 839      * @param int $id The competency id
 840      * @return boolean
 841      */
 842     public static function delete_competency($id) {
 843         $params = self::validate_parameters(self::delete_competency_parameters(),
 844                                             array(
 845                                                 'id' => $id,
 846                                             ));
 847
 848         $competency = api::read_competency($params['id']);
 849         $context = $competency->get_context();
 850         self::validate_context($context);
 851
 852         return api::delete_competency($params['id']);
 853     }
 854
 855     /**
 856      * Returns description of delete_competency() result value.
 857      *
 858      * @return \external_description
 859      */
 860     public static function delete_competency_returns() {
 861         return new external_value(PARAM_BOOL, 'True if the delete was successful');
 862     }
 863
 864     /**
 865      * Returns description of update_competency() parameters.
 866      *
 867      * @return \external_function_parameters
 868      */
 869     public static function update_competency_parameters() {
 870         $structure = competency_exporter::get_update_structure();
 871         $params = array('competency' => $structure);
 872         return new external_function_parameters($params);
 873     }
 874
 875     /**
 876      * Update an existing competency
 877      *
 878      * @param array $competency The array of competency fields (id is required).
 879      * @return boolean
 880      */
 881     public static function update_competency($competency) {
 882
 883         $params = self::validate_parameters(self::update_competency_parameters(),
 884                                             array('competency' => $competency));
 885         $params = $params['competency'];
 886
 887         $competency = api::read_competency($params['id']);
 888         self::validate_context($competency->get_context());
 889
 890         $params = (object) $params;
 891
 892         return api::update_competency($params);
 893     }
 894
 895     /**
 896      * Returns description of update_competency_framework() result value.
 897      *
 898      * @return \external_description
 899      */
 900     public static function update_competency_returns() {
 901         return new external_value(PARAM_BOOL, 'True if the update was successful');
 902     }
 903
 904     /**
 905      * Returns description of list_competencies() parameters.
 906      *
 907      * @return \external_function_parameters
 908      */
 909     public static function list_competencies_parameters() {
 910         return self::list_parameters_structure();
 911     }
 912
 913     /**
 914      * List the existing competency.
 915      *
 916      * @param string $filters
 917      * @param int $sort
 918      * @param string $order
 919      * @param string $skip
 920      * @param int $limit
 921      *
 922      * @return array
 923      * @throws \required_capability_exception
 924      * @throws invalid_parameter_exception
 925      */
 926     public static function list_competencies($filters, $sort, $order, $skip, $limit) {
 927         global $PAGE;
 928
 929         $params = self::validate_parameters(self::list_competencies_parameters(),
 930                                             array(
 931                                                 'filters' => $filters,
 932                                                 'sort' => $sort,
 933                                                 'order' => $order,
 934                                                 'skip' => $skip,
 935                                                 'limit' => $limit
 936                                             ));
 937
 938         if ($params['order'] !== '' && $params['order'] !== 'ASC' && $params['order'] !== 'DESC') {
 939             throw new invalid_parameter_exception('Invalid order param. Must be ASC, DESC or empty.');
 940         }
 941
 942         $safefilters = array();
 943         $validcolumns = array('id', 'shortname', 'description', 'sortorder',
 944                               'idnumber', 'parentid', 'competencyframeworkid');
 945         foreach ($params['filters'] as $filter) {
 946             if (!in_array($filter->column, $validcolumns)) {
 947                 throw new invalid_parameter_exception('Filter column was invalid');
 948             }
 949             $safefilters[$filter->column] = $filter->value;
 950         }
 951
 952         $context = null;
 953         if (isset($safefilters['competencyframeworkid'])) {
 954             $framework = api::read_framework($safefilters['competencyframeworkid']);
 955             $context = $framework->get_context();
 956         } else {
 957             $context = context_system::instance();
 958         }
 959
 960         self::validate_context($context);
 961         $output = $PAGE->get_renderer('tool_lp');
 962
 963         $results = api::list_competencies(
 964             $safefilters,
 965             $params['sort'],
 966             $params['order'],
 967             $params['skip'],
 968             $params['limit']
 969         );
 970
 971         $records = array();
 972         foreach ($results as $result) {
 973             $exporter = new competency_exporter($result, array('context' => $context));
 974             $record = $exporter->export($output);
 975             array_push($records, $record);
 976         }
 977         return $records;
 978     }
 979
 980     /**
 981      * Returns description of list_competencies() result value.
 982      *
 983      * @return \external_description
 984      */
 985     public static function list_competencies_returns() {
 986         return new external_multiple_structure(competency_exporter::get_read_structure());
 987     }
 988
 989     /**
 990      * Returns description of search_competencies() parameters.
 991      *
 992      * @return \external_function_parameters
 993      */
 994     public static function search_competencies_parameters() {
 995         $searchtext = new external_value(
 996             PARAM_RAW,
 997             'Text to search for',
 998             VALUE_REQUIRED
 999         );
1000         $frameworkid = new external_value(
1001             PARAM_INT,
1002             'Competency framework id',
1003             VALUE_REQUIRED
1004         );
1005
1006         $params = array(
1007             'searchtext' => $searchtext,
1008             'competencyframeworkid' => $frameworkid
1009         );
1010         return new external_function_parameters($params);
1011     }
1012
1013     /**
1014      * List the existing competency frameworks
1015      *
1016      * @param string $searchtext Text to search.
1017      * @param int $competencyframeworkid Framework id.
1018      *
1019      * @return array
1020      */
1021     public static function search_competencies($searchtext, $competencyframeworkid) {
1022         global $PAGE;
1023
1024         $params = self::validate_parameters(self::search_competencies_parameters(),
1025                                             array(
1026                                                 'searchtext' => $searchtext,
1027                                                 'competencyframeworkid' => $competencyframeworkid
1028                                             ));
1029
1030         $framework = api::read_framework($params['competencyframeworkid']);
1031         $context = $framework->get_context();
1032         self::validate_context($context);
1033         $output = $PAGE->get_renderer('tool_lp');
1034
1035         $results = api::search_competencies($params['searchtext'], $params['competencyframeworkid']);
1036         $records = array();
1037         foreach ($results as $result) {
1038             $exporter = new competency_exporter($result, array('context' => $context));
1039             $record = $exporter->export($output);
1040
1041             array_push($records, $record);
1042         }
1043
1044         return $records;
1045     }
1046
1047     /**
1048      * Returns description of search_competencies() result value.
1049      *
1050      * @return \external_description
1051      */
1052     public static function search_competencies_returns() {
1053         return new external_multiple_structure(competency_exporter::get_read_structure());
1054     }
1055
1056     /**
1057      * Returns description of count_competencies() parameters.
1058      *
1059      * @return \external_function_parameters
1060      */
1061     public static function count_competencies_parameters() {
1062         return self::count_parameters_structure();
1063     }
1064
1065     /**
1066      * Count the existing competency frameworks.
1067      *
1068      * @param string $filters Filters to use.
1069      * @return boolean
1070      */
1071     public static function count_competencies($filters) {
1072         $params = self::validate_parameters(self::count_competencies_parameters(),
1073                                             array(
1074                                                 'filters' => $filters
1075                                             ));
1076
1077         $safefilters = array();
1078         $validcolumns = array('id', 'shortname', 'description', 'sortorder', 'idnumber',
1079                               'parentid', 'competencyframeworkid');
1080         foreach ($params['filters'] as $filter) {
1081             if (!in_array($filter['column'], $validcolumns)) {
1082                 throw new invalid_parameter_exception('Filter column was invalid');
1083             }
1084             $safefilters[$filter['column']] = $filter['value'];
1085         }
1086
1087         $context = null;
1088         if (isset($safefilters['competencyframeworkid'])) {
1089             $framework = api::read_framework($safefilters['competencyframeworkid']);
1090             $context = $framework->get_context();
1091         } else {
1092             $context = context_system::instance();
1093         }
1094
1095         self::validate_context($context);
1096
1097         return api::count_competencies($safefilters);
1098     }
1099
1100     /**
1101      * Returns description of count_competencies() result value.
1102      *
1103      * @return \external_description
1104      */
1105     public static function count_competencies_returns() {
1106         return new external_value(PARAM_INT, 'The number of competencies found.');
1107     }
1108
1109     /**
1110      * Returns description of data_for_competencies_manage_page() parameters.
1111      *
1112      * @return \external_function_parameters
1113      */
1114     public static function data_for_competencies_manage_page_parameters() {
1115         $competencyframeworkid = new external_value(
1116             PARAM_INT,
1117             'The competency framework id',
1118             VALUE_REQUIRED
1119         );
1120         $search = new external_value(
1121             PARAM_RAW,
1122             'A search string',
1123             VALUE_DEFAULT,
1124             ''
1125         );
1126         $params = array(
1127             'competencyframeworkid' => $competencyframeworkid,
1128             'search' => $search
1129         );
1130         return new external_function_parameters($params);
1131     }
1132
1133     /**
1134      * Loads the data required to render the competencies_manage_page template.
1135      *
1136      * @param int $competencyframeworkid Framework id.
1137      * @param string $search Text to search.
1138      *
1139      * @return boolean
1140      */
1141     public static function data_for_competencies_manage_page($competencyframeworkid, $search) {
1142         global $PAGE;
1143
1144         $params = self::validate_parameters(self::data_for_competencies_manage_page_parameters(),
1145                                             array(
1146                                                 'competencyframeworkid' => $competencyframeworkid,
1147                                                 'search' => $search
1148                                             ));
1149
1150         $framework = api::read_framework($params['competencyframeworkid']);
1151         self::validate_context($framework->get_context());
1152         $output = $PAGE->get_renderer('tool_lp');
1153
1154         $renderable = new output\manage_competencies_page($framework, $params['search'], $framework->get_context());
1155
1156         $data = $renderable->export_for_template($output);
1157
1158         return $data;
1159     }
1160
1161     /**
1162      * Returns description of data_for_competencies_manage_page() result value.
1163      *
1164      * @return \external_description
1165      */
1166     public static function data_for_competencies_manage_page_returns() {
1167         return new external_single_structure(array (
1168             'framework' => competency_framework_exporter::get_read_structure(),
1169             'canmanage' => new external_value(PARAM_BOOL, 'True if this user has permission to manage competency frameworks'),
1170             'pagecontextid' => new external_value(PARAM_INT, 'Context id for the framework'),
1171             'search' => new external_value(PARAM_RAW, 'Current search string'),
1172             'rulesmodules' => new external_value(PARAM_RAW, 'JSON encoded data for rules')
1173         ));
1174
1175     }
1176
1177     /**
1178      * Returns description of data_for_competency_summary() parameters.
1179      *
1180      * @return \external_function_parameters
1181      */
1182     public static function data_for_competency_summary_parameters() {
1183         $competencyid = new external_value(
1184             PARAM_INT,
1185             'The competency id',
1186             VALUE_REQUIRED
1187         );
1188         $includerelated = new external_value(
1189             PARAM_BOOL,
1190             'Include or not related competencies',
1191             VALUE_DEFAULT,
1192             false
1193         );
1194         $includecourses = new external_value(
1195             PARAM_BOOL,
1196             'Include or not competency courses',
1197             VALUE_DEFAULT,
1198             false
1199         );
1200         $params = array(
1201             'competencyid' => $competencyid,
1202             'includerelated' => $includerelated,
1203             'includecourses' => $includecourses
1204         );
1205         return new external_function_parameters($params);
1206     }
1207
1208     /**
1209      * Loads the data required to render the competency_page template.
1210      *
1211      * @param int $competencyid Competency id.
1212      * @param boolean $includerelated Include or not related competencies.
1213      * @param boolean $includecourses Include or not competency courses.
1214      *
1215      * @return \stdClass
1216      */
1217     public static function data_for_competency_summary($competencyid, $includerelated = false, $includecourses = false) {
1218         global $PAGE;
1219         $params = self::validate_parameters(self::data_for_competency_summary_parameters(),
1220                                             array(
1221                                                 'competencyid' => $competencyid,
1222                                                 'includerelated' => $includerelated,
1223                                                 'includecourses' => $includecourses
1224                                             ));
1225
1226         $competency = api::read_competency($params['competencyid']);
1227         $framework = api::read_framework($competency->get_competencyframeworkid());
1228         $renderable = new output\competency_summary($competency, $framework, $params['includerelated'], $params['includecourses']);
1229         $renderer = $PAGE->get_renderer('tool_lp');
1230
1231         $data = $renderable->export_for_template($renderer);
1232
1233         return $data;
1234     }
1235
1236     /**
1237      * Returns description of data_for_competency_summary_() result value.
1238      *
1239      * @return \external_description
1240      */
1241     public static function data_for_competency_summary_returns() {
1242         return competency_summary_exporter::get_read_structure();
1243     }
1244
1245     /**
1246      * Returns description of set_parent_competency() parameters.
1247      *
1248      * @return \external_function_parameters
1249      */
1250     public static function set_parent_competency_parameters() {
1251         $competencyid = new external_value(
1252             PARAM_INT,
1253             'The competency id',
1254             VALUE_REQUIRED
1255         );
1256         $parentid = new external_value(
1257             PARAM_INT,
1258             'The new competency parent id',
1259             VALUE_REQUIRED
1260         );
1261         $params = array(
1262             'competencyid' => $competencyid,
1263             'parentid' => $parentid
1264         );
1265         return new external_function_parameters($params);
1266     }
1267
1268     /**
1269      * Move the competency to a new parent.
1270      *
1271      * @param int $competencyid Competency id.
1272      * @param int $parentid Parent id.
1273      *
1274      * @return bool
1275      */
1276     public static function set_parent_competency($competencyid, $parentid) {
1277         $params = self::validate_parameters(self::set_parent_competency_parameters(),
1278                                             array(
1279                                                 'competencyid' => $competencyid,
1280                                                 'parentid' => $parentid
1281                                             ));
1282
1283         $competency = api::read_competency($params['competencyid']);
1284         self::validate_context($competency->get_context());
1285
1286         return api::set_parent_competency($params['competencyid'], $params['parentid']);
1287     }
1288
1289     /**
1290      * Returns description of set_parent_competency() result value.
1291      *
1292      * @return \external_description
1293      */
1294     public static function set_parent_competency_returns() {
1295         return new external_value(PARAM_BOOL, 'True if the update was successful');
1296     }
1297
1298     /**
1299      * Returns description of move_up_competency() parameters.
1300      *
1301      * @return \external_function_parameters
1302      */
1303     public static function move_up_competency_parameters() {
1304         $competencyid = new external_value(
1305             PARAM_INT,
1306             'The competency id',
1307             VALUE_REQUIRED
1308         );
1309         $params = array(
1310             'id' => $competencyid,
1311         );
1312         return new external_function_parameters($params);
1313     }
1314
1315     /**
1316      * Change the sort order of a competency.
1317      *
1318      * @param int $competencyid Competency id.
1319      * @return boolean
1320      */
1321     public static function move_up_competency($competencyid) {
1322         $params = self::validate_parameters(self::move_up_competency_parameters(),
1323                                             array(
1324                                                 'id' => $competencyid,
1325                                             ));
1326
1327         $competency = api::read_competency($params['id']);
1328         self::validate_context($competency->get_context());
1329
1330         return api::move_up_competency($params['id']);
1331     }
1332
1333     /**
1334      * Returns description of move_up_competency() result value.
1335      *
1336      * @return \external_description
1337      */
1338     public static function move_up_competency_returns() {
1339         return new external_value(PARAM_BOOL, 'True if the update was successful');
1340     }
1341
1342     /**
1343      * Returns description of move_down_competency() parameters.
1344      *
1345      * @return \external_function_parameters
1346      */
1347     public static function move_down_competency_parameters() {
1348         $competencyid = new external_value(
1349             PARAM_INT,
1350             'The competency id',
1351             VALUE_REQUIRED
1352         );
1353         $params = array(
1354             'id' => $competencyid,
1355         );
1356         return new external_function_parameters($params);
1357     }
1358
1359     /**
1360      * Change the sort order of a competency.
1361      *
1362      * @param int $competencyid Competency id.
1363      * @return boolean
1364      */
1365     public static function move_down_competency($competencyid) {
1366         $params = self::validate_parameters(self::move_down_competency_parameters(),
1367                                             array(
1368                                                 'id' => $competencyid,
1369                                             ));
1370
1371         $competency = api::read_competency($params['id']);
1372         self::validate_context($competency->get_context());
1373
1374         return api::move_down_competency($params['id']);
1375     }
1376
1377     /**
1378      * Returns description of move_down_competency() result value.
1379      *
1380      * @return \external_description
1381      */
1382     public static function move_down_competency_returns() {
1383         return new external_value(PARAM_BOOL, 'True if the update was successful');
1384     }
1385
1386     /**
1387      * Returns description of count_courses_using_competency() parameters.
1388      *
1389      * @return \external_function_parameters
1390      */
1391     public static function count_courses_using_competency_parameters() {
1392         $competencyid = new external_value(
1393             PARAM_INT,
1394             'The competency id',
1395             VALUE_REQUIRED
1396         );
1397         $params = array(
1398             'id' => $competencyid,
1399         );
1400         return new external_function_parameters($params);
1401     }
1402
1403     /**
1404      * Count the courses (visible to this user) that use this competency.
1405      *
1406      * @param int $competencyid Competency id.
1407      * @return int
1408      */
1409     public static function count_courses_using_competency($competencyid) {
1410         $params = self::validate_parameters(self::count_courses_using_competency_parameters(),
1411                                             array(
1412                                                 'id' => $competencyid,
1413                                             ));
1414
1415         $competency = api::read_competency($params['id']);
1416         self::validate_context($competency->get_context());
1417
1418         return api::count_courses_using_competency($params['id']);
1419     }
1420
1421     /**
1422      * Returns description of count_courses_using_competency() result value.
1423      *
1424      * @return \external_description
1425      */
1426     public static function count_courses_using_competency_returns() {
1427         return new external_value(PARAM_INT, 'The number of courses using this competency');
1428     }
1429
1430     /**
1431      * Returns description of list_courses_using_competency() parameters.
1432      *
1433      * @return \external_function_parameters
1434      */
1435     public static function list_courses_using_competency_parameters() {
1436         $competencyid = new external_value(
1437             PARAM_INT,
1438             'The competency id',
1439             VALUE_REQUIRED
1440         );
1441         $params = array(
1442             'id' => $competencyid,
1443         );
1444         return new external_function_parameters($params);
1445     }
1446
1447     /**
1448      * Count the courses (visible to this user) that use this competency.
1449      *
1450      * @param int $competencyid Competency id.
1451      * @return array
1452      */
1453     public static function list_courses_using_competency($competencyid) {
1454         global $PAGE;
1455
1456         $params = self::validate_parameters(self::list_courses_using_competency_parameters(),
1457                                             array(
1458                                                 'id' => $competencyid,
1459                                             ));
1460
1461         $competency = api::read_competency($params['id']);
1462         self::validate_context($competency->get_context());
1463         $output = $PAGE->get_renderer('tool_lp');
1464
1465         $results = array();
1466         $courses = api::list_courses_using_competency($params['id']);
1467         foreach ($courses as $course) {
1468             $context = context_course::instance($course->id);
1469             $exporter = new course_summary_exporter($course, array('context' => $context));
1470             $result = $exporter->export($output);
1471             array_push($results, $result);
1472         }
1473         return $results;
1474     }
1475
1476     /**
1477      * Returns description of list_courses_using_competency() result value.
1478      *
1479      * @return \external_description
1480      */
1481     public static function list_courses_using_competency_returns() {
1482         return new external_multiple_structure(course_summary_exporter::get_read_structure());
1483     }
1484
1485     /**
1486      * Returns description of count_competencies_in_course() parameters.
1487      *
1488      * @return \external_function_parameters
1489      */
1490     public static function count_competencies_in_course_parameters() {
1491         $courseid = new external_value(
1492             PARAM_INT,
1493             'The course id',
1494             VALUE_REQUIRED
1495         );
1496         $params = array(
1497             'id' => $courseid,
1498         );
1499         return new external_function_parameters($params);
1500     }
1501
1502     /**
1503      * Count the competencies (visible to this user) in this course.
1504      *
1505      * @param int $courseid The course id to check.
1506      * @return int
1507      */
1508     public static function count_competencies_in_course($courseid) {
1509         $params = self::validate_parameters(self::count_competencies_in_course_parameters(),
1510                                             array(
1511                                                 'id' => $courseid,
1512                                             ));
1513
1514         self::validate_context(context_course::instance($params['id']));
1515
1516         return api::count_competencies_in_course($params['id']);
1517     }
1518
1519     /**
1520      * Returns description of count_competencies_in_course() result value.
1521      *
1522      * @return \external_description
1523      */
1524     public static function count_competencies_in_course_returns() {
1525         return new external_value(PARAM_INT, 'The number of competencies in this course.');
1526     }
1527
1528     /**
1529      * Returns description of list_course_module_competencies() parameters.
1530      *
1531      * @return \external_function_parameters
1532      */
1533     public static function list_course_module_competencies_parameters() {
1534         $cmid = new external_value(
1535             PARAM_INT,
1536             'The course module id',
1537             VALUE_REQUIRED
1538         );
1539         $params = array(
1540             'cmid' => $cmid
1541         );
1542         return new external_function_parameters($params);
1543     }
1544
1545     /**
1546      * List the course modules using this competency (visible to this user) in this course.
1547      *
1548      * @param int $cmid The course module id to check.
1549      * @return array
1550      */
1551     public static function list_course_module_competencies($cmid) {
1552         global $PAGE;
1553
1554         $params = self::validate_parameters(self::list_course_module_competencies_parameters(),
1555                                             array(
1556                                                 'cmid' => $cmid
1557                                             ));
1558
1559         $context = context_module::instance($params['cmid']);
1560         self::validate_context($context);
1561
1562         $output = $PAGE->get_renderer('tool_lp');
1563
1564         $apiresult = api::list_course_module_competencies($params['cmid']);
1565         $result = array();
1566
1567         foreach ($apiresult as $cmrecord) {
1568             $one = new stdClass();
1569             $exporter = new competency_exporter($cmrecord['competency']);
1570             $one->competency = $exporter->export($output);
1571             $exporter = new course_module_competency_exporter($cmrecord['coursemodulecompetency']);
1572             $one->coursemodulecompetency = $exporter->export($output);
1573
1574             $result[] = (array) $one;
1575         }
1576
1577         return $result;
1578     }
1579
1580     /**
1581      * Returns description of list_course_module_competencies() result value.
1582      *
1583      * @return \external_description
1584      */
1585     public static function list_course_module_competencies_returns() {
1586         return new external_multiple_structure(
1587             new external_single_structure(array(
1588                 'competency' => competency_exporter::get_read_structure(),
1589                 'coursemodulecompetency' => course_module_competency_exporter::get_read_structure()
1590             ))
1591         );
1592     }
1593
1594     /**
1595      * Returns description of list_course_modules_using_competency() parameters.
1596      *
1597      * @return \external_function_parameters
1598      */
1599     public static function list_course_modules_using_competency_parameters() {
1600         $competencyid = new external_value(
1601             PARAM_INT,
1602             'The competency id',
1603             VALUE_REQUIRED
1604         );
1605         $courseid = new external_value(
1606             PARAM_INT,
1607             'The course id',
1608             VALUE_REQUIRED
1609         );
1610         $params = array(
1611             'competencyid' => $competencyid,
1612             'courseid' => $courseid,
1613         );
1614         return new external_function_parameters($params);
1615     }
1616
1617     /**
1618      * List the course modules using this competency (visible to this user) in this course.
1619      *
1620      * @param int $competencyid The competency id to check.
1621      * @param int $courseid The course id to check.
1622      * @return array
1623      */
1624     public static function list_course_modules_using_competency($competencyid, $courseid) {
1625         global $PAGE;
1626
1627         $params = self::validate_parameters(self::list_course_modules_using_competency_parameters(),
1628                                             array(
1629                                                 'competencyid' => $competencyid,
1630                                                 'courseid' => $courseid,
1631                                             ));
1632
1633         $coursecontext = context_course::instance($params['courseid']);
1634         self::validate_context($coursecontext);
1635
1636         $output = $PAGE->get_renderer('tool_lp');
1637
1638         $coursemodules = api::list_course_modules_using_competency($params['competencyid'], $params['courseid']);
1639         $result = array();
1640
1641         $fastmodinfo = get_fast_modinfo($cm->course);
1642
1643         foreach ($coursemodules as $cmid) {
1644             $cminfo = $fastmodinfo->cms[$cmid];
1645             $exporter = new course_module_summary_exporter(null, array('cm' => $cminfo));
1646             $coursemodulesummary = $exporter->export($output);
1647
1648             $result[] = $coursemodulesummary;
1649         }
1650
1651         return $result;
1652     }
1653
1654     /**
1655      * Returns description of list_course_modules_using_competency() result value.
1656      *
1657      * @return \external_description
1658      */
1659     public static function list_course_modules_using_competency_returns() {
1660         return new external_multiple_structure(course_module_summary_exporter::get_read_structure());
1661     }
1662
1663     /**
1664      * Returns description of list_course_competencies() parameters.
1665      *
1666      * @return \external_function_parameters
1667      */
1668     public static function list_course_competencies_parameters() {
1669         $courseid = new external_value(
1670             PARAM_INT,
1671             'The course id',
1672             VALUE_REQUIRED
1673         );
1674         $params = array(
1675             'id' => $courseid,
1676         );
1677         return new external_function_parameters($params);
1678     }
1679
1680     /**
1681      * List the competencies (visible to this user) in this course.
1682      *
1683      * @param int $courseid The course id to check.
1684      * @return array
1685      */
1686     public static function list_course_competencies($courseid) {
1687         global $PAGE;
1688
1689         $params = self::validate_parameters(self::list_course_competencies_parameters(),
1690                                             array(
1691                                                 'id' => $courseid,
1692                                             ));
1693
1694         $coursecontext = context_course::instance($params['id']);
1695         self::validate_context($coursecontext);
1696
1697         $output = $PAGE->get_renderer('tool_lp');
1698
1699         $competencies = api::list_course_competencies($params['id']);
1700         $result = array();
1701
1702         $contextcache = array();
1703         foreach ($competencies as $competency) {
1704             if (!isset($contextcache[$competency['competency']->get_competencyframeworkid()])) {
1705                 $contextcache[$competency['competency']->get_competencyframeworkid()] = $competency['competency']->get_context();
1706             }
1707             $context = $contextcache[$competency['competency']->get_competencyframeworkid()];
1708             $exporter = new competency_exporter($competency['competency'], array('context' => $context));
1709             $competencyrecord = $exporter->export($output);
1710             $exporter = new course_competency_exporter($competency['coursecompetency'], array('context' => $context));
1711             $coursecompetencyrecord = $exporter->export($output);
1712
1713             $result[] = array(
1714                 'competency' => $competencyrecord,
1715                 'coursecompetency' => $coursecompetencyrecord
1716             );
1717         }
1718
1719         return $result;
1720     }
1721
1722     /**
1723      * Returns description of list_course_competencies() result value.
1724      *
1725      * @return \external_description
1726      */
1727     public static function list_course_competencies_returns() {
1728         return new external_multiple_structure(
1729             new external_single_structure(array(
1730                 'competency' => competency_exporter::get_read_structure(),
1731                 'coursecompetency' => course_competency_exporter::get_read_structure()
1732             ))
1733         );
1734
1735     }
1736
1737     /**
1738      * Returns description of add_competency_to_course() parameters.
1739      *
1740      * @return \external_function_parameters
1741      */
1742     public static function add_competency_to_course_parameters() {
1743         $courseid = new external_value(
1744             PARAM_INT,
1745             'The course id',
1746             VALUE_REQUIRED
1747         );
1748         $competencyid = new external_value(
1749             PARAM_INT,
1750             'The competency id',
1751             VALUE_REQUIRED
1752         );
1753         $params = array(
1754             'courseid' => $courseid,
1755             'competencyid' => $competencyid,
1756         );
1757         return new external_function_parameters($params);
1758     }
1759
1760     /**
1761      * Count the competencies (visible to this user) in this course.
1762      *
1763      * @param int $courseid The course id to check.
1764      * @param int $competencyid Competency id.
1765      * @return int
1766      */
1767     public static function add_competency_to_course($courseid, $competencyid) {
1768         $params = self::validate_parameters(self::add_competency_to_course_parameters(),
1769                                             array(
1770                                                 'courseid' => $courseid,
1771                                                 'competencyid' => $competencyid,
1772                                             ));
1773
1774         self::validate_context(context_course::instance($params['courseid']));
1775
1776         return api::add_competency_to_course($params['courseid'], $params['competencyid']);
1777     }
1778
1779     /**
1780      * Returns description of add_competency_to_course() result value.
1781      *
1782      * @return \external_description
1783      */
1784     public static function add_competency_to_course_returns() {
1785         return new external_value(PARAM_BOOL, 'True if successful.');
1786     }
1787
1788     /**
1789      * Returns description of remove_competency_from_course() parameters.
1790      *
1791      * @return \external_function_parameters
1792      */
1793     public static function remove_competency_from_course_parameters() {
1794         $courseid = new external_value(
1795             PARAM_INT,
1796             'The course id',
1797             VALUE_REQUIRED
1798         );
1799         $competencyid = new external_value(
1800             PARAM_INT,
1801             'The competency id',
1802             VALUE_REQUIRED
1803         );
1804         $params = array(
1805             'courseid' => $courseid,
1806             'competencyid' => $competencyid,
1807         );
1808         return new external_function_parameters($params);
1809     }
1810
1811     /**
1812      * Count the competencies (visible to this user) in this course.
1813      *
1814      * @param int $courseid The course id to check.
1815      * @param int $competencyid Competency id.
1816      * @return int
1817      */
1818     public static function remove_competency_from_course($courseid, $competencyid) {
1819         $params = self::validate_parameters(self::remove_competency_from_course_parameters(),
1820                                             array(
1821                                                 'courseid' => $courseid,
1822                                                 'competencyid' => $competencyid,
1823                                             ));
1824
1825         self::validate_context(context_course::instance($params['courseid']));
1826
1827         return api::remove_competency_from_course($params['courseid'], $params['competencyid']);
1828     }
1829
1830     /**
1831      * Returns description of remove_competency_from_course() result value.
1832      *
1833      * @return \external_description
1834      */
1835     public static function remove_competency_from_course_returns() {
1836         return new external_value(PARAM_BOOL, 'True if successful.');
1837     }
1838
1839     /**
1840      * Returns description of data_for_course_competenies_page() parameters.
1841      *
1842      * @return \external_function_parameters
1843      */
1844     public static function data_for_course_competencies_page_parameters() {
1845         $courseid = new external_value(
1846             PARAM_INT,
1847             'The course id',
1848             VALUE_REQUIRED
1849         );
1850         $params = array('courseid' => $courseid);
1851         return new external_function_parameters($params);
1852     }
1853
1854     /**
1855      * Loads the data required to render the course_competencies_page template.
1856      *
1857      * @param int $courseid The course id to check.
1858      * @return boolean
1859      */
1860     public static function data_for_course_competencies_page($courseid) {
1861         global $PAGE;
1862         $params = self::validate_parameters(self::data_for_course_competencies_page_parameters(),
1863                                             array(
1864                                                 'courseid' => $courseid,
1865                                             ));
1866         self::validate_context(context_course::instance($params['courseid']));
1867
1868         $renderable = new output\course_competencies_page($params['courseid']);
1869         $renderer = $PAGE->get_renderer('tool_lp');
1870
1871         $data = $renderable->export_for_template($renderer);
1872
1873         return $data;
1874     }
1875
1876     /**
1877      * Returns description of data_for_course_competencies_page() result value.
1878      *
1879      * @return \external_description
1880      */
1881     public static function data_for_course_competencies_page_returns() {
1882         $uc = user_competency_exporter::get_read_structure();
1883         $uc->required = VALUE_OPTIONAL;
1884
1885         return new external_single_structure(array (
1886             'courseid' => new external_value(PARAM_INT, 'The current course id'),
1887             'pagecontextid' => new external_value(PARAM_INT, 'The current page context ID.'),
1888             'gradableuserid' => new external_value(PARAM_INT, 'Current user id, if the user is a gradable user.', VALUE_OPTIONAL),
1889             'canmanagecompetencyframeworks' => new external_value(PARAM_BOOL, 'User can manage competency frameworks'),
1890             'canmanagecoursecompetencies' => new external_value(PARAM_BOOL, 'User can manage linked course competencies'),
1891             'competencies' => new external_multiple_structure(new external_single_structure(array(
1892                 'competency' => competency_exporter::get_read_structure(),
1893                 'coursecompetency' => course_competency_exporter::get_read_structure(),
1894                 'coursemodules' => new external_multiple_structure(course_module_summary_exporter::get_read_structure()),
1895                 'usercompetency' => $uc,
1896                 'ruleoutcomeoptions' => new external_multiple_structure(
1897                     new external_single_structure(array(
1898                         'value' => new external_value(PARAM_INT, 'The option value'),
1899                         'text' => new external_value(PARAM_NOTAGS, 'The name of the option'),
1900                         'selected' => new external_value(PARAM_BOOL, 'If this is the currently selected option'),
1901                 ))),
1902                 'comppath' => competency_path_exporter::get_read_structure(),
1903             ))),
1904             'manageurl' => new external_value(PARAM_LOCALURL, 'Url to the manage competencies page.'),
1905         ));
1906
1907     }
1908
1909     /**
1910      * Returns description of reorder_course_competency() parameters.
1911      *
1912      * @return \external_function_parameters
1913      */
1914     public static function reorder_course_competency_parameters() {
1915         $courseid = new external_value(
1916             PARAM_INT,
1917             'The course id',
1918             VALUE_REQUIRED
1919         );
1920         $competencyidfrom = new external_value(
1921             PARAM_INT,
1922             'The competency id we are moving',
1923             VALUE_REQUIRED
1924         );
1925         $competencyidto = new external_value(
1926             PARAM_INT,
1927             'The competency id we are moving to',
1928             VALUE_REQUIRED
1929         );
1930         $params = array(
1931             'courseid' => $courseid,
1932             'competencyidfrom' => $competencyidfrom,
1933             'competencyidto' => $competencyidto,
1934         );
1935         return new external_function_parameters($params);
1936     }
1937
1938     /**
1939      * Change the order of course competencies.
1940      *
1941      * @param int $courseid The course id
1942      * @param int $competencyidfrom The competency to move.
1943      * @param int $competencyidto The competency to move to.
1944      * @return bool
1945      */
1946     public static function reorder_course_competency($courseid, $competencyidfrom, $competencyidto) {
1947         $params = self::validate_parameters(self::reorder_course_competency_parameters(),
1948                                             array(
1949                                                 'courseid' => $courseid,
1950                                                 'competencyidfrom' => $competencyidfrom,
1951                                                 'competencyidto' => $competencyidto,
1952                                             ));
1953         self::validate_context(context_course::instance($params['courseid']));
1954
1955         return api::reorder_course_competency($params['courseid'], $params['competencyidfrom'], $params['competencyidto']);
1956     }
1957
1958     /**
1959      * Returns description of reorder_course_competency() result value.
1960      *
1961      * @return \external_description
1962      */
1963     public static function reorder_course_competency_returns() {
1964         return new external_value(PARAM_BOOL, 'True if successful.');
1965     }
1966
1967     /**
1968      * Returns description of reorder_template_competency() parameters.
1969      *
1970      * @return \external_function_parameters
1971      */
1972     public static function reorder_template_competency_parameters() {
1973         $templateid = new external_value(
1974             PARAM_INT,
1975             'The template id',
1976             VALUE_REQUIRED
1977         );
1978         $competencyidfrom = new external_value(
1979             PARAM_INT,
1980             'The competency id we are moving',
1981             VALUE_REQUIRED
1982         );
1983         $competencyidto = new external_value(
1984             PARAM_INT,
1985             'The competency id we are moving to',
1986             VALUE_REQUIRED
1987         );
1988         $params = array(
1989             'templateid' => $templateid,
1990             'competencyidfrom' => $competencyidfrom,
1991             'competencyidto' => $competencyidto,
1992         );
1993         return new external_function_parameters($params);
1994     }
1995
1996     /**
1997      * Change the order of template competencies.
1998      *
1999      * @param int $templateid The template id
2000      * @param int $competencyidfrom The competency to move.
2001      * @param int $competencyidto The competency to move to.
2002      * @return bool
2003      */
2004     public static function reorder_template_competency($templateid, $competencyidfrom, $competencyidto) {
2005         $params = self::validate_parameters(self::reorder_template_competency_parameters(),
2006             array(
2007                 'templateid' => $templateid,
2008                 'competencyidfrom' => $competencyidfrom,
2009                 'competencyidto' => $competencyidto,
2010             ));
2011
2012         $template = api::read_template($params['templateid']);
2013         self::validate_context($template->get_context());
2014
2015         return api::reorder_template_competency($params['templateid'], $params['competencyidfrom'], $params['competencyidto']);
2016     }
2017
2018     /**
2019      * Returns description of reorder_template_competency() result value.
2020      *
2021      * @return \external_description
2022      */
2023     public static function reorder_template_competency_returns() {
2024         return new external_value(PARAM_BOOL, 'True if successful.');
2025     }
2026
2027     /**
2028      * Returns description of create_template() parameters.
2029      *
2030      * @return \external_function_parameters
2031      */
2032     public static function create_template_parameters() {
2033         $structure = template_exporter::get_create_structure();
2034         $params = array('template' => $structure);
2035         return new external_function_parameters($params);
2036     }
2037
2038     /**
2039      * Create a new learning plan template
2040      *
2041      * @param array $template The list of fields for the template.
2042      * @return \stdClass Record of new template.
2043      */
2044     public static function create_template($template) {
2045         global $PAGE;
2046
2047         $params = self::validate_parameters(self::create_template_parameters(),
2048                                             array('template' => $template));
2049         $params = $params['template'];
2050         $context = self::get_context_from_params($params);
2051         self::validate_context($context);
2052         $output = $PAGE->get_renderer('tool_lp');
2053
2054         unset($params['contextlevel']);
2055         unset($params['instanceid']);
2056         $params = (object) $params;
2057         $params->contextid = $context->id;
2058
2059         $result = api::create_template($params);
2060         $exporter = new template_exporter($result);
2061         $record = $exporter->export($output);
2062         return $record;
2063     }
2064
2065     /**
2066      * Returns description of create_template() result value.
2067      *
2068      * @return \external_description
2069      */
2070     public static function create_template_returns() {
2071         return template_exporter::get_read_structure();
2072     }
2073
2074     /**
2075      * Returns description of read_template() parameters.
2076      *
2077      * @return \external_function_parameters
2078      */
2079     public static function read_template_parameters() {
2080         $id = new external_value(
2081             PARAM_INT,
2082             'Data base record id for the template',
2083             VALUE_REQUIRED
2084         );
2085
2086         $params = array(
2087             'id' => $id,
2088         );
2089         return new external_function_parameters($params);
2090     }
2091
2092     /**
2093      * Read a learning plan template by id.
2094      *
2095      * @param int $id The id of the template.
2096      * @return \stdClass
2097      */
2098     public static function read_template($id) {
2099         global $PAGE;
2100
2101         $params = self::validate_parameters(self::read_template_parameters(),
2102                                             array(
2103                                                 'id' => $id,
2104                                             ));
2105
2106         $template = api::read_template($params['id']);
2107         self::validate_context($template->get_context());
2108         $output = $PAGE->get_renderer('tool_lp');
2109
2110         $exporter = new template_exporter($template);
2111         $record = $exporter->export($output);
2112         return $record;
2113     }
2114
2115     /**
2116      * Returns description of read_template() result value.
2117      *
2118      * @return \external_description
2119      */
2120     public static function read_template_returns() {
2121         return template_exporter::get_read_structure();
2122     }
2123
2124     /**
2125      * Returns description of delete_template() parameters.
2126      *
2127      * @return \external_function_parameters
2128      */
2129     public static function delete_template_parameters() {
2130         $id = new external_value(
2131             PARAM_INT,
2132             'Data base record id for the template',
2133             VALUE_REQUIRED
2134         );
2135
2136         $deleteplans = new external_value(
2137             PARAM_BOOL,
2138             'Boolean to indicate if plans must be deleted',
2139             VALUE_REQUIRED
2140         );
2141
2142         $params = array(
2143             'id' => $id,
2144             'deleteplans' => $deleteplans
2145         );
2146         return new external_function_parameters($params);
2147     }
2148
2149     /**
2150      * Delete a learning plan template
2151      *
2152      * @param int $id The learning plan template id
2153      * @param boolean $deleteplans True to delete the plans associated to template or false to unlink them
2154      * @return boolean
2155      */
2156     public static function delete_template($id, $deleteplans = true) {
2157         $params = self::validate_parameters(self::delete_template_parameters(),
2158                                             array(
2159                                                 'id' => $id,
2160                                                 'deleteplans' => $deleteplans,
2161                                             ));
2162
2163         $template = api::read_template($params['id']);
2164         self::validate_context($template->get_context());
2165
2166         return api::delete_template($params['id'], $params['deleteplans']);
2167     }
2168
2169     /**
2170      * Returns description of delete_template() result value.
2171      *
2172      * @return \external_description
2173      */
2174     public static function delete_template_returns() {
2175         return new external_value(PARAM_BOOL, 'True if the delete was successful');
2176     }
2177
2178     /**
2179      * Returns description of update_template() parameters.
2180      *
2181      * @return \external_function_parameters
2182      */
2183     public static function update_template_parameters() {
2184         $structure = template_exporter::get_update_structure();
2185         $params = array('template' => $structure);
2186         return new external_function_parameters($params);
2187     }
2188
2189     /**
2190      * Update an existing learning plan template
2191      *
2192      * @param array $template The list of fields for the template.
2193      * @return boolean
2194      */
2195     public static function update_template($template) {
2196
2197         $params = self::validate_parameters(self::update_template_parameters(),
2198                                             array('template' => $template));
2199         $params = $params['template'];
2200         $template = api::read_template($params['id']);
2201         self::validate_context($template->get_context());
2202
2203         $params = (object) $params;
2204
2205         return api::update_template($params);
2206     }
2207
2208     /**
2209      * Returns description of update_template() result value.
2210      *
2211      * @return \external_description
2212      */
2213     public static function update_template_returns() {
2214         return new external_value(PARAM_BOOL, 'True if the update was successful');
2215     }
2216
2217     /**
2218      * Returns description of duplicate_template() parameters.
2219      *
2220      * @return \external_function_parameters
2221      */
2222     public static function duplicate_template_parameters() {
2223         $templateid = new external_value(
2224             PARAM_INT,
2225             'The template id',
2226             VALUE_REQUIRED
2227         );
2228
2229         $params = array(
2230             'id' => $templateid
2231         );
2232         return new external_function_parameters($params);
2233     }
2234
2235     /**
2236      * Duplicate a learning plan template.
2237      *
2238      * @param int $id the id of the learning plan template to duplicate
2239      * @return boolean Record of new template.
2240      */
2241     public static function duplicate_template($id) {
2242         global $PAGE;
2243
2244         $params = self::validate_parameters(self::duplicate_template_parameters(),
2245                                             array(
2246                                                 'id' => $id,
2247                                             ));
2248
2249         $template = api::read_template($params['id']);
2250         self::validate_context($template->get_context());
2251         $output = $PAGE->get_renderer('tool_lp');
2252
2253         $result = api::duplicate_template($params['id']);
2254         $exporter = new template_exporter($result);
2255         return $exporter->export($output);
2256     }
2257
2258     /**
2259      * Returns description of duplicate_template() result value.
2260      *
2261      * @return \external_description
2262      */
2263     public static function duplicate_template_returns() {
2264         return template_exporter::get_read_structure();
2265     }
2266
2267     /**
2268      * Returns description of list_templates() parameters.
2269      *
2270      * @return \external_function_parameters
2271      */
2272     public static function list_templates_parameters() {
2273         $sort = new external_value(
2274             PARAM_ALPHANUMEXT,
2275             'Column to sort by.',
2276             VALUE_DEFAULT,
2277             ''
2278         );
2279         $order = new external_value(
2280             PARAM_ALPHA,
2281             'Sort direction. Should be either ASC or DESC',
2282             VALUE_DEFAULT,
2283             ''
2284         );
2285         $skip = new external_value(
2286             PARAM_INT,
2287             'Skip this number of records before returning results',
2288             VALUE_DEFAULT,
2289             0
2290         );
2291         $limit = new external_value(
2292             PARAM_INT,
2293             'Return this number of records at most.',
2294             VALUE_DEFAULT,
2295             0
2296         );
2297         $includes = new external_value(
2298             PARAM_ALPHA,
2299             'What other contexts to fetch the templates from. (children, parents, self)',
2300             VALUE_DEFAULT,
2301             'children'
2302         );
2303         $onlyvisible = new external_value(
2304             PARAM_BOOL,
2305             'If should list only visible templates',
2306             VALUE_DEFAULT,
2307             false
2308         );
2309
2310         $params = array(
2311             'sort' => $sort,
2312             'order' => $order,
2313             'skip' => $skip,
2314             'limit' => $limit,
2315             'context' => self::get_context_parameters(),
2316             'includes' => $includes,
2317             'onlyvisible' => $onlyvisible
2318         );
2319         return new external_function_parameters($params);
2320     }
2321
2322     /**
2323      * List the existing learning plan templates
2324      *
2325      * @param string $sort Field to sort by.
2326      * @param string $order Sort order.
2327      * @param int $skip Limitstart.
2328      * @param int $limit Number of rows to return.
2329      * @param array $context
2330      * @param bool $includes
2331      * @param bool $onlyvisible
2332      *
2333      * @return array
2334      */
2335     public static function list_templates($sort, $order, $skip, $limit, $context, $includes, $onlyvisible) {
2336         global $PAGE;
2337
2338         $params = self::validate_parameters(self::list_templates_parameters(),
2339                                             array(
2340                                                 'sort' => $sort,
2341                                                 'order' => $order,
2342                                                 'skip' => $skip,
2343                                                 'limit' => $limit,
2344                                                 'context' => $context,
2345                                                 'includes' => $includes,
2346                                                 'onlyvisible' => $onlyvisible
2347                                             ));
2348
2349         $context = self::get_context_from_params($params['context']);
2350         self::validate_context($context);
2351         $output = $PAGE->get_renderer('tool_lp');
2352
2353         if ($params['order'] !== '' && $params['order'] !== 'ASC' && $params['order'] !== 'DESC') {
2354             throw new invalid_parameter_exception('Invalid order param. Must be ASC, DESC or empty.');
2355         }
2356
2357         $results = api::list_templates($params['sort'],
2358                                        $params['order'],
2359                                        $params['skip'],
2360                                        $params['limit'],
2361                                        $context,
2362                                        $params['includes'],
2363                                        $params['onlyvisible']);
2364         $records = array();
2365         foreach ($results as $result) {
2366             $exporter = new template_exporter($result);
2367             $record = $exporter->export($output);
2368             array_push($records, $record);
2369         }
2370         return $records;
2371     }
2372
2373     /**
2374      * Returns description of list_templates() result value.
2375      *
2376      * @return \external_description
2377      */
2378     public static function list_templates_returns() {
2379         return new external_multiple_structure(template_exporter::get_read_structure());
2380     }
2381
2382     /**
2383      * Returns description of count_templates() parameters.
2384      *
2385      * @return \external_function_parameters
2386      */
2387     public static function count_templates_parameters() {
2388         $includes = new external_value(
2389             PARAM_ALPHA,
2390             'What other contextes to fetch the frameworks from. (children, parents, self)',
2391             VALUE_DEFAULT,
2392             'children'
2393         );
2394
2395         $params = array(
2396             'context' => self::get_context_parameters(),
2397             'includes' => $includes
2398         );
2399         return new external_function_parameters($params);
2400     }
2401
2402     /**
2403      * Count the existing learning plan templates
2404      *
2405      * @param array $context
2406      * @param string $includes
2407      * @return int
2408      */
2409     public static function count_templates($context, $includes) {
2410         $params = self::validate_parameters(self::count_templates_parameters(),
2411                                             array(
2412                                                 'context' => $context,
2413                                                 'includes' => $includes
2414                                             ));
2415         $context = self::get_context_from_params($params['context']);
2416         self::validate_context($context);
2417
2418         return api::count_templates($context, $includes);
2419     }
2420
2421     /**
2422      * Returns description of count_templates() result value.
2423      *
2424      * @return \external_description
2425      */
2426     public static function count_templates_returns() {
2427         return new external_value(PARAM_INT, 'The number of learning plan templates found.');
2428     }
2429
2430     /**
2431      * Returns description of data_for_templates_manage_page() parameters.
2432      *
2433      * @return \external_function_parameters
2434      */
2435     public static function data_for_templates_manage_page_parameters() {
2436         $params = array('pagecontext' => self::get_context_parameters());
2437         return new external_function_parameters($params);
2438     }
2439
2440     /**
2441      * Loads the data required to render the templates_manage_page template.
2442      *
2443      * @param array $pagecontext The page context info.
2444      * @return boolean
2445      */
2446     public static function data_for_templates_manage_page($pagecontext) {
2447         global $PAGE;
2448
2449         $params = self::validate_parameters(self::data_for_templates_manage_page_parameters(), array(
2450             'pagecontext' => $pagecontext
2451         ));
2452         $context = self::get_context_from_params($params['pagecontext']);
2453         self::validate_context($context);
2454
2455         $renderable = new output\manage_templates_page($context);
2456         $renderer = $PAGE->get_renderer('tool_lp');
2457
2458         $data = $renderable->export_for_template($renderer);
2459
2460         return $data;
2461     }
2462
2463     /**
2464      * Returns description of data_for_templates_manage_page() result value.
2465      *
2466      * @return \external_description
2467      */
2468     public static function data_for_templates_manage_page_returns() {
2469         return new external_single_structure(array (
2470             'templates' => new external_multiple_structure(
2471                 template_exporter::get_read_structure()
2472             ),
2473             'pluginbaseurl' => new external_value(PARAM_LOCALURL, 'Url to the tool_lp plugin folder on this Moodle site'),
2474             'navigation' => new external_multiple_structure(
2475                 new external_value(PARAM_RAW, 'HTML for a navigation item that should be on this page')
2476             ),
2477             'pagecontextid' => new external_value(PARAM_INT, 'The page context id'),
2478             'canmanage' => new external_value(PARAM_BOOL, 'Whether the user manage the templates')
2479         ));
2480
2481     }
2482
2483     /**
2484      * Returns description of count_templates_using_competency() parameters.
2485      *
2486      * @return \external_function_parameters
2487      */
2488     public static function count_templates_using_competency_parameters() {
2489         $competencyid = new external_value(
2490             PARAM_INT,
2491             'The competency id',
2492             VALUE_REQUIRED
2493         );
2494         $params = array(
2495             'id' => $competencyid,
2496         );
2497         return new external_function_parameters($params);
2498     }
2499
2500     /**
2501      * Count the learning plan templates (visible to this user) that use this competency.
2502      *
2503      * @param int $competencyid Competency id.
2504      * @return int
2505      */
2506     public static function count_templates_using_competency($competencyid) {
2507         $params = self::validate_parameters(self::count_templates_using_competency_parameters(),
2508                                             array(
2509                                                 'id' => $competencyid,
2510                                             ));
2511
2512         $competency = api::read_competency($params['id']);
2513         self::validate_context($competency->get_context());
2514
2515         return api::count_templates_using_competency($params['id']);
2516     }
2517
2518     /**
2519      * Returns description of count_templates_using_competency() result value.
2520      *
2521      * @return \external_description
2522      */
2523     public static function count_templates_using_competency_returns() {
2524         return new external_value(PARAM_INT, 'The number of learning plan templates using this competency');
2525     }
2526
2527     /**
2528      * Returns description of list_templates_using_competency() parameters.
2529      *
2530      * @return \external_function_parameters
2531      */
2532     public static function list_templates_using_competency_parameters() {
2533         $competencyid = new external_value(
2534             PARAM_INT,
2535             'The competency id',
2536             VALUE_REQUIRED
2537         );
2538         $params = array(
2539             'id' => $competencyid,
2540         );
2541         return new external_function_parameters($params);
2542     }
2543
2544     /**
2545      * List the learning plan templates (visible to this user) that use this competency.
2546      *
2547      * @param int $competencyid Competency id.
2548      * @return array
2549      */
2550     public static function list_templates_using_competency($competencyid) {
2551         global $PAGE;
2552
2553         $params = self::validate_parameters(self::list_templates_using_competency_parameters(),
2554                                             array(
2555                                                 'id' => $competencyid,
2556                                             ));
2557
2558         $competency = api::read_competency($params['id']);
2559         self::validate_context($competency->get_context());
2560         $output = $PAGE->get_renderer('tool_lp');
2561
2562         $templates = api::list_templates_using_competency($params['id']);
2563         $records = array();
2564
2565         foreach ($templates as $template) {
2566             $exporter = new template_exporter($template);
2567             $record = $exporter->export($output);
2568             $records[] = $record;
2569         }
2570
2571         return $records;
2572     }
2573
2574     /**
2575      * Returns description of list_templates_using_competency() result value.
2576      *
2577      * @return \external_description
2578      */
2579     public static function list_templates_using_competency_returns() {
2580         return new external_multiple_structure(template_exporter::get_read_structure());
2581     }
2582
2583     /**
2584      * Returns description of count_competencies_in_template() parameters.
2585      *
2586      * @return \external_function_parameters
2587      */
2588     public static function count_competencies_in_template_parameters() {
2589         $templateid = new external_value(
2590             PARAM_INT,
2591             'The template id',
2592             VALUE_REQUIRED
2593         );
2594         $params = array(
2595             'id' => $templateid,
2596         );
2597         return new external_function_parameters($params);
2598     }
2599
2600     /**
2601      * Count the competencies (visible to this user) in this learning plan template.
2602      *
2603      * @param int $templateid The template id to check
2604      * @return int
2605      */
2606     public static function count_competencies_in_template($templateid) {
2607         global $PAGE;
2608         $params = self::validate_parameters(self::count_competencies_in_template_parameters(),
2609                                             array(
2610                                                 'id' => $templateid,
2611                                             ));
2612         $template = api::read_template($params['id']);
2613         self::validate_context($template->get_context());
2614
2615         return api::count_competencies_in_template($params['id']);
2616     }
2617
2618     /**
2619      * Returns description of count_competencies_in_template() result value.
2620      *
2621      * @return \external_description
2622      */
2623     public static function count_competencies_in_template_returns() {
2624         return new external_value(PARAM_INT, 'The number of competencies in this learning plan template.');
2625     }
2626
2627     /**
2628      * Returns description of list_competencies_in_template() parameters.
2629      *
2630      * @return \external_function_parameters
2631      */
2632     public static function list_competencies_in_template_parameters() {
2633         $templateid = new external_value(
2634             PARAM_INT,
2635             'The template id',
2636             VALUE_REQUIRED
2637         );
2638         $params = array(
2639             'id' => $templateid,
2640         );
2641         return new external_function_parameters($params);
2642     }
2643
2644     /**
2645      * List the competencies (visible to this user) in this learning plan template.
2646      *
2647      * @param int $templateid Template id.
2648      * @return array
2649      */
2650     public static function list_competencies_in_template($templateid) {
2651         global $PAGE;
2652
2653         $params = self::validate_parameters(self::list_competencies_in_template_parameters(),
2654                                             array(
2655                                                 'id' => $templateid,
2656                                             ));
2657
2658         $template = api::read_template($params['id']);
2659         self::validate_context($template->get_context());
2660         $output = $PAGE->get_renderer('tool_lp');
2661
2662         $competencies = api::list_competencies_in_template($params['id']);
2663         $results = array();
2664         $contextcache = array();
2665
2666         foreach ($competencies as $competency) {
2667             if (!isset($contextcache[$competency->get_competencyframeworkid()])) {
2668                 $contextcache[$competency->get_competencyframeworkid()] = $competency->get_context();
2669             }
2670             $context = $contextcache[$competency->get_competencyframeworkid()];
2671             $exporter = new competency_exporter($competency, array('context' => $context));
2672             $record = $exporter->export($output);
2673             array_push($results, $record);
2674         }
2675         return $results;
2676     }
2677
2678     /**
2679      * Returns description of list_competencies_in_template() result value.
2680      *
2681      * @return \external_description
2682      */
2683     public static function list_competencies_in_template_returns() {
2684         return new external_multiple_structure(competency_exporter::get_read_structure());
2685     }
2686
2687     /**
2688      * Returns description of add_competency_to_template() parameters.
2689      *
2690      * @return \external_function_parameters
2691      */
2692     public static function add_competency_to_template_parameters() {
2693         $templateid = new external_value(
2694             PARAM_INT,
2695             'The template id',
2696             VALUE_REQUIRED
2697         );
2698         $competencyid = new external_value(
2699             PARAM_INT,
2700             'The competency id',
2701             VALUE_REQUIRED
2702         );
2703         $params = array(
2704             'templateid' => $templateid,
2705             'competencyid' => $competencyid,
2706         );
2707         return new external_function_parameters($params);
2708     }
2709
2710     /**
2711      * Count the competencies (visible to this user) in this template.
2712      *
2713      * @param int $templateid Template id.
2714      * @param int $competencyid Competency id.
2715      * @return int
2716      */
2717     public static function add_competency_to_template($templateid, $competencyid) {
2718         global $PAGE;
2719         $params = self::validate_parameters(self::add_competency_to_template_parameters(),
2720                                             array(
2721                                                 'templateid' => $templateid,
2722                                                 'competencyid' => $competencyid,
2723                                             ));
2724
2725         $template = api::read_template($params['templateid']);
2726         self::validate_context($template->get_context());
2727
2728         return api::add_competency_to_template($params['templateid'], $params['competencyid']);
2729     }
2730
2731     /**
2732      * Returns description of add_competency_to_template() result value.
2733      *
2734      * @return \external_description
2735      */
2736     public static function add_competency_to_template_returns() {
2737         return new external_value(PARAM_BOOL, 'True if successful.');
2738     }
2739
2740     /**
2741      * Returns description of add_competency_to_plan() parameters.
2742      *
2743      * @return \external_function_parameters
2744      */
2745     public static function add_competency_to_plan_parameters() {
2746         $planid = new external_value(
2747             PARAM_INT,
2748             'The plan id',
2749             VALUE_REQUIRED
2750         );
2751         $competencyid = new external_value(
2752             PARAM_INT,
2753             'The competency id',
2754             VALUE_REQUIRED
2755         );
2756         $params = array(
2757             'planid' => $planid,
2758             'competencyid' => $competencyid,
2759         );
2760         return new external_function_parameters($params);
2761     }
2762
2763     /**
2764      * add competency to a learning plan.
2765      *
2766      * @param int $planid Plan id.
2767      * @param int $competencyid Competency id.
2768      * @return int
2769      */
2770     public static function add_competency_to_plan($planid, $competencyid) {
2771         $params = self::validate_parameters(self::add_competency_to_plan_parameters(),
2772                                             array(
2773                                                 'planid' => $planid,
2774                                                 'competencyid' => $competencyid,
2775                                             ));
2776
2777         $plan = api::read_plan($params['planid']);
2778         self::validate_context($plan->get_context());
2779
2780         return api::add_competency_to_plan($params['planid'], $params['competencyid']);
2781     }
2782
2783     /**
2784      * Returns description of add_competency_to_plan() result value.
2785      *
2786      * @return \external_description
2787      */
2788     public static function add_competency_to_plan_returns() {
2789         return new external_value(PARAM_BOOL, 'True if successful.');
2790     }
2791
2792     /**
2793      * Returns description of remove_competency_from_plan() parameters.
2794      *
2795      * @return \external_function_parameters
2796      */
2797     public static function remove_competency_from_plan_parameters() {
2798         $planid = new external_value(
2799             PARAM_INT,
2800             'The plan id',
2801             VALUE_REQUIRED
2802         );
2803         $competencyid = new external_value(
2804             PARAM_INT,
2805             'The competency id',
2806             VALUE_REQUIRED
2807         );
2808         $params = array(
2809             'planid' => $planid,
2810             'competencyid' => $competencyid,
2811         );
2812         return new external_function_parameters($params);
2813     }
2814
2815     /**
2816      * Remove a competency from plan.
2817      *
2818      * @param int $planid Plan id.
2819      * @param int $competencyid Competency id.
2820      * @return int
2821      */
2822     public static function remove_competency_from_plan($planid, $competencyid) {
2823         $params = self::validate_parameters(self::remove_competency_from_plan_parameters(),
2824                                             array(
2825                                                 'planid' => $planid,
2826                                                 'competencyid' => $competencyid,
2827                                             ));
2828         $plan = api::read_plan($params['planid']);
2829         self::validate_context($plan->get_context());
2830
2831         return api::remove_competency_from_plan($params['planid'], $params['competencyid']);
2832     }
2833
2834     /**
2835      * Returns description of remove_competency_from_plan() result value.
2836      *
2837      * @return \external_description
2838      */
2839     public static function remove_competency_from_plan_returns() {
2840         return new external_value(PARAM_BOOL, 'True if successful.');
2841     }
2842
2843     /**
2844      * Returns description of remove_competency_from_template() parameters.
2845      *
2846      * @return \external_function_parameters
2847      */
2848     public static function remove_competency_from_template_parameters() {
2849         $templateid = new external_value(
2850             PARAM_INT,
2851             'The template id',
2852             VALUE_REQUIRED
2853         );
2854         $competencyid = new external_value(
2855             PARAM_INT,
2856             'The competency id',
2857             VALUE_REQUIRED
2858         );
2859         $params = array(
2860             'templateid' => $templateid,
2861             'competencyid' => $competencyid,
2862         );
2863         return new external_function_parameters($params);
2864     }
2865
2866     /**
2867      * Returns description of reorder_plan_competency() parameters.
2868      *
2869      * @return \external_function_parameters
2870      */
2871     public static function reorder_plan_competency_parameters() {
2872         $planid = new external_value(
2873             PARAM_INT,
2874             'The plan id',
2875             VALUE_REQUIRED
2876         );
2877         $competencyidfrom = new external_value(
2878             PARAM_INT,
2879             'The competency id we are moving',
2880             VALUE_REQUIRED
2881         );
2882         $competencyidto = new external_value(
2883             PARAM_INT,
2884             'The competency id we are moving to',
2885             VALUE_REQUIRED
2886         );
2887         $params = array(
2888             'planid' => $planid,
2889             'competencyidfrom' => $competencyidfrom,
2890             'competencyidto' => $competencyidto,
2891         );
2892         return new external_function_parameters($params);
2893     }
2894
2895     /**
2896      * Change the order of plan competencies.
2897      *
2898      * @param int $planid The plan id
2899      * @param int $competencyidfrom The competency to move.
2900      * @param int $competencyidto The competency to move to.
2901      * @return bool
2902      */
2903     public static function reorder_plan_competency($planid, $competencyidfrom, $competencyidto) {
2904         $params = self::validate_parameters(self::reorder_plan_competency_parameters(),
2905             array(
2906                 'planid' => $planid,
2907                 'competencyidfrom' => $competencyidfrom,
2908                 'competencyidto' => $competencyidto,
2909             ));
2910
2911         $plan = api::read_plan($params['planid']);
2912         self::validate_context($plan->get_context());
2913
2914         return api::reorder_plan_competency($params['planid'], $params['competencyidfrom'], $params['competencyidto']);
2915     }
2916
2917     /**
2918      * Returns description of reorder_plan_competency() result value.
2919      *
2920      * @return \external_description
2921      */
2922     public static function reorder_plan_competency_returns() {
2923         return new external_value(PARAM_BOOL, 'True if successful.');
2924     }
2925
2926     /**
2927      * Returns description of external function parameters.
2928      *
2929      * @return \external_function_parameters
2930      */
2931     public static function user_competency_cancel_review_request_parameters() {
2932         return new external_function_parameters(array(
2933             'userid' => new external_value(PARAM_INT, 'The user ID'),
2934             'competencyid' => new external_value(PARAM_INT, 'The competency ID'),
2935         ));
2936     }
2937
2938     /**
2939      * External function user_competency_cancel_review_request.
2940      *
2941      * @param int $userid The user ID.
2942      * @param int $competencyid The competency ID.
2943      * @return boolean
2944      */
2945     public static function user_competency_cancel_review_request($userid, $competencyid) {
2946         $params = self::validate_parameters(self::user_competency_cancel_review_request_parameters(), array(
2947             'userid' => $userid,
2948             'competencyid' => $competencyid
2949         ));
2950
2951         $context = context_user::instance($params['userid']);
2952         self::validate_context($context);
2953
2954         return api::user_competency_cancel_review_request($userid, $competencyid);
2955     }
2956
2957     /**
2958      * Returns description of external function result value.
2959      *
2960      * @return \external_function_parameters
2961      */
2962     public static function user_competency_cancel_review_request_returns() {
2963         return new external_value(PARAM_BOOL, 'The success');
2964     }
2965
2966     /**
2967      * Returns description of external function parameters.
2968      *
2969      * @return \external_function_parameters
2970      */
2971     public static function user_competency_request_review_parameters() {
2972         return new external_function_parameters(array(
2973             'userid' => new external_value(PARAM_INT, 'The user ID'),
2974             'competencyid' => new external_value(PARAM_INT, 'The competency ID'),
2975         ));
2976     }
2977
2978     /**
2979      * External function user_competency_request_review.
2980      *
2981      * @param int $userid The user ID.
2982      * @param int $competencyid The competency ID.
2983      * @return boolean
2984      */
2985     public static function user_competency_request_review($userid, $competencyid) {
2986         $params = self::validate_parameters(self::user_competency_request_review_parameters(), array(
2987             'userid' => $userid,
2988             'competencyid' => $competencyid,
2989         ));
2990
2991         $context = context_user::instance($params['userid']);
2992         self::validate_context($context);
2993
2994         return api::user_competency_request_review($userid, $competencyid);
2995     }
2996
2997     /**
2998      * Returns description of external function result value.
2999      *
3000      * @return \external_function_parameters
3001      */
3002     public static function user_competency_request_review_returns() {
3003         return new external_value(PARAM_BOOL, 'The success');
3004     }
3005
3006     /**
3007      * Returns description of external function parameters.
3008      *
3009      * @return \external_function_parameters
3010      */
3011     public static function user_competency_start_review_parameters() {
3012         return new external_function_parameters(array(
3013             'userid' => new external_value(PARAM_INT, 'The user ID'),
3014             'competencyid' => new external_value(PARAM_INT, 'The competency ID'),
3015         ));
3016     }
3017
3018     /**
3019      * External function user_competency_start_review.
3020      *
3021      * @param int $userid The user ID.
3022      * @param int $competencyid The competency ID.
3023      * @return boolean
3024      */
3025     public static function user_competency_start_review($userid, $competencyid) {
3026         $params = self::validate_parameters(self::user_competency_start_review_parameters(), array(
3027             'userid' => $userid,
3028             'competencyid' => $competencyid
3029         ));
3030
3031         $context = context_user::instance($params['userid']);
3032         self::validate_context($context);
3033
3034         return api::user_competency_start_review($userid, $competencyid);
3035     }
3036
3037     /**
3038      * Returns description of external function result value.
3039      *
3040      * @return \external_function_parameters
3041      */
3042     public static function user_competency_start_review_returns() {
3043         return new external_value(PARAM_BOOL, 'The success');
3044     }
3045
3046     /**
3047      * Returns description of external function parameters.
3048      *
3049      * @return \external_function_parameters
3050      */
3051     public static function user_competency_stop_review_parameters() {
3052         return new external_function_parameters(array(
3053             'userid' => new external_value(PARAM_INT, 'The user ID'),
3054             'competencyid' => new external_value(PARAM_INT, 'The competency ID'),
3055         ));
3056     }
3057
3058     /**
3059      * External function user_competency_stop_review.
3060      *
3061      * @param int $userid The user ID.
3062      * @param int $competencyid The competency ID.
3063      * @return boolean
3064      */
3065     public static function user_competency_stop_review($userid, $competencyid) {
3066         $params = self::validate_parameters(self::user_competency_stop_review_parameters(), array(
3067             'userid' => $userid,
3068             'competencyid' => $competencyid
3069         ));
3070
3071         $context = context_user::instance($params['userid']);
3072         self::validate_context($context);
3073
3074         return api::user_competency_stop_review($userid, $competencyid);
3075     }
3076
3077     /**
3078      * Returns description of external function result value.
3079      *
3080      * @return \external_function_parameters
3081      */
3082     public static function user_competency_stop_review_returns() {
3083         return new external_value(PARAM_BOOL, 'The success');
3084     }
3085
3086     /**
3087      * Returns description of template_has_related_data() parameters.
3088      *
3089      * @return \external_function_parameters
3090      */
3091     public static function template_has_related_data_parameters() {
3092         $templateid = new external_value(
3093             PARAM_INT,
3094             'The template id',
3095             VALUE_REQUIRED
3096         );
3097         $params = array(
3098             'id' => $templateid,
3099         );
3100         return new external_function_parameters($params);
3101     }
3102
3103     /**
3104      * Check if template has related data.
3105      *
3106      * @param int $templateid Template id.
3107      * @return boolean
3108      */
3109     public static function template_has_related_data($templateid) {
3110         $params = self::validate_parameters(self::template_has_related_data_parameters(),
3111                                             array(
3112                                                 'id' => $templateid,
3113                                             ));
3114
3115         $template = api::read_template($params['id']);
3116         self::validate_context($template->get_context());
3117
3118         return api::template_has_related_data($params['id']);
3119     }
3120
3121     /**
3122      * Returns description of template_has_related_data() result value.
3123      *
3124      * @return \external_description
3125      */
3126     public static function template_has_related_data_returns() {
3127         return new external_value(PARAM_BOOL, 'True if the template has related data');
3128     }
3129
3130     /**
3131      * Count the competencies (visible to this user) in this learning plan template.
3132      *
3133      * @param int $templateid Template id.
3134      * @param int $competencyid Competency id.
3135      * @return int
3136      */
3137     public static function remove_competency_from_template($templateid, $competencyid) {
3138         $params = self::validate_parameters(self::remove_competency_from_template_parameters(),
3139                                             array(
3140                                                 'templateid' => $templateid,
3141                                                 'competencyid' => $competencyid,
3142                                             ));
3143         $template = api::read_template($params['templateid']);
3144         self::validate_context($template->get_context());
3145
3146         return api::remove_competency_from_template($params['templateid'], $params['competencyid']);
3147     }
3148
3149     /**
3150      * Returns description of remove_competency_from_template() result value.
3151      *
3152      * @return \external_description
3153      */
3154     public static function remove_competency_from_template_returns() {
3155         return new external_value(PARAM_BOOL, 'True if successful.');
3156     }
3157
3158     /**
3159      * Returns description of data_for_template_competenies_page() parameters.
3160      *
3161      * @return \external_function_parameters
3162      */
3163     public static function data_for_template_competencies_page_parameters() {
3164         $templateid = new external_value(
3165             PARAM_INT,
3166             'The template id',
3167             VALUE_REQUIRED
3168         );
3169         $params = array('templateid' => $templateid, 'pagecontext' => self::get_context_parameters());
3170         return new external_function_parameters($params);
3171     }
3172
3173     /**
3174      * Loads the data required to render the template_competencies_page template.
3175      *
3176      * @param int $templateid Template id.
3177      * @param array $pagecontext The page context info.
3178      * @return boolean
3179      */
3180     public static function data_for_template_competencies_page($templateid, $pagecontext) {
3181         global $PAGE;
3182         $params = self::validate_parameters(self::data_for_template_competencies_page_parameters(),
3183                                             array(
3184                                                 'templateid' => $templateid,
3185                                                 'pagecontext' => $pagecontext
3186                                             ));
3187
3188         $context = self::get_context_from_params($params['pagecontext']);
3189         self::validate_context($context);
3190
3191         $template = api::read_template($params['templateid']);
3192         $renderable = new output\template_competencies_page($template, $context);
3193         $renderer = $PAGE->get_renderer('tool_lp');
3194
3195         $data = $renderable->export_for_template($renderer);
3196
3197         return $data;
3198     }
3199
3200     /**
3201      * Returns description of data_for_template_competencies_page() result value.
3202      *
3203      * @return \external_description
3204      */
3205     public static function data_for_template_competencies_page_returns() {
3206         return new external_single_structure(array (
3207             'template' => template_exporter::get_read_structure(),
3208             'pagecontextid' => new external_value(PARAM_INT, 'Context ID'),
3209             'canmanagecompetencyframeworks' => new external_value(PARAM_BOOL, 'User can manage competency frameworks'),
3210             'canmanagetemplatecompetencies' => new external_value(PARAM_BOOL, 'User can manage learning plan templates'),
3211             'competencies' => new external_multiple_structure(
3212                 competency_summary_exporter::get_read_structure()
3213             ),
3214             'manageurl' => new external_value(PARAM_LOCALURL, 'Url to the manage competencies page.'),
3215             'pluginbaseurl' => new external_value(PARAM_LOCALURL, 'Base URL of the plugin.'),
3216             'statistics' => template_statistics_exporter::get_read_structure()
3217         ));
3218
3219     }
3220
3221     /**
3222      * Returns description of data_for_plan_competenies_page() parameters.
3223      *
3224      * @return \external_function_parameters
3225      */
3226     public static function data_for_plan_page_parameters() {
3227         $planid = new external_value(
3228             PARAM_INT,
3229             'The plan id',
3230             VALUE_REQUIRED
3231         );
3232         $params = array('planid' => $planid);
3233         return new external_function_parameters($params);
3234     }
3235
3236     /**
3237      * Loads the data required to render the plan_page template.
3238      *
3239      * @param int $planid Learning Plan id.
3240      * @return boolean
3241      */
3242     public static function data_for_plan_page($planid) {
3243         global $PAGE;
3244         $params = self::validate_parameters(self::data_for_plan_page_parameters(),
3245                                             array(
3246                                                 'planid' => $planid
3247                                             ));
3248         $plan = api::read_plan($params['planid']);
3249         self::validate_context($plan->get_context());
3250
3251         $renderable = new output\plan_page($plan);
3252         $renderer = $PAGE->get_renderer('tool_lp');
3253
3254         $data = $renderable->export_for_template($renderer);
3255
3256         return $data;
3257     }
3258
3259     /**
3260      * Returns description of data_for_plan_page() result value.
3261      *
3262      * @return \external_description
3263      */
3264     public static function data_for_plan_page_returns() {
3265         $uc = user_competency_exporter::get_read_structure();
3266         $ucp = user_competency_plan_exporter::get_read_structure();
3267
3268         $uc->required = VALUE_OPTIONAL;
3269         $ucp->required = VALUE_OPTIONAL;
3270
3271         return new external_single_structure(array (
3272             'plan' => plan_exporter::get_read_structure(),
3273             'contextid' => new external_value(PARAM_INT, 'Context ID.'),
3274             'pluginbaseurl' => new external_value(PARAM_URL, 'Plugin base URL.'),
3275             'competencies' => new external_multiple_structure(
3276                 new external_single_structure(array(
3277                     'competency' => competency_exporter::get_read_structure(),
3278                     'comppath' => competency_path_exporter::get_read_structure(),
3279                     'usercompetency' => $uc,
3280                     'usercompetencyplan' => $ucp
3281                 ))
3282             )
3283         ));
3284     }
3285
3286     /**
3287      * Returns description of create_plan() parameters.
3288      *
3289      * @return \external_function_parameters
3290      */
3291     public static function create_plan_parameters() {
3292         $structure = plan_exporter::get_create_structure();
3293         $params = array('plan' => $structure);
3294         return new external_function_parameters($params);
3295     }
3296
3297     /**
3298      * Create a new learning plan.
3299      *
3300      * @param array $plan List of fields for the plan.
3301      * @return array New plan record.
3302      */
3303     public static function create_plan($plan) {
3304         global $PAGE;
3305
3306         $params = self::validate_parameters(self::create_plan_parameters(),
3307                                             array('plan' => $plan));
3308         $params = $params['plan'];
3309
3310         $context = context_user::instance($params['userid']);
3311         self::validate_context($context);
3312         $output = $PAGE->get_renderer('tool_lp');
3313
3314         $params = (object) $params;
3315
3316         $result = api::create_plan($params);
3317         $exporter = new plan_exporter($result, array('template' => null));
3318         return $exporter->export($output);
3319     }
3320
3321     /**
3322      * Returns description of create_plan() result value.
3323      *
3324      * @return \external_description
3325      */
3326     public static function create_plan_returns() {
3327         return plan_exporter::get_read_structure();
3328     }
3329
3330     /**
3331      * Returns description of update_plan() parameters.
3332      *
3333      * @return \external_function_parameters
3334      */
3335     public static function update_plan_parameters() {
3336         $structure = plan_exporter::get_update_structure();
3337         $params = array('plan' => $structure);
3338         return new external_function_parameters($params);
3339     }
3340
3341     /**
3342      * Updates a new learning plan.
3343      *
3344      * @param array $plan Fields for the plan (id is required)
3345      * @return mixed
3346      */
3347     public static function update_plan($plan) {
3348         global $PAGE;
3349
3350         $params = self::validate_parameters(self::update_plan_parameters(),
3351                                             array('plan' => $plan));
3352
3353         $params = $params['plan'];
3354
3355         $plan = api::read_plan($params['id']);
3356         self::validate_context($plan->get_context());
3357         $output = $PAGE->get_renderer('tool_lp');
3358
3359         $params = (object) $params;
3360         $result = api::update_plan($params);
3361         $exporter = plan_exporter($result);
3362         $record = $exporter->export($output);
3363         return external_api::clean_returnvalue(self::update_plan_returns(), $record);
3364     }
3365
3366     /**
3367      * Returns description of update_plan() result value.
3368      *
3369      * @return \external_description
3370      */
3371     public static function update_plan_returns() {
3372         return plan_exporter::get_read_structure();
3373     }
3374
3375     /**
3376      * Returns description of complete_plan() parameters.
3377      *
3378      * @return \external_function_parameters
3379      */
3380     public static function complete_plan_parameters() {
3381         $planid = new external_value(
3382             PARAM_INT,
3383             'The plan id',