[Summary view] [Print] [Text view]

   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  /**
  28   * Returns an instance of format class (extending format_base) for given course
  29   *
  30   * @param int|stdClass $courseorid either course id or
  31   *     an object that has the property 'format' and may contain property 'id'
  32   * @return format_base
  33   */
  34  function course_get_format($courseorid) {
  35      return format_base::instance($courseorid);
  36  }
  37  
  38  /**
  39   * Base class for course formats
  40   *
  41   * Each course format must declare class
  42   * class format_FORMATNAME extends format_base {}
  43   * in file lib.php
  44   *
  45   * For each course just one instance of this class is created and it will always be returned by
  46   * course_get_format($courseorid). Format may store it's specific course-dependent options in
  47   * variables of this class.
  48   *
  49   * In rare cases instance of child class may be created just for format without course id
  50   * i.e. to check if format supports AJAX.
  51   *
  52   * Also course formats may extend class section_info and overwrite
  53   * format_base::build_section_cache() to return more information about sections.
  54   *
  55   * If you are upgrading from Moodle 2.3 start with copying the class format_legacy and renaming
  56   * it to format_FORMATNAME, then move the code from your callback functions into
  57   * appropriate functions of the class.
  58   *
  59   * @package    core_course
  60   * @copyright  2012 Marina Glancy
  61   * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  62   */
  63  abstract class format_base {
  64      /** @var int Id of the course in this instance (maybe 0) */
  65      protected $courseid;
  66      /** @var string format used for this course. Please note that it can be different from
  67       * course.format field if course referes to non-existing of disabled format */
  68      protected $format;
  69      /** @var stdClass data for course object, please use {@link format_base::get_course()} */
  70      protected $course = false;
  71      /** @var array caches format options, please use {@link format_base::get_format_options()} */
  72      protected $formatoptions = array();
  73      /** @var array cached instances */
  74      private static $instances = array();
  75      /** @var array plugin name => class name. */
  76      private static $classesforformat = array('site' => 'site');
  77  
  78      /**
  79       * Creates a new instance of class
  80       *
  81       * Please use {@link course_get_format($courseorid)} to get an instance of the format class
  82       *
  83       * @param string $format
  84       * @param int $courseid
  85       * @return format_base
  86       */
  87      protected function __construct($format, $courseid) {
  88          $this->format = $format;
  89          $this->courseid = $courseid;
  90      }
  91  
  92      /**
  93       * Validates that course format exists and enabled and returns either itself or default format
  94       *
  95       * @param string $format
  96       * @return string
  97       */
  98      protected static final function get_format_or_default($format) {
  99          if (array_key_exists($format, self::$classesforformat)) {
 100              return self::$classesforformat[$format];
 101          }
 102  
 103          $plugins = get_sorted_course_formats();
 104          foreach ($plugins as $plugin) {
 105              self::$classesforformat[$plugin] = $plugin;
 106          }
 107  
 108          if (array_key_exists($format, self::$classesforformat)) {
 109              return self::$classesforformat[$format];
 110          }
 111  
 112          if (PHPUNIT_TEST && class_exists('format_' . $format)) {
 113              // Allow unittests to use non-existing course formats.
 114              return $format;
 115          }
 116  
 117          // Else return default format
 118          $defaultformat = get_config('moodlecourse', 'format');
 119          if (!in_array($defaultformat, $plugins)) {
 120              // when default format is not set correctly, use the first available format
 121              $defaultformat = reset($plugins);
 122          }
 123          debugging('Format plugin format_'.$format.' is not found. Using default format_'.$defaultformat, DEBUG_DEVELOPER);
 124  
 125          self::$classesforformat[$format] = $defaultformat;
 126          return $defaultformat;
 127      }
 128  
 129      /**
 130       * Get class name for the format
 131       *
 132       * If course format xxx does not declare class format_xxx, format_legacy will be returned.
 133       * This function also includes lib.php file from corresponding format plugin
 134       *
 135       * @param string $format
 136       * @return string
 137       */
 138      protected static final function get_class_name($format) {
 139          global $CFG;
 140          static $classnames = array('site' => 'format_site');
 141          if (!isset($classnames[$format])) {
 142              $plugins = core_component::get_plugin_list('format');
 143              $usedformat = self::get_format_or_default($format);
 144              if (isset($plugins[$usedformat]) && file_exists($plugins[$usedformat].'/lib.php')) {
 145                  require_once($plugins[$usedformat].'/lib.php');
 146              }
 147              $classnames[$format] = 'format_'. $usedformat;
 148              if (!class_exists($classnames[$format])) {
 149                  require_once($CFG->dirroot.'/course/format/formatlegacy.php');
 150                  $classnames[$format] = 'format_legacy';
 151              }
 152          }
 153          return $classnames[$format];
 154      }
 155  
 156      /**
 157       * Returns an instance of the class
 158       *
 159       * @todo MDL-35727 use MUC for caching of instances, limit the number of cached instances
 160       *
 161       * @param int|stdClass $courseorid either course id or
 162       *     an object that has the property 'format' and may contain property 'id'
 163       * @return format_base
 164       */
 165      public static final function instance($courseorid) {
 166          global $DB;
 167          if (!is_object($courseorid)) {
 168              $courseid = (int)$courseorid;
 169              if ($courseid && isset(self::$instances[$courseid]) && count(self::$instances[$courseid]) == 1) {
 170                  $formats = array_keys(self::$instances[$courseid]);
 171                  $format = reset($formats);
 172              } else {
 173                  $format = $DB->get_field('course', 'format', array('id' => $courseid), MUST_EXIST);
 174              }
 175          } else {
 176              $format = $courseorid->format;
 177              if (isset($courseorid->id)) {
 178                  $courseid = clean_param($courseorid->id, PARAM_INT);
 179              } else {
 180                  $courseid = 0;
 181              }
 182          }
 183          // validate that format exists and enabled, use default otherwise
 184          $format = self::get_format_or_default($format);
 185          if (!isset(self::$instances[$courseid][$format])) {
 186              $classname = self::get_class_name($format);
 187              self::$instances[$courseid][$format] = new $classname($format, $courseid);
 188          }
 189          return self::$instances[$courseid][$format];
 190      }
 191  
 192      /**
 193       * Resets cache for the course (or all caches)
 194       * To be called from {@link rebuild_course_cache()}
 195       *
 196       * @param int $courseid
 197       */
 198      public static final function reset_course_cache($courseid = 0) {
 199          if ($courseid) {
 200              if (isset(self::$instances[$courseid])) {
 201                  foreach (self::$instances[$courseid] as $format => $object) {
 202                      // in case somebody keeps the reference to course format object
 203                      self::$instances[$courseid][$format]->course = false;
 204                      self::$instances[$courseid][$format]->formatoptions = array();
 205                  }
 206                  unset(self::$instances[$courseid]);
 207              }
 208          } else {
 209              self::$instances = array();
 210          }
 211      }
 212  
 213      /**
 214       * Returns the format name used by this course
 215       *
 216       * @return string
 217       */
 218      public final function get_format() {
 219          return $this->format;
 220      }
 221  
 222      /**
 223       * Returns id of the course (0 if course is not specified)
 224       *
 225       * @return int
 226       */
 227      public final function get_courseid() {
 228          return $this->courseid;
 229      }
 230  
 231      /**
 232       * Returns a record from course database table plus additional fields
 233       * that course format defines
 234       *
 235       * @return stdClass
 236       */
 237      public function get_course() {
 238          global $DB;
 239          if (!$this->courseid) {
 240              return null;
 241          }
 242          if ($this->course === false) {
 243              $this->course = get_course($this->courseid);
 244              $options = $this->get_format_options();
 245              $dbcoursecolumns = null;
 246              foreach ($options as $optionname => $optionvalue) {
 247                  if (isset($this->course->$optionname)) {
 248                      // Course format options must not have the same names as existing columns in db table "course".
 249                      if (!isset($dbcoursecolumns)) {
 250                          $dbcoursecolumns = $DB->get_columns('course');
 251                      }
 252                      if (isset($dbcoursecolumns[$optionname])) {
 253                          debugging('The option name '.$optionname.' in course format '.$this->format.
 254                              ' is invalid because the field with the same name exists in {course} table',
 255                              DEBUG_DEVELOPER);
 256                          continue;
 257                      }
 258                  }
 259                  $this->course->$optionname = $optionvalue;
 260              }
 261          }
 262          return $this->course;
 263      }
 264  
 265      /**
 266       * Returns true if the course has a front page.
 267       *
 268       * This function is called to determine if the course has a view page, whether or not
 269       * it contains a listing of activities. It can be useful to set this to false when the course
 270       * format has only one activity and ignores the course page. Or if there are multiple
 271       * activities but no page to see the centralised information.
 272       *
 273       * Initially this was created to know if forms should add a button to return to the course page.
 274       * So if 'Return to course' does not make sense in your format your should probably return false.
 275       *
 276       * @return boolean
 277       * @since Moodle 2.6
 278       */
 279      public function has_view_page() {
 280          return true;
 281      }
 282  
 283      /**
 284       * Returns true if this course format uses sections
 285       *
 286       * This function may be called without specifying the course id
 287       * i.e. in {@link course_format_uses_sections()}
 288       *
 289       * Developers, note that if course format does use sections there should be defined a language
 290       * string with the name 'sectionname' defining what the section relates to in the format, i.e.
 291       * $string['sectionname'] = 'Topic';
 292       * or
 293       * $string['sectionname'] = 'Week';
 294       *
 295       * @return bool
 296       */
 297      public function uses_sections() {
 298          return false;
 299      }
 300  
 301      /**
 302       * Returns a list of sections used in the course
 303       *
 304       * This is a shortcut to get_fast_modinfo()->get_section_info_all()
 305       * @see get_fast_modinfo()
 306       * @see course_modinfo::get_section_info_all()
 307       *
 308       * @return array of section_info objects
 309       */
 310      public final function get_sections() {
 311          if ($course = $this->get_course()) {
 312              $modinfo = get_fast_modinfo($course);
 313              return $modinfo->get_section_info_all();
 314          }
 315          return array();
 316      }
 317  
 318      /**
 319       * Returns information about section used in course
 320       *
 321       * @param int|stdClass $section either section number (field course_section.section) or row from course_section table
 322       * @param int $strictness
 323       * @return section_info
 324       */
 325      public final function get_section($section, $strictness = IGNORE_MISSING) {
 326          if (is_object($section)) {
 327              $sectionnum = $section->section;
 328          } else {
 329              $sectionnum = $section;
 330          }
 331          $sections = $this->get_sections();
 332          if (array_key_exists($sectionnum, $sections)) {
 333              return $sections[$sectionnum];
 334          }
 335          if ($strictness == MUST_EXIST) {
 336              throw new moodle_exception('sectionnotexist');
 337          }
 338          return null;
 339      }
 340  
 341      /**
 342       * Returns the display name of the given section that the course prefers.
 343       *
 344       * @param int|stdClass $section Section object from database or just field course_sections.section
 345       * @return Display name that the course format prefers, e.g. "Topic 2"
 346       */
 347      public function get_section_name($section) {
 348          if (is_object($section)) {
 349              $sectionnum = $section->section;
 350          } else {
 351              $sectionnum = $section;
 352          }
 353          return get_string('sectionname', 'format_'.$this->format) . ' ' . $sectionnum;
 354      }
 355  
 356      /**
 357       * Returns the information about the ajax support in the given source format
 358       *
 359       * The returned object's property (boolean)capable indicates that
 360       * the course format supports Moodle course ajax features.
 361       *
 362       * @return stdClass
 363       */
 364      public function supports_ajax() {
 365          // no support by default
 366          $ajaxsupport = new stdClass();
 367          $ajaxsupport->capable = false;
 368          return $ajaxsupport;
 369      }
 370  
 371      /**
 372       * Custom action after section has been moved in AJAX mode
 373       *
 374       * Used in course/rest.php
 375       *
 376       * @return array This will be passed in ajax respose
 377       */
 378      public function ajax_section_move() {
 379          return null;
 380      }
 381  
 382      /**
 383       * The URL to use for the specified course (with section)
 384       *
 385       * Please note that course view page /course/view.php?id=COURSEID is hardcoded in many
 386       * places in core and contributed modules. If course format wants to change the location
 387       * of the view script, it is not enough to change just this function. Do not forget
 388       * to add proper redirection.
 389       *
 390       * @param int|stdClass $section Section object from database or just field course_sections.section
 391       *     if null the course view page is returned
 392       * @param array $options options for view URL. At the moment core uses:
 393       *     'navigation' (bool) if true and section has no separate page, the function returns null
 394       *     'sr' (int) used by multipage formats to specify to which section to return
 395       * @return null|moodle_url
 396       */
 397      public function get_view_url($section, $options = array()) {
 398          $course = $this->get_course();
 399          $url = new moodle_url('/course/view.php', array('id' => $course->id));
 400  
 401          if (array_key_exists('sr', $options)) {
 402              $sectionno = $options['sr'];
 403          } else if (is_object($section)) {
 404              $sectionno = $section->section;
 405          } else {
 406              $sectionno = $section;
 407          }
 408          if (!empty($options['navigation']) && $sectionno !== null) {
 409              // by default assume that sections are never displayed on separate pages
 410              return null;
 411          }
 412          if ($this->uses_sections() && $sectionno !== null) {
 413              $url->set_anchor('section-'.$sectionno);
 414          }
 415          return $url;
 416      }
 417  
 418      /**
 419       * Loads all of the course sections into the navigation
 420       *
 421       * This method is called from {@link global_navigation::load_course_sections()}
 422       *
 423       * By default the method {@link global_navigation::load_generic_course_sections()} is called
 424       *
 425       * When overwriting please note that navigationlib relies on using the correct values for
 426       * arguments $type and $key in {@link navigation_node::add()}
 427       *
 428       * Example of code creating a section node:
 429       * $sectionnode = $node->add($sectionname, $url, navigation_node::TYPE_SECTION, null, $section->id);
 430       * $sectionnode->nodetype = navigation_node::NODETYPE_BRANCH;
 431       *
 432       * Example of code creating an activity node:
 433       * $activitynode = $sectionnode->add($activityname, $action, navigation_node::TYPE_ACTIVITY, null, $activity->id, $icon);
 434       * if (global_navigation::module_extends_navigation($activity->modname)) {
 435       *     $activitynode->nodetype = navigation_node::NODETYPE_BRANCH;
 436       * } else {
 437       *     $activitynode->nodetype = navigation_node::NODETYPE_LEAF;
 438       * }
 439       *
 440       * Also note that if $navigation->includesectionnum is not null, the section with this relative
 441       * number needs is expected to be loaded
 442       *
 443       * @param global_navigation $navigation
 444       * @param navigation_node $node The course node within the navigation
 445       */
 446      public function extend_course_navigation($navigation, navigation_node $node) {
 447          if ($course = $this->get_course()) {
 448              $navigation->load_generic_course_sections($course, $node);
 449          }
 450          return array();
 451      }
 452  
 453      /**
 454       * Returns the list of blocks to be automatically added for the newly created course
 455       *
 456       * @see blocks_add_default_course_blocks()
 457       *
 458       * @return array of default blocks, must contain two keys BLOCK_POS_LEFT and BLOCK_POS_RIGHT
 459       *     each of values is an array of block names (for left and right side columns)
 460       */
 461      public function get_default_blocks() {
 462          global $CFG;
 463          if (!empty($CFG->defaultblocks)){
 464              return blocks_parse_default_blocks_list($CFG->defaultblocks);
 465          }
 466          $blocknames = array(
 467              BLOCK_POS_LEFT => array(),
 468              BLOCK_POS_RIGHT => array('search_forums', 'news_items', 'calendar_upcoming', 'recent_activity')
 469          );
 470          return $blocknames;
 471      }
 472  
 473      /**
 474       * Returns the localised name of this course format plugin
 475       *
 476       * @return lang_string
 477       */
 478      public final function get_format_name() {
 479          return new lang_string('pluginname', 'format_'.$this->get_format());
 480      }
 481  
 482      /**
 483       * Definitions of the additional options that this course format uses for course
 484       *
 485       * This function may be called often, it should be as fast as possible.
 486       * Avoid using get_string() method, use "new lang_string()" instead
 487       * It is not recommended to use dynamic or course-dependant expressions here
 488       * This function may be also called when course does not exist yet.
 489       *
 490       * Option names must be different from fields in the {course} talbe or any form elements on
 491       * course edit form, it may even make sence to use special prefix for them.
 492       *
 493       * Each option must have the option name as a key and the array of properties as a value:
 494       * 'default' - default value for this option (assumed null if not specified)
 495       * 'type' - type of the option value (PARAM_INT, PARAM_RAW, etc.)
 496       *
 497       * Additional properties used by default implementation of
 498       * {@link format_base::create_edit_form_elements()} (calls this method with $foreditform = true)
 499       * 'label' - localised human-readable label for the edit form
 500       * 'element_type' - type of the form element, default 'text'
 501       * 'element_attributes' - additional attributes for the form element, these are 4th and further
 502       *    arguments in the moodleform::addElement() method
 503       * 'help' - string for help button. Note that if 'help' value is 'myoption' then the string with
 504       *    the name 'myoption_help' must exist in the language file
 505       * 'help_component' - language component to look for help string, by default this the component
 506       *    for this course format
 507       *
 508       * This is an interface for creating simple form elements. If format plugin wants to use other
 509       * methods such as disableIf, it can be done by overriding create_edit_form_elements().
 510       *
 511       * Course format options can be accessed as:
 512       * $this->get_course()->OPTIONNAME (inside the format class)
 513       * course_get_format($course)->get_course()->OPTIONNAME (outside of format class)
 514       *
 515       * All course options are returned by calling:
 516       * $this->get_format_options();
 517       *
 518       * @param bool $foreditform
 519       * @return array of options
 520       */
 521      public function course_format_options($foreditform = false) {
 522          return array();
 523      }
 524  
 525      /**
 526       * Definitions of the additional options that this course format uses for section
 527       *
 528       * See {@link format_base::course_format_options()} for return array definition.
 529       *
 530       * Additionally section format options may have property 'cache' set to true
 531       * if this option needs to be cached in {@link get_fast_modinfo()}. The 'cache' property
 532       * is recommended to be set only for fields used in {@link format_base::get_section_name()},
 533       * {@link format_base::extend_course_navigation()} and {@link format_base::get_view_url()}
 534       *
 535       * For better performance cached options are recommended to have 'cachedefault' property
 536       * Unlike 'default', 'cachedefault' should be static and not access get_config().
 537       *
 538       * Regardless of value of 'cache' all options are accessed in the code as
 539       * $sectioninfo->OPTIONNAME
 540       * where $sectioninfo is instance of section_info, returned by
 541       * get_fast_modinfo($course)->get_section_info($sectionnum)
 542       * or get_fast_modinfo($course)->get_section_info_all()
 543       *
 544       * All format options for particular section are returned by calling:
 545       * $this->get_format_options($section);
 546       *
 547       * @param bool $foreditform
 548       * @return array
 549       */
 550      public function section_format_options($foreditform = false) {
 551          return array();
 552      }
 553  
 554      /**
 555       * Returns the format options stored for this course or course section
 556       *
 557       * When overriding please note that this function is called from rebuild_course_cache()
 558       * and section_info object, therefore using of get_fast_modinfo() and/or any function that
 559       * accesses it may lead to recursion.
 560       *
 561       * @param null|int|stdClass|section_info $section if null the course format options will be returned
 562       *     otherwise options for specified section will be returned. This can be either
 563       *     section object or relative section number (field course_sections.section)
 564       * @return array
 565       */
 566      public function get_format_options($section = null) {
 567          global $DB;
 568          if ($section === null) {
 569              $options = $this->course_format_options();
 570          } else {
 571              $options = $this->section_format_options();
 572          }
 573          if (empty($options)) {
 574              // there are no option for course/sections anyway, no need to go further
 575              return array();
 576          }
 577          if ($section === null) {
 578              // course format options will be returned
 579              $sectionid = 0;
 580          } else if ($this->courseid && isset($section->id)) {
 581              // course section format options will be returned
 582              $sectionid = $section->id;
 583          } else if ($this->courseid && is_int($section) &&
 584                  ($sectionobj = $DB->get_record('course_sections',
 585                          array('section' => $section, 'course' => $this->courseid), 'id'))) {
 586              // course section format options will be returned
 587              $sectionid = $sectionobj->id;
 588          } else {
 589              // non-existing (yet) section was passed as an argument
 590              // default format options for course section will be returned
 591              $sectionid = -1;
 592          }
 593          if (!array_key_exists($sectionid, $this->formatoptions)) {
 594              $this->formatoptions[$sectionid] = array();
 595              // first fill with default values
 596              foreach ($options as $optionname => $optionparams) {
 597                  $this->formatoptions[$sectionid][$optionname] = null;
 598                  if (array_key_exists('default', $optionparams)) {
 599                      $this->formatoptions[$sectionid][$optionname] = $optionparams['default'];
 600                  }
 601              }
 602              if ($this->courseid && $sectionid !== -1) {
 603                  // overwrite the default options values with those stored in course_format_options table
 604                  // nothing can be stored if we are interested in generic course ($this->courseid == 0)
 605                  // or generic section ($sectionid === 0)
 606                  $records = $DB->get_records('course_format_options',
 607                          array('courseid' => $this->courseid,
 608                                'format' => $this->format,
 609                                'sectionid' => $sectionid
 610                              ), '', 'id,name,value');
 611                  foreach ($records as $record) {
 612                      if (array_key_exists($record->name, $this->formatoptions[$sectionid])) {
 613                          $value = $record->value;
 614                          if ($value !== null && isset($options[$record->name]['type'])) {
 615                              // this will convert string value to number if needed
 616                              $value = clean_param($value, $options[$record->name]['type']);
 617                          }
 618                          $this->formatoptions[$sectionid][$record->name] = $value;
 619                      }
 620                  }
 621              }
 622          }
 623          return $this->formatoptions[$sectionid];
 624      }
 625  
 626      /**
 627       * Adds format options elements to the course/section edit form
 628       *
 629       * This function is called from {@link course_edit_form::definition_after_data()}
 630       *
 631       * @param MoodleQuickForm $mform form the elements are added to
 632       * @param bool $forsection 'true' if this is a section edit form, 'false' if this is course edit form
 633       * @return array array of references to the added form elements
 634       */
 635      public function create_edit_form_elements(&$mform, $forsection = false) {
 636          $elements = array();
 637          if ($forsection) {
 638              $options = $this->section_format_options(true);
 639          } else {
 640              $options = $this->course_format_options(true);
 641          }
 642          foreach ($options as $optionname => $option) {
 643              if (!isset($option['element_type'])) {
 644                  $option['element_type'] = 'text';
 645              }
 646              $args = array($option['element_type'], $optionname, $option['label']);
 647              if (!empty($option['element_attributes'])) {
 648                  $args = array_merge($args, $option['element_attributes']);
 649              }
 650              $elements[] = call_user_func_array(array($mform, 'addElement'), $args);
 651              if (isset($option['help'])) {
 652                  $helpcomponent = 'format_'. $this->get_format();
 653                  if (isset($option['help_component'])) {
 654                      $helpcomponent = $option['help_component'];
 655                  }
 656                  $mform->addHelpButton($optionname, $option['help'], $helpcomponent);
 657              }
 658              if (isset($option['type'])) {
 659                  $mform->setType($optionname, $option['type']);
 660              }
 661              if (is_null($mform->getElementValue($optionname)) && isset($option['default'])) {
 662                  $mform->setDefault($optionname, $option['default']);
 663              }
 664          }
 665          return $elements;
 666      }
 667  
 668      /**
 669       * Override if you need to perform some extra validation of the format options
 670       *
 671       * @param array $data array of ("fieldname"=>value) of submitted data
 672       * @param array $files array of uploaded files "element_name"=>tmp_file_path
 673       * @param array $errors errors already discovered in edit form validation
 674       * @return array of "element_name"=>"error_description" if there are errors,
 675       *         or an empty array if everything is OK.
 676       *         Do not repeat errors from $errors param here
 677       */
 678      public function edit_form_validation($data, $files, $errors) {
 679          return array();
 680      }
 681  
 682      /**
 683       * Updates format options for a course or section
 684       *
 685       * If $data does not contain property with the option name, the option will not be updated
 686       *
 687       * @param stdClass|array $data return value from {@link moodleform::get_data()} or array with data
 688       * @param null|int null if these are options for course or section id (course_sections.id)
 689       *     if these are options for section
 690       * @return bool whether there were any changes to the options values
 691       */
 692      protected function update_format_options($data, $sectionid = null) {
 693          global $DB;
 694          if (!$sectionid) {
 695              $allformatoptions = $this->course_format_options();
 696              $sectionid = 0;
 697          } else {
 698              $allformatoptions = $this->section_format_options();
 699          }
 700          if (empty($allformatoptions)) {
 701              // nothing to update anyway
 702              return false;
 703          }
 704          $defaultoptions = array();
 705          $cached = array();
 706          foreach ($allformatoptions as $key => $option) {
 707              $defaultoptions[$key] = null;
 708              if (array_key_exists('default', $option)) {
 709                  $defaultoptions[$key] = $option['default'];
 710              }
 711              $cached[$key] = ($sectionid === 0 || !empty($option['cache']));
 712          }
 713          $records = $DB->get_records('course_format_options',
 714                  array('courseid' => $this->courseid,
 715                        'format' => $this->format,
 716                        'sectionid' => $sectionid
 717                      ), '', 'name,id,value');
 718          $changed = $needrebuild = false;
 719          $data = (array)$data;
 720          foreach ($defaultoptions as $key => $value) {
 721              if (isset($records[$key])) {
 722                  if (array_key_exists($key, $data) && $records[$key]->value !== $data[$key]) {
 723                      $DB->set_field('course_format_options', 'value',
 724                              $data[$key], array('id' => $records[$key]->id));
 725                      $changed = true;
 726                      $needrebuild = $needrebuild || $cached[$key];
 727                  }
 728              } else {
 729                  if (array_key_exists($key, $data) && $data[$key] !== $value) {
 730                      $newvalue = $data[$key];
 731                      $changed = true;
 732                      $needrebuild = $needrebuild || $cached[$key];
 733                  } else {
 734                      $newvalue = $value;
 735                      // we still insert entry in DB but there are no changes from user point of
 736                      // view and no need to call rebuild_course_cache()
 737                  }
 738                  $DB->insert_record('course_format_options', array(
 739                      'courseid' => $this->courseid,
 740                      'format' => $this->format,
 741                      'sectionid' => $sectionid,
 742                      'name' => $key,
 743                      'value' => $newvalue
 744                  ));
 745              }
 746          }
 747          if ($needrebuild) {
 748              rebuild_course_cache($this->courseid, true);
 749          }
 750          if ($changed) {
 751              // reset internal caches
 752              if (!$sectionid) {
 753                  $this->course = false;
 754              }
 755              unset($this->formatoptions[$sectionid]);
 756          }
 757          return $changed;
 758      }
 759  
 760      /**
 761       * Updates format options for a course
 762       *
 763       * If $data does not contain property with the option name, the option will not be updated
 764       *
 765       * @param stdClass|array $data return value from {@link moodleform::get_data()} or array with data
 766       * @param stdClass $oldcourse if this function is called from {@link update_course()}
 767       *     this object contains information about the course before update
 768       * @return bool whether there were any changes to the options values
 769       */
 770      public function update_course_format_options($data, $oldcourse = null) {
 771          return $this->update_format_options($data);
 772      }
 773  
 774      /**
 775       * Updates format options for a section
 776       *
 777       * Section id is expected in $data->id (or $data['id'])
 778       * If $data does not contain property with the option name, the option will not be updated
 779       *
 780       * @param stdClass|array $data return value from {@link moodleform::get_data()} or array with data
 781       * @return bool whether there were any changes to the options values
 782       */
 783      public function update_section_format_options($data) {
 784          $data = (array)$data;
 785          return $this->update_format_options($data, $data['id']);
 786      }
 787  
 788      /**
 789       * Return an instance of moodleform to edit a specified section
 790       *
 791       * Default implementation returns instance of editsection_form that automatically adds
 792       * additional fields defined in {@link format_base::section_format_options()}
 793       *
 794       * Format plugins may extend editsection_form if they want to have custom edit section form.
 795       *
 796       * @param mixed $action the action attribute for the form. If empty defaults to auto detect the
 797       *              current url. If a moodle_url object then outputs params as hidden variables.
 798       * @param array $customdata the array with custom data to be passed to the form
 799       *     /course/editsection.php passes section_info object in 'cs' field
 800       *     for filling availability fields
 801       * @return moodleform
 802       */
 803      public function editsection_form($action, $customdata = array()) {
 804          global $CFG;
 805          require_once($CFG->dirroot. '/course/editsection_form.php');
 806          $context = context_course::instance($this->courseid);
 807          if (!array_key_exists('course', $customdata)) {
 808              $customdata['course'] = $this->get_course();
 809          }
 810          return new editsection_form($action, $customdata);
 811      }
 812  
 813      /**
 814       * Allows course format to execute code on moodle_page::set_course()
 815       *
 816       * @param moodle_page $page instance of page calling set_course
 817       */
 818      public function page_set_course(moodle_page $page) {
 819      }
 820  
 821      /**
 822       * Allows course format to execute code on moodle_page::set_cm()
 823       *
 824       * Current module can be accessed as $page->cm (returns instance of cm_info)
 825       *
 826       * @param moodle_page $page instance of page calling set_cm
 827       */
 828      public function page_set_cm(moodle_page $page) {
 829      }
 830  
 831      /**
 832       * Course-specific information to be output on any course page (usually above navigation bar)
 833       *
 834       * Example of usage:
 835       * define
 836       * class format_FORMATNAME_XXX implements renderable {}
 837       *
 838       * create format renderer in course/format/FORMATNAME/renderer.php, define rendering function:
 839       * class format_FORMATNAME_renderer extends plugin_renderer_base {
 840       *     protected function render_format_FORMATNAME_XXX(format_FORMATNAME_XXX $xxx) {
 841       *         return html_writer::tag('div', 'This is my header/footer');
 842       *     }
 843       * }
 844       *
 845       * Return instance of format_FORMATNAME_XXX in this function, the appropriate method from
 846       * plugin renderer will be called
 847       *
 848       * @return null|renderable null for no output or object with data for plugin renderer
 849       */
 850      public function course_header() {
 851          return null;
 852      }
 853  
 854      /**
 855       * Course-specific information to be output on any course page (usually in the beginning of
 856       * standard footer)
 857       *
 858       * See {@link format_base::course_header()} for usage
 859       *
 860       * @return null|renderable null for no output or object with data for plugin renderer
 861       */
 862      public function course_footer() {
 863          return null;
 864      }
 865  
 866      /**
 867       * Course-specific information to be output immediately above content on any course page
 868       *
 869       * See {@link format_base::course_header()} for usage
 870       *
 871       * @return null|renderable null for no output or object with data for plugin renderer
 872       */
 873      public function course_content_header() {
 874          return null;
 875      }
 876  
 877      /**
 878       * Course-specific information to be output immediately below content on any course page
 879       *
 880       * See {@link format_base::course_header()} for usage
 881       *
 882       * @return null|renderable null for no output or object with data for plugin renderer
 883       */
 884      public function course_content_footer() {
 885          return null;
 886      }
 887  
 888      /**
 889       * Returns instance of page renderer used by this plugin
 890       *
 891       * @param moodle_page $page
 892       * @return renderer_base
 893       */
 894      public function get_renderer(moodle_page $page) {
 895          return $page->get_renderer('format_'. $this->get_format());
 896      }
 897  
 898      /**
 899       * Returns true if the specified section is current
 900       *
 901       * By default we analyze $course->marker
 902       *
 903       * @param int|stdClass|section_info $section
 904       * @return bool
 905       */
 906      public function is_section_current($section) {
 907          if (is_object($section)) {
 908              $sectionnum = $section->section;
 909          } else {
 910              $sectionnum = $section;
 911          }
 912          return ($sectionnum && ($course = $this->get_course()) && $course->marker == $sectionnum);
 913      }
 914  
 915      /**
 916       * Allows to specify for modinfo that section is not available even when it is visible and conditionally available.
 917       *
 918       * Note: affected user can be retrieved as: $section->modinfo->userid
 919       *
 920       * Course format plugins can override the method to change the properties $available and $availableinfo that were
 921       * calculated by conditional availability.
 922       * To make section unavailable set:
 923       *     $available = false;
 924       * To make unavailable section completely hidden set:
 925       *     $availableinfo = '';
 926       * To make unavailable section visible with availability message set:
 927       *     $availableinfo = get_string('sectionhidden', 'format_xxx');
 928       *
 929       * @param section_info $section
 930       * @param bool $available the 'available' propery of the section_info as it was evaluated by conditional availability.
 931       *     Can be changed by the method but 'false' can not be overridden by 'true'.
 932       * @param string $availableinfo the 'availableinfo' propery of the section_info as it was evaluated by conditional availability.
 933       *     Can be changed by the method
 934       */
 935      public function section_get_available_hook(section_info $section, &$available, &$availableinfo) {
 936      }
 937  }
 938  
 939  /**
 940   * Pseudo course format used for the site main page
 941   *
 942   * @package    core_course
 943   * @copyright  2012 Marina Glancy
 944   * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
 945   */
 946  class format_site extends format_base {
 947  
 948      /**
 949       * Returns the display name of the given section that the course prefers.
 950       *
 951       * @param int|stdClass $section Section object from database or just field section.section
 952       * @return Display name that the course format prefers, e.g. "Topic 2"
 953       */
 954      function get_section_name($section) {
 955          return get_string('site');
 956      }
 957  
 958      /**
 959       * For this fake course referring to the whole site, the site homepage is always returned
 960       * regardless of arguments
 961       *
 962       * @param int|stdClass $section
 963       * @param array $options
 964       * @return null|moodle_url
 965       */
 966      public function get_view_url($section, $options = array()) {
 967          return new moodle_url('/');
 968      }
 969  
 970      /**
 971       * Returns the list of blocks to be automatically added on the site frontpage when moodle is installed
 972       *
 973       * @return array of default blocks, must contain two keys BLOCK_POS_LEFT and BLOCK_POS_RIGHT
 974       *     each of values is an array of block names (for left and right side columns)
 975       */
 976      public function get_default_blocks() {
 977          return blocks_get_default_site_course_blocks();
 978      }
 979  
 980      /**
 981       * Definitions of the additional options that site uses
 982       *
 983       * @param bool $foreditform
 984       * @return array of options
 985       */
 986      public function course_format_options($foreditform = false) {
 987          static $courseformatoptions = false;
 988          if ($courseformatoptions === false) {
 989              $courseformatoptions = array(
 990                  'numsections' => array(
 991                      'default' => 1,
 992                      'type' => PARAM_INT,
 993                  ),
 994              );
 995          }
 996          return $courseformatoptions;
 997      }
 998  }