Search moodle.org's
Developer Documentation

See Release Notes

  • Bug fixes for general core bugs in 3.10.x will end 8 November 2021 (12 months).
  • Bug fixes for security issues in 3.10.x will end 9 May 2022 (18 months).
  • PHP version: minimum PHP 7.2.0 Note: minimum PHP version has increased since Moodle 3.8. PHP 7.3.x and 7.4.x are supported too.
/lib/ -> pagelib.php (source)

Differences Between: [Versions 310 and 311] [Versions 310 and 400] [Versions 310 and 401] [Versions 310 and 402] [Versions 310 and 403] [Versions 39 and 310]

This file contains the moodle_page class. There is normally a single instance of this class in the $PAGE global variable. This class is a central repository of information about the page we are building up to send back to the user.

Copyright: 1999 onwards Martin Dougiamas {@link http://moodle.com}
License: http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
File Size: 2095 lines (79 kb)
Included or required:0 times
Referenced: 0 times
Includes or requires: 0 files

Defines 1 class

moodle_page:: (101 methods):
  force_settings_menu()
  is_settings_menu_forced()
  magic_get_state()
  magic_get_headerprinted()
  magic_get_course()
  magic_get_cm()
  magic_get_activityrecord()
  magic_get_activityname()
  magic_get_category()
  magic_get_categories()
  magic_get_context()
  magic_get_pagetype()
  magic_get_bodyid()
  magic_get_pagelayout()
  magic_get_layout_options()
  magic_get_subpage()
  magic_get_bodyclasses()
  magic_get_title()
  magic_get_heading()
  magic_get_headingmenu()
  magic_get_docspath()
  magic_get_url()
  magic_get_alternateversions()
  magic_get_blocks()
  magic_get_requires()
  magic_get_cacheable()
  magic_get_focuscontrol()
  magic_get_button()
  magic_get_theme()
  magic_get_blockmanipulations()
  magic_get_devicetypeinuse()
  magic_get_periodicrefreshdelay()
  magic_get_opencontainers()
  magic_get_navigation()
  magic_get_navbar()
  magic_get_settingsnav()
  magic_get_flatnav()
  magic_get_requestip()
  magic_get_requestorigin()
  __get()
  __set()
  get_renderer()
  has_navbar()
  start_collecting_javascript_requirements()
  end_collecting_javascript_requirements()
  user_is_editing()
  user_can_edit_blocks()
  user_allowed_editing()
  debug_summary()
  set_state()
  set_course()
  set_context()
  set_cm()
  set_activity_record()
  set_pagetype()
  set_pagelayout()
  set_subpage()
  add_body_class()
  add_body_classes()
  set_title()
  set_heading()
  set_headingmenu()
  set_category_by_id()
  set_docs_path()
  set_url()
  ensure_param_not_in_url()
  add_alternate_version()
  set_focuscontrol()
  set_button()
  set_blocks_editing_capability()
  set_other_editing_capability()
  set_cacheable()
  set_periodic_refresh_delay()
  force_theme()
  reload_theme()
  https_required()
  verify_https_required()
  starting_output()
  initialise_theme_and_output()
  get_where_theme_was_initialised()
  reset_theme_and_output()
  resolve_theme()
  initialise_default_pagetype()
  initialise_standard_body_classes()
  load_activity_record()
  ensure_category_loaded()
  load_category()
  ensure_categories_loaded()
  ensure_theme_not_set()
  url_to_class_name()
  all_editing_caps()
  has_set_url()
  set_block_actions_done()
  get_popup_notification_allowed()
  set_popup_notification_allowed()
  apply_theme_region_manipulations()
  add_report_nodes()
  add_header_action()
  get_header_actions()
  set_include_region_main_settings_in_header_actions()
  include_region_main_settings_in_header_actions()


Class: moodle_page  - X-Ref

$PAGE is a central store of information about the current page we are
generating in response to the user's request.

It does not do very much itself
except keep track of information, however, it serves as the access point to
some more significant components like $PAGE->theme, $PAGE->requires,
$PAGE->blocks, etc.

force_settings_menu($forced = true)   X-Ref
Force the settings menu to be displayed on this page. This will only force the
settings menu on an activity / resource page that is being displayed on a theme that
uses a settings menu.

param: bool $forced default of true, can be sent false to turn off the force.

is_settings_menu_forced()   X-Ref
Check to see if the settings menu is forced to display on this activity / resource page.
This only applies to themes that use the settings menu.

return: bool True if the settings menu is forced to display.

magic_get_state()   X-Ref
Please do not call this method directly, use the ->state syntax. {@link moodle_page::__get()}.

return: integer one of the STATE_XXX constants. You should not normally need

magic_get_headerprinted()   X-Ref
Please do not call this method directly, use the ->headerprinted syntax. {@link moodle_page::__get()}.

return: bool has the header already been printed?

magic_get_course()   X-Ref
Please do not call this method directly, use the ->course syntax. {@link moodle_page::__get()}.

return: stdClass the current course that we are inside - a row from the

magic_get_cm()   X-Ref
Please do not call this method directly, use the ->cm syntax. {@link moodle_page::__get()}.

return: cm_info the course_module that this page belongs to. Will be null

magic_get_activityrecord()   X-Ref
Please do not call this method directly, use the ->activityrecord syntax. {@link moodle_page::__get()}.

return: stdClass the row from the activities own database table (for example

magic_get_activityname()   X-Ref
Please do not call this method directly, use the ->activityname syntax. {@link moodle_page::__get()}.

return: string the The type of activity we are in, for example 'forum' or 'quiz'.

magic_get_category()   X-Ref
Please do not call this method directly, use the ->category syntax. {@link moodle_page::__get()}.

return: stdClass the category that the page course belongs to. If there isn't one

magic_get_categories()   X-Ref
Please do not call this method directly, use the ->categories syntax. {@link moodle_page::__get()}.

return: array an array of all the categories the page course belongs to,

magic_get_context()   X-Ref
Please do not call this method directly, use the ->context syntax. {@link moodle_page::__get()}.

return: context the main context to which this page belongs.

magic_get_pagetype()   X-Ref
Please do not call this method directly, use the ->pagetype syntax. {@link moodle_page::__get()}.

return: string e.g. 'my-index' or 'mod-quiz-attempt'.

magic_get_bodyid()   X-Ref
Please do not call this method directly, use the ->pagetype syntax. {@link moodle_page::__get()}.

return: string The id to use on the body tag, uses {@link magic_get_pagetype()}.

magic_get_pagelayout()   X-Ref
Please do not call this method directly, use the ->pagelayout syntax. {@link moodle_page::__get()}.

return: string the general type of page this is. For example 'standard', 'popup', 'home'.

magic_get_layout_options()   X-Ref
Please do not call this method directly, use the ->layout_options syntax. {@link moodle_page::__get()}.

return: array returns arrays with options for layout file

magic_get_subpage()   X-Ref
Please do not call this method directly, use the ->subpage syntax. {@link moodle_page::__get()}.

return: string The subpage identifier, if any.

magic_get_bodyclasses()   X-Ref
Please do not call this method directly, use the ->bodyclasses syntax. {@link moodle_page::__get()}.

return: string the class names to put on the body element in the HTML.

magic_get_title()   X-Ref
Please do not call this method directly, use the ->title syntax. {@link moodle_page::__get()}.

return: string the title that should go in the <head> section of the HTML of this page.

magic_get_heading()   X-Ref
Please do not call this method directly, use the ->heading syntax. {@link moodle_page::__get()}.

return: string the main heading that should be displayed at the top of the <body>.

magic_get_headingmenu()   X-Ref
Please do not call this method directly, use the ->heading syntax. {@link moodle_page::__get()}.

return: string The menu (or actions) to display in the heading

magic_get_docspath()   X-Ref
Please do not call this method directly, use the ->docspath syntax. {@link moodle_page::__get()}.

return: string the path to the Moodle docs for this page.

magic_get_url()   X-Ref
Please do not call this method directly, use the ->url syntax. {@link moodle_page::__get()}.

return: moodle_url the clean URL required to load the current page. (You

magic_get_alternateversions()   X-Ref
The list of alternate versions of this page.

return: array mime type => object with ->url and ->title.

magic_get_blocks()   X-Ref
Please do not call this method directly, use the ->blocks syntax. {@link moodle_page::__get()}.

return: block_manager the blocks manager object for this page.

magic_get_requires()   X-Ref
Please do not call this method directly, use the ->requires syntax. {@link moodle_page::__get()}.

return: page_requirements_manager tracks the JavaScript, CSS files, etc. required by this page.

magic_get_cacheable()   X-Ref
Please do not call this method directly, use the ->cacheable syntax. {@link moodle_page::__get()}.

return: bool can this page be cached by the user's browser.

magic_get_focuscontrol()   X-Ref
Please do not call this method directly, use the ->focuscontrol syntax. {@link moodle_page::__get()}.

return: string the id of the HTML element to be focused when the page has loaded.

magic_get_button()   X-Ref
Please do not call this method directly, use the ->button syntax. {@link moodle_page::__get()}.

return: string the HTML to go where the Turn editing on button normally goes.

magic_get_theme()   X-Ref
Please do not call this method directly, use the ->theme syntax. {@link moodle_page::__get()}.

return: theme_config the initialised theme for this page.

magic_get_blockmanipulations()   X-Ref
Returns an array of minipulations or false if there are none to make.

return: bool|array

magic_get_devicetypeinuse()   X-Ref
Please do not call this method directly, use the ->devicetypeinuse syntax. {@link moodle_page::__get()}.

return: string The device type being used.

magic_get_periodicrefreshdelay()   X-Ref
Please do not call this method directly use the ->periodicrefreshdelay syntax
{@link moodle_page::__get()}

return: int The periodic refresh delay to use with meta refresh

magic_get_opencontainers()   X-Ref
Please do not call this method directly use the ->opencontainers syntax. {@link moodle_page::__get()}

return: xhtml_container_stack tracks XHTML tags on this page that have been opened but not closed.

magic_get_navigation()   X-Ref
Return the navigation object

return: global_navigation

magic_get_navbar()   X-Ref
Return a navbar object

return: navbar

magic_get_settingsnav()   X-Ref
Returns the settings navigation object

return: settings_navigation

magic_get_flatnav()   X-Ref
Returns the flat navigation object

return: flat_navigation

magic_get_requestip()   X-Ref
Returns request IP address.

return: string IP address or null if unknown

magic_get_requestorigin()   X-Ref
Returns the origin of current request.

Note: constants are not required because we need to use these values in logging and reports.

return: string 'web', 'ws', 'cli', 'restore', etc.

__get($name)   X-Ref
PHP overloading magic to make the $PAGE->course syntax work by redirecting
it to the corresponding $PAGE->magic_get_course() method if there is one, and
throwing an exception if not.

param: string $name property name
return: mixed

__set($name, $value)   X-Ref
PHP overloading magic to catch obvious coding errors.

This method has been created to catch obvious coding errors where the
developer has tried to set a page property using $PAGE->key = $value.
In the moodle_page class all properties must be set using the appropriate
$PAGE->set_something($value) method.

param: string $name property name
param: mixed $value Value
return: void Throws exception if field not defined in page class

get_renderer($component, $subtype = null, $target = null)   X-Ref
Returns instance of page renderer

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

has_navbar()   X-Ref
Checks to see if there are any items on the navbar object

return: bool true if there are, false if not

start_collecting_javascript_requirements()   X-Ref
Switches from the regular requirements manager to the fragment requirements manager to
capture all necessary JavaScript to display a chunk of HTML such as an mform. This is for use
by the get_fragment() web service and not for use elsewhere.


end_collecting_javascript_requirements()   X-Ref
Switches back from collecting fragment JS requirement to the original requirement manager


user_is_editing()   X-Ref
Should the current user see this page in editing mode.
That is, are they allowed to edit this page, and are they currently in
editing mode.

return: bool

user_can_edit_blocks()   X-Ref
Does the user have permission to edit blocks on this page.

return: bool

user_allowed_editing()   X-Ref
Does the user have permission to see this page in editing mode.

return: bool

debug_summary()   X-Ref
Get a description of this page. Normally displayed in the footer in developer debug mode.

return: string

set_state($state)   X-Ref
Set the state.

The state must be one of that STATE_... constants, and the state is only allowed to advance one step at a time.

param: int $state The new state.

set_course($course)   X-Ref
Set the current course. This sets both $PAGE->course and $COURSE. It also
sets the right theme and locale.

Normally you don't need to call this function yourself, require_login will
call it for you if you pass a $course to it. You can use this function
on pages that do need to call require_login().

Sets $PAGE->context to the course context, if it is not already set.

param: stdClass $course the course to set as the global course.

set_context($context)   X-Ref
Set the main context to which this page belongs.

param: context $context a context object. You normally get this with context_xxxx::instance().

set_cm($cm, $course = null, $module = null)   X-Ref
The course module that this page belongs to (if it does belong to one).

param: stdClass|cm_info $cm a record from course_modules table or cm_info from get_fast_modinfo().
param: stdClass $course
param: stdClass $module
return: void

set_activity_record($module)   X-Ref
Sets the activity record. This could be a row from the main table for a
module. For instance if the current module (cm) is a forum this should be a row
from the forum table.

param: stdClass $module A row from the main database table for the module that this page belongs to.

set_pagetype($pagetype)   X-Ref
Sets the pagetype to use for this page.

Normally you do not need to set this manually, it is automatically created
from the script name. However, on some pages this is overridden.
For example the page type for course/view.php includes the course format,
for example 'course-view-weeks'. This gets used as the id attribute on
<body> and also for determining which blocks are displayed.

param: string $pagetype e.g. 'my-index' or 'mod-quiz-attempt'.

set_pagelayout($pagelayout)   X-Ref
Sets the layout to use for this page.

The page layout determines how the page will be displayed, things such as
block regions, content areas, etc are controlled by the layout.
The theme in use for the page will determine that the layout contains.

This properly defaults to 'base', so you only need to call this function if
you want something different. The exact range of supported layouts is specified
in the standard theme.

For an idea of the common page layouts see
{@link http://docs.moodle.org/dev/Themes_2.0#The_different_layouts_as_of_August_17th.2C_2010}
But please keep in mind that it may be (and normally is) out of date.
The only place to find an accurate up-to-date list of the page layouts
available for your version of Moodle is {@link theme/base/config.php}

param: string $pagelayout the page layout this is. For example 'popup', 'home'.

set_subpage($subpage)   X-Ref
If context->id and pagetype are not enough to uniquely identify this page,
then you can set a subpage id as well. For example, the tags page sets

param: string $subpage an arbitrary identifier that, along with context->id

add_body_class($class)   X-Ref
Adds a CSS class to the body tag of the page.

param: string $class add this class name ot the class attribute on the body tag.

add_body_classes($classes)   X-Ref
Adds an array of body classes to the body tag of this page.

param: array $classes this utility method calls add_body_class for each array element.

set_title($title)   X-Ref
Sets the title for the page.
This is normally used within the title tag in the head of the page.

param: string $title the title that should go in the <head> section of the HTML of this page.

set_heading($heading, bool $applyformatting = true)   X-Ref
Sets the heading to use for the page.
This is normally used as the main heading at the top of the content.

param: string $heading the main heading that should be displayed at the top of the <body>.
param: bool $applyformatting apply format_string() - by default true.

set_headingmenu($menu)   X-Ref
Sets some HTML to use next to the heading {@link moodle_page::set_heading()}

param: string $menu The menu/content to show in the heading

set_category_by_id($categoryid)   X-Ref
Set the course category this page belongs to manually.

This automatically sets $PAGE->course to be the site course. You cannot
use this method if you have already set $PAGE->course - in that case,
the category must be the one that the course belongs to. This also
automatically sets the page context to the category context.

param: int $categoryid The id of the category to set.

set_docs_path($path)   X-Ref
Set a different path to use for the 'Moodle docs for this page' link.

By default, it uses the pagetype, which is normally the same as the
script name. So, for example, for mod/quiz/attempt.php, pagetype is
mod-quiz-attempt, and so docspath is mod/quiz/attempt.

param: string $path the path to use at the end of the moodle docs URL.

set_url($url, array $params = null)   X-Ref
You should call this method from every page to set the URL that should be used to return to this page.

Used, for example, by the blocks editing UI to know where to return the
user after an action.
For example, course/view.php does:
$id = optional_param('id', 0, PARAM_INT);
$PAGE->set_url('/course/view.php', array('id' => $id));

param: moodle_url|string $url URL relative to $CFG->wwwroot or {@link moodle_url} instance
param: array $params parameters to add to the URL

ensure_param_not_in_url($param)   X-Ref
Make sure page URL does not contain the given URL parameter.

This should not be necessary if the script has called set_url properly.
However, in some situations like the block editing actions; when the URL
has been guessed, it will contain dangerous block-related actions.
Therefore, the blocks code calls this function to clean up such parameters
before doing any redirect.

param: string $param the name of the parameter to make sure is not in the

add_alternate_version($title, $url, $mimetype)   X-Ref
Sets an alternative version of this page.

There can be alternate versions of some pages (for example an RSS feed version).
Call this method for each alternative version available.
For each alternative version a link will be included in the <head> tag.

param: string $title The title to give the alternate version.
param: string|moodle_url $url The URL of the alternate version.
param: string $mimetype The mime-type of the alternate version.

set_focuscontrol($controlid)   X-Ref
Specify a form control should be focused when the page has loaded.

param: string $controlid the id of the HTML element to be focused.

set_button($html)   X-Ref
Specify a fragment of HTML that goes where the 'Turn editing on' button normally goes.

param: string $html the HTML to display there.

set_blocks_editing_capability($capability)   X-Ref
Set the capability that allows users to edit blocks on this page.

Normally the default of 'moodle/site:manageblocks' is used, but a few
pages like the My Moodle page need to use a different capability
like 'moodle/my:manageblocks'.

param: string $capability a capability.

set_other_editing_capability($capability)   X-Ref
Some pages let you turn editing on for reasons other than editing blocks.
If that is the case, you can pass other capabilities that let the user
edit this page here.

param: string|array $capability either a capability, or an array of capabilities.

set_cacheable($cacheable)   X-Ref
Sets whether the browser should cache this page or not.

param: bool $cacheable can this page be cached by the user's browser.

set_periodic_refresh_delay($delay = null)   X-Ref
Sets the page to periodically refresh

This function must be called before $OUTPUT->header has been called or
a coding exception will be thrown.

param: int $delay Sets the delay before refreshing the page, if set to null refresh is cancelled.

force_theme($themename)   X-Ref
Force this page to use a particular theme.

Please use this cautiously.
It is only intended to be used by the themes selector admin page.

param: string $themename the name of the theme to use.

reload_theme()   X-Ref
Reload theme settings.

This is used when we need to reset settings
because they are now double cached in theme.

https_required()   X-Ref


verify_https_required()   X-Ref


starting_output()   X-Ref
This method is called when the page first moves out of the STATE_BEFORE_HEADER
state. This is our last change to initialise things.


initialise_theme_and_output()   X-Ref
Method for use by Moodle core to set up the theme. Do not
use this in your own code.

Make sure the right theme for this page is loaded. Tell our
blocks_manager about the theme block regions, and then, if
we are $PAGE, set up the global $OUTPUT.

return: void

get_where_theme_was_initialised()   X-Ref
For diagnostic/debugging purposes, find where the theme setup was triggered.

return: null|array null if theme not yet setup. Stacktrace if it was.

reset_theme_and_output()   X-Ref
Reset the theme and output for a new context. This only makes sense from
external::validate_context(). Do not cheat.

return: string the name of the theme that should be used on this page.

resolve_theme()   X-Ref
Work out the theme this page should use.

This depends on numerous $CFG settings, and the properties of this page.

return: string the name of the theme that should be used on this page.

initialise_default_pagetype($script = null)   X-Ref
Sets ->pagetype from the script name. For example, if the script that was
run is mod/quiz/view.php, ->pagetype will be set to 'mod-quiz-view'.

param: string $script the path to the script that should be used to

initialise_standard_body_classes()   X-Ref
Initialises the CSS classes that will be added to body tag of the page.

The function is responsible for adding all of the critical CSS classes
that describe the current page, and its state.
This includes classes that describe the following for example:
- Current language
- Language direction
- YUI CSS initialisation
- Pagelayout
These are commonly used in CSS to target specific types of pages.

load_activity_record()   X-Ref
Loads the activity record for the current CM object associated with this
page.

This will load {@link moodle_page::$_module} with a row from the related
module table in the database.
For instance if {@link moodle_page::$_cm} is a forum then a row from the
forum table will be loaded.

ensure_category_loaded()   X-Ref
This function ensures that the category of the current course has been
loaded, and if not, the function loads it now.

return: void

load_category($categoryid)   X-Ref
Loads the requested category into the pages categories array.

param: int $categoryid

ensure_categories_loaded()   X-Ref
Ensures that the category the current course is within, as well as all of
its parent categories, have been loaded.

return: void

ensure_theme_not_set()   X-Ref
Ensure the theme has not been loaded yet. If it has an exception is thrown.


url_to_class_name($url)   X-Ref
Converts the provided URL into a CSS class that be used within the page.
This is primarily used to add the wwwroot to the body tag as a CSS class.

param: string $url
return: string

all_editing_caps()   X-Ref
Combines all of the required editing caps for the page and returns them
as an array.

return: array

has_set_url()   X-Ref
Returns true if the page URL has beem set.

return: bool

set_block_actions_done($setting = true)   X-Ref
Gets set when the block actions for the page have been processed.

param: bool $setting

get_popup_notification_allowed()   X-Ref
Are popup notifications allowed on this page?
Popup notifications may be disallowed in situations such as while upgrading or completing a quiz

return: bool true if popup notifications may be displayed

set_popup_notification_allowed($allowed)   X-Ref
Allow or disallow popup notifications on this page. Popups are allowed by default.

param: bool $allowed true if notifications are allowed. False if not allowed. They are allowed by default.

apply_theme_region_manipulations($region)   X-Ref
Returns the block region having made any required theme manipulations.

param: string $region
return: string

add_report_nodes($userid, $nodeinfo)   X-Ref
Add a report node and a specific report to the navigation.

param: int $userid The user ID that we are looking to add this report node to.
param: array $nodeinfo Name and url of the final node that we are creating.

add_header_action(string $html)   X-Ref
Add some HTML to the list of actions to render in the header actions menu.

param: string $html The HTML to add.

get_header_actions()   X-Ref
Get the list of HTML for actions to render in the header actions menu.

return: string[]

set_include_region_main_settings_in_header_actions(bool $value)   X-Ref
Set the flag to indicate if the region main settings should be rendered as an action
in the header actions menu rather than at the top of the content.

param: bool $value If the settings should be in the header.

include_region_main_settings_in_header_actions()   X-Ref
Check if the  region main settings should be rendered as an action in the header actions
menu rather than at the top of the content.

return: bool