[Summary view]

Differences Between: [Versions 400 and 402] [Versions 400 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   * This is the external method used for fetching the addable blocks in a given page.
  19   *
  20   * @package    core_block
  21   * @since      Moodle 3.11
  22   * @copyright  2020 Mihail Geshoski <mihail@moodle.com>
  23   * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  24   */
  25  
  26  namespace core_block\external;
  27  
  28  defined('MOODLE_INTERNAL') || die();
  29  
  30  global $CFG;
  31  require_once($CFG->libdir . '/externallib.php');
  32  
  33  use external_api;
  34  use external_function_parameters;
  35  use external_multiple_structure;
  36  use external_single_structure;
  37  use external_value;
  38  
  39  /**
  40   * This is the external method used for fetching the addable blocks in a given page.
  41   *
  42   * @copyright  2020 Mihail Geshoski <mihail@moodle.com>
  43   * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  44   */
  45  class fetch_addable_blocks extends external_api {
  46  
  47      /**
  48       * Describes the parameters for execute.
  49       *
  50       * @return external_function_parameters
  51       */
  52      public static function execute_parameters(): external_function_parameters {
  53          return new external_function_parameters(
  54              [
  55                  'pagecontextid' => new external_value(PARAM_INT, 'The context ID of the page.'),
  56                  'pagetype' => new external_value(PARAM_ALPHANUMEXT, 'The type of the page.'),
  57                  'pagelayout' => new external_value(PARAM_ALPHA, 'The layout of the page.'),
  58                  'subpage' => new external_value(PARAM_TEXT, 'The subpage identifier', VALUE_DEFAULT, ''),
  59              ]
  60          );
  61      }
  62  
  63      /**
  64       * Fetch the addable blocks in a given page.
  65       *
  66       * @param int $pagecontextid The context ID of the page
  67       * @param string $pagetype The type of the page
  68       * @param string $pagelayout The layout of the page
  69       * @param string $subpage The subpage identifier
  70       * @return array The blocks list
  71       */
  72      public static function execute(int $pagecontextid, string $pagetype, string $pagelayout, string $subpage = ''): array {
  73          global $PAGE;
  74  
  75          $params = self::validate_parameters(self::execute_parameters(),
  76              [
  77                  'pagecontextid' => $pagecontextid,
  78                  'pagetype' => $pagetype,
  79                  'pagelayout' => $pagelayout,
  80                  'subpage' => $subpage,
  81              ]
  82          );
  83  
  84          $context = \context::instance_by_id($params['pagecontextid']);
  85          // Validate the context. This will also set the context in $PAGE.
  86          self::validate_context($context);
  87  
  88          // We need to manually set the page layout and page type.
  89          $PAGE->set_pagelayout($params['pagelayout']);
  90          $PAGE->set_pagetype($params['pagetype']);
  91          $PAGE->set_subpage($params['subpage']);
  92  
  93          // Firstly, we need to load all currently existing page blocks to later determine which blocks are addable.
  94          $PAGE->blocks->load_blocks(false);
  95          $PAGE->blocks->create_all_block_instances();
  96  
  97          $addableblocks = $PAGE->blocks->get_addable_blocks();
  98  
  99          return array_map(function($block) {
 100              return [
 101                  'name' => $block->name,
 102                  'title' => get_string('pluginname', "block_{$block->name}")
 103              ];
 104          }, $addableblocks);
 105      }
 106  
 107      /**
 108       * Describes the execute return value.
 109       *
 110       * @return external_multiple_structure
 111       */
 112      public static function execute_returns(): external_multiple_structure {
 113          return new external_multiple_structure(
 114              new external_single_structure(
 115                  [
 116                      'name' => new external_value(PARAM_PLUGIN, 'The name of the block.'),
 117                      'title' => new external_value(PARAM_RAW, 'The title of the block.'),
 118                  ]
 119              ),
 120              'List of addable blocks in a given page.'
 121          );
 122      }
 123  }