Merge branch 'MDL-57636_master' of https://github.com/dasistwas/moodle
[moodle.git] / lib / classes / output / external.php
CommitLineData
9bdcf579
DW
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 * 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 */
25
26namespace core\output;
27
28use external_api;
29use external_function_parameters;
a26ce248
DW
30use external_multiple_structure;
31use external_single_structure;
9bdcf579
DW
32use external_value;
33use core_component;
34use moodle_exception;
35use context_system;
36use theme_config;
37
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 */
45class 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.'),
bd87693f 56 'includecomments' => new external_value(PARAM_BOOL, 'Include comments or not', VALUE_DEFAULT, false)
9bdcf579
DW
57 )
58 );
59 }
60
9bdcf579
DW
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 */
bd87693f 69 public static function load_template($component, $template, $themename, $includecomments = false) {
9bdcf579
DW
70 global $DB, $CFG, $PAGE;
71
72 $params = self::validate_parameters(self::load_template_parameters(),
73 array('component' => $component,
74 'template' => $template,
bd87693f 75 'themename' => $themename,
76 'includecomments' => $includecomments));
9bdcf579 77
e0034b5d 78 $loader = new mustache_template_source_loader();
fcc383db 79 // Will throw exceptions if the template does not exist.
e0034b5d
RW
80 return $loader->load(
81 $params['component'],
82 $params['template'],
83 $params['themename'],
84 $params['includecomments']
85 );
9bdcf579
DW
86 }
87
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 }
a26ce248 96
e0034b5d
RW
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 }
110
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;
127
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 );
137
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 };
159
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 }
167
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 ]);
179
180 return new external_single_structure([
181 'templates' => new external_multiple_structure($resourcestructure),
182 'strings' => new external_multiple_structure($resourcestructure)
183 ]);
184 }
185
a26ce248 186 /**
95b06c13 187 * Returns description of load_icon_map() parameters.
a26ce248
DW
188 *
189 * @return external_function_parameters
190 */
e330b1c2
DW
191 public static function load_fontawesome_icon_map_parameters() {
192 return new external_function_parameters([]);
a26ce248
DW
193 }
194
195 /**
196 * Return a mapping of icon names to icons.
197 *
198 * @return array the mapping
199 */
e330b1c2 200 public static function load_fontawesome_icon_map() {
e330b1c2 201 $instance = icon_system::instance(icon_system::FONTAWESOME);
a26ce248 202
95b06c13 203 $map = $instance->get_icon_name_map();
a26ce248
DW
204
205 $result = [];
206
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 }
217
218 /**
95b06c13 219 * Returns description of load_icon_map() result value.
a26ce248
DW
220 *
221 * @return external_description
222 */
e330b1c2 223 public static function load_fontawesome_icon_map_returns() {
a26ce248
DW
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 }
9bdcf579
DW
232}
233