[Summary view]

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