course/format/lib.php

   1 <?php
   2 // This file is part of Moodle - http://moodle.org/
   3 //
   4 // Moodle is free software: you can redistribute it and/or modify
   5 // it under the terms of the GNU General Public License as published by
   6 // the Free Software Foundation, either version 3 of the License, or
   7 // (at your option) any later version.
   8 //
   9 // Moodle is distributed in the hope that it will be useful,
  10 // but WITHOUT ANY WARRANTY; without even the implied warranty of
  11 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  12 // GNU General Public License for more details.
  13 //
  14 // You should have received a copy of the GNU General Public License
  15 // along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
  16
  17 /**
  18  * Base class for course format plugins
  19  *
  20  * @package    core_course
  21  * @copyright  2012 Marina Glancy
  22  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  23  */
  24
  25 defined('MOODLE_INTERNAL') || die;
  26
  27 use core_courseformat\base as course_format;
  28 use core_courseformat\output\site_renderer;
  29
  30 /**
  31  * Returns an instance of format class (extending course_format) for given course
  32  *
  33  * @param int|stdClass $courseorid either course id or
  34  *     an object that has the property 'format' and may contain property 'id'
  35  * @return course_format
  36  */
  37 function course_get_format($courseorid) {
  38     return course_format::instance($courseorid);
  39 }
  40
  41 /**
  42  * Pseudo course format used for the site main page
  43  *
  44  * @package    core_course
  45  * @copyright  2012 Marina Glancy
  46  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  47  */
  48 class format_site extends course_format {
  49
  50     /**
  51      * Returns the display name of the given section that the course prefers.
  52      *
  53      * @param int|stdClass $section Section object from database or just field section.section
  54      * @return Display name that the course format prefers, e.g. "Topic 2"
  55      */
  56     function get_section_name($section) {
  57         $section = $this->get_section($section);
  58         if ((string)$section->name !== '') {
  59             // Return the name the user set.
  60             return format_string($section->name, true, array('context' => context_course::instance($this->courseid)));
  61         } else {
  62             return get_string('site');
  63         }
  64     }
  65
  66     /**
  67      * For this fake course referring to the whole site, the site homepage is always returned
  68      * regardless of arguments
  69      *
  70      * @param int|stdClass $section
  71      * @param array $options
  72      * @return null|moodle_url
  73      */
  74     public function get_view_url($section, $options = array()) {
  75         return new moodle_url('/', array('redirect' => 0));
  76     }
  77
  78     /**
  79      * Returns the list of blocks to be automatically added on the site frontpage when moodle is installed
  80      *
  81      * @return array of default blocks, must contain two keys BLOCK_POS_LEFT and BLOCK_POS_RIGHT
  82      *     each of values is an array of block names (for left and right side columns)
  83      */
  84     public function get_default_blocks() {
  85         return blocks_get_default_site_course_blocks();
  86     }
  87
  88     /**
  89      * Definitions of the additional options that site uses
  90      *
  91      * @param bool $foreditform
  92      * @return array of options
  93      */
  94     public function course_format_options($foreditform = false) {
  95         static $courseformatoptions = false;
  96         if ($courseformatoptions === false) {
  97             $courseformatoptions = array(
  98                 'numsections' => array(
  99                     'default' => 1,
 100                     'type' => PARAM_INT,
 101                 ),
 102             );
 103         }
 104         return $courseformatoptions;
 105     }
 106
 107     /**
 108      * Returns whether this course format allows the activity to
 109      * have "triple visibility state" - visible always, hidden on course page but available, hidden.
 110      *
 111      * @param stdClass|cm_info $cm course module (may be null if we are displaying a form for adding a module)
 112      * @param stdClass|section_info $section section where this module is located or will be added to
 113      * @return bool
 114      */
 115     public function allow_stealth_module_visibility($cm, $section) {
 116         return true;
 117     }
 118
 119     /**
 120      * Returns instance of page renderer used by the site page
 121      *
 122      * @param moodle_page $page the current page
 123      * @return renderer_base
 124      */
 125     public function get_renderer(moodle_page $page) {
 126         return new site_renderer($page, null);
 127     }
 128
 129     /**
 130      * Site format uses only section 1.
 131      *
 132      * @return int
 133      */
 134     public function get_section_number(): int {
 135         return 1;
 136     }
 137 }
 138
 139 /**
 140  * 'Converts' a value from what is stored in the database into what is used by edit forms.
 141  *
 142  * @param array $dest The destination array
 143  * @param array $source The source array
 144  * @param array $option The definition structure of the option.
 145  * @param string $optionname The name of the option, as provided in the definition.
 146  */
 147 function contract_value(array &$dest, array $source, array $option, string $optionname) : void {
 148     if (substr($optionname, -7) == '_editor') { // Suffix '_editor' indicates that the element is an editor.
 149         $name = substr($optionname, 0, -7);
 150         if (isset($source[$name])) {
 151             $dest[$optionname] = [
 152                 'text' => clean_param_if_not_null($source[$name], $option['type'] ?? PARAM_RAW),
 153                 'format' => clean_param_if_not_null($source[$name . 'format'], PARAM_INT),
 154             ];
 155         }
 156     } else {
 157         if (isset($source[$optionname])) {
 158             $dest[$optionname] = clean_param_if_not_null($source[$optionname], $option['type'] ?? PARAM_RAW);
 159         }
 160     }
 161 }
 162
 163 /**
 164  * Cleans the given param, unless it is null.
 165  *
 166  * @param mixed $param The variable we are cleaning.
 167  * @param string $type Expected format of param after cleaning.
 168  * @return mixed Null if $param is null, otherwise the cleaned value.
 169  * @throws coding_exception
 170  */
 171 function clean_param_if_not_null($param, string $type = PARAM_RAW) {
 172     if ($param === null) {
 173         return null;
 174     } else {
 175         return clean_param($param, $type);
 176     }
 177 }
 178
 179 /**
 180  * 'Converts' a value from what is used in edit forms into a value(s) to be stored in the database.
 181  *
 182  * @param array $dest The destination array
 183  * @param array $source The source array
 184  * @param array $option The definition structure of the option.
 185  * @param string $optionname The name of the option, as provided in the definition.
 186  */
 187 function expand_value(array &$dest, array $source, array $option, string $optionname) : void {
 188     if (substr($optionname, -7) == '_editor') { // Suffix '_editor' indicates that the element is an editor.
 189         $name = substr($optionname, 0, -7);
 190         if (is_string($source[$optionname])) {
 191             $dest[$name]            = clean_param($source[$optionname], $option['type'] ?? PARAM_RAW);
 192             $dest[$name . 'format'] = 1;
 193         } else {
 194             $dest[$name]            = clean_param($source[$optionname]['text'], $option['type'] ?? PARAM_RAW);
 195             $dest[$name . 'format'] = clean_param($source[$optionname]['format'], PARAM_INT);
 196         }
 197         unset($dest[$optionname]);
 198     } else {
 199         $dest[$optionname] = clean_param($source[$optionname], $option['type'] ?? PARAM_RAW);
 200     }
 201 }
 202
 203 /**
 204  * Course-module fragment renderer method.
 205  *
 206  * The fragment arguments are id and sr (section return).
 207  *
 208  * @param array $args The fragment arguments.
 209  * @return string The rendered cm item.
 210  *
 211  * @throws require_login_exception
 212  */
 213 function core_courseformat_output_fragment_cmitem($args): string {
 214     global $PAGE;
 215
 216     [$course, $cm] = get_course_and_cm_from_cmid($args['id']);
 217     if (!can_access_course($course, null, '', true) || !$cm->uservisible) {
 218         throw new require_login_exception('Activity is not available');
 219     }
 220
 221     $format = course_get_format($course);
 222     if (!empty($args['sr'])) {
 223         $format->set_section_number($args['sr']);
 224     }
 225     $renderer = $format->get_renderer($PAGE);
 226     $section = $cm->get_section_info();
 227     return $renderer->course_section_updated_cm_item($format, $section, $cm);
 228 }
 229
 230 /**
 231  * Section fragment renderer method.
 232  *
 233  * The fragment arguments are courseid, section id and sr (section return).
 234  *
 235  * @param array $args The fragment arguments.
 236  * @return string The rendered section.
 237  *
 238  * @throws require_login_exception
 239  */
 240 function core_courseformat_output_fragment_section($args): string {
 241     global $PAGE;
 242
 243     $course = get_course($args['courseid']);
 244     if (!can_access_course($course, null, '', true)) {
 245         throw new require_login_exception('Course is not available');
 246     }
 247
 248     $format = course_get_format($course);
 249     if (!empty($args['sr'])) {
 250         $format->set_section_number($args['sr']);
 251     }
 252
 253     $modinfo = $format->get_modinfo();
 254     $section = $modinfo->get_section_info_by_id($args['id'], MUST_EXIST);
 255     if (!$section->uservisible) {
 256         throw new require_login_exception('Section is not available');
 257     }
 258
 259     $renderer = $format->get_renderer($PAGE);
 260     return $renderer->course_section_updated($format, $section);
 261 }