[Summary view]

Differences Between: [Versions 310 and 402] [Versions 310 and 403]

   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   * Block generator base class.
  19   *
  20   * @package    core
  21   * @category   test
  22   * @copyright  2012 Petr Skoda {@link http://skodak.org}
  23   * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  24   */
  25  
  26  defined('MOODLE_INTERNAL') || die();
  27  
  28  /**
  29   * Block generator base class.
  30   *
  31   * Extend in blocks/xxxx/tests/generator/lib.php as class block_xxxx_generator.
  32   *
  33   * @package    core
  34   * @category   test
  35   * @copyright  2012 Petr Skoda {@link http://skodak.org}
  36   * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  37   */
  38  abstract class testing_block_generator extends component_generator_base {
  39      /** @var number of created instances */
  40      protected $instancecount = 0;
  41  
  42      /**
  43       * To be called from data reset code only,
  44       * do not use in tests.
  45       * @return void
  46       */
  47      public function reset() {
  48          $this->instancecount = 0;
  49      }
  50  
  51      /**
  52       * Returns block name
  53       * @return string name of block that this class describes
  54       * @throws coding_exception if class invalid
  55       */
  56      public function get_blockname() {
  57          $matches = null;
  58          if (!preg_match('/^block_([a-z0-9_]+)_generator$/', get_class($this), $matches)) {
  59              throw new coding_exception('Invalid block generator class name: '.get_class($this));
  60          }
  61  
  62          if (empty($matches[1])) {
  63              throw new coding_exception('Invalid block generator class name: '.get_class($this));
  64          }
  65          return $matches[1];
  66      }
  67  
  68      /**
  69       * Fill in record defaults.
  70       *
  71       * @param stdClass $record
  72       * @return stdClass
  73       */
  74      protected function prepare_record(stdClass $record) {
  75          $record->blockname = $this->get_blockname();
  76          if (!isset($record->parentcontextid)) {
  77              $record->parentcontextid = context_system::instance()->id;
  78          }
  79          if (!isset($record->showinsubcontexts)) {
  80              $record->showinsubcontexts = 0;
  81          }
  82          if (!isset($record->pagetypepattern)) {
  83              $record->pagetypepattern = '*';
  84          }
  85          if (!isset($record->subpagepattern)) {
  86              $record->subpagepattern = null;
  87          }
  88          if (!isset($record->defaultregion)) {
  89              $record->defaultregion = 'side-pre';
  90          }
  91          if (!isset($record->defaultweight)) {
  92              $record->defaultweight = 5;
  93          }
  94          if (!isset($record->configdata)) {
  95              $record->configdata = null;
  96          }
  97          return $record;
  98      }
  99  
 100      /**
 101       * Create a test block instance.
 102       *
 103       * The $record passed in becomes the basis for the new row added to the
 104       * block_instances table. You only need to supply the values of interest.
 105       * Any missing values have sensible defaults filled in.
 106       *
 107       * The $options array provides additional data, not directly related to what
 108       * will be inserted in the block_instance table, which may affect the block
 109       * that is created. The meanings of any data passed here depends on the particular
 110       * type of block being created.
 111       *
 112       * @param array|stdClass $record forms the basis for the entry to be inserted in the block_instances table.
 113       * @param array $options further, block-specific options to control how the block is created.
 114       * @return stdClass the block_instance record that has just been created.
 115       */
 116      public function create_instance($record = null, $options = array()) {
 117          global $DB, $PAGE;
 118  
 119          $this->instancecount++;
 120  
 121          // Creating a block is a back end operation, which should not cause any output to happen.
 122          // This will allow us to check that the theme was not initialised while creating the block instance.
 123          $outputstartedbefore = $PAGE->get_where_theme_was_initialised();
 124  
 125          $record = (object)(array)$record;
 126          $this->preprocess_record($record, $options);
 127          $record = $this->prepare_record($record);
 128  
 129          if (empty($record->timecreated)) {
 130              $record->timecreated = time();
 131          }
 132          if (empty($record->timemodified)) {
 133              $record->timemodified = time();
 134          }
 135  
 136          $id = $DB->insert_record('block_instances', $record);
 137          context_block::instance($id);
 138  
 139          $instance = $DB->get_record('block_instances', array('id' => $id), '*', MUST_EXIST);
 140  
 141          // If the theme was initialised while creating the block instance, something somewhere called an output
 142          // function. Rather than leaving this as a hard-to-debug situation, let's make it fail with a clear error.
 143          $outputstartedafter = $PAGE->get_where_theme_was_initialised();
 144  
 145          if ($outputstartedbefore === null && $outputstartedafter !== null) {
 146              throw new coding_exception('Creating a block_' . $this->get_blockname() . ' initialised the theme and output!',
 147                  'This should not happen. Creating a block should be a pure back-end operation. Unnecessarily initialising ' .
 148                  'the output mechanism at the wrong time can cause subtle bugs and is a significant performance hit. There is ' .
 149                  'likely a call to an output function that caused it:' . PHP_EOL . PHP_EOL .
 150                  format_backtrace($outputstartedafter, true));
 151          }
 152  
 153          return $instance;
 154      }
 155  
 156      /**
 157       * Can be overridden to do block-specific processing. $record can be modified
 158       * in-place.
 159       *
 160       * @param stdClass $record the data, before defaults are filled in.
 161       * @param array $options further, block-specific options, as passed to {@link create_instance()}.
 162       */
 163      protected function preprocess_record(stdClass $record, array $options) {
 164      }
 165  }