[Summary view]

Differences Between: [Versions 39 and 400] [Versions 39 and 401] [Versions 39 and 402] [Versions 39 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   * Blocks external API
  19   *
  20   * @package    core_block
  21   * @category   external
  22   * @copyright  2017 Juan Leyva <juan@moodle.com>
  23   * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  24   * @since      Moodle 3.3
  25   */
  26  
  27  defined('MOODLE_INTERNAL') || die;
  28  
  29  require_once("$CFG->libdir/externallib.php");
  30  
  31  /**
  32   * Blocks external functions
  33   *
  34   * @package    core_block
  35   * @category   external
  36   * @copyright  2015 Juan Leyva <juan@moodle.com>
  37   * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  38   * @since      Moodle 3.3
  39   */
  40  class core_block_external extends external_api {
  41  
  42  
  43      /**
  44       * Returns a block structure.
  45       *
  46       * @return external_single_structure a block single structure.
  47       * @since  Moodle 3.6
  48       */
  49      private static function get_block_structure() {
  50          return new external_single_structure(
  51              array(
  52                  'instanceid'    => new external_value(PARAM_INT, 'Block instance id.'),
  53                  'name'          => new external_value(PARAM_PLUGIN, 'Block name.'),
  54                  'region'        => new external_value(PARAM_ALPHANUMEXT, 'Block region.'),
  55                  'positionid'    => new external_value(PARAM_INT, 'Position id.'),
  56                  'collapsible'   => new external_value(PARAM_BOOL, 'Whether the block is collapsible.'),
  57                  'dockable'      => new external_value(PARAM_BOOL, 'Whether the block is dockable.'),
  58                  'weight'        => new external_value(PARAM_INT, 'Used to order blocks within a region.', VALUE_OPTIONAL),
  59                  'visible'       => new external_value(PARAM_BOOL, 'Whether the block is visible.', VALUE_OPTIONAL),
  60                  'contents'      => new external_single_structure(
  61                      array(
  62                          'title'         => new external_value(PARAM_RAW, 'Block title.'),
  63                          'content'       => new external_value(PARAM_RAW, 'Block contents.'),
  64                          'contentformat' => new external_format_value('content'),
  65                          'footer'        => new external_value(PARAM_RAW, 'Block footer.'),
  66                          'files'         => new external_files('Block files.'),
  67                      ),
  68                      'Block contents (if required).', VALUE_OPTIONAL
  69                  ),
  70                  'configs' => new external_multiple_structure(
  71                      new external_single_structure(
  72                          array(
  73                              'name' => new external_value(PARAM_RAW, 'Name.'),
  74                              'value' => new external_value(PARAM_RAW, 'JSON encoded representation of the config value.'),
  75                              'type' => new external_value(PARAM_ALPHA, 'Type (instance or plugin).'),
  76                          )
  77                      ),
  78                      'Block instance and plugin configuration settings.', VALUE_OPTIONAL
  79                  ),
  80              ), 'Block information.'
  81          );
  82      }
  83  
  84      /**
  85       * Convenience function for getting all the blocks of the current $PAGE.
  86       *
  87       * @param bool $includeinvisible Whether to include not visible blocks or not
  88       * @param bool $returncontents Whether to return the block contents
  89       * @return array Block information
  90       * @since  Moodle 3.6
  91       */
  92      private static function get_all_current_page_blocks($includeinvisible = false, $returncontents = false) {
  93          global $PAGE, $OUTPUT;
  94  
  95          // Set page URL to a fake URL to avoid errors.
  96          $PAGE->set_url(new \moodle_url('/webservice/core_block_external/'));
  97  
  98          // Load the block instances for all the regions.
  99          $PAGE->blocks->load_blocks($includeinvisible);
 100          $PAGE->blocks->create_all_block_instances();
 101  
 102          $allblocks = array();
 103          $blocks = $PAGE->blocks->get_content_for_all_regions($OUTPUT);
 104          foreach ($blocks as $region => $regionblocks) {
 105              $regioninstances = $PAGE->blocks->get_blocks_for_region($region);
 106              // Index block instances to retrieve required info.
 107              $blockinstances = array();
 108              foreach ($regioninstances as $ri) {
 109                  $blockinstances[$ri->instance->id] = $ri;
 110              }
 111  
 112              foreach ($regionblocks as $bc) {
 113                  $block = [
 114                      'instanceid' => $bc->blockinstanceid,
 115                      'name' => $blockinstances[$bc->blockinstanceid]->instance->blockname,
 116                      'region' => $region,
 117                      'positionid' => $bc->blockpositionid,
 118                      'collapsible' => (bool) $bc->collapsible,
 119                      'dockable' => (bool) $bc->dockable,
 120                      'weight' => $blockinstances[$bc->blockinstanceid]->instance->weight,
 121                      'visible' => $blockinstances[$bc->blockinstanceid]->instance->visible,
 122                  ];
 123                  if ($returncontents) {
 124                      $block['contents'] = (array) $blockinstances[$bc->blockinstanceid]->get_content_for_external($OUTPUT);
 125                  }
 126                  $configs = (array) $blockinstances[$bc->blockinstanceid]->get_config_for_external();
 127                  foreach ($configs as $type => $data) {
 128                      foreach ((array) $data as $name => $value) {
 129                          $block['configs'][] = [
 130                              'name' => $name,
 131                              'value' => json_encode($value), // Always JSON encode, we may receive non-scalar values.
 132                              'type' => $type,
 133                          ];
 134                      }
 135                  }
 136  
 137                  $allblocks[] = $block;
 138              }
 139          }
 140          return $allblocks;
 141      }
 142  
 143      /**
 144       * Returns description of get_course_blocks parameters.
 145       *
 146       * @return external_function_parameters
 147       * @since Moodle 3.3
 148       */
 149      public static function get_course_blocks_parameters() {
 150          return new external_function_parameters(
 151              array(
 152                  'courseid'  => new external_value(PARAM_INT, 'course id'),
 153                  'returncontents' => new external_value(PARAM_BOOL, 'Whether to return the block contents.', VALUE_DEFAULT, false),
 154              )
 155          );
 156      }
 157  
 158      /**
 159       * Returns blocks information for a course.
 160       *
 161       * @param int $courseid The course id
 162       * @param bool $returncontents Whether to return the block contents
 163       * @return array Blocks list and possible warnings
 164       * @throws moodle_exception
 165       * @since Moodle 3.3
 166       */
 167      public static function get_course_blocks($courseid, $returncontents = false) {
 168          global $PAGE;
 169  
 170          $warnings = array();
 171          $params = self::validate_parameters(self::get_course_blocks_parameters(),
 172              ['courseid' => $courseid, 'returncontents' => $returncontents]);
 173  
 174          $course = get_course($params['courseid']);
 175          $context = context_course::instance($course->id);
 176          self::validate_context($context);
 177  
 178          // Specific layout for frontpage course.
 179          if ($course->id == SITEID) {
 180              $PAGE->set_pagelayout('frontpage');
 181              $PAGE->set_pagetype('site-index');
 182          } else {
 183              $PAGE->set_pagelayout('course');
 184              // Ensure course format is set (view course/view.php).
 185              $course->format = course_get_format($course)->get_format();
 186              $PAGE->set_pagetype('course-view-' . $course->format);
 187          }
 188  
 189          $allblocks = self::get_all_current_page_blocks(false, $params['returncontents']);
 190  
 191          return array(
 192              'blocks' => $allblocks,
 193              'warnings' => $warnings
 194          );
 195      }
 196  
 197      /**
 198       * Returns description of get_course_blocks result values.
 199       *
 200       * @return external_single_structure
 201       * @since Moodle 3.3
 202       */
 203      public static function get_course_blocks_returns() {
 204  
 205          return new external_single_structure(
 206              array(
 207                  'blocks' => new external_multiple_structure(self::get_block_structure(), 'List of blocks in the course.'),
 208                  'warnings'  => new external_warnings(),
 209              )
 210          );
 211      }
 212  
 213      /**
 214       * Returns description of get_dashboard_blocks parameters.
 215       *
 216       * @return external_function_parameters
 217       * @since Moodle 3.6
 218       */
 219      public static function get_dashboard_blocks_parameters() {
 220          return new external_function_parameters(
 221              array(
 222                  'userid'  => new external_value(PARAM_INT, 'User id (optional), default is current user.', VALUE_DEFAULT, 0),
 223                  'returncontents' => new external_value(PARAM_BOOL, 'Whether to return the block contents.', VALUE_DEFAULT, false),
 224              )
 225          );
 226      }
 227  
 228      /**
 229       * Returns blocks information for the given user dashboard.
 230       *
 231       * @param int $userid The user id to retrive the blocks from, optional, default is to current user.
 232       * @param bool $returncontents Whether to return the block contents
 233       * @return array Blocks list and possible warnings
 234       * @throws moodle_exception
 235       * @since Moodle 3.6
 236       */
 237      public static function get_dashboard_blocks($userid = 0, $returncontents = false) {
 238          global $CFG, $USER, $PAGE;
 239  
 240          require_once($CFG->dirroot . '/my/lib.php');
 241  
 242          $warnings = array();
 243          $params = self::validate_parameters(self::get_dashboard_blocks_parameters(),
 244              ['userid' => $userid, 'returncontents' => $returncontents]);
 245  
 246          $userid = $params['userid'];
 247          if (empty($userid)) {
 248              $userid = $USER->id;
 249          }
 250  
 251          if ($USER->id != $userid) {
 252              // We must check if the current user can view other users dashboard.
 253              require_capability('moodle/site:config', context_system::instance());
 254              $user = core_user::get_user($userid, '*', MUST_EXIST);
 255              core_user::require_active_user($user);
 256          }
 257  
 258          $context = context_user::instance($userid);;
 259          self::validate_context($context);
 260  
 261          // Get the My Moodle page info.  Should always return something unless the database is broken.
 262          if (!$currentpage = my_get_page($userid, MY_PAGE_PRIVATE)) {
 263              throw new moodle_exception('mymoodlesetup');
 264          }
 265  
 266          $PAGE->set_context($context);
 267          $PAGE->set_pagelayout('mydashboard');
 268          $PAGE->set_pagetype('my-index');
 269          $PAGE->blocks->add_region('content');   // Need to add this special regition to retrieve the central blocks.
 270          $PAGE->set_subpage($currentpage->id);
 271  
 272          // Load the block instances in the current $PAGE for all the regions.
 273          $returninvisible = has_capability('moodle/my:manageblocks', $context) ? true : false;
 274          $allblocks = self::get_all_current_page_blocks($returninvisible, $params['returncontents']);
 275  
 276          return array(
 277              'blocks' => $allblocks,
 278              'warnings' => $warnings
 279          );
 280      }
 281  
 282      /**
 283       * Returns description of get_dashboard_blocks result values.
 284       *
 285       * @return external_single_structure
 286       * @since Moodle 3.6
 287       */
 288      public static function get_dashboard_blocks_returns() {
 289  
 290          return new external_single_structure(
 291              array(
 292                  'blocks' => new external_multiple_structure(self::get_block_structure(), 'List of blocks in the dashboard.'),
 293                  'warnings'  => new external_warnings(),
 294              )
 295          );
 296      }
 297  }