[Summary view]

Differences Between: [Versions 311 and 402] [Versions 311 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   * Table external API.
  19   *
  20   * @package    core_table
  21   * @category   external
  22   * @copyright  2020 Simey Lameze <simey@moodle.com>
  23   * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  24   */
  25  
  26  namespace core_table\external\dynamic;
  27  
  28  use external_api;
  29  use external_function_parameters;
  30  use external_multiple_structure;
  31  use external_single_structure;
  32  use external_value;
  33  use external_warnings;
  34  
  35  /**
  36   * Core table external functions.
  37   *
  38   * @package    core_table
  39   * @category   external
  40   * @copyright  2020 Simey Lameze <simey@moodle.com>
  41   * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  42   */
  43  class get extends external_api {
  44  
  45      /**
  46       * Describes the parameters for fetching the table html.
  47       *
  48       * @return external_function_parameters
  49       * @since Moodle 3.9
  50       */
  51      public static function execute_parameters(): external_function_parameters {
  52          return new external_function_parameters ([
  53              'component' => new external_value(
  54                  PARAM_COMPONENT,
  55                  'Component',
  56                  VALUE_REQUIRED
  57              ),
  58              'handler' => new external_value(
  59                  // Note: We do not have a PARAM_CLASSNAME which would have been ideal.
  60                  PARAM_ALPHANUMEXT,
  61                  'Handler',
  62                  VALUE_REQUIRED
  63              ),
  64              'uniqueid' => new external_value(
  65                  PARAM_ALPHANUMEXT,
  66                  'Unique ID for the container',
  67                  VALUE_REQUIRED
  68              ),
  69              'sortdata' => new external_multiple_structure(
  70                  new external_single_structure([
  71                      'sortby' => new external_value(
  72                          PARAM_ALPHANUMEXT,
  73                          'The name of a sortable column',
  74                          VALUE_REQUIRED
  75                      ),
  76                      'sortorder' => new external_value(
  77                          PARAM_ALPHANUMEXT,
  78                          'The direction that this column should be sorted by',
  79                          VALUE_REQUIRED
  80                      ),
  81                  ]),
  82                  'The combined sort order of the table. Multiple fields can be specified.',
  83                  VALUE_OPTIONAL,
  84                  []
  85              ),
  86              'filters' => new external_multiple_structure(
  87                  new external_single_structure([
  88                      'name' => new external_value(PARAM_ALPHANUM, 'Name of the filter', VALUE_REQUIRED),
  89                      'jointype' => new external_value(PARAM_INT, 'Type of join for filter values', VALUE_REQUIRED),
  90                      'values' => new external_multiple_structure(
  91                          new external_value(PARAM_RAW, 'Filter value'),
  92                          'The value to filter on',
  93                          VALUE_REQUIRED
  94                      )
  95                  ]),
  96                  'The filters that will be applied in the request',
  97                  VALUE_OPTIONAL
  98              ),
  99              'jointype' => new external_value(PARAM_INT, 'Type of join to join all filters together', VALUE_REQUIRED),
 100              'firstinitial' => new external_value(
 101                  PARAM_RAW,
 102                  'The first initial to sort filter on',
 103                  VALUE_REQUIRED,
 104                  null
 105              ),
 106              'lastinitial' => new external_value(
 107                  PARAM_RAW,
 108                  'The last initial to sort filter on',
 109                  VALUE_REQUIRED,
 110                  null
 111              ),
 112              'pagenumber' => new external_value(
 113                  PARAM_INT,
 114                  'The page number',
 115                  VALUE_REQUIRED,
 116                  null
 117              ),
 118              'pagesize' => new external_value(
 119                  PARAM_INT,
 120                  'The number of records per page',
 121                  VALUE_REQUIRED,
 122                  null
 123              ),
 124              'hiddencolumns' => new external_multiple_structure(
 125                  new external_value(
 126                      PARAM_ALPHANUMEXT,
 127                      'Name of column',
 128                      VALUE_REQUIRED,
 129                      null
 130                  )
 131              ),
 132              'resetpreferences' => new external_value(
 133                  PARAM_BOOL,
 134                  'Whether the table preferences should be reset',
 135                  VALUE_REQUIRED,
 136                  null
 137              ),
 138          ]);
 139      }
 140  
 141      /**
 142       * External function to get the table view content.
 143       *
 144       * @param string $component The component.
 145       * @param string $handler Dynamic table class name.
 146       * @param string $uniqueid Unique ID for the container.
 147       * @param array $sortdata The columns and order to sort by
 148       * @param array $filters The filters that will be applied in the request.
 149       * @param string $jointype The join type.
 150       * @param string $firstinitial The first name initial to filter on
 151       * @param string $lastinitial The last name initial to filter on
 152       * @param int $pagenumber The page number.
 153       * @param int $pagesize The number of records.
 154       * @param string $jointype The join type.
 155       * @param bool $resetpreferences Whether it is resetting table preferences or not.
 156       *
 157       * @return array
 158       */
 159      public static function execute(
 160          string $component,
 161          string $handler,
 162          string $uniqueid,
 163          array $sortdata,
 164          ?array $filters = null,
 165          ?string $jointype = null,
 166          ?string $firstinitial = null,
 167          ?string $lastinitial = null,
 168          ?int $pagenumber = null,
 169          ?int $pagesize = null,
 170          ?array $hiddencolumns = null,
 171          ?bool $resetpreferences = null
 172      ) {
 173          global $PAGE;
 174  
 175          [
 176              'component' => $component,
 177              'handler' => $handler,
 178              'uniqueid' => $uniqueid,
 179              'sortdata' => $sortdata,
 180              'filters' => $filters,
 181              'jointype' => $jointype,
 182              'firstinitial' => $firstinitial,
 183              'lastinitial' => $lastinitial,
 184              'pagenumber' => $pagenumber,
 185              'pagesize' => $pagesize,
 186              'hiddencolumns' => $hiddencolumns,
 187              'resetpreferences' => $resetpreferences,
 188          ] = self::validate_parameters(self::execute_parameters(), [
 189              'component' => $component,
 190              'handler' => $handler,
 191              'uniqueid' => $uniqueid,
 192              'sortdata' => $sortdata,
 193              'filters' => $filters,
 194              'jointype' => $jointype,
 195              'firstinitial' => $firstinitial,
 196              'lastinitial' => $lastinitial,
 197              'pagenumber' => $pagenumber,
 198              'pagesize' => $pagesize,
 199              'hiddencolumns' => $hiddencolumns,
 200              'resetpreferences' => $resetpreferences,
 201          ]);
 202  
 203          $tableclass = "\\{$component}\\table\\{$handler}";
 204          if (!class_exists($tableclass)) {
 205              throw new \UnexpectedValueException("Table handler class {$tableclass} not found. " .
 206                  "Please make sure that your table handler class is under the \\{$component}\\table namespace.");
 207          }
 208  
 209          if (!is_subclass_of($tableclass, \core_table\dynamic::class)) {
 210              throw new \UnexpectedValueException("Table handler class {$tableclass} does not support dynamic updating.");
 211          }
 212  
 213          $filtersetclass = "{$tableclass}_filterset";
 214          if (!class_exists($filtersetclass)) {
 215              throw new \UnexpectedValueException("The filter specified ({$filtersetclass}) is invalid.");
 216          }
 217  
 218          $filterset = new $filtersetclass();
 219          $filterset->set_join_type($jointype);
 220          foreach ($filters as $rawfilter) {
 221              $filterset->add_filter_from_params(
 222                  $rawfilter['name'],
 223                  $rawfilter['jointype'],
 224                  $rawfilter['values']
 225              );
 226          }
 227  
 228          $instance = new $tableclass($uniqueid);
 229          $instance->set_filterset($filterset);
 230          self::validate_context($instance->get_context());
 231  
 232          $instance->set_sortdata($sortdata);
 233          $alphabet = get_string('alphabet', 'langconfig');
 234  
 235          if ($firstinitial !== null && ($firstinitial === '' || strpos($alphabet, $firstinitial) !== false)) {
 236              $instance->set_first_initial($firstinitial);
 237          }
 238  
 239          if ($lastinitial !== null && ($lastinitial === '' || strpos($alphabet, $lastinitial) !== false)) {
 240              $instance->set_last_initial($lastinitial);
 241          }
 242  
 243          if ($pagenumber !== null) {
 244              $instance->set_page_number($pagenumber);
 245          }
 246  
 247          if ($pagesize === null) {
 248              $pagesize = 20;
 249          }
 250  
 251          if ($hiddencolumns !== null) {
 252              $instance->set_hidden_columns($hiddencolumns);
 253          }
 254  
 255          if ($resetpreferences === true) {
 256              $instance->mark_table_to_reset();
 257          }
 258  
 259          $PAGE->set_url($instance->baseurl);
 260  
 261          ob_start();
 262          $instance->out($pagesize, true);
 263          $tablehtml = ob_get_contents();
 264          ob_end_clean();
 265  
 266          return [
 267              'html' => $tablehtml,
 268              'warnings' => []
 269          ];
 270      }
 271  
 272      /**
 273       * Describes the data returned from the external function.
 274       *
 275       * @return external_single_structure
 276       * @since Moodle 3.9
 277       */
 278      public static function execute_returns(): external_single_structure {
 279          return new external_single_structure([
 280              'html' => new external_value(PARAM_RAW, 'The raw html of the requested table.'),
 281              'warnings' => new external_warnings()
 282          ]);
 283      }
 284  }