MDL-41398 output: implemented maintenance renderer
[moodle.git] / lib / outputfactories.php
CommitLineData
d9c8f425 1<?php
d9c8f425 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/**
f8129210 18 * Interface and classes for creating appropriate renderers for various parts of Moodle.
d9c8f425 19 *
20 * Please see http://docs.moodle.org/en/Developement:How_Moodle_outputs_HTML
21 * for an overview.
22 *
35a191a1
SH
23 * @copyright 2009 Tim Hunt
24 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
f8129210 25 * @package core
76be40cc 26 * @category output
d9c8f425 27 */
28
78bfb562
PS
29defined('MOODLE_INTERNAL') || die();
30
c927e35c
PS
31/** General rendering target, usually normal browser page */
32define('RENDERER_TARGET_GENERAL', 'general');
33
166ac0a3
SH
34/** General rendering target, usually normal browser page, but with limited capacity to avoid API use */
35define('RENDERER_TARGET_MAINTENANCE', 'maintenance');
36
c927e35c
PS
37/** Plain text rendering for CLI scripts and cron */
38define('RENDERER_TARGET_CLI', 'cli');
39
1adaa404
PS
40/** Plain text rendering for Ajax scripts*/
41define('RENDERER_TARGET_AJAX', 'ajax');
42
c927e35c
PS
43/** Plain text rendering intended for sending via email */
44define('RENDERER_TARGET_TEXTEMAIL', 'textemail');
45
46/** Rich text html rendering intended for sending via email */
47define('RENDERER_TARGET_HTMLEMAIL', 'htmlemail');
48
35a191a1 49// note: maybe we could define portfolio export target too
c927e35c
PS
50
51
d9c8f425 52/**
53 * A renderer factory is just responsible for creating an appropriate renderer
54 * for any given part of Moodle.
55 *
56 * Which renderer factory to use is chose by the current theme, and an instance
57 * if created automatically when the theme is set up.
58 *
59 * A renderer factory must also have a constructor that takes a theme_config object.
60 * (See {@link renderer_factory_base::__construct} for an example.)
61 *
62 * @copyright 2009 Tim Hunt
35a191a1
SH
63 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
64 * @since Moodle 2.0
f8129210 65 * @package core
76be40cc 66 * @category output
d9c8f425 67 */
68interface renderer_factory {
35a191a1 69
d9c8f425 70 /**
71 * Return the renderer for a particular part of Moodle.
72 *
78946b9b 73 * The renderer interfaces are defined by classes called {plugin}_renderer
d9c8f425 74 * where {plugin} is the name of the component. The renderers for core Moodle are
75 * defined in lib/renderer.php. For plugins, they will be defined in a file
76 * called renderer.php inside the plugin.
77 *
78946b9b 78 * Renderers will normally want to subclass the renderer_base class.
d9c8f425 79 * (However, if you really know what you are doing, you don't have to do that.)
80 *
81 * There is no separate interface definition for renderers. The default
78946b9b 82 * {plugin}_renderer implementation also serves to define the API for
d9c8f425 83 * other implementations of the interface, whether or not they subclass it.
d9c8f425 84 *
85 * A particular plugin can define multiple renderers if it wishes, using the
78946b9b
PS
86 * $subtype parameter. For example workshop_renderer,
87 * workshop_allocation_manual_renderer etc.
d9c8f425 88 *
d9c8f425 89 * @param moodle_page $page the page the renderer is outputting content for.
56cbc53b 90 * @param string $component name such as 'core', 'mod_forum' or 'qtype_multichoice'.
d9c8f425 91 * @param string $subtype optional subtype such as 'news' resulting to 'mod_forum_news'
c927e35c 92 * @param string $target one of rendering target constants
35a191a1 93 * @return renderer_base an object implementing the requested renderer interface.
d9c8f425 94 */
c927e35c 95 public function get_renderer(moodle_page $page, $component, $subtype=null, $target=null);
d9c8f425 96}
97
78946b9b 98
d9c8f425 99/**
100 * This is a base class to help you implement the renderer_factory interface.
101 *
102 * It keeps a cache of renderers that have been constructed, so you only need
103 * to construct each one once in you subclass.
104 *
105 * It also has a method to get the name of, and include the renderer.php with
106 * the definition of, the standard renderer class for a given module.
107 *
108 * @copyright 2009 Tim Hunt
35a191a1
SH
109 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
110 * @since Moodle 2.0
f8129210 111 * @package core
76be40cc 112 * @category output
d9c8f425 113 */
114abstract class renderer_factory_base implements renderer_factory {
35a191a1 115 /**
76be40cc 116 * @var theme_config The theme we belong to.
35a191a1 117 */
d9c8f425 118 protected $theme;
c927e35c 119
d9c8f425 120 /**
121 * Constructor.
35a191a1 122 *
d9c8f425 123 * @param theme_config $theme the theme we belong to.
124 */
78946b9b 125 public function __construct(theme_config $theme) {
d9c8f425 126 $this->theme = $theme;
127 }
78946b9b 128
c927e35c
PS
129 /**
130 * Returns suffix of renderer class expected for given target.
35a191a1 131 *
c927e35c
PS
132 * @param string $target one of the renderer target constants, target is guessed if null used
133 * @return array two element array, first element is target, second the target suffix string
134 */
135 protected function get_target_suffix($target) {
166ac0a3
SH
136 if (empty($target) || $target === RENDERER_TARGET_MAINTENANCE) {
137 // If the target hasn't been specified we need to guess the defaults.
138 // We also override the target with the default if the maintenance target has been provided.
139 // This ensures we don't use the maintenance renderer if we are processing a special target.
1adaa404
PS
140 if (CLI_SCRIPT) {
141 $target = RENDERER_TARGET_CLI;
142 } else if (AJAX_SCRIPT) {
143 $target = RENDERER_TARGET_AJAX;
144 }
c927e35c
PS
145 }
146
147 switch ($target) {
148 case RENDERER_TARGET_CLI: $suffix = '_cli'; break;
1adaa404 149 case RENDERER_TARGET_AJAX: $suffix = '_ajax'; break;
c927e35c
PS
150 case RENDERER_TARGET_TEXTEMAIL: $suffix = '_textemail'; break;
151 case RENDERER_TARGET_HTMLEMAIL: $suffix = '_htmlemail'; break;
166ac0a3 152 case RENDERER_TARGET_MAINTENANCE: $suffix = '_maintenance'; break;
c927e35c
PS
153 default: $target = RENDERER_TARGET_GENERAL; $suffix = '';
154 }
155
156 return array($target, $suffix);
157 }
158
d9c8f425 159 /**
160 * For a given module name, return the name of the standard renderer class
161 * that defines the renderer interface for that module.
162 *
163 * Also, if it exists, include the renderer.php file for that module, so
164 * the class definition of the default renderer has been loaded.
165 *
166 * @param string $component name such as 'core', 'mod_forum' or 'qtype_multichoice'.
167 * @param string $subtype optional subtype such as 'news' resulting to 'mod_forum_news'
168 * @return string the name of the standard renderer class for that module.
166ac0a3 169 * @throws coding_exception
d9c8f425 170 */
c927e35c 171 protected function standard_renderer_classname($component, $subtype = null) {
166ac0a3 172 global $CFG; // Needed in included files.
78946b9b 173
166ac0a3 174 // Standardize component name ala frankenstyle.
56da374e 175 list($plugin, $type) = core_component::normalize_component($component);
88623be1
PS
176 if ($type === null) {
177 $component = $plugin;
178 } else {
179 $component = $plugin.'_'.$type;
180 }
181
78946b9b 182 if ($component !== 'core') {
166ac0a3 183 // Renderers are stored in renderer.php files.
b0d1d941 184 if (!$compdirectory = core_component::get_component_directory($component)) {
166ac0a3 185 throw new coding_exception('Invalid component specified in renderer request', $component);
56cbc53b
PS
186 }
187 $rendererfile = $compdirectory . '/renderer.php';
188 if (file_exists($rendererfile)) {
189 include_once($rendererfile);
d9c8f425 190 }
78946b9b 191
56cbc53b 192 } else if (!empty($subtype)) {
9e19a0f0
PS
193 $coresubsystems = core_component::get_core_subsystems();
194 if (!array_key_exists($subtype, $coresubsystems)) { // There may be nulls.
166ac0a3 195 throw new coding_exception('Invalid core subtype "' . $subtype . '" in renderer request', $subtype);
56cbc53b 196 }
9e19a0f0
PS
197 if ($coresubsystems[$subtype]) {
198 $rendererfile = $coresubsystems[$subtype] . '/renderer.php';
199 if (file_exists($rendererfile)) {
200 include_once($rendererfile);
201 }
56cbc53b 202 }
78946b9b 203 }
56cbc53b
PS
204
205 if (empty($subtype)) {
78946b9b 206 $class = $component . '_renderer';
d9c8f425 207 } else {
78946b9b 208 $class = $component . '_' . $subtype . '_renderer';
d9c8f425 209 }
d9c8f425 210 return $class;
211 }
212}
213
d9c8f425 214/**
f8129210
SH
215 * This is the default renderer factory for Moodle.
216 *
217 * It simply returns an instance of the appropriate standard renderer class.
d9c8f425 218 *
219 * @copyright 2009 Tim Hunt
35a191a1
SH
220 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
221 * @since Moodle 2.0
f8129210 222 * @package core
76be40cc 223 * @category output
d9c8f425 224 */
225class standard_renderer_factory extends renderer_factory_base {
35a191a1 226
d9c8f425 227 /**
228 * Implement the subclass method
35a191a1 229 *
d9c8f425 230 * @param moodle_page $page the page the renderer is outputting content for.
56cbc53b 231 * @param string $component name such as 'core', 'mod_forum' or 'qtype_multichoice'.
d9c8f425 232 * @param string $subtype optional subtype such as 'news' resulting to 'mod_forum_news'
c927e35c 233 * @param string $target one of rendering target constants
35a191a1 234 * @return renderer_base an object implementing the requested renderer interface.
d9c8f425 235 */
c927e35c 236 public function get_renderer(moodle_page $page, $component, $subtype = null, $target = null) {
56cbc53b
PS
237 $classname = $this->standard_renderer_classname($component, $subtype);
238 if (!class_exists($classname)) {
239 throw new coding_exception('Request for an unknown renderer class ' . $classname);
d9c8f425 240 }
d9c8f425 241
c927e35c
PS
242 list($target, $suffix) = $this->get_target_suffix($target);
243 if (class_exists($classname . $suffix)) {
244 // use the specialised renderer for given target, default renderer might also decide
245 // to implement support for more targets
246 $classname = $classname . $suffix;
d9c8f425 247 }
c927e35c
PS
248
249 return new $classname($page, $target);
d9c8f425 250 }
251}
252
253
254/**
f8129210 255 * This is renderer factory allows themes to override the standard renderers using php code.
d9c8f425 256 *
257 * It will load any code from theme/mytheme/renderers.php and
258 * theme/parenttheme/renderers.php, if then exist. Then whenever you ask for
259 * a renderer for 'component', it will create a mytheme_component_renderer or a
78946b9b 260 * parenttheme_component_renderer, instead of a component_renderer,
d9c8f425 261 * if either of those classes exist.
262 *
d9c8f425 263 * @copyright 2009 Tim Hunt
35a191a1
SH
264 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
265 * @since Moodle 2.0
f8129210 266 * @package core
76be40cc 267 * @category output
d9c8f425 268 */
56cbc53b
PS
269class theme_overridden_renderer_factory extends renderer_factory_base {
270
35a191a1 271 /**
76be40cc 272 * @var array An array of renderer prefixes
35a191a1 273 */
d9c8f425 274 protected $prefixes = array();
275
276 /**
277 * Constructor.
35a191a1 278 * @param theme_config $theme the theme we are rendering for.
d9c8f425 279 */
78946b9b 280 public function __construct(theme_config $theme) {
d9c8f425 281 parent::__construct($theme);
d9c8f425 282 // Initialise $this->prefixes.
78946b9b 283 $this->prefixes = $theme->renderer_prefixes();
d9c8f425 284 }
285
286 /**
287 * Implement the subclass method
35a191a1 288 *
d9c8f425 289 * @param moodle_page $page the page the renderer is outputting content for.
56cbc53b 290 * @param string $component name such as 'core', 'mod_forum' or 'qtype_multichoice'.
d9c8f425 291 * @param string $subtype optional subtype such as 'news' resulting to 'mod_forum_news'
c927e35c 292 * @param string $target one of rendering target constants
35a191a1 293 * @return renderer_base an object implementing the requested renderer interface.
d9c8f425 294 */
c927e35c 295 public function get_renderer(moodle_page $page, $component, $subtype = null, $target = null) {
56cbc53b
PS
296 $classname = $this->standard_renderer_classname($component, $subtype);
297 if (!class_exists($classname)) {
298 // standard renderer must always exist
299 throw new coding_exception('Request for an unknown renderer class ' . $classname);
78946b9b
PS
300 }
301
c927e35c
PS
302 list($target, $suffix) = $this->get_target_suffix($target);
303
304 // theme lib.php and renderers.php files are loaded automatically
305 // when loading the theme configs
306
307 // first try the renderers with correct suffix
308 foreach ($this->prefixes as $prefix) {
309 if (class_exists($prefix . '_' . $classname . $suffix)) {
310 $classname = $prefix . '_' . $classname . $suffix;
311 return new $classname($page, $target);
312 }
313 }
314 if (class_exists($classname . $suffix)) {
315 // use the specialised renderer for given target, default renderer might also decide
316 // to implement support for more targets
317 $classname = $classname . $suffix;
318 return new $classname($page, $target);
319 }
320
321 // then try general renderer
d9c8f425 322 foreach ($this->prefixes as $prefix) {
56cbc53b
PS
323 if (class_exists($prefix . '_' . $classname)) {
324 $classname = $prefix . '_' . $classname;
c927e35c 325 return new $classname($page, $target);
d9c8f425 326 }
327 }
c927e35c
PS
328
329 return new $classname($page, $target);
d9c8f425 330 }
35a191a1 331}