Search moodle.org's
Developer Documentation

See Release Notes
Long Term Support Release

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

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

   1  <?php
   2  // This file is part of Moodle - http://moodle.org/
   3  //
   4  // Moodle is free software: you can redistribute it and/or modify
   5  // it under the terms of the GNU General Public License as published by
   6  // the Free Software Foundation, either version 3 of the License, or
   7  // (at your option) any later version.
   8  //
   9  // Moodle is distributed in the hope that it will be useful,
  10  // but WITHOUT ANY WARRANTY; without even the implied warranty of
  11  // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  12  // GNU General Public License for more details.
  13  //
  14  // You should have received a copy of the GNU General Public License
  15  // along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
  16  
  17  /**
  18   * External interface library for customfields component
  19   *
  20   * @package   core_customfield
  21   * @copyright 2018 David Matamoros <davidmc@moodle.com>
  22   * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  23   */
  24  
  25  defined('MOODLE_INTERNAL') || die;
  26  
  27  require_once($CFG->libdir . "/externallib.php");
  28  
  29  /**
  30   * Class core_customfield_external
  31   *
  32   * @copyright 2018 David Matamoros <davidmc@moodle.com>
  33   * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  34   */
  35  class core_customfield_external extends external_api {
  36  
  37      /**
  38       * Parameters for delete_field
  39       *
  40       * @return external_function_parameters
  41       */
  42      public static function delete_field_parameters() {
  43          return new external_function_parameters(
  44                  array('id' => new external_value(PARAM_INT, 'Custom field ID to delete', VALUE_REQUIRED))
  45          );
  46      }
  47  
  48      /**
  49       * Delete custom field function
  50       *
  51       * @param int $id
  52       */
  53      public static function delete_field($id) {
  54          $params = self::validate_parameters(self::delete_field_parameters(), ['id' => $id]);
  55  
  56          $record = \core_customfield\field_controller::create($params['id']);
  57          $handler = $record->get_handler();
  58          if (!$handler->can_configure()) {
  59              throw new moodle_exception('nopermissionconfigure', 'core_customfield');
  60          }
  61          $handler->delete_field_configuration($record);
  62      }
  63  
  64      /**
  65       * Return for delete_field
  66       */
  67      public static function delete_field_returns() {
  68      }
  69  
  70      /**
  71       * Parameters for reload template function
  72       *
  73       * @return external_function_parameters
  74       */
  75      public static function reload_template_parameters() {
  76          return new external_function_parameters(
  77              array(
  78                  'component' => new external_value(PARAM_COMPONENT, 'component', VALUE_REQUIRED),
  79                  'area' => new external_value(PARAM_ALPHANUMEXT, 'area', VALUE_REQUIRED),
  80                  'itemid' => new external_value(PARAM_INT, 'itemid', VALUE_REQUIRED)
  81              )
  82          );
  83      }
  84  
  85      /**
  86       * Reload template function
  87       *
  88       * @param string $component
  89       * @param string $area
  90       * @param int $itemid
  91       * @return array|object|stdClass
  92       */
  93      public static function reload_template($component, $area, $itemid) {
  94          global $PAGE;
  95  
  96          $params = self::validate_parameters(self::reload_template_parameters(),
  97                        ['component' => $component, 'area' => $area, 'itemid' => $itemid]);
  98  
  99          $PAGE->set_context(context_system::instance());
 100          $handler = \core_customfield\handler::get_handler($params['component'], $params['area'], $params['itemid']);
 101          self::validate_context($handler->get_configuration_context());
 102          if (!$handler->can_configure()) {
 103              throw new moodle_exception('nopermissionconfigure', 'core_customfield');
 104          }
 105          $output = $PAGE->get_renderer('core_customfield');
 106          $outputpage = new \core_customfield\output\management($handler);
 107          return $outputpage->export_for_template($output);
 108      }
 109  
 110      /**
 111       * Ajax returns on reload template.
 112       *
 113       * @return external_single_structure
 114       */
 115      public static function reload_template_returns() {
 116          return new external_single_structure(
 117              array(
 118                  'component' => new external_value(PARAM_COMPONENT, 'component'),
 119                  'area' => new external_value(PARAM_ALPHANUMEXT, 'area'),
 120                  'itemid' => new external_value(PARAM_INT, 'itemid'),
 121                  'usescategories' => new external_value(PARAM_BOOL, 'view has categories'),
 122                  'categories' => new external_multiple_structure(
 123                      new external_single_structure(
 124                          array(
 125                              'id' => new external_value(PARAM_INT, 'id'),
 126                              'nameeditable' => new external_value(PARAM_RAW, 'inplace editable name'),
 127                              'addfieldmenu' => new external_value(PARAM_RAW, 'addfieldmenu'),
 128                              'fields' => new external_multiple_structure(
 129                                  new external_single_structure(
 130                                      array(
 131                                          'name' => new external_value(PARAM_NOTAGS, 'name'),
 132                                          'shortname' => new external_value(PARAM_NOTAGS, 'shortname'),
 133                                          'type' => new external_value(PARAM_NOTAGS, 'type'),
 134                                          'id' => new external_value(PARAM_INT, 'id'),
 135                                      )
 136                                  )
 137                              , '', VALUE_OPTIONAL),
 138                          )
 139                      )
 140                  ),
 141              )
 142          );
 143      }
 144  
 145      /**
 146       * Parameters for delete category
 147       *
 148       * @return external_function_parameters
 149       */
 150      public static function delete_category_parameters() {
 151          return new external_function_parameters(
 152                  array('id' => new external_value(PARAM_INT, 'category ID to delete', VALUE_REQUIRED))
 153          );
 154      }
 155  
 156      /**
 157       * Delete category function
 158       *
 159       * @param int $id
 160       */
 161      public static function delete_category($id) {
 162          $category = core_customfield\category_controller::create($id);
 163          $handler = $category->get_handler();
 164          self::validate_context($handler->get_configuration_context());
 165          if (!$handler->can_configure()) {
 166              throw new moodle_exception('nopermissionconfigure', 'core_customfield');
 167          }
 168          $handler->delete_category($category);
 169      }
 170  
 171      /**
 172       * Return for delete category
 173       */
 174      public static function delete_category_returns() {
 175      }
 176  
 177  
 178      /**
 179       * Parameters for create category
 180       *
 181       * @return external_function_parameters
 182       */
 183      public static function create_category_parameters() {
 184          return new external_function_parameters(
 185              array(
 186                  'component' => new external_value(PARAM_COMPONENT, 'component', VALUE_REQUIRED),
 187                  'area' => new external_value(PARAM_ALPHANUMEXT, 'area', VALUE_REQUIRED),
 188                  'itemid' => new external_value(PARAM_INT, 'itemid', VALUE_REQUIRED)
 189              )
 190          );
 191      }
 192  
 193      /**
 194       * Create category function
 195       *
 196       * @param string $component
 197       * @param string $area
 198       * @param int    $itemid
 199       * @return mixed
 200       */
 201      public static function create_category($component, $area, $itemid) {
 202          $params = self::validate_parameters(self::create_category_parameters(),
 203              ['component' => $component, 'area' => $area, 'itemid' => $itemid]);
 204  
 205          $handler = \core_customfield\handler::get_handler($params['component'], $params['area'], $params['itemid']);
 206          self::validate_context($handler->get_configuration_context());
 207          if (!$handler->can_configure()) {
 208              throw new moodle_exception('nopermissionconfigure', 'core_customfield');
 209          }
 210          return $handler->create_category();
 211      }
 212  
 213      /**
 214       * Return for create category
 215       */
 216      public static function create_category_returns() {
 217          return new external_value(PARAM_INT, 'Id of the category');
 218      }
 219  
 220      /**
 221       * Parameters for move field.
 222       *
 223       * @return external_function_parameters
 224       */
 225      public static function move_field_parameters() {
 226          return new external_function_parameters(
 227                  ['id' => new external_value(PARAM_INT, 'Id of the field to move', VALUE_REQUIRED),
 228                   'categoryid' => new external_value(PARAM_INT, 'New parent category id', VALUE_REQUIRED),
 229                   'beforeid'   => new external_value(PARAM_INT, 'Id of the field before which it needs to be moved',
 230                       VALUE_DEFAULT, 0)]
 231          );
 232      }
 233  
 234      /**
 235       * Move/reorder field. Move a field to another category and/or change sortorder of fields
 236       *
 237       * @param int $id field id
 238       * @param int $categoryid
 239       * @param int $beforeid
 240       */
 241      public static function move_field($id, $categoryid, $beforeid) {
 242          $params = self::validate_parameters(self::move_field_parameters(),
 243              ['id' => $id, 'categoryid' => $categoryid, 'beforeid' => $beforeid]);
 244          $field = \core_customfield\field_controller::create($params['id']);
 245          $handler = $field->get_handler();
 246          self::validate_context($handler->get_configuration_context());
 247          if (!$handler->can_configure()) {
 248              throw new moodle_exception('nopermissionconfigure', 'core_customfield');
 249          }
 250          $handler->move_field($field, $params['categoryid'], $params['beforeid']);
 251      }
 252  
 253      /**
 254       * Return for move field
 255       */
 256      public static function move_field_returns() {
 257      }
 258  
 259      /**
 260       * Return for move category
 261       *
 262       * @return external_function_parameters
 263       */
 264      public static function move_category_parameters() {
 265          return new external_function_parameters(
 266                  ['id' => new external_value(PARAM_INT, 'Category ID to move', VALUE_REQUIRED),
 267                   'beforeid'   => new external_value(PARAM_INT, 'Id of the category before which it needs to be moved',
 268                       VALUE_DEFAULT, 0)]
 269          );
 270      }
 271  
 272      /**
 273       * Reorder categories. Move category to the new position
 274       *
 275       * @param int $id category id
 276       * @param int $beforeid
 277       */
 278      public static function move_category(int $id, int $beforeid) {
 279          $params = self::validate_parameters(self::move_category_parameters(),
 280              ['id' => $id, 'beforeid' => $beforeid]);
 281          $category = core_customfield\category_controller::create($id);
 282          $handler = $category->get_handler();
 283          self::validate_context($handler->get_configuration_context());
 284          if (!$handler->can_configure()) {
 285              throw new moodle_exception('nopermissionconfigure', 'core_customfield');
 286          }
 287          $handler->move_category($category, $params['beforeid']);
 288      }
 289  
 290      /**
 291       * Return for move category
 292       */
 293      public static function move_category_returns() {
 294      }
 295  }