MDL-52715 js: Merge M.str and clean memory
[moodle.git] / lib / external / externallib.php
CommitLineData
11e76602
JM
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/**
19 * external API for core library
20 *
21 * @package core_webservice
22 * @category external
23 * @copyright 2012 Jerome Mouneyrac <jerome@moodle.com>
24 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
25 */
26
27defined('MOODLE_INTERNAL') || die;
28
29require_once("$CFG->libdir/externallib.php");
30
31/**
32 * Web service related functions
33 *
34 * @package core
35 * @category external
36 * @copyright 2012 Jerome Mouneyrac <jerome@moodle.com>
37 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
38 * @since Moodle 2.4
39 */
40class core_external extends external_api {
41
42
43 /**
44 * Format the received string parameters to be sent to the core get_string() function.
45 *
46 * @param array $stringparams
47 * @return object|string
5bcfd504 48 * @since Moodle 2.4
11e76602
JM
49 */
50 public static function format_string_parameters($stringparams) {
51 // Check if there are some string params.
52 $strparams = new stdClass();
53 if (!empty($stringparams)) {
54 // There is only one string parameter.
55 if (count($stringparams) == 1) {
56 $stringparam = array_pop($stringparams);
57 if (isset($stringparam['name'])) {
58 $strparams->{$stringparam['name']} = $stringparam['value'];
59 } else {
60 // It is a not named string parameter.
61 $strparams = $stringparam['value'];
62 }
63 } else {
64 // There are more than one parameter.
65 foreach ($stringparams as $stringparam) {
66
67 // If a parameter is unnamed throw an exception
68 // unnamed param is only possible if one only param is sent.
69 if (empty($stringparam['name'])) {
fd6ab92b 70 throw new moodle_exception('unnamedstringparam', 'webservice');
11e76602
JM
71 }
72
73 $strparams->{$stringparam['name']} = $stringparam['value'];
74 }
75 }
76 }
77 return $strparams;
78 }
79
80 /**
81 * Returns description of get_string parameters
82 *
83 * @return external_function_parameters
84 * @since Moodle 2.4
85 */
86 public static function get_string_parameters() {
87 return new external_function_parameters(
88 array('stringid' => new external_value(PARAM_STRINGID, 'string identifier'),
89 'component' => new external_value(PARAM_COMPONENT,'component', VALUE_DEFAULT, 'moodle'),
90 'lang' => new external_value(PARAM_LANG, 'lang', VALUE_DEFAULT, null),
91 'stringparams' => new external_multiple_structure (
92 new external_single_structure(array(
93 'name' => new external_value(PARAM_ALPHANUMEXT, 'param name
94 - if the string expect only one $a parameter then don\'t send this field, just send the value.', VALUE_OPTIONAL),
95 'value' => new external_value(PARAM_TEXT,'param value'))),
96 'the definition of a string param (i.e. {$a->name})', VALUE_DEFAULT, array()
97 )
98 )
99 );
100 }
101
102 /**
103 * Return a core get_string() call
104 *
105 * @param string $identifier string identifier
106 * @param string $component string component
107 * @param array $stringparams the string params
108 * @return string
109 * @since Moodle 2.4
110 */
bef63c52 111 public static function get_string($stringid, $component = 'moodle', $lang = null, $stringparams = array()) {
11e76602 112 $params = self::validate_parameters(self::get_string_parameters(),
bef63c52 113 array('stringid'=>$stringid, 'component' => $component, 'lang' => $lang, 'stringparams' => $stringparams));
11e76602 114
bef63c52
DW
115 $stringmanager = get_string_manager();
116 return $stringmanager->get_string($params['stringid'], $params['component'],
11e76602
JM
117 core_external::format_string_parameters($params['stringparams']), $params['lang']);
118 }
119
120 /**
121 * Returns description of get_string() result value
122 *
123 * @return string
124 * @since Moodle 2.4
125 */
126 public static function get_string_returns() {
127 return new external_value(PARAM_TEXT, 'translated string');
128 }
129
130 /**
131 * Returns description of get_string parameters
132 *
133 * @return external_function_parameters
134 * @since Moodle 2.4
135 */
136 public static function get_strings_parameters() {
137 return new external_function_parameters(
138 array('strings' => new external_multiple_structure (
139 new external_single_structure (array(
140 'stringid' => new external_value(PARAM_STRINGID, 'string identifier'),
141 'component' => new external_value(PARAM_COMPONENT, 'component', VALUE_DEFAULT, 'moodle'),
142 'lang' => new external_value(PARAM_LANG, 'lang', VALUE_DEFAULT, null),
143 'stringparams' => new external_multiple_structure (
144 new external_single_structure(array(
145 'name' => new external_value(PARAM_ALPHANUMEXT, 'param name
146 - if the string expect only one $a parameter then don\'t send this field, just send the value.', VALUE_OPTIONAL),
147 'value' => new external_value(PARAM_TEXT, 'param value'))),
148 'the definition of a string param (i.e. {$a->name})', VALUE_DEFAULT, array()
149 ))
150 )
151 )
152 )
153 );
154 }
155
156 /**
157 * Return multiple call to core get_string()
158 *
159 * @param array $strings strings to translate
160 * @return array
161 *
162 * @since Moodle 2.4
163 */
164 public static function get_strings($strings) {
165 $params = self::validate_parameters(self::get_strings_parameters(),
166 array('strings'=>$strings));
bef63c52 167 $stringmanager = get_string_manager();
11e76602
JM
168
169 $translatedstrings = array();
170 foreach($params['strings'] as $string) {
171
bef63c52 172 if (!empty($string['lang'])) {
11e76602
JM
173 $lang = $string['lang'];
174 } else {
175 $lang = current_language();
176 }
177
178 $translatedstrings[] = array(
179 'stringid' => $string['stringid'],
180 'component' => $string['component'],
181 'lang' => $lang,
bef63c52 182 'string' => $stringmanager->get_string($string['stringid'], $string['component'],
11e76602
JM
183 core_external::format_string_parameters($string['stringparams']), $lang));
184 }
185
186 return $translatedstrings;
187 }
188
189 /**
190 * Returns description of get_string() result value
191 *
192 * @return array
193 * @since Moodle 2.4
194 */
195 public static function get_strings_returns() {
196 return new external_multiple_structure(
197 new external_single_structure(array(
198 'stringid' => new external_value(PARAM_STRINGID, 'string id'),
199 'component' => new external_value(PARAM_COMPONENT, 'string component'),
200 'lang' => new external_value(PARAM_LANG, 'lang'),
201 'string' => new external_value(PARAM_TEXT, 'translated string'))
202 ));
203 }
204
205 /**
206 * Returns description of get_component_strings parameters
207 *
208 * @return external_function_parameters
209 * @since Moodle 2.4
210 */
211 public static function get_component_strings_parameters() {
212 return new external_function_parameters(
213 array('component' => new external_value(PARAM_COMPONENT, 'component'),
214 'lang' => new external_value(PARAM_LANG, 'lang', VALUE_DEFAULT, null),
215 )
216 );
217 }
218
219 /**
220 * Return all lang strings of a component - call to core get_component_strings().
221 *
222 * @param string $component component name
223 * @return array
224 *
225 * @since Moodle 2.4
226 */
227 public static function get_component_strings($component, $lang = null) {
228
229 if (empty($lang)) {
230 $lang = current_language();
231 }
232
233 $params = self::validate_parameters(self::get_component_strings_parameters(),
234 array('component'=>$component, 'lang' => $lang));
235
236 $stringmanager = get_string_manager();
237
238 $wsstrings = array();
239 $componentstrings = $stringmanager->load_component_strings($params['component'], $params['lang']);
240 foreach($componentstrings as $stringid => $string) {
c5f7628d
JM
241 $wsstring = array();
242 $wsstring['stringid'] = $stringid;
243 $wsstring['string'] = $string;
244 $wsstrings[] = $wsstring;
11e76602
JM
245 }
246
247 return $wsstrings;
248 }
249
250 /**
251 * Returns description of get_component_strings() result value
252 *
253 * @return array
254 * @since Moodle 2.4
255 */
256 public static function get_component_strings_returns() {
257 return new external_multiple_structure(
258 new external_single_structure(array(
259 'stringid' => new external_value(PARAM_STRINGID, 'string id'),
c5f7628d 260 'string' => new external_value(PARAM_RAW, 'translated string'))
11e76602
JM
261 ));
262 }
cc73ea07
AG
263
264 /**
265 * Returns description of get_fragment parameters
266 *
267 * @return external_function_parameters
268 * @since Moodle 3.1
269 */
270 public static function get_fragment_parameters() {
271 return new external_function_parameters(
272 array(
273 'component' => new external_value(PARAM_RAW, 'Component for the callback e.g. mod_asign'),
274 'callback' => new external_value(PARAM_RAW, 'Name of the callback to execute'),
275 'args' => new external_multiple_structure(
276 new external_single_structure(
277 array(
278 'name' => new external_value(PARAM_ALPHANUMEXT, 'param name'),
279 'value' => new external_value(PARAM_TEXT, 'param value')
280 )
281 ), 'args for the callback are optional', VALUE_OPTIONAL
282 )
283 )
284 );
285 }
286
287 /**
288 * Get a HTML fragment for inserting into something. Initial use is for inserting mforms into
289 * a page using AJAX.
290 *
291 * @param string $component Name of the component.
292 * @param string $callback Function callback name.
293 * @param array $args optional arguments for the callback.
294 * @return array HTML and JavaScript fragments for insertion into stuff.
295 * @since Moodle 3.1
296 */
297 public static function get_fragment($component, $callback, $args = null) {
0b39d21a 298 global $OUTPUT, $PAGE;
cc73ea07
AG
299
300 $params = self::validate_parameters(self::get_fragment_parameters(),
301 array(
302 'component' => $component,
303 'callback' => $callback,
304 'args' => $args
305 )
306 );
307
308 // Reformat arguments into something less unwieldy.
309 $arguments = array();
310 foreach ($params['args'] as $paramargument) {
311 $arguments[$paramargument['name']] = $paramargument['value'];
312 }
313
314 // Remove warning about context not being set.
315 $PAGE->set_context(context_system::instance());
316
0b39d21a
DM
317 // Hack alert: Forcing bootstrap_renderer to initiate moodle page.
318 $OUTPUT->header();
319
320 // Overwriting page_requirements_manager with the fragment one so only JS included from
321 // this point is returned to the user.
cc73ea07
AG
322 $PAGE->set_requirements_for_fragments();
323 $data = component_callback($params['component'], $params['callback'], $arguments);
324 $jsfooter = $PAGE->requires->get_end_code();
325 $output = array('html' => $data, 'javascript' => $jsfooter);
326 return $output;
327 }
328
329 /**
330 * Returns description of get_fragment() result value
331 *
332 * @return array
333 * @since Moodle 3.1
334 */
335 public static function get_fragment_returns() {
336 return new external_single_structure(
337 array(
338 'html' => new external_value(PARAM_RAW, 'HTML fragment.'),
339 'javascript' => new external_value(PARAM_RAW, 'JavaScript fragment')
340 )
341 );
342 }
11e76602 343}