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/>.
  16
  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  */
  28
  29 defined('MOODLE_INTERNAL') || die();
  30
  31 /** General rendering target, usually normal browser page */
  32 define('RENDERER_TARGET_GENERAL', 'general');
  33
  34 /** General rendering target, usually normal browser page, but with limited capacity to avoid API use */
  35 define('RENDERER_TARGET_MAINTENANCE', 'maintenance');
  36
  37 /** Plain text rendering for CLI scripts and cron */
  38 define('RENDERER_TARGET_CLI', 'cli');
  39
  40 /** Plain text rendering for Ajax scripts*/
  41 define('RENDERER_TARGET_AJAX', 'ajax');
  42
  43 /** Plain text rendering intended for sending via email */
  44 define('RENDERER_TARGET_TEXTEMAIL', 'textemail');
  45
  46 /** Rich text html rendering intended for sending via email */
  47 define('RENDERER_TARGET_HTMLEMAIL', 'htmlemail');
  48
  49 // note: maybe we could define portfolio export target too
  50
  51
  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 {
  69
  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 }
  97
  98
  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;
 119
 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     }
 128
 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         }
 146
 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         }
 155
 156         return array($target, $suffix);
 157     }
 158
 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.
 173
 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         }
 181
 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             }
 191
 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         }
 204
 205         if (empty($subtype)) {
 206             $class = $component . '_renderer';
 207         } else {
 208             $class = $component . '_' . $subtype . '_renderer';
 209         }
 210         return $class;
 211     }
 212 }
 213
 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 {
 226
 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         }
 241
 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         }
 248
 249         return new $classname($page, $target);
 250     }
 251 }
 252
 253
 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 {
 270
 271     /**
 272      * @var array An array of renderer prefixes
 273      */
 274     protected $prefixes = array();
 275
 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     }
 285
 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         }
 301
 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
 322         foreach ($this->prefixes as $prefix) {
 323             if (class_exists($prefix . '_' . $classname)) {
 324                 $classname = $prefix . '_' . $classname;
 325                 return new $classname($page, $target);
 326             }
 327         }
 328
 329         return new $classname($page, $target);
 330     }
 331 }