mirror of
https://github.com/moodle/moodle.git
synced 2025-01-18 14:03:52 +01:00
003577cd85
They were only added to support templates, and due to refactoring are not required any more. So we should remove this API change.
448 lines
18 KiB
PHP
448 lines
18 KiB
PHP
<?php
|
|
// This file is part of Moodle - http://moodle.org/
|
|
//
|
|
// Moodle is free software: you can redistribute it and/or modify
|
|
// it under the terms of the GNU General Public License as published by
|
|
// the Free Software Foundation, either version 3 of the License, or
|
|
// (at your option) any later version.
|
|
//
|
|
// Moodle is distributed in the hope that it will be useful,
|
|
// but WITHOUT ANY WARRANTY; without even the implied warranty of
|
|
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
|
|
// GNU General Public License for more details.
|
|
//
|
|
// You should have received a copy of the GNU General Public License
|
|
// along with Moodle. If not, see <http://www.gnu.org/licenses/>.
|
|
|
|
/**
|
|
* Interface and classes for creating appropriate renderers for various parts of Moodle.
|
|
*
|
|
* Please see http://docs.moodle.org/en/Developement:How_Moodle_outputs_HTML
|
|
* for an overview.
|
|
*
|
|
* @copyright 2009 Tim Hunt
|
|
* @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
|
|
* @package core
|
|
* @category output
|
|
*/
|
|
|
|
defined('MOODLE_INTERNAL') || die();
|
|
|
|
/** General rendering target, usually normal browser page */
|
|
define('RENDERER_TARGET_GENERAL', 'general');
|
|
|
|
/** General rendering target, usually normal browser page, but with limited capacity to avoid API use */
|
|
define('RENDERER_TARGET_MAINTENANCE', 'maintenance');
|
|
|
|
/** Plain text rendering for CLI scripts and cron */
|
|
define('RENDERER_TARGET_CLI', 'cli');
|
|
|
|
/** Plain text rendering for Ajax scripts*/
|
|
define('RENDERER_TARGET_AJAX', 'ajax');
|
|
|
|
/** Plain text rendering intended for sending via email */
|
|
define('RENDERER_TARGET_TEXTEMAIL', 'textemail');
|
|
|
|
/** Rich text html rendering intended for sending via email */
|
|
define('RENDERER_TARGET_HTMLEMAIL', 'htmlemail');
|
|
|
|
// note: maybe we could define portfolio export target too
|
|
|
|
|
|
/**
|
|
* A renderer factory is just responsible for creating an appropriate renderer
|
|
* for any given part of Moodle.
|
|
*
|
|
* Which renderer factory to use is chose by the current theme, and an instance
|
|
* if created automatically when the theme is set up.
|
|
*
|
|
* A renderer factory must also have a constructor that takes a theme_config object.
|
|
* (See {@link renderer_factory_base::__construct} for an example.)
|
|
*
|
|
* @copyright 2009 Tim Hunt
|
|
* @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
|
|
* @since Moodle 2.0
|
|
* @package core
|
|
* @category output
|
|
*/
|
|
interface renderer_factory {
|
|
|
|
/**
|
|
* Return the renderer for a particular part of Moodle.
|
|
*
|
|
* The renderer interfaces are defined by classes called {plugin}_renderer
|
|
* where {plugin} is the name of the component. The renderers for core Moodle are
|
|
* defined in lib/renderer.php. For plugins, they will be defined in a file
|
|
* called renderer.php inside the plugin.
|
|
*
|
|
* Renderers will normally want to subclass the renderer_base class.
|
|
* (However, if you really know what you are doing, you don't have to do that.)
|
|
*
|
|
* There is no separate interface definition for renderers. The default
|
|
* {plugin}_renderer implementation also serves to define the API for
|
|
* other implementations of the interface, whether or not they subclass it.
|
|
*
|
|
* A particular plugin can define multiple renderers if it wishes, using the
|
|
* $subtype parameter. For example workshop_renderer,
|
|
* workshop_allocation_manual_renderer etc.
|
|
*
|
|
* @param moodle_page $page the page the renderer is outputting content for.
|
|
* @param string $component name such as 'core', 'mod_forum' or 'qtype_multichoice'.
|
|
* @param string $subtype optional subtype such as 'news' resulting to 'mod_forum_news'
|
|
* @param string $target one of rendering target constants
|
|
* @return renderer_base an object implementing the requested renderer interface.
|
|
*/
|
|
public function get_renderer(moodle_page $page, $component, $subtype=null, $target=null);
|
|
}
|
|
|
|
|
|
/**
|
|
* This is a base class to help you implement the renderer_factory interface.
|
|
*
|
|
* It keeps a cache of renderers that have been constructed, so you only need
|
|
* to construct each one once in you subclass.
|
|
*
|
|
* It also has a method to get the name of, and include the renderer.php with
|
|
* the definition of, the standard renderer class for a given module.
|
|
*
|
|
* @copyright 2009 Tim Hunt
|
|
* @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
|
|
* @since Moodle 2.0
|
|
* @package core
|
|
* @category output
|
|
*/
|
|
abstract class renderer_factory_base implements renderer_factory {
|
|
/**
|
|
* @var theme_config The theme we belong to.
|
|
*/
|
|
protected $theme;
|
|
|
|
/**
|
|
* Constructor.
|
|
*
|
|
* @param theme_config $theme the theme we belong to.
|
|
*/
|
|
public function __construct(theme_config $theme) {
|
|
$this->theme = $theme;
|
|
}
|
|
|
|
/**
|
|
* Returns suffix of renderer class expected for given target.
|
|
*
|
|
* @param string $target one of the renderer target constants, target is guessed if null used
|
|
* @return array two element array, first element is target, second the target suffix string
|
|
*/
|
|
protected function get_target_suffix($target) {
|
|
if (empty($target) || $target === RENDERER_TARGET_MAINTENANCE) {
|
|
// If the target hasn't been specified we need to guess the defaults.
|
|
// We also override the target with the default if the maintenance target has been provided.
|
|
// This ensures we don't use the maintenance renderer if we are processing a special target.
|
|
if (CLI_SCRIPT) {
|
|
$target = RENDERER_TARGET_CLI;
|
|
} else if (AJAX_SCRIPT) {
|
|
$target = RENDERER_TARGET_AJAX;
|
|
}
|
|
}
|
|
|
|
switch ($target) {
|
|
case RENDERER_TARGET_CLI: $suffix = '_cli'; break;
|
|
case RENDERER_TARGET_AJAX: $suffix = '_ajax'; break;
|
|
case RENDERER_TARGET_TEXTEMAIL: $suffix = '_textemail'; break;
|
|
case RENDERER_TARGET_HTMLEMAIL: $suffix = '_htmlemail'; break;
|
|
case RENDERER_TARGET_MAINTENANCE: $suffix = '_maintenance'; break;
|
|
default: $target = RENDERER_TARGET_GENERAL; $suffix = '';
|
|
}
|
|
|
|
return array($target, $suffix);
|
|
}
|
|
|
|
/**
|
|
* For a given module name, return the possible class names
|
|
* that defines the renderer interface for that module.
|
|
*
|
|
* Newer auto-loaded class names are returned as well as the old style _renderable classnames.
|
|
*
|
|
* Also, if it exists, include the renderer.php file for that module, so
|
|
* the class definition of the default renderer has been loaded.
|
|
*
|
|
* @param string $component name such as 'core', 'mod_forum' or 'qtype_multichoice'.
|
|
* @param string $subtype optional subtype such as 'news' resulting to:
|
|
* '\mod_forum\output\news_renderer'
|
|
* or '\mod_forum\output\news\renderer'
|
|
* or non-autoloaded 'mod_forum_news'
|
|
* @return array[] Each element of the array is an array with keys:
|
|
* classname - The class name to search
|
|
* autoloaded - Does this classname assume autoloading?
|
|
* validwithprefix - Is this class name valid when a prefix is added to it?
|
|
* validwithoutprefix - Is this class name valid when no prefix is added to it?
|
|
* @throws coding_exception
|
|
*/
|
|
protected function standard_renderer_classnames($component, $subtype = null) {
|
|
global $CFG; // Needed in included files.
|
|
$classnames = array();
|
|
|
|
// Standardize component name ala frankenstyle.
|
|
list($plugin, $type) = core_component::normalize_component($component);
|
|
if ($type === null) {
|
|
$component = $plugin;
|
|
} else {
|
|
$component = $plugin.'_'.$type;
|
|
}
|
|
|
|
if ($component !== 'core') {
|
|
// Renderers are stored in renderer.php files.
|
|
if (!$compdirectory = core_component::get_component_directory($component)) {
|
|
throw new coding_exception('Invalid component specified in renderer request', $component);
|
|
}
|
|
$rendererfile = $compdirectory . '/renderer.php';
|
|
if (file_exists($rendererfile)) {
|
|
include_once($rendererfile);
|
|
}
|
|
|
|
} else if (!empty($subtype)) {
|
|
$coresubsystems = core_component::get_core_subsystems();
|
|
if (!array_key_exists($subtype, $coresubsystems)) { // There may be nulls.
|
|
throw new coding_exception('Invalid core subtype "' . $subtype . '" in renderer request', $subtype);
|
|
}
|
|
if ($coresubsystems[$subtype]) {
|
|
$rendererfile = $coresubsystems[$subtype] . '/renderer.php';
|
|
if (file_exists($rendererfile)) {
|
|
include_once($rendererfile);
|
|
}
|
|
}
|
|
}
|
|
|
|
if (empty($subtype)) {
|
|
// Theme specific auto-loaded name (only valid when prefixed with the theme name).
|
|
$classnames[] = array(
|
|
'validwithprefix' => true,
|
|
'validwithoutprefix' => false,
|
|
'autoloaded' => true,
|
|
'classname' => '\\output\\' . $component . '_renderer'
|
|
);
|
|
|
|
// Standard autoloaded plugin name (not valid with a prefix).
|
|
$classnames[] = array(
|
|
'validwithprefix' => false,
|
|
'validwithoutprefix' => true,
|
|
'autoloaded' => true,
|
|
'classname' => '\\' . $component . '\\output\\renderer'
|
|
);
|
|
// Legacy class name - (valid with or without a prefix).
|
|
$classnames[] = array(
|
|
'validwithprefix' => true,
|
|
'validwithoutprefix' => true,
|
|
'autoloaded' => false,
|
|
'classname' => $component . '_renderer'
|
|
);
|
|
} else {
|
|
// Theme specific auto-loaded name (only valid when prefixed with the theme name).
|
|
$classnames[] = array(
|
|
'validwithprefix' => true,
|
|
'validwithoutprefix' => false,
|
|
'autoloaded' => true,
|
|
'classname' => '\\output\\' . $component . '\\' . $subtype . '_renderer'
|
|
);
|
|
// Version of the above with subtype being a namespace level on it's own.
|
|
$classnames[] = array(
|
|
'validwithprefix' => true,
|
|
'validwithoutprefix' => false,
|
|
'autoloaded' => true,
|
|
'classname' => '\\output\\' . $component . '\\' . $subtype . '\\renderer'
|
|
);
|
|
// Standard autoloaded plugin name (not valid with a prefix).
|
|
$classnames[] = array(
|
|
'validwithprefix' => false,
|
|
'validwithoutprefix' => true,
|
|
'autoloaded' => true,
|
|
'classname' => '\\' . $component . '\\output\\' . $subtype . '_renderer'
|
|
);
|
|
// Version of the above with subtype being a namespace level on it's own.
|
|
$classnames[] = array(
|
|
'validwithprefix' => false,
|
|
'validwithoutprefix' => true,
|
|
'autoloaded' => true,
|
|
'classname' => '\\' . $component . '\\output\\' . $subtype . '\\renderer'
|
|
);
|
|
// Legacy class name - (valid with or without a prefix).
|
|
$classnames[] = array(
|
|
'validwithprefix' => true,
|
|
'validwithoutprefix' => true,
|
|
'autoloaded' => false,
|
|
'classname' => $component . '_' . $subtype . '_renderer'
|
|
);
|
|
}
|
|
return $classnames;
|
|
}
|
|
}
|
|
|
|
/**
|
|
* This is the default renderer factory for Moodle.
|
|
*
|
|
* It simply returns an instance of the appropriate standard renderer class.
|
|
*
|
|
* @copyright 2009 Tim Hunt
|
|
* @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
|
|
* @since Moodle 2.0
|
|
* @package core
|
|
* @category output
|
|
*/
|
|
class standard_renderer_factory extends renderer_factory_base {
|
|
|
|
/**
|
|
* Implement the subclass method
|
|
*
|
|
* @param moodle_page $page the page the renderer is outputting content for.
|
|
* @param string $component name such as 'core', 'mod_forum' or 'qtype_multichoice'.
|
|
* @param string $subtype optional subtype such as 'news' resulting to 'mod_forum_news'
|
|
* @param string $target one of rendering target constants
|
|
* @return renderer_base an object implementing the requested renderer interface.
|
|
*/
|
|
public function get_renderer(moodle_page $page, $component, $subtype = null, $target = null) {
|
|
$classnames = $this->standard_renderer_classnames($component, $subtype);
|
|
$classname = '';
|
|
|
|
list($target, $suffix) = $this->get_target_suffix($target);
|
|
// First look for a version with a suffix.
|
|
foreach ($classnames as $classnamedetails) {
|
|
if ($classnamedetails['validwithoutprefix']) {
|
|
$newclassname = $classnamedetails['classname'] . $suffix;
|
|
if (class_exists($newclassname)) {
|
|
$classname = $newclassname;
|
|
break;
|
|
} else {
|
|
$newclassname = $classnamedetails['classname'];
|
|
if (class_exists($newclassname)) {
|
|
$classname = $newclassname;
|
|
break;
|
|
}
|
|
}
|
|
}
|
|
}
|
|
// Now look for a non-suffixed version.
|
|
if (empty($classname)) {
|
|
foreach ($classnames as $classnamedetails) {
|
|
if ($classnamedetails['validwithoutprefix']) {
|
|
$newclassname = $classnamedetails['classname'];
|
|
if (class_exists($newclassname)) {
|
|
$classname = $newclassname;
|
|
break;
|
|
}
|
|
}
|
|
}
|
|
}
|
|
|
|
if (empty($classname)) {
|
|
// Standard renderer must always exist.
|
|
throw new coding_exception('Request for an unknown renderer class. Searched for: ' . var_export($classnames, true));
|
|
}
|
|
|
|
return new $classname($page, $target);
|
|
}
|
|
}
|
|
|
|
|
|
/**
|
|
* This is renderer factory allows themes to override the standard renderers using php code.
|
|
*
|
|
* It will load any code from theme/mytheme/renderers.php and
|
|
* theme/parenttheme/renderers.php, if then exist. Then whenever you ask for
|
|
* a renderer for 'component', it will create a mytheme_component_renderer or a
|
|
* parenttheme_component_renderer, instead of a component_renderer,
|
|
* if either of those classes exist.
|
|
*
|
|
* @copyright 2009 Tim Hunt
|
|
* @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
|
|
* @since Moodle 2.0
|
|
* @package core
|
|
* @category output
|
|
*/
|
|
class theme_overridden_renderer_factory extends renderer_factory_base {
|
|
|
|
/**
|
|
* @var array An array of renderer prefixes
|
|
*/
|
|
protected $prefixes = array();
|
|
|
|
/**
|
|
* Constructor.
|
|
* @param theme_config $theme the theme we are rendering for.
|
|
*/
|
|
public function __construct(theme_config $theme) {
|
|
parent::__construct($theme);
|
|
// Initialise $this->prefixes.
|
|
$this->prefixes = $theme->renderer_prefixes();
|
|
}
|
|
|
|
/**
|
|
* Implement the subclass method
|
|
*
|
|
* @param moodle_page $page the page the renderer is outputting content for.
|
|
* @param string $component name such as 'core', 'mod_forum' or 'qtype_multichoice'.
|
|
* @param string $subtype optional subtype such as 'news' resulting to 'mod_forum_news'
|
|
* @param string $target one of rendering target constants
|
|
* @return renderer_base an object implementing the requested renderer interface.
|
|
*/
|
|
public function get_renderer(moodle_page $page, $component, $subtype = null, $target = null) {
|
|
$classnames = $this->standard_renderer_classnames($component, $subtype);
|
|
|
|
list($target, $suffix) = $this->get_target_suffix($target);
|
|
|
|
// Theme lib.php and renderers.php files are loaded automatically
|
|
// when loading the theme configs.
|
|
|
|
// First try the renderers with correct suffix.
|
|
foreach ($this->prefixes as $prefix) {
|
|
foreach ($classnames as $classnamedetails) {
|
|
if ($classnamedetails['validwithprefix']) {
|
|
if ($classnamedetails['autoloaded']) {
|
|
$newclassname = $prefix . $classnamedetails['classname'] . $suffix;
|
|
} else {
|
|
$newclassname = $prefix . '_' . $classnamedetails['classname'] . $suffix;
|
|
}
|
|
if (class_exists($newclassname)) {
|
|
return new $newclassname($page, $target);
|
|
}
|
|
}
|
|
}
|
|
}
|
|
foreach ($classnames as $classnamedetails) {
|
|
if ($classnamedetails['validwithoutprefix']) {
|
|
$newclassname = $classnamedetails['classname'] . $suffix;
|
|
if (class_exists($newclassname)) {
|
|
// Use the specialised renderer for given target, default renderer might also decide
|
|
// to implement support for more targets.
|
|
return new $newclassname($page, $target);
|
|
}
|
|
}
|
|
}
|
|
|
|
// Then try general renderer.
|
|
foreach ($this->prefixes as $prefix) {
|
|
foreach ($classnames as $classnamedetails) {
|
|
if ($classnamedetails['validwithprefix']) {
|
|
if ($classnamedetails['autoloaded']) {
|
|
$newclassname = $prefix . $classnamedetails['classname'];
|
|
} else {
|
|
$newclassname = $prefix . '_' . $classnamedetails['classname'];
|
|
}
|
|
if (class_exists($newclassname)) {
|
|
return new $newclassname($page, $target);
|
|
}
|
|
}
|
|
}
|
|
}
|
|
|
|
// Final attempt - no prefix or suffix.
|
|
foreach ($classnames as $classnamedetails) {
|
|
if ($classnamedetails['validwithoutprefix']) {
|
|
$newclassname = $classnamedetails['classname'];
|
|
if (class_exists($newclassname)) {
|
|
return new $newclassname($page, $target);
|
|
}
|
|
}
|
|
}
|
|
throw new coding_exception('Request for an unknown renderer ' . $component . ', ' . $subtype . ', ' . $target);
|
|
}
|
|
}
|