From: tjhunt <tjhunt>
Date: Wed, 6 May 2009 09:29:05 +0000 (+0000)
Subject: moodle_page: MDL-12212 improve comments and add some work-in-progress warnings
X-Git-Url: http://git.mjollnir.org/gw?a=commitdiff_plain;h=b7b2d0f37dbdf54e7e4d2ed7bdeb011dc0641d22;p=moodle.git

moodle_page: MDL-12212 improve comments and add some work-in-progress warnings
---

diff --git a/admin/settings.php b/admin/settings.php
index c823812b34..847814b426 100644
--- a/admin/settings.php
+++ b/admin/settings.php
@@ -83,12 +83,13 @@ if (empty($SITE->fullname)) {
     echo '</form>';
 
 } else {
+    // Note: MDL-19010 there will be further changes to printing header and blocks.
+    // The code will be much nicer than this eventually.
     $pageblocks = blocks_setup($PAGE);
 
     $preferred_width_left = blocks_preferred_width($pageblocks[BLOCK_POS_LEFT]);
     $preferred_width_right = blocks_preferred_width($pageblocks[BLOCK_POS_RIGHT]);
 
-    // The search page currently doesn't handle block editing
     if ($PAGE->user_allowed_editing()) {
         $options = $PAGE->url->params();
         if ($PAGE->user_is_editing()) {
diff --git a/course/view.php b/course/view.php
index d0d0cb83b3..478a0b0cdb 100644
--- a/course/view.php
+++ b/course/view.php
@@ -92,6 +92,9 @@
     $PAGE->set_url('course/view.php', array('id' => $course->id));
     $PAGE->set_pagetype('course-view-' . $course->format);
     $PAGE->set_other_editing_capability('moodle/course:manageactivities');
+
+    // Note: MDL-19010 there will be further changes to printing header and blocks.
+    // The code will be much nicer than this eventually.
     $pageblocks = blocks_setup($PAGE, BLOCKS_PINNED_BOTH);
 
     if ($reset_user_allowed_editing) {
diff --git a/lib/adminlib.php b/lib/adminlib.php
index 77c7700f54..59e74f23e2 100644
--- a/lib/adminlib.php
+++ b/lib/adminlib.php
@@ -3946,6 +3946,8 @@ function admin_externalpage_print_header($focus='') {
     define('ADMIN_EXT_HEADER_PRINTED', 'true');
 
     if (!empty($SITE->fullname) and !empty($SITE->shortname)) {
+        // Note: MDL-19010 there will be further changes to printing header and blocks.
+        // The code will be much nicer than this eventually.
         $pageblocks = blocks_setup($PAGE);
 
         $preferred_width_left = blocks_preferred_width($pageblocks[BLOCK_POS_LEFT]);
@@ -3958,7 +3960,6 @@ function admin_externalpage_print_header($focus='') {
         $current = $adminroot->locate($section, true);
         $visiblepathtosection = array_reverse($current->visiblepath);
 
-        // The search page currently doesn't handle block editing
         if ($PAGE->user_allowed_editing()) {
             $options = $PAGE->url->params();
             if ($PAGE->user_is_editing()) {
diff --git a/lib/pagelib.php b/lib/pagelib.php
index 3d4c189b2d..7d08f4ce45 100644
--- a/lib/pagelib.php
+++ b/lib/pagelib.php
@@ -115,6 +115,7 @@ class moodle_page {
 /// methods, but instead use the $PAGE->x syntax.
 
     /**
+     * Please do not call this method directly, use the ->state syntax. @see __get().
      * @return integer one of the STATE_... constants. You should not normally need
      * to use this in your code. It is indended for internal use by this class
      * and its friends like print_header, to check that everything is working as
@@ -125,18 +126,18 @@ class moodle_page {
     }
 
     /**
-     * @return boolean has the header already been printed? Also accessible as
-     * $PAGE->headerprinted.
+     * Please do not call this method directly, use the ->headerprinted syntax. @see __get().
+     * @return boolean has the header already been printed?
      */
     public function get_headerprinted() {
         return $this->_state >= self::STATE_IN_BODY;
     }
 
     /**
+     * Please do not call this method directly, use the ->course syntax. @see __get().
      * @return object 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. You can also access this
-     * as $PAGE->course.
+     * an actual course, this will be the site course.
      */
     public function get_course() {
         global $SITE;
@@ -147,6 +148,7 @@ class moodle_page {
     }
 
     /**
+     * Please do not call this method directly, use the ->cm syntax. @see __get().
      * @return object 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,
@@ -157,10 +159,10 @@ class moodle_page {
     }
 
     /**
-     * @return object 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.
+     * Please do not call this method directly, use the ->activityrecord syntax. @see __get().
+     * @return object 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.
      */
     public function get_activityrecord() {
         if (is_null($this->_module) && !is_null($this->_cm)) {
@@ -170,10 +172,9 @@ class moodle_page {
     }
 
     /**
-     * @return object 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.
+     * Please do not call this method directly, use the ->activityname syntax. @see __get().
+     * @return string|null the The type of activity we are in, for example 'forum' or 'quiz'.
+     * Will be null if this page is not within a module.
      */
     public function get_activityname() {
         if (is_null($this->_cm)) {
@@ -183,6 +184,7 @@ class moodle_page {
     }
 
     /**
+     * Please do not call this method directly, use the ->category syntax. @see __get().
      * @return mixed the category that the page course belongs to. If there isn't one
      * (that is, if this is the front page course) returns null.
      */
@@ -196,6 +198,7 @@ class moodle_page {
     }
 
     /**
+     * Please do not call this method directly, use the ->categories syntax. @see __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
@@ -207,6 +210,7 @@ class moodle_page {
     }
 
     /**
+     * Please do not call this method directly, use the ->context syntax. @see __get().
      * @return object the main context to which this page belongs.
      */
     public function get_context() {
@@ -217,6 +221,7 @@ class moodle_page {
     }
 
     /**
+     * Please do not call this method directly, use the ->pagetype syntax. @see __get().
      * @return string e.g. 'my-index' or 'mod-quiz-attempt'. Same as the id attribute on <body>.
      */
     public function get_pagetype() {
@@ -227,6 +232,7 @@ class moodle_page {
     }
 
     /**
+     * Please do not call this method directly, use the ->subpage syntax. @see __get().
      * @return string|null The subpage identifier, if any.
      */
     public function get_subpage() {
@@ -234,6 +240,7 @@ class moodle_page {
     }
 
     /**
+     * Please do not call this method directly, use the ->bodyclasses syntax. @see __get().
      * @return string the class names to put on the body element in the HTML.
      */
     public function get_bodyclasses() {
@@ -241,7 +248,8 @@ class moodle_page {
     }
 
     /**
-     * @return string the class names to put on the body element in the HTML.
+     * Please do not call this method directly, use the ->docspath syntax. @see __get().
+     * @return string the path to the Moodle docs for this page.
      */
     public function get_docspath() {
         if (is_string($this->_docspath)) {
@@ -252,6 +260,7 @@ class moodle_page {
     }
 
     /**
+     * Please do not call this method directly, use the ->url syntax. @see __get().
      * @return moodle_url the clean URL required to load the current page. (You
      * should normally use this in preference to $ME or $FULLME.)
      */
@@ -265,6 +274,7 @@ class moodle_page {
     }
 
     /**
+     * Please do not call this method directly, use the ->blocks syntax. @see __get().
      * @return blocks_manager the blocks manager object for this page.
      */
     public function get_blocks() {
@@ -281,7 +291,9 @@ class moodle_page {
     }
 
     /**
-     * PHP overloading magic to make the $PAGE->course syntax work.
+     * PHP overloading magic to make the $PAGE->course syntax work by redirecting
+     * it to the corresponding $PAGE->get_course() method if there is one, and
+     * throwing an exception if not.
      */
     public function __get($field) {
         $getmethod = 'get_' . $field;
diff --git a/mod/chat/view.php b/mod/chat/view.php
index df0f4f96c0..0262da2525 100644
--- a/mod/chat/view.php
+++ b/mod/chat/view.php
@@ -61,6 +61,9 @@
 
 // Initialize $PAGE, compute blocks
     $PAGE->set_url('mod/chat/view.php', array('id' => $cm->id));
+
+    // Note: MDL-19010 there will be further changes to printing header and blocks.
+    // The code will be much nicer than this eventually.
     $pageblocks = blocks_setup($PAGE);
     $blocks_preferred_width = bounded_number(180, blocks_preferred_width($pageblocks[BLOCK_POS_LEFT]), 210);
 
diff --git a/mod/data/view.php b/mod/data/view.php
index 5c7b6ab924..3be4028d10 100755
--- a/mod/data/view.php
+++ b/mod/data/view.php
@@ -276,6 +276,8 @@
     }
 
 /// Print the page header
+    // Note: MDL-19010 there will be further changes to printing header and blocks.
+    // The code will be much nicer than this eventually.
     $title = $course->shortname.': ' . format_string($data->name);
 
     $buttons = '<table><tr><td>'.update_module_button($cm->id, $course->id, get_string('modulename', 'data')).'</td>';
diff --git a/mod/quiz/view.php b/mod/quiz/view.php
index 4da7cda611..3042a45b34 100644
--- a/mod/quiz/view.php
+++ b/mod/quiz/view.php
@@ -71,6 +71,8 @@
     }
     require_js(array('yui_yahoo', 'yui_event'));
 
+    // Note: MDL-19010 there will be further changes to printing header and blocks.
+    // The code will be much nicer than this eventually.
     $title = $course->shortname . ': ' . format_string($quiz->name);
 
     $buttons = '<table><tr><td>'.update_module_button($cm->id, $course->id, get_string('modulename', 'quiz')).'</td>';
diff --git a/my/index.php b/my/index.php
index ddd6cfdd20..5a5eb8c433 100644
--- a/my/index.php
+++ b/my/index.php
@@ -24,6 +24,8 @@
     $PAGE->set_url('my/index.php');
     $PAGE->set_blocks_editing_capability('moodle/my:manageblocks');
 
+    // Note: MDL-19010 there will be further changes to printing header and blocks.
+    // The code will be much nicer than this eventually.
     $pageblocks = blocks_setup($PAGE,BLOCKS_PINNED_BOTH);
 
     if (($edit != -1) and $PAGE->user_allowed_editing()) {