Difference between revisions of "Output renderers"

Jump to: navigation, search
(Renderers)
(Theme customisations)
Line 94: Line 94:
  
 
==Theme renderers==
 
==Theme renderers==
 +
 +
Theme renderers are stored in renderers.php file in theme folder. The actual overriding of renderers is the responsibility of renderer_factory classes which may be selected in theme config.php.
  
 
=Low level HTML output=
 
=Low level HTML output=

Revision as of 20:02, 7 January 2010

Note: This page is a work-in-progress. Feedback and suggested improvements are welcome. Please join the discussion on moodle.org or use the page comments.

Output renderers
Project state Specification
Tracker issue MDL-21235
Discussion n/a
Assignee Petr Škoda (škoďák) + David Mudrak + feedback and ideas from other developers

Moodle 2.0


Goals

  • stable API
  • easy to use
  • easy to customise via themes

Renderers

Output renderer is a class with collection of methods that handle rendering of visual aspects of Moodle pages, emails, html export, etc. In 1.9 general output related functions were located in weblib.php and modules stored rendering code in lib.php, locallib.php, view.php, etc.

Output renderer instances are obtained through moodle_page::get_renderer($component, $subtype = null, $target = null) method. Current core_renderer is available through the global $OUTPUT variable, please note this global should not be used in low level APIs.

The general renderer class naming convention is:

{theme name}_{plugin type}_{plugin_name}_renderer_{target} - custom_corners_core_renderer, mod_workshop_renderer, mod_forum_renderer_cli, etc.

Renderer targets

I most cases we are rendering page output for web browsers, sometimes we need to generate different output for command line scripts, email messages, etc.

renderer_base

Abstract class every other renderer must extend. Renderer base implements basic methods and support for renderer dispatching. The most important method is render(), it is using class name of the widget passed in first parameter to find fine correct protected rendering method (widget rendering methods have render_ prefix.

core_renderer

Core renderer implements:

  1. page header and footer related rendering
  2. boxes and containers
  3. general widget methods - heading, single button, select form, heading, arrows, language selection, user login info
  4. error messages, notifications
  5. blocks

For example user avatar rendering involves following methods and classes:

class core_renderer extends renderer_base {
  // ...
 
  public function render(widget $widget) {
     // calls $this->render_user_image($widget) when parameter with class user_image submitted 
  }
  protected function render_user_picture(user_picture $userpicture) {
    // returns html markup for user avatar
  }
  public function user_picture($userrecord, array $options=null) {
    // helper method that constructs $user_image widget and calls $this->render
    $picture = new user_picture($userrecord, $options);
    return $this->render($picture);
  }
 
  // ...
}
 
class user_picture extends widget {
  public $userrecord;
  public $options;
 
  public function __construct($userrecord, array $options=null) {
      // ...
  }
}

Developer has two options, either call

echo $OUTPUT->user_picture($user);

or create new instance:

$picture = new user_picture($user);
echo $OUTPUT->render($picture);

The point is that the first is usually one line only, it is also possible to have multiple helpers with different parameters. The second options enables more options without cluttering the simple API with tens of optional method parameters.

core_renderer_cli

_cli suffix indicates this is a core renderer for CLI rendering target (CLI scripts). For example headings are using => instead if H2 html tag.

Core subsystem renderers

Plugin renderers

Plugin renderers are stored in renderer.php file in the same folder as the lib.php file of each plugin.

Bootstrap renderer

Bootstrap renderer is used as a temporary $OUTPUT before the full initialisation of standard core renderer.

Theme customisations

Theme renderers

Theme renderers are stored in renderers.php file in theme folder. The actual overriding of renderers is the responsibility of renderer_factory classes which may be selected in theme config.php.

Low level HTML output

See also