See Release Notes
Long Term Support Release
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 (defined('PREFERRED_RENDERER_TARGET')) { 141 $target = PREFERRED_RENDERER_TARGET; 142 } else if (CLI_SCRIPT) { 143 $target = RENDERER_TARGET_CLI; 144 } else if (AJAX_SCRIPT) { 145 $target = RENDERER_TARGET_AJAX; 146 } 147 } 148 149 switch ($target) { 150 case RENDERER_TARGET_CLI: $suffix = '_cli'; break; 151 case RENDERER_TARGET_AJAX: $suffix = '_ajax'; break; 152 case RENDERER_TARGET_TEXTEMAIL: $suffix = '_textemail'; break; 153 case RENDERER_TARGET_HTMLEMAIL: $suffix = '_htmlemail'; break; 154 case RENDERER_TARGET_MAINTENANCE: $suffix = '_maintenance'; break; 155 default: $target = RENDERER_TARGET_GENERAL; $suffix = ''; 156 } 157 158 return array($target, $suffix); 159 } 160 161 /** 162 * For a given module name, return the possible class names 163 * that defines the renderer interface for that module. 164 * 165 * Newer auto-loaded class names are returned as well as the old style _renderable classnames. 166 * 167 * Also, if it exists, include the renderer.php file for that module, so 168 * the class definition of the default renderer has been loaded. 169 * 170 * @param string $component name such as 'core', 'mod_forum' or 'qtype_multichoice'. 171 * @param string $subtype optional subtype such as 'news' resulting to: 172 * '\mod_forum\output\news_renderer' 173 * or '\mod_forum\output\news\renderer' 174 * or non-autoloaded 'mod_forum_news' 175 * @return array[] Each element of the array is an array with keys: 176 * classname - The class name to search 177 * autoloaded - Does this classname assume autoloading? 178 * validwithprefix - Is this class name valid when a prefix is added to it? 179 * validwithoutprefix - Is this class name valid when no prefix is added to it? 180 * @throws coding_exception 181 */ 182 protected function standard_renderer_classnames($component, $subtype = null) { 183 global $CFG; // Needed in included files. 184 $classnames = array(); 185 186 // Standardize component name ala frankenstyle. 187 list($plugin, $type) = core_component::normalize_component($component); 188 if ($type === null) { 189 $component = $plugin; 190 } else { 191 $component = $plugin.'_'.$type; 192 } 193 194 if ($component !== 'core') { 195 // Renderers are stored in renderer.php files. 196 if (!$compdirectory = core_component::get_component_directory($component)) { 197 throw new coding_exception('Invalid component specified in renderer request', $component); 198 } 199 $rendererfile = $compdirectory . '/renderer.php'; 200 if (file_exists($rendererfile)) { 201 include_once($rendererfile); 202 } 203 204 } else if (!empty($subtype)) { 205 $coresubsystems = core_component::get_core_subsystems(); 206 if (!array_key_exists($subtype, $coresubsystems)) { // There may be nulls. 207 throw new coding_exception('Invalid core subtype "' . $subtype . '" in renderer request', $subtype); 208 } 209 if ($coresubsystems[$subtype]) { 210 $rendererfile = $coresubsystems[$subtype] . '/renderer.php'; 211 if (file_exists($rendererfile)) { 212 include_once($rendererfile); 213 } 214 } 215 } 216 217 if (empty($subtype)) { 218 // Theme specific auto-loaded name (only valid when prefixed with the theme name). 219 $classnames[] = array( 220 'validwithprefix' => true, 221 'validwithoutprefix' => false, 222 'autoloaded' => true, 223 'classname' => '\\output\\' . $component . '_renderer' 224 ); 225 226 // Standard autoloaded plugin name (not valid with a prefix). 227 $classnames[] = array( 228 'validwithprefix' => false, 229 'validwithoutprefix' => true, 230 'autoloaded' => true, 231 'classname' => '\\' . $component . '\\output\\renderer' 232 ); 233 // Legacy class name - (valid with or without a prefix). 234 $classnames[] = array( 235 'validwithprefix' => true, 236 'validwithoutprefix' => true, 237 'autoloaded' => false, 238 'classname' => $component . '_renderer' 239 ); 240 } else { 241 // Theme specific auto-loaded name (only valid when prefixed with the theme name). 242 $classnames[] = array( 243 'validwithprefix' => true, 244 'validwithoutprefix' => false, 245 'autoloaded' => true, 246 'classname' => '\\output\\' . $component . '\\' . $subtype . '_renderer' 247 ); 248 // Version of the above with subtype being a namespace level on it's own. 249 $classnames[] = array( 250 'validwithprefix' => true, 251 'validwithoutprefix' => false, 252 'autoloaded' => true, 253 'classname' => '\\output\\' . $component . '\\' . $subtype . '\\renderer' 254 ); 255 // Standard autoloaded plugin name (not valid with a prefix). 256 $classnames[] = array( 257 'validwithprefix' => false, 258 'validwithoutprefix' => true, 259 'autoloaded' => true, 260 'classname' => '\\' . $component . '\\output\\' . $subtype . '_renderer' 261 ); 262 // Version of the above with subtype being a namespace level on it's own. 263 $classnames[] = array( 264 'validwithprefix' => false, 265 'validwithoutprefix' => true, 266 'autoloaded' => true, 267 'classname' => '\\' . $component . '\\output\\' . $subtype . '\\renderer' 268 ); 269 // Legacy class name - (valid with or without a prefix). 270 $classnames[] = array( 271 'validwithprefix' => true, 272 'validwithoutprefix' => true, 273 'autoloaded' => false, 274 'classname' => $component . '_' . $subtype . '_renderer' 275 ); 276 } 277 return $classnames; 278 } 279 } 280 281 /** 282 * This is the default renderer factory for Moodle. 283 * 284 * It simply returns an instance of the appropriate standard renderer class. 285 * 286 * @copyright 2009 Tim Hunt 287 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later 288 * @since Moodle 2.0 289 * @package core 290 * @category output 291 */ 292 class standard_renderer_factory extends renderer_factory_base { 293 294 /** 295 * Implement the subclass method 296 * 297 * @param moodle_page $page the page the renderer is outputting content for. 298 * @param string $component name such as 'core', 'mod_forum' or 'qtype_multichoice'. 299 * @param string $subtype optional subtype such as 'news' resulting to 'mod_forum_news' 300 * @param string $target one of rendering target constants 301 * @return renderer_base an object implementing the requested renderer interface. 302 */ 303 public function get_renderer(moodle_page $page, $component, $subtype = null, $target = null) { 304 $classnames = $this->standard_renderer_classnames($component, $subtype); 305 $classname = ''; 306 307 list($target, $suffix) = $this->get_target_suffix($target); 308 // First look for a version with a suffix. 309 foreach ($classnames as $classnamedetails) { 310 if ($classnamedetails['validwithoutprefix']) { 311 $newclassname = $classnamedetails['classname'] . $suffix; 312 if (class_exists($newclassname)) { 313 $classname = $newclassname; 314 break; 315 } else { 316 $newclassname = $classnamedetails['classname']; 317 if (class_exists($newclassname)) { 318 $classname = $newclassname; 319 break; 320 } 321 } 322 } 323 } 324 // Now look for a non-suffixed version. 325 if (empty($classname)) { 326 foreach ($classnames as $classnamedetails) { 327 if ($classnamedetails['validwithoutprefix']) { 328 $newclassname = $classnamedetails['classname']; 329 if (class_exists($newclassname)) { 330 $classname = $newclassname; 331 break; 332 } 333 } 334 } 335 } 336 337 if (empty($classname)) { 338 // Standard renderer must always exist. 339 throw new coding_exception('Request for an unknown renderer class. Searched for: ' . var_export($classnames, true)); 340 } 341 342 return new $classname($page, $target); 343 } 344 } 345 346 347 /** 348 * This is renderer factory allows themes to override the standard renderers using php code. 349 * 350 * It will load any code from theme/mytheme/renderers.php and 351 * theme/parenttheme/renderers.php, if then exist. Then whenever you ask for 352 * a renderer for 'component', it will create a mytheme_component_renderer or a 353 * parenttheme_component_renderer, instead of a component_renderer, 354 * if either of those classes exist. 355 * 356 * @copyright 2009 Tim Hunt 357 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later 358 * @since Moodle 2.0 359 * @package core 360 * @category output 361 */ 362 class theme_overridden_renderer_factory extends renderer_factory_base { 363 364 /** 365 * @var array An array of renderer prefixes 366 */ 367 protected $prefixes = array(); 368 369 /** 370 * Constructor. 371 * @param theme_config $theme the theme we are rendering for. 372 */ 373 public function __construct(theme_config $theme) { 374 parent::__construct($theme); 375 // Initialise $this->prefixes. 376 $this->prefixes = $theme->renderer_prefixes(); 377 } 378 379 /** 380 * Implement the subclass method 381 * 382 * @param moodle_page $page the page the renderer is outputting content for. 383 * @param string $component name such as 'core', 'mod_forum' or 'qtype_multichoice'. 384 * @param string $subtype optional subtype such as 'news' resulting to 'mod_forum_news' 385 * @param string $target one of rendering target constants 386 * @return renderer_base an object implementing the requested renderer interface. 387 */ 388 public function get_renderer(moodle_page $page, $component, $subtype = null, $target = null) { 389 $classnames = $this->standard_renderer_classnames($component, $subtype); 390 391 list($target, $suffix) = $this->get_target_suffix($target); 392 393 // Theme lib.php and renderers.php files are loaded automatically 394 // when loading the theme configs. 395 396 // First try the renderers with correct suffix. 397 foreach ($this->prefixes as $prefix) { 398 foreach ($classnames as $classnamedetails) { 399 if ($classnamedetails['validwithprefix']) { 400 if ($classnamedetails['autoloaded']) { 401 $newclassname = $prefix . $classnamedetails['classname'] . $suffix; 402 } else { 403 $newclassname = $prefix . '_' . $classnamedetails['classname'] . $suffix; 404 } 405 if (class_exists($newclassname)) { 406 return new $newclassname($page, $target); 407 } 408 } 409 } 410 } 411 foreach ($classnames as $classnamedetails) { 412 if ($classnamedetails['validwithoutprefix']) { 413 $newclassname = $classnamedetails['classname'] . $suffix; 414 if (class_exists($newclassname)) { 415 // Use the specialised renderer for given target, default renderer might also decide 416 // to implement support for more targets. 417 return new $newclassname($page, $target); 418 } 419 } 420 } 421 422 // Then try general renderer. 423 foreach ($this->prefixes as $prefix) { 424 foreach ($classnames as $classnamedetails) { 425 if ($classnamedetails['validwithprefix']) { 426 if ($classnamedetails['autoloaded']) { 427 $newclassname = $prefix . $classnamedetails['classname']; 428 } else { 429 $newclassname = $prefix . '_' . $classnamedetails['classname']; 430 } 431 if (class_exists($newclassname)) { 432 return new $newclassname($page, $target); 433 } 434 } 435 } 436 } 437 438 // Final attempt - no prefix or suffix. 439 foreach ($classnames as $classnamedetails) { 440 if ($classnamedetails['validwithoutprefix']) { 441 $newclassname = $classnamedetails['classname']; 442 if (class_exists($newclassname)) { 443 return new $newclassname($page, $target); 444 } 445 } 446 } 447 throw new coding_exception('Request for an unknown renderer ' . $component . ', ' . $subtype . ', ' . $target); 448 } 449 }
title
Description
Body
title
Description
Body
title
Description
Body
title
Body