Output API

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.

Moodle 2.9

See Output Components for (much) older information on the using output components in previous versions of Moodle.

This page is a fresh attempt to explain how renderers, renderables, themes and templates all work together for Moodle 2.9.

Lets start with building a page that is part of an admin tool.

E.g. /admin/tool/demo/index.php

   // Standard GPL and phpdocs
   require_once(__DIR__ . '/../../../config.php');
   require_once($CFG->libdir.'/adminlib.php');
   
   admin_externalpage_setup('tooldemo');
   
   $title = get_string('pluginname', 'tool_demo');
   $pagetitle = $title;
   // Set up the page.
   $url = new moodle_url("/admin/tool/demo/index.php");
   $PAGE->set_url($url);
   $PAGE->set_title($title);
   $PAGE->set_heading($title);
   echo $OUTPUT->header();
   echo $OUTPUT->heading($pagetitle);
   
   $renderable = new \tool_demo\output\index_page('Some text');
   $pluginrenderer = $PAGE->get_renderer('tool_demo');
   echo $pluginrenderer->render($renderable);
   
   echo $OUTPUT->footer();
   

Explaining this demo step by step we have firstly the standard config and includes, plus the admin_externalpage_setup('tooldemo') which calls require_login and performs permissions checks for admin pages.

   // Standard GPL and phpdocs
   require_once(__DIR__ . '/../../../config.php');
   require_once($CFG->libdir.'/adminlib.php');
   
   admin_externalpage_setup('tooldemo');

Then we load the title of the page from a lang string (see String_API ). We use this string to set some $PAGE properties (url title and heading).

   $title = get_string('pluginname', 'tool_demo');
   $pagetitle = $title;
   // Set up the page.
   $url = new moodle_url("/admin/tool/demo/index.php");
   $PAGE->set_url($url);
   $PAGE->set_title($title);
   $PAGE->set_heading($title);

What is $PAGE and where did it come from ?

$PAGE is a global variable used to track the state of the page that is being returned. It is an instance of the moodle_page class defined in lib/pagelib.php.

The most important properties stored in $PAGE are the page context, the url, the layout, title and headings. $PAGE also gives access to some other important classes such as $PAGE->requires, which is an instance of the page_requirements_manager (lib/outputrequirementslib.php). The page_requirements_manager class lets us set dependencies on e.g. javascript and css to be inserted in the correct place in the page (The order things are inserted in the page is hugely important for performance).

$PAGE also lets us load specific renderers for a plugin, or plugin and subtype. We will cover renderers in more detail soon.

TODO...