lib/outputfactories.php

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