MDL-67264 core_course: Begin set up for Activity chooser
[moodle.git] / 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/>.
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  */
25 defined('MOODLE_INTERNAL') || die;
27 require_once($CFG->libdir . "/externallib.php");
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 {
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     }
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]);
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     }
64     /**
65      * Return for delete_field
66      */
67     public static function delete_field_returns() {
68     }
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     }
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;
96         $params = self::validate_parameters(self::reload_template_parameters(),
97                       ['component' => $component, 'area' => $area, 'itemid' => $itemid]);
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     }
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_INT, '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                                         'editfieldurl' => new external_value(PARAM_URL, 'edit field url'),
135                                         'id' => new external_value(PARAM_INT, 'id'),
136                                     )
137                                 )
138                             , '', VALUE_OPTIONAL),
139                         )
140                     )
141                 ),
142             )
143         );
144     }
146     /**
147      * Parameters for delete category
148      *
149      * @return external_function_parameters
150      */
151     public static function delete_category_parameters() {
152         return new external_function_parameters(
153                 array('id' => new external_value(PARAM_INT, 'category ID to delete', VALUE_REQUIRED))
154         );
155     }
157     /**
158      * Delete category function
159      *
160      * @param int $id
161      */
162     public static function delete_category($id) {
163         $category = core_customfield\category_controller::create($id);
164         $handler = $category->get_handler();
165         self::validate_context($handler->get_configuration_context());
166         if (!$handler->can_configure()) {
167             throw new moodle_exception('nopermissionconfigure', 'core_customfield');
168         }
169         $handler->delete_category($category);
170     }
172     /**
173      * Return for delete category
174      */
175     public static function delete_category_returns() {
176     }
179     /**
180      * Parameters for create category
181      *
182      * @return external_function_parameters
183      */
184     public static function create_category_parameters() {
185         return new external_function_parameters(
186             array(
187                 'component' => new external_value(PARAM_COMPONENT, 'component', VALUE_REQUIRED),
188                 'area' => new external_value(PARAM_ALPHANUMEXT, 'area', VALUE_REQUIRED),
189                 'itemid' => new external_value(PARAM_INT, 'itemid', VALUE_REQUIRED)
190             )
191         );
192     }
194     /**
195      * Create category function
196      *
197      * @param string $component
198      * @param string $area
199      * @param int    $itemid
200      * @return mixed
201      */
202     public static function create_category($component, $area, $itemid) {
203         $params = self::validate_parameters(self::create_category_parameters(),
204             ['component' => $component, 'area' => $area, 'itemid' => $itemid]);
206         $handler = \core_customfield\handler::get_handler($params['component'], $params['area'], $params['itemid']);
207         self::validate_context($handler->get_configuration_context());
208         if (!$handler->can_configure()) {
209             throw new moodle_exception('nopermissionconfigure', 'core_customfield');
210         }
211         return $handler->create_category();
212     }
214     /**
215      * Return for create category
216      */
217     public static function create_category_returns() {
218         return new external_value(PARAM_INT, 'Id of the category');
219     }
221     /**
222      * Parameters for move field.
223      *
224      * @return external_function_parameters
225      */
226     public static function move_field_parameters() {
227         return new external_function_parameters(
228                 ['id' => new external_value(PARAM_INT, 'Id of the field to move', VALUE_REQUIRED),
229                  'categoryid' => new external_value(PARAM_INT, 'New parent category id', VALUE_REQUIRED),
230                  'beforeid'   => new external_value(PARAM_INT, 'Id of the field before which it needs to be moved',
231                      VALUE_DEFAULT, 0)]
232         );
233     }
235     /**
236      * Move/reorder field. Move a field to another category and/or change sortorder of fields
237      *
238      * @param int $id field id
239      * @param int $categoryid
240      * @param int $beforeid
241      */
242     public static function move_field($id, $categoryid, $beforeid) {
243         $params = self::validate_parameters(self::move_field_parameters(),
244             ['id' => $id, 'categoryid' => $categoryid, 'beforeid' => $beforeid]);
245         $field = \core_customfield\field_controller::create($params['id']);
246         $handler = $field->get_handler();
247         self::validate_context($handler->get_configuration_context());
248         if (!$handler->can_configure()) {
249             throw new moodle_exception('nopermissionconfigure', 'core_customfield');
250         }
251         $handler->move_field($field, $params['categoryid'], $params['beforeid']);
252     }
254     /**
255      * Return for move field
256      */
257     public static function move_field_returns() {
258     }
260     /**
261      * Return for move category
262      *
263      * @return external_function_parameters
264      */
265     public static function move_category_parameters() {
266         return new external_function_parameters(
267                 ['id' => new external_value(PARAM_INT, 'Category ID to move', VALUE_REQUIRED),
268                  'beforeid'   => new external_value(PARAM_INT, 'Id of the category before which it needs to be moved',
269                      VALUE_DEFAULT, 0)]
270         );
271     }
273     /**
274      * Reorder categories. Move category to the new position
275      *
276      * @param int $id category id
277      * @param int $beforeid
278      */
279     public static function move_category(int $id, int $beforeid) {
280         $params = self::validate_parameters(self::move_category_parameters(),
281             ['id' => $id, 'beforeid' => $beforeid]);
282         $category = core_customfield\category_controller::create($id);
283         $handler = $category->get_handler();
284         self::validate_context($handler->get_configuration_context());
285         if (!$handler->can_configure()) {
286             throw new moodle_exception('nopermissionconfigure', 'core_customfield');
287         }
288         $handler->move_category($category, $params['beforeid']);
289     }
291     /**
292      * Return for move category
293      */
294     public static function move_category_returns() {
295     }