customfield/externallib.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  * 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 }