Merge branch '42057-26' of git://github.com/samhemelryk/moodle
[moodle.git] / lib / outputfactories.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  * Interface and classes for creating appropriate renderers for various parts of Moodle.
19  *
20  * Please see http://docs.moodle.org/en/Developement:How_Moodle_outputs_HTML
21  * for an overview.
22  *
23  * @copyright 2009 Tim Hunt
24  * @license  http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
25  * @package core
26  * @category output
27  */
29 defined('MOODLE_INTERNAL') || die();
31 /** General rendering target, usually normal browser page */
32 define('RENDERER_TARGET_GENERAL', 'general');
34 /** General rendering target, usually normal browser page, but with limited capacity to avoid API use */
35 define('RENDERER_TARGET_MAINTENANCE', 'maintenance');
37 /** Plain text rendering for CLI scripts and cron */
38 define('RENDERER_TARGET_CLI', 'cli');
40 /** Plain text rendering for Ajax scripts*/
41 define('RENDERER_TARGET_AJAX', 'ajax');
43 /** Plain text rendering intended for sending via email */
44 define('RENDERER_TARGET_TEXTEMAIL', 'textemail');
46 /** Rich text html rendering intended for sending via email */
47 define('RENDERER_TARGET_HTMLEMAIL', 'htmlemail');
49 // note: maybe we could define portfolio export target too
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
63  * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
64  * @since Moodle 2.0
65  * @package core
66  * @category output
67  */
68 interface renderer_factory {
70     /**
71      * Return the renderer for a particular part of Moodle.
72      *
73      * The renderer interfaces are defined by classes called {plugin}_renderer
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      *
78      * Renderers will normally want to subclass the renderer_base class.
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
82      * {plugin}_renderer implementation also serves to define the API for
83      * other implementations of the interface, whether or not they subclass it.
84      *
85      * A particular plugin can define multiple renderers if it wishes, using the
86      * $subtype parameter. For example workshop_renderer,
87      * workshop_allocation_manual_renderer etc.
88      *
89      * @param moodle_page $page the page the renderer is outputting content for.
90      * @param string $component name such as 'core', 'mod_forum' or 'qtype_multichoice'.
91      * @param string $subtype optional subtype such as 'news' resulting to 'mod_forum_news'
92      * @param string $target one of rendering target constants
93      * @return renderer_base an object implementing the requested renderer interface.
94      */
95     public function get_renderer(moodle_page $page, $component, $subtype=null, $target=null);
96 }
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
109  * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
110  * @since Moodle 2.0
111  * @package core
112  * @category output
113  */
114 abstract class renderer_factory_base implements renderer_factory {
115     /**
116      * @var theme_config The theme we belong to.
117      */
118     protected $theme;
120     /**
121      * Constructor.
122      *
123      * @param theme_config $theme the theme we belong to.
124      */
125     public function __construct(theme_config $theme) {
126         $this->theme = $theme;
127     }
129     /**
130      * Returns suffix of renderer class expected for given target.
131      *
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) {
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.
140             if (CLI_SCRIPT) {
141                 $target = RENDERER_TARGET_CLI;
142             } else if (AJAX_SCRIPT) {
143                 $target = RENDERER_TARGET_AJAX;
144             }
145         }
147         switch ($target) {
148             case RENDERER_TARGET_CLI: $suffix = '_cli'; break;
149             case RENDERER_TARGET_AJAX: $suffix = '_ajax'; break;
150             case RENDERER_TARGET_TEXTEMAIL: $suffix = '_textemail'; break;
151             case RENDERER_TARGET_HTMLEMAIL: $suffix = '_htmlemail'; break;
152             case RENDERER_TARGET_MAINTENANCE: $suffix = '_maintenance'; break;
153             default: $target = RENDERER_TARGET_GENERAL; $suffix = '';
154         }
156         return array($target, $suffix);
157     }
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.
169      * @throws coding_exception
170      */
171     protected function standard_renderer_classname($component, $subtype = null) {
172         global $CFG; // Needed in included files.
174         // Standardize component name ala frankenstyle.
175         list($plugin, $type) = core_component::normalize_component($component);
176         if ($type === null) {
177             $component = $plugin;
178         } else {
179             $component = $plugin.'_'.$type;
180         }
182         if ($component !== 'core') {
183             // Renderers are stored in renderer.php files.
184             if (!$compdirectory = core_component::get_component_directory($component)) {
185                 throw new coding_exception('Invalid component specified in renderer request', $component);
186             }
187             $rendererfile = $compdirectory . '/renderer.php';
188             if (file_exists($rendererfile)) {
189                 include_once($rendererfile);
190             }
192         } else if (!empty($subtype)) {
193             $coresubsystems = core_component::get_core_subsystems();
194             if (!array_key_exists($subtype, $coresubsystems)) { // There may be nulls.
195                 throw new coding_exception('Invalid core subtype "' . $subtype . '" in renderer request', $subtype);
196             }
197             if ($coresubsystems[$subtype]) {
198                 $rendererfile = $coresubsystems[$subtype] . '/renderer.php';
199                 if (file_exists($rendererfile)) {
200                     include_once($rendererfile);
201                 }
202             }
203         }
205         if (empty($subtype)) {
206             $class = $component . '_renderer';
207         } else {
208             $class = $component . '_' . $subtype . '_renderer';
209         }
210         return $class;
211     }
214 /**
215  * This is the default renderer factory for Moodle.
216  *
217  * It simply returns an instance of the appropriate standard renderer class.
218  *
219  * @copyright 2009 Tim Hunt
220  * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
221  * @since Moodle 2.0
222  * @package core
223  * @category output
224  */
225 class standard_renderer_factory extends renderer_factory_base {
227     /**
228      * Implement the subclass method
229      *
230      * @param moodle_page $page the page the renderer is outputting content for.
231      * @param string $component name such as 'core', 'mod_forum' or 'qtype_multichoice'.
232      * @param string $subtype optional subtype such as 'news' resulting to 'mod_forum_news'
233      * @param string $target one of rendering target constants
234      * @return renderer_base an object implementing the requested renderer interface.
235      */
236     public function get_renderer(moodle_page $page, $component, $subtype = null, $target = null) {
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);
240         }
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;
247         }
249         return new $classname($page, $target);
250     }
254 /**
255  * This is renderer factory allows themes to override the standard renderers using php code.
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
260  * parenttheme_component_renderer, instead of a component_renderer,
261  * if either of those classes exist.
262  *
263  * @copyright 2009 Tim Hunt
264  * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
265  * @since Moodle 2.0
266  * @package core
267  * @category output
268  */
269 class theme_overridden_renderer_factory extends renderer_factory_base {
271     /**
272      * @var array An array of renderer prefixes
273      */
274     protected $prefixes = array();
276     /**
277      * Constructor.
278      * @param theme_config $theme the theme we are rendering for.
279      */
280     public function __construct(theme_config $theme) {
281         parent::__construct($theme);
282         // Initialise $this->prefixes.
283         $this->prefixes = $theme->renderer_prefixes();
284     }
286     /**
287      * Implement the subclass method
288      *
289      * @param moodle_page $page the page the renderer is outputting content for.
290      * @param string $component name such as 'core', 'mod_forum' or 'qtype_multichoice'.
291      * @param string $subtype optional subtype such as 'news' resulting to 'mod_forum_news'
292      * @param string $target one of rendering target constants
293      * @return renderer_base an object implementing the requested renderer interface.
294      */
295     public function get_renderer(moodle_page $page, $component, $subtype = null, $target = null) {
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);
300         }
302         list($target, $suffix) = $this->get_target_suffix($target);
304         // theme lib.php and renderers.php files are loaded automatically
305         // when loading the theme configs
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         }
321         // then try general renderer
322         foreach ($this->prefixes as $prefix) {
323             if (class_exists($prefix . '_' . $classname)) {
324                 $classname = $prefix . '_' . $classname;
325                 return new $classname($page, $target);
326             }
327         }
329         return new $classname($page, $target);
330     }