Output API: Difference between revisions
Damyon Wiese (talk | contribs) No edit summary |
Damyon Wiese (talk | contribs) No edit summary |
||
| Line 25: | Line 25: | ||
$PAGE->set_title($title); | $PAGE->set_title($title); | ||
$PAGE->set_heading($title); | $PAGE->set_heading($title); | ||
echo $ | |||
echo $ | $output = $PAGE->get_renderer('tool_demo'); | ||
echo $output->header(); | |||
echo $output->heading($pagetitle); | |||
$renderable = new \tool_demo\output\index_page('Some text'); | $renderable = new \tool_demo\output\index_page('Some text'); | ||
echo $output->render($renderable); | |||
echo $ | |||
echo $ | echo $output->footer(); | ||
</code> | </code> | ||
| Line 60: | Line 62: | ||
What is $PAGE and where did it come from ? | 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. | $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. See [[Page_API]] for more information on the $PAGE variable. | ||
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). | 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 | $PAGE also lets us load specific renderers for a plugin, or plugin and subtype. We will cover renderers in more detail next. | ||
<code php> | |||
$output = $PAGE->get_renderer('tool_demo'); | |||
</code> | |||
This gets an instance of the plugin_renderer_base class that we use to create all output for our page. Themers can subclass this renderer to override specific render methods in order to customise Moodle's output. See [[Output_renderers]] for more information, and [[Overriding_a_renderer]] for information about how themers can customise a renderer. | |||
Note - some pages use the global variable $OUTPUT to generate their output. This is a generic renderer used for core pages etc, but plugins should always use a more specific plugin renderer. | |||
<code php> | |||
echo $output->header(); | |||
echo $output->heading($pagetitle); | |||
</code> | |||
This code prints the header of the page and adds one heading to the page at the top of the content region. Page headings are very important in Moodle and should be applied consistently. See [[HTML_Guidelines]] for more information on how and where to use headings. | |||
<code php> | |||
$renderable = new \tool_demo\output\index_page('Some text'); | |||
echo $output->render($renderable); | |||
</code> | |||
This is the most interesting part of our page. We are creating a renderable and telling our renderer to render it. The renderable is usually more complex than this, it should hold all the data required for the renderer to display the page. This means we should perform all our logic such as database queries, page parameters and access checks in advance and the results should be passed as data to the renderable. The renderable then just takes that data and returns a HTML representation of it. | |||
<code php> | |||
echo $output->footer(); | |||
</code> | |||
This prints the HTML for the bottom of the page. It is very important because it also prints out things that were added to the page_requirements_manager and need to be printed in the footer. Things like javascript includes, navigation tree setup, closing open containers tags etc. The reason all javascripts are added to the footer of the page is for performance. If you add javascript includes to the top of the page, or inline with the content the browser must stop and execute the javascript before it can render the page. See https://developers.google.com/speed/docs/insights/BlockingJS for more information. | |||
Revision as of 04:29, 28 April 2015
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');
// Set up the page.
$title = get_string('pluginname', 'tool_demo');
$pagetitle = $title;
$url = new moodle_url("/admin/tool/demo/index.php");
$PAGE->set_url($url);
$PAGE->set_title($title);
$PAGE->set_heading($title);
$output = $PAGE->get_renderer('tool_demo');
echo $output->header();
echo $output->heading($pagetitle);
$renderable = new \tool_demo\output\index_page('Some text');
echo $output->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).
// Set up the page.
$title = get_string('pluginname', 'tool_demo');
$pagetitle = $title;
$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. See Page_API for more information on the $PAGE variable.
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 next.
$output = $PAGE->get_renderer('tool_demo');
This gets an instance of the plugin_renderer_base class that we use to create all output for our page. Themers can subclass this renderer to override specific render methods in order to customise Moodle's output. See Output_renderers for more information, and Overriding_a_renderer for information about how themers can customise a renderer.
Note - some pages use the global variable $OUTPUT to generate their output. This is a generic renderer used for core pages etc, but plugins should always use a more specific plugin renderer.
echo $output->header();
echo $output->heading($pagetitle);
This code prints the header of the page and adds one heading to the page at the top of the content region. Page headings are very important in Moodle and should be applied consistently. See HTML_Guidelines for more information on how and where to use headings.
$renderable = new \tool_demo\output\index_page('Some text');
echo $output->render($renderable);
This is the most interesting part of our page. We are creating a renderable and telling our renderer to render it. The renderable is usually more complex than this, it should hold all the data required for the renderer to display the page. This means we should perform all our logic such as database queries, page parameters and access checks in advance and the results should be passed as data to the renderable. The renderable then just takes that data and returns a HTML representation of it.
echo $output->footer();
This prints the HTML for the bottom of the page. It is very important because it also prints out things that were added to the page_requirements_manager and need to be printed in the footer. Things like javascript includes, navigation tree setup, closing open containers tags etc. The reason all javascripts are added to the footer of the page is for performance. If you add javascript includes to the top of the page, or inline with the content the browser must stop and execute the javascript before it can render the page. See https://developers.google.com/speed/docs/insights/BlockingJS for more information.
