Page API

The Page API is used to set up the current page, add JavaScript, and configure how things will be displayed to the user.

Overview

The Page API is an integral part of any Moodle page. It also the developer to set things up they way they envisage it. Through the Page API you can set things like the title, initial heading, where the user is for the navigation, and which layout you think the page should use.

This document starts off with a couple of easy to follow examples that you quickly read through, and then proceeds to provide a more complete description of how to set up a page for display.

Examples

There are several quick to follow examples of basic page setup depending upon what sort of page you are creating.

Activity page

This example covers how to set up a basic page for use within an activity plugin and is undoubtedly the simplest example as much of the work is done behind the scenes for you. // File: /mod/mymodulename/view.php require_once('../../config.php'); $cmid = required_param('id', PARAM_INT); $cm = get_coursemodule_by_id('mymodulename', $cmid, 0, false, MUST_EXIST); $course = $DB->get_record('course', array('id' => $cm->course), '*', MUST_EXIST);

require_login($course, true, $cm); $PAGE->set_url('/mod/mymodulename/index.php', array('id' => $cm->id)); $PAGE->set_title('My modules page title'); $PAGE->set_heading('My modules page heading'); I'm going to assume you know what the first four lines are doing, if not you are starting in the wrong place.

So lets start at require_login and assume you already have the course and course module objects ready to use. When you call require_login part of the magic it does for you is set up the basic for the current page.
In the case of the example above because require_login is given a course and course module it is already setting up much of the page for you. It is giving the course and course module objects to the page, setting the context for the page to the course modules context, and setting the page layout to incourse so that you get the standard look of a course module.

The set up that we are having to do is as follows:

1. Set the URL for the page. This MUST be done.
2. Set a title for the page. Most likely will be shown in the <title> tag.
3. Set the heading for the page. Most likely used in the pages header.

And that is it, if you were to add a bit of simple output there you would get a page that already looks like other module pages you would have seen. Simple as.

Local plugin page

This is the most thorough example. Because the local plugin does not normally work within any context and can be completely stand alone they tend to involve more set up then the average plugin.

$PAGE

For every page request Moodle sets up a couple of global structures they you will likely to need. $DB the database object, and $CFG which stores configuration are two that you are likely already aware of. $PAGE is the focus of this article, it is a moodle_page instance that stores all of the information and is used by the output library $OUTPUT when displaying the page.
It's important to note the difference between $PAGE and $OUTPUT, $PAGE is for setting up the page and $OUTPUT is for displaying the page. $PAGE contains lots of logic and magic, $OUTPUT is purely about display and does little more than produce HTML.

Required set up

When creating a page in Moodle there are a couple of things that you must set, and a couple of things that get set for you in many cases but not all of the time.

URL

This is an absolute must, failing to set this will lead to Moodle displaying a error that it has not being set.
It can be set in the following manner:

$PAGE->set_url(new moodle_url('/page/to/your/file.php', array('key' => 'value', 'id' => 3))); $PAGE->set_url('/page/to/your/file.php', array('key' => 'value', 'id' => 3)); $PAGE->set_url('/page/to/your/file.php?key=value&id=3');

The above code sets the page URL 3 times, and highlights the 3 different ways you can set the URL. Either of the first two methods are the preferred way as it provides 100% accuracy when processing the URL. Internally set_url() converts what ever you give it to a moodle_url object.

The URL that you give to the page is going to be use by a lot of Moodle core API's. Most importantly it is going to be used to create the navigation for your page so it's very important you set it accurately.

Context

This is an absolute must as well, however in many cases it will be set for you magically by Moodle.

In order to set the context for the page you must provide a context object, in Moodle 2.2 and greater this will look as follows: // Moodle 2.2 and greater $PAGE->set_context(context_system::instance()); $PAGE->set_context(context_coursecat::instance($categoryid)); $PAGE->set_context(context_course::instance($courseid)); $PAGE->set_context(context_module::instance($moduleid));

In Moodle 2.0+, and Moodle 2.1+ the following is the equivilant code: // Moodle 2.2 and greater $PAGE->set_context(get_system_context()); $PAGE->set_context(get_context_instance(CONTEXT_COURSECAT, $categoryid)); $PAGE->set_context(get_context_instance(CONTEXT_COURSE, $courseid)); $PAGE->set_context(get_context_instance(CONTEXT_MODULE, $moduleid));

In both examples above setting different types of contexts has been illustrated however you should only ever call set_context() once with the context that is most appropriate to the page you are creating.
If it is a plugin then the context to use would be the context you are using for your capability checks.

As mentioned above the other thing to be aware of is that in some circumstances this gets automatically set for you.
If your script calls require_login (and most scripts have to) and you are providing a course, or a module to your require login call then you will not need to call set_context().
This is because require_login handles it for you.

If your script doesn't call require_login, or you don't call it with a course and/or module then you will need to manually set the context as shown.

Advanced set up

$PAGE->set_course($courserecord)

This allows you to set the course the page belongs to. Normally when you call require_login the course you give it automatically gets sent to $PAGE for you. However if you don't want to require login for the course, but you need it in $PAGE then you can call set_course and provide it. Note that if you do this then you MUST use the context of the course when calling set_context().

$PAGE->set_cm($coursemodulerecord)

Like set page above, sometimes you need to manually set the course module for $PAGE. Again you must set the context to the context of the course module if you call this.

$PAGE->set_activity_record($activityrecord)

If you have called require_login with a course module, or you have manually set a course module on $PAGE then one other thing you may want to do is set the activity module record on $PAGE as well. This is best done when you have already fetched the activity record yourself in which case manually setting the activity record may reduce the number of queries for the page by 1.

$PAGE->set_button($htmlstring)

This allows you to set some HTML that will be shown in the navigation bar where the `Turn on editing` button normally lives.

$PAGE->set_headingmenu($htmlstring)

This allows you to set some HTML that will be shown next to the pages main heading where the language select box normally lives.