diff --git a/lib/pagelib.php b/lib/pagelib.php index aafe23a79dca9..a02bfcf1ef7a3 100644 --- a/lib/pagelib.php +++ b/lib/pagelib.php @@ -1,5 +1,4 @@ blocks, etc. * * @copyright 2009 Tim Hunt - * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later + * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later * @since Moodle 2.0 + * @package core + * @category page + * + * The following properties are alphabetical. Please keep it that way so that its + * easy to maintain. * * @property-read string $activityname The type of activity we are in, for example 'forum' or 'quiz'. * Will be null if this page is not within a module. - * @property-read object $activityrecord The row from the activities own database table (for example + * @property-read stdClass $activityrecord The row from the activities own database table (for example * the forum or quiz table) that this page belongs to. Will be null * if this page is not within a module. * @property-read array $alternativeversions Mime type => object with ->url and ->title. * @property-read blocks_manager $blocks The blocks manager object for this page. - * @property-read string $bodyclasses Returns a string to use within the class attribute on the body tag. + * @property-read string $bodyclasses A string to use within the class attribute on the body tag. + * @property-read string $bodyid A string to use as the id of the body tag. * @property-read string $button The HTML to go where the Turn editing on button normally goes. * @property-read bool $cacheable Defaults to true. Set to false to stop the page being cached at all. * @property-read array $categories An array of all the categories the page course belongs to, * starting with the immediately containing category, and working out to * the top-level category. This may be the empty array if we are in the * front page course. - * @property-read mixed $category The category that the page course belongs to. If there isn't one returns null. - * @property-read object $cm The course_module that this page belongs to. Will be null + * @property-read mixed $category The category that the page course belongs to. + * @property-read cm_info $cm The course_module that this page belongs to. Will be null * if this page is not within a module. This is a full cm object, as loaded * by get_coursemodule_from_id or get_coursemodule_from_instance, * so the extra modname and name fields are present. - * @property-read object $context The main context to which this page belongs. - * @property-read object $course The current course that we are inside - a row from the + * @property-read context $context The main context to which this page belongs. + * @property-read stdClass $course The current course that we are inside - a row from the * course table. (Also available as $COURSE global.) If we are not inside * an actual course, this will be the site course. * @property-read string $devicetypeinuse The name of the device type in use * @property-read string $docspath The path to the Moodle docs for this page. * @property-read string $focuscontrol The id of the HTML element to be focused when the page has loaded. - * @property-read bool $headerprinted + * @property-read bool $headerprinted True if the page header has already been printed. * @property-read string $heading The main heading that should be displayed at the top of the . * @property-read string $headingmenu The menu (or actions) to display in the heading - * @property-read array $layout_options Returns arrays with options for layout file. - * @property-read navbar $navbar Returns the navbar object used to display the navbar - * @property-read global_navigation $navigation Returns the global navigation structure + * @property-read array $layout_options An arrays with options for the layout file. + * @property-read array $legacythemeinuse True if the legacy browser theme is in use. + * @property-read navbar $navbar The navbar object used to display the navbar + * @property-read global_navigation $navigation The navigation structure for this page. * @property-read xml_container_stack $opencontainers Tracks XHTML tags on this page that have been opened but not closed. * mainly for internal use by the rendering code. * @property-read string $pagelayout The general type of page this is. For example 'normal', 'popup', 'home'. * Allows the theme to display things differently, if it wishes to. - * @property-read string $pagetype Returns the page type string, should be used as the id for the body tag in the theme. + * @property-read string $pagetype The page type string, should be used as the id for the body tag in the theme. * @property-read int $periodicrefreshdelay The periodic refresh delay to use with meta refresh * @property-read page_requirements_manager $requires Tracks the JavaScript, CSS files, etc. required by this page. - * @property-read settings_navigation $settingsnav + * @property-read settings_navigation $settingsnav The settings navigation * @property-read int $state One of the STATE_... constants * @property-read string $subpage The subpage identifier, if any. - * @property-read theme_config $theme Returns the initialised theme for this page. + * @property-read theme_config $theme The theme for this page. * @property-read string $title The title that should go in the section of the HTML of this page. * @property-read moodle_url $url The moodle url object for this page. */ class moodle_page { - /**#@+ Tracks the where we are in the generation of the page. */ + + /** The state of the page before it has printed the header **/ const STATE_BEFORE_HEADER = 0; + + /** The state the page is in temporarily while the header is being printed **/ const STATE_PRINTING_HEADER = 1; + + /** The state the page is in while content is presumably being printed **/ const STATE_IN_BODY = 2; - const STATE_DONE = 3; - /**#@-*/ -/// Field declarations ========================================================= + /** + * The state the page is when the footer has been printed and its function is + * complete. + */ + const STATE_DONE = 3; + /** + * @var int The current state of the page. The state a page is within + * determines what actions are possible for it. + */ protected $_state = self::STATE_BEFORE_HEADER; + /** + * @var stdClass The course currently associated with this page. + * If not has been provided the front page course is used. + */ protected $_course = null; /** - * If this page belongs to a module, this is the cm_info module description object. - * @var cm_info + * @var cm_info If this page belongs to a module, this is the cm_info module + * description object. */ protected $_cm = null; /** - * If $_cm is not null, then this will hold the corresponding row from the - * modname table. For example, if $_cm->modname is 'quiz', this will be a - * row from the quiz table. + * @var stdClass If $_cm is not null, then this will hold the corresponding + * row from the modname table. For example, if $_cm->modname is 'quiz', this + * will be a row from the quiz table. */ protected $_module = null; /** - * The context that this page belongs to. + * @var context The context that this page belongs to. */ protected $_context = null; /** - * This holds any categories that $_course belongs to, starting with the + * @var array This holds any categories that $_course belongs to, starting with the * particular category it belongs to, and working out through any parent * categories to the top level. These are loaded progressively, if needed. * There are three states. $_categories = null initially when nothing is @@ -130,111 +151,206 @@ class moodle_page { */ protected $_categories = null; + /** + * @var array An array of CSS classes that should be added to the body tag in HTML. + */ protected $_bodyclasses = array(); + /** + * @var string The title for the page. Used within the title tag in the HTML head. + */ protected $_title = ''; + /** + * @var string The string to use as the heading of the page. Shown near the top of the + * page within most themes. + */ protected $_heading = ''; + /** + * @var string The pagetype is used to describe the page and defaults to a representation + * of the physical path to the page e.g. my-index, mod-quiz-attempt + */ protected $_pagetype = null; + /** + * @var string The pagelayout to use when displaying this page. The + * pagelayout needs to have been defined by the theme in use, or one of its + * parents. By default base is used however standard is the more common layout. + * Note that this gets automatically set by core during operations like + * require_login. + */ protected $_pagelayout = 'base'; /** - * List of theme layout options, these are ignored by core. + * @var array List of theme layout options, these are ignored by core. * To be used in individual theme layout files only. - * @var array */ protected $_layout_options = array(); + /** + * @var string An optional arbitrary parameter that can be set on pages where the context + * and pagetype is not enough to identify the page. + */ protected $_subpage = ''; + /** + * @var string Set a different path to use for the 'Moodle docs for this page' link. + * By default, it uses the path of the file for instance mod/quiz/attempt. + */ protected $_docspath = null; - /** @var string|null A legacy class that will be added to the body tag */ + /** + * @var string A legacy class that will be added to the body tag + */ protected $_legacyclass = null; + /** + * @var moodle_url The URL for this page. This is mandatory and must be set + * before output is started. + */ protected $_url = null; + /** + * @var array An array of links to alternative versions of this page. + * Primarily used for RSS versions of the current page. + */ protected $_alternateversions = array(); + /** + * @var block_manager The blocks manager for this page. It is reponsible for + * the blocks and there content on this page. + */ protected $_blocks = null; + /** + * @var page_requirements_manager Page requirements manager. It is reponsible + * for all JavaScript and CSS resources required by this page. + */ protected $_requires = null; + /** + * @var string The capability required by the user in order to edit blocks + * and block settings on this page. + */ protected $_blockseditingcap = 'moodle/site:manageblocks'; + /** + * @var bool An internal flag to record when block actions have been processed. + * Remember block actions occur on the current URL and it is important that + * even they are never executed more than once. + */ protected $_block_actions_done = false; + /** + * @var array An array of any other capabilities the current user must have + * in order to editing the page and/or its content (not just blocks). + */ protected $_othereditingcaps = array(); + /** + * @var bool Sets whether this page should be cached by the browser or not. + * If it is set to true (default) the page is served with caching headers. + */ protected $_cacheable = true; + /** + * @var string Can be set to the ID of an element on the page, if done that + * element receives focus when the page loads. + */ protected $_focuscontrol = ''; + /** + * @var string HTML to go where the turn on editing button is located. This + * is nearly a legacy item and not used very often any more. + */ protected $_button = ''; + /** + * @var theme_config The theme to use with this page. This has to be properly + * initialised via {@link moodle_page::initialise_theme_and_output()} which + * happens magically before any operation that requires it. + */ protected $_theme = null; - /** @var global_navigation Contains the global navigation structure*/ + + /** + * @var global_navigation Contains the global navigation structure. + */ protected $_navigation = null; - /** @var null|settings_navigation Contains the settings navigation structure*/ + + /** + * @var settings_navigation Contains the settings navigation structure. + */ protected $_settingsnav = null; - /** @var null|navbar Contains the navbar structure*/ + + /** + * @var navbar Contains the navbar structure. + */ protected $_navbar = null; - /** @var string */ + + /** + * @var string The menu (or actions) to display in the heading. + */ protected $_headingmenu = null; /** - * Then the theme is initialised, we save the stack trace, for use in error messages. - * @var array stack trace. + * @var array stack trace. Then the theme is initialised, we save the stack + * trace, for use in error messages. */ protected $_wherethemewasinitialised = null; - /** @var xhtml_container_stack tracks XHTML tags on this page that have been opened but not closed. */ + /** + * @var xhtml_container_stack Tracks XHTML tags on this page that have been + * opened but not closed. + */ protected $_opencontainers; /** - * Sets the page to refresh after a given delay (in seconds) using meta refresh - * in {@link standard_head_html()} in outputlib.php + * @var int Sets the page to refresh after a given delay (in seconds) using + * meta refresh in {@link standard_head_html()} in outputlib.php * If set to null(default) the page is not refreshed - * @var int|null */ protected $_periodicrefreshdelay = null; /** - * This is simply to improve backwards compatibility. If old code relies on - * a page class that implements print_header, or complex logic in - * user_allowed_editing then we stash an instance of that other class here, + * @var stdClass This is simply to improve backwards compatibility. If old + * code relies on a page class that implements print_header, or complex logic + * in user_allowed_editing then we stash an instance of that other class here, * and delegate to it in certain situations. */ protected $_legacypageobject = null; /** - * Associative array of browser shortnames (as used by check_browser_version) + * @var array Associative array of browser shortnames (as used by check_browser_version) * and their minimum required versions - * @var array */ protected $_legacybrowsers = array('MSIE' => 6.0); /** - * Is set to the name of the device type in use. + * @var string Is set to the name of the device type in use. * This will we worked out when it is first used. - * - * @var string */ protected $_devicetypeinuse = null; + /** + * @var bool Used to determine if HTTPS should be required for login. + */ protected $_https_login_required = false; + /** + * @var bool Determines if popup notifications allowed on this page. + * Code such as the quiz module disables popup notifications in situations + * such as upgrading or completing a quiz. + */ protected $_popup_notification_allowed = true; -/// Magic getter methods ============================================================= -/// Due to the __get magic below, you normally do not call these as $PAGE->magic_get_x -/// methods, but instead use the $PAGE->x syntax. + // Magic getter methods ============================================================= + // Due to the __get magic below, you normally do not call these as $PAGE->magic_get_x + // methods, but instead use the $PAGE->x syntax. /** - * Please do not call this method directly, use the ->state syntax. {@link __get()}. - * @return integer one of the STATE_... constants. You should not normally need + * 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 * to use this in your code. It is intended for internal use by this class * and its friends like print_header, to check that everything is working as * expected. Also accessible as $PAGE->state. @@ -244,18 +360,16 @@ protected function magic_get_state() { } /** - * Please do not call this method directly, use the ->headerprinted syntax. {@link __get()}. - * @return boolean has the header already been printed? + * Please do not call this method directly, use the ->headerprinted syntax. {@link moodle_page::__get()}. + * @return bool has the header already been printed? */ protected function magic_get_headerprinted() { return $this->_state >= self::STATE_IN_BODY; } /** - * Please do not call this method directly, use the ->course syntax. {@link __get()}. - * - * @global object - * @return object the current course that we are inside - a row from the + * 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 * course table. (Also available as $COURSE global.) If we are not inside * an actual course, this will be the site course. */ @@ -268,20 +382,19 @@ protected function magic_get_course() { } /** - * Please do not call this method directly, use the ->cm syntax. {@link __get()}. - * @return object the course_module that this page belongs to. Will be null + * 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 * if this page is not within a module. This is a full cm object, as loaded * by get_coursemodule_from_id or get_coursemodule_from_instance, * so the extra modname and name fields are present. - * @return cm_info */ protected function magic_get_cm() { return $this->_cm; } /** - * Please do not call this method directly, use the ->activityrecord syntax. {@link __get()}. - * @return object the row from the activities own database table (for example + * 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 * the forum or quiz table) that this page belongs to. Will be null * if this page is not within a module. */ @@ -293,8 +406,8 @@ protected function magic_get_activityrecord() { } /** - * Please do not call this method directly, use the ->activityname syntax. {@link __get()}. - * @return string|null the The type of activity we are in, for example 'forum' or 'quiz'. + * 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'. * Will be null if this page is not within a module. */ protected function magic_get_activityname() { @@ -305,8 +418,8 @@ protected function magic_get_activityname() { } /** - * Please do not call this method directly, use the ->category syntax. {@link __get()}. - * @return mixed the category that the page course belongs to. If there isn't one + * 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 * (that is, if this is the front page course) returns null. */ protected function magic_get_category() { @@ -319,7 +432,7 @@ protected function magic_get_category() { } /** - * Please do not call this method directly, use the ->categories syntax. {@link __get()}. + * 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, * starting with the immediately containing category, and working out to * the top-level category. This may be the empty array if we are in the @@ -331,8 +444,8 @@ protected function magic_get_categories() { } /** - * Please do not call this method directly, use the ->context syntax. {@link __get()}. - * @return object the main context to which this page belongs. + * 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. */ protected function magic_get_context() { if (is_null($this->_context)) { @@ -350,7 +463,7 @@ protected function magic_get_context() { } /** - * Please do not call this method directly, use the ->pagetype syntax. {@link __get()}. + * 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'. */ protected function magic_get_pagetype() { @@ -362,7 +475,7 @@ protected function magic_get_pagetype() { } /** - * Please do not call this method directly, use the ->pagetype syntax. {@link __get()}. + * 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()}. */ protected function magic_get_bodyid() { @@ -370,7 +483,7 @@ protected function magic_get_bodyid() { } /** - * Please do not call this method directly, use the ->pagelayout syntax. {@link __get()}. + * 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'. * Allows the theme to display things differently, if it wishes to. */ @@ -379,7 +492,7 @@ protected function magic_get_pagelayout() { } /** - * Please do not call this method directly, use the ->layout_tions syntax. {@link __get()}. + * Please do not call this method directly, use the ->layout_tions syntax. {@link moodle_page::__get()}. * @return array returns arrys with options for layout file */ protected function magic_get_layout_options() { @@ -387,15 +500,15 @@ protected function magic_get_layout_options() { } /** - * Please do not call this method directly, use the ->subpage syntax. {@link __get()}. - * @return string|null The subpage identifier, if any. + * Please do not call this method directly, use the ->subpage syntax. {@link moodle_page::__get()}. + * @return string The subpage identifier, if any. */ protected function magic_get_subpage() { return $this->_subpage; } /** - * Please do not call this method directly, use the ->bodyclasses syntax. {@link __get()}. + * 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. */ protected function magic_get_bodyclasses() { @@ -403,7 +516,7 @@ protected function magic_get_bodyclasses() { } /** - * Please do not call this method directly, use the ->title syntax. {@link __get()}. + * Please do not call this method directly, use the ->title syntax. {@link moodle_page::__get()}. * @return string the title that should go in the section of the HTML of this page. */ protected function magic_get_title() { @@ -411,7 +524,7 @@ protected function magic_get_title() { } /** - * Please do not call this method directly, use the ->heading syntax. {@link __get()}. + * 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 . */ protected function magic_get_heading() { @@ -419,7 +532,7 @@ protected function magic_get_heading() { } /** - * Please do not call this method directly, use the ->heading syntax. {@link __get()}. + * 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 */ protected function magic_get_headingmenu() { @@ -427,7 +540,7 @@ protected function magic_get_headingmenu() { } /** - * Please do not call this method directly, use the ->docspath syntax. {@link __get()}. + * 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. */ protected function magic_get_docspath() { @@ -439,7 +552,7 @@ protected function magic_get_docspath() { } /** - * Please do not call this method directly, use the ->url syntax. {@link __get()}. + * 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 * should normally use this in preference to $ME or $FULLME.) */ @@ -463,7 +576,7 @@ protected function magic_get_alternateversions() { } /** - * Please do not call this method directly, use the ->blocks syntax. {@link __get()}. + * Please do not call this method directly, use the ->blocks syntax. {@link moodle_page::__get()}. * @return blocks_manager the blocks manager object for this page. */ protected function magic_get_blocks() { @@ -480,7 +593,7 @@ protected function magic_get_blocks() { } /** - * Please do not call this method directly, use the ->requires syntax. {@link __get()}. + * 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. */ protected function magic_get_requires() { @@ -492,15 +605,15 @@ protected function magic_get_requires() { } /** - * Please do not call this method directly, use the ->cacheable syntax. {@link __get()}. - * @return boolean can this page be cached by the user's browser. + * 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. */ protected function magic_get_cacheable() { return $this->_cacheable; } /** - * Please do not call this method directly, use the ->focuscontrol syntax. {@link __get()}. + * 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. */ protected function magic_get_focuscontrol() { @@ -508,7 +621,7 @@ protected function magic_get_focuscontrol() { } /** - * Please do not call this method directly, use the ->button syntax. {@link __get()}. + * 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. */ protected function magic_get_button() { @@ -516,7 +629,7 @@ protected function magic_get_button() { } /** - * Please do not call this method directly, use the ->theme syntax. {@link __get()}. + * Please do not call this method directly, use the ->theme syntax. {@link moodle_page::__get()}. * @return theme_config the initialised theme for this page. */ protected function magic_get_theme() { @@ -527,8 +640,7 @@ protected function magic_get_theme() { } /** - * Please do not call this method directly, use the ->devicetypeinuse syntax. {@link __get()}. - * + * Please do not call this method directly, use the ->devicetypeinuse syntax. {@link moodle_page::__get()}. * @return string The device type being used. */ protected function magic_get_devicetypeinuse() { @@ -539,7 +651,7 @@ protected function magic_get_devicetypeinuse() { } /** - * Please do not call this method directly, use the ->legacythemeinuse syntax. {@link __get()}. + * Please do not call this method directly, use the ->legacythemeinuse syntax. {@link moodle_page::__get()}. * @deprecated since 2.1 * @return bool */ @@ -550,7 +662,7 @@ protected function magic_get_legacythemeinuse() { /** * Please do not call this method directly use the ->periodicrefreshdelay syntax - * {@link __get()} + * {@link moodle_page::__get()} * @return int The periodic refresh delay to use with meta refresh */ protected function magic_get_periodicrefreshdelay() { @@ -558,7 +670,7 @@ protected function magic_get_periodicrefreshdelay() { } /** - * Please do not call this method directly use the ->opencontainers syntax. {@link __get()} + * 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. * mainly for internal use by the rendering code. */ @@ -608,7 +720,7 @@ protected function magic_get_settingsnav() { * it to the corresponding $PAGE->magic_get_course() method if there is one, and * throwing an exception if not. * - * @param $name string property name + * @param string $name property name * @return mixed */ public function __get($name) { @@ -621,11 +733,16 @@ public function __get($name) { } /** - * PHP overloading magic which prevents the $PAGE->context = $context; syntax + * 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 $name string property name - * @param $name mixed value - * @return void, throws exception if field not defined in page class + * @param string $name property name + * @param mixed $value Value + * @return void Throws exception if field not defined in page class */ public function __set($name, $value) { if (method_exists($this, 'set_' . $name)) { @@ -635,10 +752,11 @@ public function __set($name, $value) { } } -/// Other information getting methods ========================================== + // Other information getting methods ========================================== /** * 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 @@ -650,6 +768,7 @@ public function get_renderer($component, $subtype = null, $target = null) { /** * Checks to see if there are any items on the navbar object + * * @return bool true if there are, false if not */ public function has_navbar() { @@ -660,9 +779,10 @@ public function has_navbar() { } /** - * @return boolean should the current user see this page in editing mode. + * 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 */ public function user_is_editing() { global $USER; @@ -670,14 +790,16 @@ public function user_is_editing() { } /** - * @return boolean does the user have permission to edit blocks on this page. + * Does the user have permission to edit blocks on this page. + * @return bool */ public function user_can_edit_blocks() { return has_capability($this->_blockseditingcap, $this->_context); } /** - * @return boolean does the user have permission to see this page in editing mode. + * Does the user have permission to see this page in editing mode. + * @return bool */ public function user_allowed_editing() { if ($this->_legacypageobject) { @@ -687,8 +809,9 @@ public function user_allowed_editing() { } /** - * @return string a description of this page. Normally displayed in the footer in + * Get a description of this page. Normally displayed in the footer in * developer debug mode. + * @return string */ public function debug_summary() { $summary = ''; @@ -703,12 +826,13 @@ public function debug_summary() { return $summary; } -/// Setter methods ============================================================= + // Setter methods ============================================================= /** * 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 integer $state the new state. + * + * @param integer $state The new state. */ public function set_state($state) { if ($state != $this->_state + 1 || $state > self::STATE_DONE) { @@ -733,7 +857,7 @@ public function set_state($state) { * * Sets $PAGE->context to the course context, if it is not already set. * - * @param object the course to set as the global course. + * @param stdClass $course the course to set as the global course. */ public function set_course($course) { global $COURSE, $PAGE; @@ -762,7 +886,8 @@ public function set_course($course) { /** * Set the main context to which this page belongs. - * @param object $context a context object, normally obtained with get_context_instance. + * + * @param context $context a context object, normally obtained with get_context_instance. */ public function set_context($context) { if ($context === null) { @@ -836,10 +961,13 @@ public function set_cm($cm, $course = null, $module = null) { } /** - * @param $module a row from the main database table for the module that this - * page belongs to. For example, if ->cm is a forum, then you can pass the - * corresponding row from the forum table here if you have it (saves a database - * query sometimes). + * 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. + * @return void */ public function set_activity_record($module) { if (is_null($this->_cm)) { @@ -852,22 +980,38 @@ public function set_activity_record($module) { } /** - * @param string $pagetype e.g. 'my-index' or 'mod-quiz-attempt'. 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 and - * also for determining which blocks are displayed. + * 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 + * and also for determining which blocks are displayed. + * + * @param string $pagetype e.g. 'my-index' or 'mod-quiz-attempt'. */ public function set_pagetype($pagetype) { $this->_pagetype = $pagetype; } /** - * @param string $pagelayout the page layout this is. For example 'popup', 'home'. + * 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'. */ public function set_pagelayout($pagelayout) { /** @@ -883,6 +1027,7 @@ public function set_pagelayout($pagelayout) { /** * 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 * and pagetype, uniquely identifies this page. */ @@ -895,6 +1040,8 @@ public function set_subpage($subpage) { } /** + * 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. */ public function add_body_class($class) { @@ -905,6 +1052,8 @@ public function add_body_class($class) { } /** + * 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. */ public function add_body_classes($classes) { @@ -914,6 +1063,9 @@ public function add_body_classes($classes) { } /** + * 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 section of the HTML of this page. */ public function set_title($title) { @@ -923,6 +1075,9 @@ public function set_title($title) { } /** + * 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 . */ public function set_heading($heading) { @@ -930,6 +1085,8 @@ public function set_heading($heading) { } /** + * 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 */ public function set_headingmenu($menu) { @@ -937,11 +1094,13 @@ public function set_headingmenu($menu) { } /** - * 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. + * 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 integer $categoryid The id of the category to set. */ public function set_category_by_id($categoryid) { @@ -960,9 +1119,11 @@ public function set_category_by_id($categoryid) { /** * 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. */ public function set_docs_path($path) { @@ -971,11 +1132,14 @@ public function set_docs_path($path) { /** * You should call this method from every page to set the cleaned-up 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. + * 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 */ @@ -1031,9 +1195,9 @@ public function ensure_param_not_in_url($param) { * If such other version exist, call this method, and a link to the alternate * version will be included in the of the page. * - * @param $title The title to give the alternate version. - * @param $url The URL of the alternate version. - * @param $mimetype The mime-type of the alternate version. + * @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. */ public function add_alternate_version($title, $url, $mimetype) { if ($this->_state > self::STATE_BEFORE_HEADER) { @@ -1064,9 +1228,12 @@ public function set_button($html) { } /** - * 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'. + * 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. */ public function set_blocks_editing_capability($capability) { @@ -1077,6 +1244,7 @@ public function set_blocks_editing_capability($capability) { * 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. */ public function set_other_editing_capability($capability) { @@ -1088,7 +1256,9 @@ public function set_other_editing_capability($capability) { } /** - * @return boolean $cacheable can this page be cached by the user's browser. + * Sets whether the browser should cache this page or not. + * + * @return bool $cacheable can this page be cached by the user's browser. */ public function set_cacheable($cacheable) { $this->_cacheable = $cacheable; @@ -1101,7 +1271,7 @@ public function set_cacheable($cacheable) { * a coding exception will be thrown. * * @param int $delay Sets the delay before refreshing the page, if set to null - * refresh is cancelled + * refresh is cancelled */ public function set_periodic_refresh_delay($delay=null) { if ($this->_state > self::STATE_BEFORE_HEADER) { @@ -1117,9 +1287,10 @@ public function set_periodic_refresh_delay($delay=null) { /** * 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. + * Please use this cautiously. + * It is only intended to be used by the themes selector admin page. * - * @param $themename the name of the theme to use. + * @param string $themename the name of the theme to use. */ public function force_theme($themename) { $this->ensure_theme_not_set(); @@ -1193,8 +1364,8 @@ public function verify_https_required() { } } -/// Initialisation methods ===================================================== -/// These set various things up in a default way. + // Initialisation methods ===================================================== + // These set various things up in a default way. /** * This method is called when the page first moves out of the STATE_BEFORE_HEADER @@ -1240,6 +1411,8 @@ protected function starting_output() { * 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 */ public function initialise_theme_and_output() { global $OUTPUT, $PAGE, $SITE; @@ -1355,6 +1528,7 @@ protected function resolve_theme() { /** * 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 ->pagetype. If not passed the $SCRIPT global will be used. * If legacy code has set $CFG->pagepath that will be used instead, and a @@ -1390,6 +1564,18 @@ protected function initialise_default_pagetype($script = null) { } } + /** + * 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. + */ protected function initialise_standard_body_classes() { global $CFG, $USER; @@ -1462,6 +1648,15 @@ protected function initialise_standard_body_classes() { } } + /** + * 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. + */ protected function load_activity_record() { global $DB; if (is_null($this->_cm)) { @@ -1470,6 +1665,13 @@ protected function load_activity_record() { $this->_module = $DB->get_record($this->_cm->modname, array('id' => $this->_cm->instance)); } + /** + * This function ensures that the category of the current course has been + * loaded, and if not, the function loads it now. + * + * @return void + * @throws coding_exception + */ protected function ensure_category_loaded() { if (is_array($this->_categories)) { return; // Already done. @@ -1484,6 +1686,12 @@ protected function ensure_category_loaded() { } } + /** + * Loads the requested category into the pages categories array. + * + * @param ing $categoryid + * @throws moodle_exception + */ protected function load_category($categoryid) { global $DB; $category = $DB->get_record('course_categories', array('id' => $categoryid)); @@ -1498,6 +1706,12 @@ protected function load_category($categoryid) { } } + /** + * Ensures that the category the current course is within, as well as all of + * its parent categories, have been loaded. + * + * @return void + */ protected function ensure_categories_loaded() { global $DB; $this->ensure_category_loaded(); @@ -1512,6 +1726,12 @@ protected function ensure_categories_loaded() { } } + /** + * Ensure the theme has not been loaded yet. If it has an exception is thrown. + * @source + * + * @throws coding_exception + */ protected function ensure_theme_not_set() { if (!is_null($this->_theme)) { throw new coding_exception('The theme has already been set up for this page ready for output. ' . @@ -1521,6 +1741,13 @@ protected function ensure_theme_not_set() { } } + /** + * 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 + */ protected function url_to_class_name($url) { $bits = parse_url($url); $class = str_replace('.', '-', $bits['host']); @@ -1536,15 +1763,23 @@ protected function url_to_class_name($url) { return $class; } + /** + * Combines all of the required editing caps for the page and returns them + * as an array. + * + * @return array + */ protected function all_editing_caps() { $caps = $this->_othereditingcaps; $caps[] = $this->_blockseditingcap; return $caps; } -/// Deprecated fields and methods for backwards compatibility ================== + // Deprecated fields and methods for backwards compatibility ================== /** + * Returns the page type. + * * @deprecated since Moodle 2.0 - use $PAGE->pagetype instead. * @return string page type. */ @@ -1554,16 +1789,20 @@ public function get_type() { } /** + * Returns the page type. + * * @deprecated since Moodle 2.0 - use $PAGE->pagetype instead. * @return string this is what page_id_and_class used to return via the $getclass parameter. */ - function get_format_name() { + public function get_format_name() { return $this->get_pagetype(); } /** + * Returns the course associated with this page. + * * @deprecated since Moodle 2.0 - use $PAGE->course instead. - * @return object course. + * @return stdClass course. */ public function get_courserecord() { debugging('Call to deprecated method moodle_page::get_courserecord. Please use $PAGE->course instead.'); @@ -1571,6 +1810,8 @@ public function get_courserecord() { } /** + * Returns the legacy page class. + * * @deprecated since Moodle 2.0 * @return string this is what page_id_and_class used to return via the $getclass parameter. */ @@ -1583,8 +1824,10 @@ public function get_legacyclass() { } /** + * Returns an array of block regions on this page. + * * @deprecated since Moodle 2.0 - use $PAGE->blocks->get_regions() instead - * @return string the places on this page where blocks can go. + * @return array the places on this page where blocks can go. */ function blocks_get_positions() { debugging('Call to deprecated method moodle_page::blocks_get_positions. Use $PAGE->blocks->get_regions() instead.'); @@ -1592,6 +1835,8 @@ function blocks_get_positions() { } /** + * Returns the default block region. + * * @deprecated since Moodle 2.0 - use $PAGE->blocks->get_default_region() instead * @return string the default place for blocks on this page. */ @@ -1601,6 +1846,9 @@ function blocks_default_position() { } /** + * Returns the default block to use of the page. + * This function no longer does anything. DO NOT USE. + * * @deprecated since Moodle 2.0 - no longer used. */ function blocks_get_default() { @@ -1608,6 +1856,9 @@ function blocks_get_default() { } /** + * Moves a block. + * This function no longer does anything. DO NOT USE. + * * @deprecated since Moodle 2.0 - no longer used. */ function blocks_move_position(&$instance, $move) { @@ -1615,6 +1866,8 @@ function blocks_move_position(&$instance, $move) { } /** + * Returns the URL parameters for the current page. + * * @deprecated since Moodle 2.0 - use $this->url->params() instead. * @return array URL parameters for this page. */ @@ -1624,6 +1877,8 @@ function url_get_parameters() { } /** + * Returns the URL path of the current page. + * * @deprecated since Moodle 2.0 - use $this->url->params() instead. * @return string URL for this page without parameters. */ @@ -1633,6 +1888,8 @@ function url_get_path() { } /** + * Returns the full URL for this page. + * * @deprecated since Moodle 2.0 - use $this->url->out() instead. * @return string full URL for this page. */ @@ -1642,15 +1899,20 @@ function url_get_full($extraparams = array()) { } /** + * Returns the legacy page object. + * * @deprecated since Moodle 2.0 - just a backwards compatibility hook. + * @return moodle_page */ function set_legacy_page_object($pageobject) { return $this->_legacypageobject = $pageobject; } /** + * Prints a header... DO NOT USE! + * * @deprecated since Moodle 2.0 - page objects should no longer be doing print_header. - * @param $_,... + * @param mixed $_,... */ function print_header($_) { if (is_null($this->_legacypageobject)) { @@ -1662,6 +1924,8 @@ function print_header($_) { } /** + * Returns the ID for this page. DO NOT USE! + * * @deprecated since Moodle 2.0 * @return the 'page id'. This concept no longer exists. */ @@ -1674,6 +1938,8 @@ function get_id() { } /** + * Returns the ID for this page. DO NOT USE! + * * @deprecated since Moodle 2.0 * @return the 'page id'. This concept no longer exists. */ @@ -1686,6 +1952,8 @@ function get_pageid() { } /** + * Returns the module record for this page. + * * @deprecated since Moodle 2.0 - user $PAGE->cm instead. * @return $this->cm; */ @@ -1693,10 +1961,20 @@ function get_modulerecord() { return $this->cm; } + /** + * Returns true if the page URL has beem set. + * + * @return bool + */ public function has_set_url() { return ($this->_url!==null); } + /** + * Gets set when the block actions for the page have been processed. + * + * @param bool $setting + */ public function set_block_actions_done($setting = true) { $this->_block_actions_done = $setting; } @@ -1704,7 +1982,8 @@ public function set_block_actions_done($setting = true) { /** * Are popup notifications allowed on this page? * Popup notifications may be disallowed in situations such as while upgrading or completing a quiz - * @return boolean true if popup notifications may be displayed + * + * @return bool true if popup notifications may be displayed */ public function get_popup_notification_allowed() { return $this->_popup_notification_allowed; @@ -1712,8 +1991,8 @@ public function get_popup_notification_allowed() { /** * Allow or disallow popup notifications on this page. Popups are allowed by default. - * @param boolean true if notifications are allowed. False if not allowed. They are allowed by default. - * @return null + * + * @param bool true if notifications are allowed. False if not allowed. They are allowed by default. */ public function set_popup_notification_allowed($allowed) { $this->_popup_notification_allowed = $allowed; @@ -1721,9 +2000,10 @@ public function set_popup_notification_allowed($allowed) { } /** + * Not needed any more. DO NOT USE! + * * @deprecated since Moodle 2.0 - * Not needed any more. - * @param $path the folder path + * @param string $path the folder path * @return array an array of page types. */ function page_import_types($path) { @@ -1732,11 +2012,12 @@ function page_import_types($path) { } /** - * @deprecated since Moodle 2.0 * Do not use this any more. The global $PAGE is automatically created for you. * If you need custom behaviour, you should just set properties of that object. + * + * @deprecated since Moodle 2.0 * @param integer $instance legacy page instance id. - * @return the global $PAGE object. + * @return moodle_page The global $PAGE object. */ function page_create_instance($instance) { global $PAGE; @@ -1744,9 +2025,11 @@ function page_create_instance($instance) { } /** - * @deprecated since Moodle 2.0 * Do not use this any more. The global $PAGE is automatically created for you. * If you need custom behaviour, you should just set properties of that object. + * + * @deprecated since Moodle 2.0 + * @return moodle_page The global $PAGE object. */ function page_create_object($type, $id = NULL) { global $CFG, $PAGE, $SITE, $ME; @@ -1791,9 +2074,12 @@ function page_create_object($type, $id = NULL) { } /** - * @deprecated since Moodle 2.0 * You should not be writing page subclasses any more. Just set properties on the * global $PAGE object to control its behaviour. + * + * @deprecated since Moodle 2.0 + * @return mixed Null if there is not a valid page mapping, or the mapping if + * it has been set. */ function page_map_class($type, $classname = NULL) { global $CFG; @@ -1818,68 +2104,78 @@ function page_map_class($type, $classname = NULL) { } /** - * @deprecated since Moodle 2.0 * Parent class from which all Moodle page classes derive * - * @package core - * @subpackage lib + * @deprecated since Moodle 2.0 + * @package core + * @category page * @copyright 1999 onwards Martin Dougiamas {@link http://moodle.com} * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later */ class page_base extends moodle_page { /** - * The numeric identifier of the page being described. - * @var int $id + * @var int The numeric identifier of the page being described. */ - var $id = NULL; - -/// Class Functions - - // HTML OUTPUT SECTION + public $id = null; - // SELF-REPORTING SECTION - - // Simple stuff, do not override this. - function get_id() { + /** + * Returns the page id + * @deprecated since Moodle 2.0 + * @return int Returns the id of the page. + */ + public function get_id() { return $this->id; } - // Initialize the data members of the parent class - function init_quick($data) { + /** + * Initialize the data members of the parent class + * @param scalar $data + */ + public function init_quick($data) { $this->id = $data->pageid; } - function init_full() { - } + /** + * DOES NOTHING... DO NOT USE. + * @deprecated since Moodle 2.0 + */ + public function init_full() {} } /** - * @deprecated since Moodle 2.0 * Class that models the behavior of a moodle course. * Although this does nothing, this class declaration should be left for now * since there may be legacy class doing class page_... extends page_course * - * @package core - * @subpackage lib + * @deprecated since Moodle 2.0 + * @package core + * @category page * @copyright 1999 onwards Martin Dougiamas {@link http://moodle.com} * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later */ -class page_course extends page_base { -} +class page_course extends page_base {} /** - * @deprecated since Moodle 2.0 * Class that models the common parts of all activity modules * - * @package core - * @subpackage lib + * @deprecated since Moodle 2.0 + * @package core + * @category page * @copyright 1999 onwards Martin Dougiamas {@link http://moodle.com} * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later */ class page_generic_activity extends page_base { - // Although this function is deprecated, it should be left here because - // people upgrading legacy code need to copy it. See - // http://docs.moodle.org/dev/Migrating_your_code_to_the_2.0_rendering_API + + /** + * Although this function is deprecated, it should be left here because + * people upgrading legacy code need to copy it. See + * http://docs.moodle.org/dev/Migrating_your_code_to_the_2.0_rendering_API + * + * @param string $title + * @param array $morenavlinks + * @param string $bodytags + * @param string $meta + */ function print_header($title, $morenavlinks = NULL, $bodytags = '', $meta = '') { global $USER, $CFG, $PAGE, $OUTPUT; @@ -1917,4 +2213,4 @@ function print_header($title, $morenavlinks = NULL, $bodytags = '', $meta = '') $PAGE->set_button($buttons); echo $OUTPUT->header(); } -} +} \ No newline at end of file