Merge branch 'MDL-57636_master' of https://github.com/dasistwas/moodle
[moodle.git] / lib / classes / output / external.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  * Mustache helper to load strings from string_manager.
19  *
20  * @package    core
21  * @category   output
22  * @copyright  2015 Damyon Wiese
23  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
24  */
26 namespace core\output;
28 use external_api;
29 use external_function_parameters;
30 use external_multiple_structure;
31 use external_single_structure;
32 use external_value;
33 use core_component;
34 use moodle_exception;
35 use context_system;
36 use theme_config;
38 /**
39  * This class contains a list of webservice functions related to output.
40  *
41  * @copyright  2015 Damyon Wiese
42  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
43  * @since      2.9
44  */
45 class external extends external_api {
46     /**
47      * Returns description of load_template() parameters.
48      *
49      * @return external_function_parameters
50      */
51     public static function load_template_parameters() {
52         return new external_function_parameters(
53                 array('component' => new external_value(PARAM_COMPONENT, 'component containing the template'),
54                       'template' => new external_value(PARAM_ALPHANUMEXT, 'name of the template'),
55                       'themename' => new external_value(PARAM_ALPHANUMEXT, 'The current theme.'),
56                       'includecomments' => new external_value(PARAM_BOOL, 'Include comments or not', VALUE_DEFAULT, false)
57                          )
58             );
59     }
61     /**
62      * Return a mustache template, and all the strings it requires.
63      *
64      * @param string $component The component that holds the template.
65      * @param string $templatename The name of the template.
66      * @param string $themename The name of the current theme.
67      * @return string the template
68      */
69     public static function load_template($component, $template, $themename, $includecomments = false) {
70         global $DB, $CFG, $PAGE;
72         $params = self::validate_parameters(self::load_template_parameters(),
73                                             array('component' => $component,
74                                                   'template' => $template,
75                                                   'themename' => $themename,
76                                                   'includecomments' => $includecomments));
78         $loader = new mustache_template_source_loader();
79         // Will throw exceptions if the template does not exist.
80         return $loader->load(
81             $params['component'],
82             $params['template'],
83             $params['themename'],
84             $params['includecomments']
85         );
86     }
88     /**
89      * Returns description of load_template() result value.
90      *
91      * @return external_description
92      */
93     public static function load_template_returns() {
94         return new external_value(PARAM_RAW, 'template');
95     }
97     /**
98      * Returns description of load_template_with_dependencies() parameters.
99      *
100      * @return external_function_parameters
101      */
102     public static function load_template_with_dependencies_parameters() {
103         return new external_function_parameters([
104             'component' => new external_value(PARAM_COMPONENT, 'component containing the template'),
105             'template' => new external_value(PARAM_ALPHANUMEXT, 'name of the template'),
106             'themename' => new external_value(PARAM_ALPHANUMEXT, 'The current theme.'),
107             'includecomments' => new external_value(PARAM_BOOL, 'Include comments or not', VALUE_DEFAULT, false)
108         ]);
109     }
111     /**
112      * Return a mustache template, and all the child templates and strings it requires.
113      *
114      * @param string $component The component that holds the template.
115      * @param string $template The name of the template.
116      * @param string $themename The name of the current theme.
117      * @param bool $includecomments Whether to strip comments from the template source.
118      * @return string the template
119      */
120     public static function load_template_with_dependencies(
121         string $component,
122         string $template,
123         string $themename,
124         bool $includecomments = false
125     ) {
126         global $DB, $CFG, $PAGE;
128         $params = self::validate_parameters(
129             self::load_template_with_dependencies_parameters(),
130             [
131                 'component' => $component,
132                 'template' => $template,
133                 'themename' => $themename,
134                 'includecomments' => $includecomments
135             ]
136         );
138         $loader = new mustache_template_source_loader();
139         // Will throw exceptions if the template does not exist.
140         $dependencies = $loader->load_with_dependencies(
141             $params['component'],
142             $params['template'],
143             $params['themename'],
144             $params['includecomments']
145         );
146         $formatdependencies = function($dependency) {
147             $results = [];
148             foreach ($dependency as $dependencycomponent => $dependencyvalues) {
149                 foreach ($dependencyvalues as $dependencyname => $dependencyvalue) {
150                     array_push($results, [
151                         'component' => $dependencycomponent,
152                         'name' => $dependencyname,
153                         'value' => $dependencyvalue
154                     ]);
155                 }
156             }
157             return $results;
158         };
160         // Now we have to unpack the dependencies into a format that can be returned
161         // by external functions (because they don't support dynamic keys).
162         return [
163             'templates' => $formatdependencies($dependencies['templates']),
164             'strings' => $formatdependencies($dependencies['strings'])
165         ];
166     }
168     /**
169      * Returns description of load_template_with_dependencies() result value.
170      *
171      * @return external_description
172      */
173     public static function load_template_with_dependencies_returns() {
174         $resourcestructure = new external_single_structure([
175             'component' => new external_value(PARAM_COMPONENT, 'component containing the resource'),
176             'name' => new external_value(PARAM_TEXT, 'name of the resource'),
177             'value' => new external_value(PARAM_RAW, 'resource value')
178         ]);
180         return new external_single_structure([
181             'templates' => new external_multiple_structure($resourcestructure),
182             'strings' => new external_multiple_structure($resourcestructure)
183         ]);
184     }
186     /**
187      * Returns description of load_icon_map() parameters.
188      *
189      * @return external_function_parameters
190      */
191     public static function load_fontawesome_icon_map_parameters() {
192         return new external_function_parameters([]);
193     }
195     /**
196      * Return a mapping of icon names to icons.
197      *
198      * @return array the mapping
199      */
200     public static function load_fontawesome_icon_map() {
201         $instance = icon_system::instance(icon_system::FONTAWESOME);
203         $map = $instance->get_icon_name_map();
205         $result = [];
207         foreach ($map as $from => $to) {
208             list($component, $pix) = explode(':', $from);
209             $one = [];
210             $one['component'] = $component;
211             $one['pix'] = $pix;
212             $one['to'] = $to;
213             $result[] = $one;
214         }
215         return $result;
216     }
218     /**
219      * Returns description of load_icon_map() result value.
220      *
221      * @return external_description
222      */
223     public static function load_fontawesome_icon_map_returns() {
224         return new external_multiple_structure(new external_single_structure(
225             array(
226                 'component' => new external_value(PARAM_COMPONENT, 'The component for the icon.'),
227                 'pix' => new external_value(PARAM_RAW, 'Value to map the icon from.'),
228                 'to' => new external_value(PARAM_RAW, 'Value to map the icon to.')
229             )
230         ));
231     }