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