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