MDL-68793 core_table: fix WS name to comply with guidelines
[moodle.git] / lib / table / classes / external / dynamic / get.php
CommitLineData
1592c3c4
SL
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 * Table external API.
19 *
20 * @package core_table
21 * @category external
22 * @copyright 2020 Simey Lameze <simey@moodle.com>
23 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
24 */
25
26namespace core_table\external\dynamic;
27
28use external_api;
29use external_function_parameters;
30use external_multiple_structure;
31use external_single_structure;
32use external_value;
33use external_warnings;
1592c3c4
SL
34
35/**
36 * Core table external functions.
37 *
38 * @package core_table
39 * @category external
40 * @copyright 2020 Simey Lameze <simey@moodle.com>
41 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
42 */
1179f07d 43class get extends external_api {
1592c3c4
SL
44
45 /**
46 * Describes the parameters for fetching the table html.
47 *
48 * @return external_function_parameters
49 * @since Moodle 3.9
50 */
51 public static function execute_parameters(): external_function_parameters {
52 return new external_function_parameters ([
4cf97b7f
SL
53 'component' => new external_value(
54 PARAM_COMPONENT,
55 'Component',
56 VALUE_REQUIRED
57 ),
1592c3c4
SL
58 'handler' => new external_value(
59 // Note: We do not have a PARAM_CLASSNAME which would have been ideal.
4cf97b7f 60 PARAM_ALPHANUMEXT,
1592c3c4
SL
61 'Handler',
62 VALUE_REQUIRED
63 ),
64 'uniqueid' => new external_value(
65 PARAM_ALPHANUMEXT,
66 'Unique ID for the container',
67 VALUE_REQUIRED
68 ),
a31a2b6d
AN
69 'sortdata' => new external_multiple_structure(
70 new external_single_structure([
71 'sortby' => new external_value(
72 PARAM_ALPHANUMEXT,
73 'The name of a sortable column',
74 VALUE_REQUIRED
75 ),
76 'sortorder' => new external_value(
77 PARAM_ALPHANUMEXT,
78 'The direction that this column should be sorted by',
79 VALUE_REQUIRED
80 ),
81 ]),
82 'The combined sort order of the table. Multiple fields can be specified.',
83 VALUE_OPTIONAL,
84 []
1592c3c4
SL
85 ),
86 'filters' => new external_multiple_structure(
87 new external_single_structure([
88 'name' => new external_value(PARAM_ALPHANUM, 'Name of the filter', VALUE_REQUIRED),
89 'jointype' => new external_value(PARAM_INT, 'Type of join for filter values', VALUE_REQUIRED),
90 'values' => new external_multiple_structure(
91 new external_value(PARAM_RAW, 'Filter value'),
92 'The value to filter on',
93 VALUE_REQUIRED
94 )
95 ]),
96 'The filters that will be applied in the request',
97 VALUE_OPTIONAL
98 ),
99 'jointype' => new external_value(PARAM_INT, 'Type of join to join all filters together', VALUE_REQUIRED),
c540a575
AN
100 'firstinitial' => new external_value(
101 PARAM_ALPHANUMEXT,
102 'The first initial to sort filter on',
103 VALUE_REQUIRED,
104 null
105 ),
106 'lastinitial' => new external_value(
107 PARAM_ALPHANUMEXT,
108 'The last initial to sort filter on',
109 VALUE_REQUIRED,
110 null
111 ),
f7b84afe
SL
112 'pagenumber' => new external_value(
113 PARAM_INT,
114 'The page number',
115 VALUE_REQUIRED,
116 null
117 ),
118 'pagesize' => new external_value(
119 PARAM_INT,
120 'The number of records per page',
121 VALUE_REQUIRED,
122 null
123 ),
e2f12c22
SL
124 'hiddencolumns' => new external_multiple_structure(
125 new external_value(
126 PARAM_ALPHANUMEXT,
127 'Name of column',
128 VALUE_REQUIRED,
129 null
130 )
131 ),
68c46a28
SL
132 'resetpreferences' => new external_value(
133 PARAM_BOOL,
134 'Whether the table preferences should be reset',
135 VALUE_REQUIRED,
136 null
137 ),
1592c3c4
SL
138 ]);
139 }
140
141 /**
1179f07d 142 * External function to get the table view content.
1592c3c4 143 *
4cf97b7f 144 * @param string $component The component.
1592c3c4
SL
145 * @param string $handler Dynamic table class name.
146 * @param string $uniqueid Unique ID for the container.
a31a2b6d 147 * @param array $sortdata The columns and order to sort by
1592c3c4
SL
148 * @param array $filters The filters that will be applied in the request.
149 * @param string $jointype The join type.
c540a575
AN
150 * @param string $firstinitial The first name initial to filter on
151 * @param string $lastinitial The last name initial to filter on
f7b84afe
SL
152 * @param int $pagenumber The page number.
153 * @param int $pagesize The number of records.
68c46a28
SL
154 * @param string $jointype The join type.
155 * @param bool $resetpreferences Whether it is resetting table preferences or not.
1592c3c4
SL
156 *
157 * @return array
158 */
c540a575 159 public static function execute(
4cf97b7f 160 string $component,
c540a575
AN
161 string $handler,
162 string $uniqueid,
a31a2b6d 163 array $sortdata,
c540a575
AN
164 ?array $filters = null,
165 ?string $jointype = null,
166 ?string $firstinitial = null,
f7b84afe
SL
167 ?string $lastinitial = null,
168 ?int $pagenumber = null,
e2f12c22 169 ?int $pagesize = null,
68c46a28
SL
170 ?array $hiddencolumns = null,
171 ?bool $resetpreferences = null
c540a575 172 ) {
1592c3c4
SL
173 global $PAGE;
174
1592c3c4 175 [
4cf97b7f 176 'component' => $component,
1592c3c4
SL
177 'handler' => $handler,
178 'uniqueid' => $uniqueid,
a31a2b6d 179 'sortdata' => $sortdata,
1592c3c4
SL
180 'filters' => $filters,
181 'jointype' => $jointype,
c540a575
AN
182 'firstinitial' => $firstinitial,
183 'lastinitial' => $lastinitial,
f7b84afe
SL
184 'pagenumber' => $pagenumber,
185 'pagesize' => $pagesize,
e2f12c22 186 'hiddencolumns' => $hiddencolumns,
68c46a28 187 'resetpreferences' => $resetpreferences,
1592c3c4 188 ] = self::validate_parameters(self::execute_parameters(), [
4cf97b7f 189 'component' => $component,
1592c3c4
SL
190 'handler' => $handler,
191 'uniqueid' => $uniqueid,
a31a2b6d 192 'sortdata' => $sortdata,
1592c3c4
SL
193 'filters' => $filters,
194 'jointype' => $jointype,
c540a575
AN
195 'firstinitial' => $firstinitial,
196 'lastinitial' => $lastinitial,
f7b84afe
SL
197 'pagenumber' => $pagenumber,
198 'pagesize' => $pagesize,
e2f12c22 199 'hiddencolumns' => $hiddencolumns,
68c46a28 200 'resetpreferences' => $resetpreferences,
1592c3c4
SL
201 ]);
202
4cf97b7f
SL
203 $tableclass = "\\{$component}\\table\\{$handler}";
204 if (!class_exists($tableclass)) {
205 throw new \UnexpectedValueException("Table handler class {$tableclass} not found. " .
206 "Please make sure that your table handler class is under the \\{$component}\\table namespace.");
207 }
208
209 if (!is_subclass_of($tableclass, \core_table\dynamic::class)) {
210 throw new \UnexpectedValueException("Table handler class {$tableclass} does not support dynamic updating.");
211 }
212
213 $filtersetclass = "{$tableclass}_filterset";
214 if (!class_exists($filtersetclass)) {
215 throw new \UnexpectedValueException("The filter specified ({$filtersetclass}) is invalid.");
216 }
217
218 $filterset = new $filtersetclass();
110f3ebf 219 $filterset->set_join_type($jointype);
1592c3c4
SL
220 foreach ($filters as $rawfilter) {
221 $filterset->add_filter_from_params(
222 $rawfilter['name'],
223 $rawfilter['jointype'],
224 $rawfilter['values']
225 );
226 }
227
4cf97b7f 228 $instance = new $tableclass($uniqueid);
1592c3c4 229 $instance->set_filterset($filterset);
5615a772
AN
230 self::validate_context($instance->get_context());
231
a31a2b6d 232 $instance->set_sortdata($sortdata);
1592c3c4 233
c540a575
AN
234 if ($firstinitial !== null) {
235 $instance->set_first_initial($firstinitial);
236 }
237
238 if ($lastinitial !== null) {
239 $instance->set_last_initial($lastinitial);
240 }
241
f7b84afe
SL
242 if ($pagenumber !== null) {
243 $instance->set_page_number($pagenumber);
244 }
1592c3c4 245
f7b84afe
SL
246 if ($pagesize === null) {
247 $pagesize = 20;
248 }
249
e2f12c22
SL
250 if ($hiddencolumns !== null) {
251 $instance->set_hidden_columns($hiddencolumns);
252 }
253
68c46a28
SL
254 if ($resetpreferences === true) {
255 $instance->mark_table_to_reset();
256 }
257
258 $PAGE->set_url($instance->baseurl);
259
1592c3c4 260 ob_start();
f7b84afe 261 $instance->out($pagesize, true);
fb17c31c 262 $tablehtml = ob_get_contents();
1592c3c4
SL
263 ob_end_clean();
264
265 return [
fb17c31c 266 'html' => $tablehtml,
1592c3c4
SL
267 'warnings' => []
268 ];
269 }
270
271 /**
272 * Describes the data returned from the external function.
273 *
274 * @return external_single_structure
275 * @since Moodle 3.9
276 */
277 public static function execute_returns(): external_single_structure {
278 return new external_single_structure([
279 'html' => new external_value(PARAM_RAW, 'The raw html of the requested table.'),
280 'warnings' => new external_warnings()
281 ]);
282 }
283}