[Summary view]

Differences Between: [Versions 310 and 402] [Versions 311 and 402] [Versions 39 and 402] [Versions 400 and 402] [Versions 401 and 402]

   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\output;
  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 context_system;
  25  use core\external\output\icon_system\load_fontawesome_map;
  26  
  27  /**
  28   * This class contains a list of webservice functions related to output.
  29   *
  30   * @package    core
  31   * @copyright  2015 Damyon Wiese
  32   * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  33   * @since      2.9
  34   */
  35  class external extends external_api {
  36      /**
  37       * Returns description of load_template() parameters.
  38       *
  39       * @return external_function_parameters
  40       */
  41      public static function load_template_parameters() {
  42          return new external_function_parameters(
  43                  array('component' => new external_value(PARAM_COMPONENT, 'component containing the template'),
  44                        'template' => new external_value(PARAM_SAFEPATH, 'name of the template'),
  45                        'themename' => new external_value(PARAM_ALPHANUMEXT, 'The current theme.'),
  46                        'includecomments' => new external_value(PARAM_BOOL, 'Include comments or not', VALUE_DEFAULT, false)
  47                           )
  48              );
  49      }
  50  
  51      /**
  52       * Return a mustache template, and all the strings it requires.
  53       *
  54       * @param string $component The component that holds the template.
  55       * @param string $templatename The name of the template.
  56       * @param string $themename The name of the current theme.
  57       * @return string the template
  58       */
  59      public static function load_template($component, $template, $themename, $includecomments = false) {
  60          global $DB, $CFG, $PAGE;
  61  
  62          $PAGE->set_context(context_system::instance());
  63          $params = self::validate_parameters(self::load_template_parameters(),
  64                                              array('component' => $component,
  65                                                    'template' => $template,
  66                                                    'themename' => $themename,
  67                                                    'includecomments' => $includecomments));
  68  
  69          $loader = new mustache_template_source_loader();
  70          // Will throw exceptions if the template does not exist.
  71          return $loader->load(
  72              $params['component'],
  73              $params['template'],
  74              $params['themename'],
  75              $params['includecomments']
  76          );
  77      }
  78  
  79      /**
  80       * Returns description of load_template() result value.
  81       *
  82       * @return \core_external\external_description
  83       */
  84      public static function load_template_returns() {
  85          return new external_value(PARAM_RAW, 'template');
  86      }
  87  
  88      /**
  89       * Returns description of load_template_with_dependencies() parameters.
  90       *
  91       * @return external_function_parameters
  92       */
  93      public static function load_template_with_dependencies_parameters() {
  94          return new external_function_parameters([
  95              'component' => new external_value(PARAM_COMPONENT, 'component containing the template'),
  96              'template' => new external_value(PARAM_SAFEPATH, 'name of the template'),
  97              'themename' => new external_value(PARAM_ALPHANUMEXT, 'The current theme.'),
  98              'includecomments' => new external_value(PARAM_BOOL, 'Include comments or not', VALUE_DEFAULT, false),
  99              'lang' => new external_value(PARAM_LANG, 'lang', VALUE_DEFAULT, null),
 100          ]);
 101      }
 102  
 103      /**
 104       * Return a mustache template, and all the child templates and strings it requires.
 105       *
 106       * @param string $component The component that holds the template.
 107       * @param string $template The name of the template.
 108       * @param string $themename The name of the current theme.
 109       * @param bool $includecomments Whether to strip comments from the template source.
 110       * @param string $lang moodle translation language, null means use current.
 111       * @return string the template
 112       */
 113      public static function load_template_with_dependencies(
 114          string $component,
 115          string $template,
 116          string $themename,
 117          bool $includecomments = false,
 118          string $lang = null
 119      ) {
 120          global $DB, $CFG, $PAGE;
 121  
 122          $params = self::validate_parameters(
 123              self::load_template_with_dependencies_parameters(),
 124              [
 125                  'component' => $component,
 126                  'template' => $template,
 127                  'themename' => $themename,
 128                  'includecomments' => $includecomments,
 129                  'lang' => $lang
 130              ]
 131          );
 132  
 133          $loader = new mustache_template_source_loader();
 134          // Will throw exceptions if the template does not exist.
 135          $dependencies = $loader->load_with_dependencies(
 136              $params['component'],
 137              $params['template'],
 138              $params['themename'],
 139              $params['includecomments'],
 140              [],
 141              [],
 142              $params['lang']
 143          );
 144          $formatdependencies = function($dependency) {
 145              $results = [];
 146              foreach ($dependency as $dependencycomponent => $dependencyvalues) {
 147                  foreach ($dependencyvalues as $dependencyname => $dependencyvalue) {
 148                      array_push($results, [
 149                          'component' => $dependencycomponent,
 150                          'name' => $dependencyname,
 151                          'value' => $dependencyvalue
 152                      ]);
 153                  }
 154              }
 155              return $results;
 156          };
 157  
 158          // Now we have to unpack the dependencies into a format that can be returned
 159          // by external functions (because they don't support dynamic keys).
 160          return [
 161              'templates' => $formatdependencies($dependencies['templates']),
 162              'strings' => $formatdependencies($dependencies['strings'])
 163          ];
 164      }
 165  
 166      /**
 167       * Returns description of load_template_with_dependencies() result value.
 168       *
 169       * @return \core_external\external_description
 170       */
 171      public static function load_template_with_dependencies_returns() {
 172          $resourcestructure = new external_single_structure([
 173              'component' => new external_value(PARAM_COMPONENT, 'component containing the resource'),
 174              'name' => new external_value(PARAM_TEXT, 'name of the resource'),
 175              'value' => new external_value(PARAM_RAW, 'resource value')
 176          ]);
 177  
 178          return new external_single_structure([
 179              'templates' => new external_multiple_structure($resourcestructure),
 180              'strings' => new external_multiple_structure($resourcestructure)
 181          ]);
 182      }
 183  
 184      /**
 185       * Returns description of load_icon_map() parameters.
 186       *
 187       * @return external_function_parameters
 188       */
 189      public static function load_fontawesome_icon_map_parameters() {
 190          return new external_function_parameters([]);
 191      }
 192  
 193      /**
 194       * Return a mapping of icon names to icons.
 195       *
 196       * @deprecated since Moodle 3.10
 197       * @return array the mapping
 198       */
 199      public static function load_fontawesome_icon_map() {
 200          global $PAGE;
 201  
 202          return load_fontawesome_map::execute($PAGE->theme->name);
 203      }
 204  
 205      /**
 206       * Returns description of load_icon_map() result value.
 207       *
 208       * @return \core_external\external_description
 209       */
 210      public static function load_fontawesome_icon_map_returns() {
 211          return load_fontawesome_map::execute_returns();
 212      }
 213  
 214      /**
 215       * The `load_fontawesome_icon_map` function has been replaced with
 216       * @see load_fontawesome_map::execute()
 217       *
 218       * @return bool
 219       */
 220      public static function load_fontawesome_icon_map_is_deprecated() {
 221          return true;
 222      }
 223  }