[Summary view] [Print] [Text view]

   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  /**
  19   * external API for core library
  20   *
  21   * @package    core_webservice
  22   * @category   external
  23   * @copyright  2012 Jerome Mouneyrac <jerome@moodle.com>
  24   * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  25   */
  26  
  27  defined('MOODLE_INTERNAL') || die;
  28  
  29  require_once("$CFG->libdir/externallib.php");
  30  
  31  /**
  32   * Web service related functions
  33   *
  34   * @package    core
  35   * @category   external
  36   * @copyright  2012 Jerome Mouneyrac <jerome@moodle.com>
  37   * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  38   * @since Moodle 2.4
  39   */
  40  class core_external extends external_api {
  41  
  42  
  43      /**
  44       * Format the received string parameters to be sent to the core get_string() function.
  45       *
  46       * @param array $stringparams
  47       * @return object|string
  48       * @since Moodle 2.4
  49       */
  50      public static function format_string_parameters($stringparams) {
  51          // Check if there are some string params.
  52          $strparams = new stdClass();
  53          if (!empty($stringparams)) {
  54              // There is only one string parameter.
  55              if (count($stringparams) == 1) {
  56                  $stringparam = array_pop($stringparams);
  57                  if (isset($stringparam['name'])) {
  58                      $strparams->{$stringparam['name']} = $stringparam['value'];
  59                  } else {
  60                      // It is a not named string parameter.
  61                      $strparams = $stringparam['value'];
  62                  }
  63              }  else {
  64                  // There are more than one parameter.
  65                  foreach ($stringparams as $stringparam) {
  66  
  67                      // If a parameter is unnamed throw an exception
  68                      // unnamed param is only possible if one only param is sent.
  69                      if (empty($stringparam['name'])) {
  70                          throw new moodle_exception('unnamedstringparam', 'webservice');
  71                      }
  72  
  73                      $strparams->{$stringparam['name']} = $stringparam['value'];
  74                  }
  75              }
  76          }
  77          return $strparams;
  78      }
  79  
  80      /**
  81       * Returns description of get_string parameters
  82       *
  83       * @return external_function_parameters
  84       * @since Moodle 2.4
  85       */
  86      public static function get_string_parameters() {
  87          return new external_function_parameters(
  88              array('stringid' => new external_value(PARAM_STRINGID, 'string identifier'),
  89                    'component' => new external_value(PARAM_COMPONENT,'component', VALUE_DEFAULT, 'moodle'),
  90                    'lang' => new external_value(PARAM_LANG, 'lang', VALUE_DEFAULT, null),
  91                    'stringparams' => new external_multiple_structure (
  92                        new external_single_structure(array(
  93                            'name' => new external_value(PARAM_ALPHANUMEXT, 'param name
  94                              - if the string expect only one $a parameter then don\'t send this field, just send the value.', VALUE_OPTIONAL),
  95                            'value' => new external_value(PARAM_RAW,'param value'))),
  96                            'the definition of a string param (i.e. {$a->name})', VALUE_DEFAULT, array()
  97                     )
  98              )
  99          );
 100      }
 101  
 102      /**
 103       * Return a core get_string() call
 104       *
 105       * @param string $identifier string identifier
 106       * @param string $component string component
 107       * @param array $stringparams the string params
 108       * @return string
 109       * @since Moodle 2.4
 110       */
 111      public static function get_string($stringid, $component = 'moodle', $lang = null, $stringparams = array()) {
 112          $params = self::validate_parameters(self::get_string_parameters(),
 113                        array('stringid'=>$stringid, 'component' => $component, 'lang' => $lang, 'stringparams' => $stringparams));
 114  
 115          $stringmanager = get_string_manager();
 116          return $stringmanager->get_string($params['stringid'], $params['component'],
 117              core_external::format_string_parameters($params['stringparams']), $params['lang']);
 118      }
 119  
 120      /**
 121       * Returns description of get_string() result value
 122       *
 123       * @return string
 124       * @since Moodle 2.4
 125       */
 126      public static function get_string_returns() {
 127          return new external_value(PARAM_RAW, 'translated string');
 128      }
 129  
 130      /**
 131       * Returns description of get_string parameters
 132       *
 133       * @return external_function_parameters
 134       * @since Moodle 2.4
 135       */
 136      public static function get_strings_parameters() {
 137          return new external_function_parameters(
 138              array('strings' => new external_multiple_structure (
 139                      new external_single_structure (array(
 140                          'stringid' => new external_value(PARAM_STRINGID, 'string identifier'),
 141                          'component' => new external_value(PARAM_COMPONENT, 'component', VALUE_DEFAULT, 'moodle'),
 142                          'lang' => new external_value(PARAM_LANG, 'lang', VALUE_DEFAULT, null),
 143                          'stringparams' => new external_multiple_structure (
 144                              new external_single_structure(array(
 145                                  'name' => new external_value(PARAM_ALPHANUMEXT, 'param name
 146                                      - if the string expect only one $a parameter then don\'t send this field, just send the value.', VALUE_OPTIONAL),
 147                                  'value' => new external_value(PARAM_RAW, 'param value'))),
 148                                  'the definition of a string param (i.e. {$a->name})', VALUE_DEFAULT, array()
 149                          ))
 150                      )
 151                  )
 152              )
 153          );
 154      }
 155  
 156      /**
 157       * Return multiple call to core get_string()
 158       *
 159       * @param array $strings strings to translate
 160       * @return array
 161       *
 162       * @since Moodle 2.4
 163       */
 164      public static function get_strings($strings) {
 165          $params = self::validate_parameters(self::get_strings_parameters(),
 166                        array('strings'=>$strings));
 167          $stringmanager = get_string_manager();
 168  
 169          $translatedstrings = array();
 170          foreach($params['strings'] as $string) {
 171  
 172              if (!empty($string['lang'])) {
 173                  $lang = $string['lang'];
 174              } else {
 175                  $lang = current_language();
 176              }
 177  
 178              $translatedstrings[] = array(
 179                  'stringid' => $string['stringid'],
 180                  'component' => $string['component'],
 181                  'lang' => $lang,
 182                  'string' => $stringmanager->get_string($string['stringid'], $string['component'],
 183                      core_external::format_string_parameters($string['stringparams']), $lang));
 184          }
 185  
 186          return $translatedstrings;
 187      }
 188  
 189      /**
 190       * Returns description of get_string() result value
 191       *
 192       * @return array
 193       * @since Moodle 2.4
 194       */
 195      public static function get_strings_returns() {
 196          return new external_multiple_structure(
 197              new external_single_structure(array(
 198                  'stringid' => new external_value(PARAM_STRINGID, 'string id'),
 199                  'component' => new external_value(PARAM_COMPONENT, 'string component'),
 200                  'lang' => new external_value(PARAM_LANG, 'lang'),
 201                  'string' => new external_value(PARAM_RAW, 'translated string'))
 202              ));
 203      }
 204  
 205       /**
 206       * Returns description of get_component_strings parameters
 207       *
 208       * @return external_function_parameters
 209       * @since Moodle 2.4
 210       */
 211      public static function get_component_strings_parameters() {
 212          return new external_function_parameters(
 213              array('component' => new external_value(PARAM_COMPONENT, 'component'),
 214                    'lang' => new external_value(PARAM_LANG, 'lang', VALUE_DEFAULT, null),
 215              )
 216          );
 217      }
 218  
 219      /**
 220       * Return all lang strings of a component - call to core get_component_strings().
 221       *
 222       * @param string $component component name
 223       * @return array
 224       *
 225       * @since Moodle 2.4
 226       */
 227      public static function get_component_strings($component, $lang = null) {
 228  
 229          if (empty($lang)) {
 230              $lang = current_language();
 231          }
 232  
 233          $params = self::validate_parameters(self::get_component_strings_parameters(),
 234                        array('component'=>$component, 'lang' => $lang));
 235  
 236          $stringmanager = get_string_manager();
 237  
 238          $wsstrings = array();
 239          $componentstrings = $stringmanager->load_component_strings($params['component'], $params['lang']);
 240          foreach($componentstrings as $stringid => $string) {
 241              $wsstring = array();
 242              $wsstring['stringid'] = $stringid;
 243              $wsstring['string'] = $string;
 244              $wsstrings[] = $wsstring;
 245          }
 246  
 247          return $wsstrings;
 248      }
 249  
 250      /**
 251       * Returns description of get_component_strings() result value
 252       *
 253       * @return array
 254       * @since Moodle 2.4
 255       */
 256      public static function get_component_strings_returns() {
 257          return new external_multiple_structure(
 258              new external_single_structure(array(
 259                  'stringid' => new external_value(PARAM_STRINGID, 'string id'),
 260                  'string' => new external_value(PARAM_RAW, 'translated string'))
 261              ));
 262      }
 263  
 264      /**
 265       * Returns description of get_fragment parameters
 266       *
 267       * @return external_function_parameters
 268       * @since Moodle 3.1
 269       */
 270      public static function get_fragment_parameters() {
 271          return new external_function_parameters(
 272              array(
 273                  'component' => new external_value(PARAM_COMPONENT, 'Component for the callback e.g. mod_assign'),
 274                  'callback' => new external_value(PARAM_ALPHANUMEXT, 'Name of the callback to execute'),
 275                  'contextid' => new external_value(PARAM_INT, 'Context ID that the fragment is from'),
 276                  'args' => new external_multiple_structure(
 277                      new external_single_structure(
 278                          array(
 279                              'name' => new external_value(PARAM_ALPHANUMEXT, 'param name'),
 280                              'value' => new external_value(PARAM_RAW, 'param value')
 281                          )
 282                      ), 'args for the callback are optional', VALUE_OPTIONAL
 283                  )
 284              )
 285          );
 286      }
 287  
 288      /**
 289       * Get a HTML fragment for inserting into something. Initial use is for inserting mforms into
 290       * a page using AJAX.
 291       * This web service is designed to be called only via AJAX and not directly.
 292       * Callbacks that are called by this web service are responsible for doing the appropriate security checks
 293       * to access the information returned. This only does minimal validation on the context.
 294       *
 295       * @param string $component Name of the component.
 296       * @param string $callback Function callback name.
 297       * @param int $contextid Context ID this fragment is in.
 298       * @param array $args optional arguments for the callback.
 299       * @return array HTML and JavaScript fragments for insertion into stuff.
 300       * @since Moodle 3.1
 301       */
 302      public static function get_fragment($component, $callback, $contextid, $args = null) {
 303          global $OUTPUT, $PAGE;
 304  
 305          $params = self::validate_parameters(self::get_fragment_parameters(),
 306                  array(
 307                      'component' => $component,
 308                      'callback' => $callback,
 309                      'contextid' => $contextid,
 310                      'args' => $args
 311                  )
 312          );
 313  
 314          // Reformat arguments into something less unwieldy.
 315          $arguments = array();
 316          foreach ($params['args'] as $paramargument) {
 317              $arguments[$paramargument['name']] = $paramargument['value'];
 318          }
 319  
 320          $context = context::instance_by_id($contextid);
 321          self::validate_context($context);
 322          $arguments['context'] = $context;
 323  
 324          // Hack alert: Forcing bootstrap_renderer to initiate moodle page.
 325          $OUTPUT->header();
 326  
 327          // Overwriting page_requirements_manager with the fragment one so only JS included from
 328          // this point is returned to the user.
 329          $PAGE->start_collecting_javascript_requirements();
 330          $data = component_callback($params['component'], 'output_fragment_' . $params['callback'], array($arguments));
 331          $jsfooter = $PAGE->requires->get_end_code();
 332          $output = array('html' => $data, 'javascript' => $jsfooter);
 333          return $output;
 334      }
 335  
 336      /**
 337       * Returns description of get_fragment() result value
 338       *
 339       * @return array
 340       * @since Moodle 3.1
 341       */
 342      public static function get_fragment_returns() {
 343          return new external_single_structure(
 344              array(
 345                  'html' => new external_value(PARAM_RAW, 'HTML fragment.'),
 346                  'javascript' => new external_value(PARAM_RAW, 'JavaScript fragment')
 347              )
 348          );
 349      }
 350  
 351      /**
 352       * Parameters for function update_inplace_editable()
 353       *
 354       * @since Moodle 3.1
 355       * @return external_function_parameters
 356       */
 357      public static function update_inplace_editable_parameters() {
 358          return new external_function_parameters(
 359              array(
 360                  'component' => new external_value(PARAM_COMPONENT, 'component responsible for the update', VALUE_REQUIRED),
 361                  'itemtype' => new external_value(PARAM_NOTAGS, 'type of the updated item inside the component', VALUE_REQUIRED),
 362                  'itemid' => new external_value(PARAM_INT, 'identifier of the updated item', VALUE_REQUIRED),
 363                  'value' => new external_value(PARAM_RAW, 'new value', VALUE_REQUIRED),
 364              ));
 365      }
 366  
 367      /**
 368       * Update any component's editable value assuming that component implements necessary callback
 369       *
 370       * @since Moodle 3.1
 371       * @param string $component
 372       * @param string $itemtype
 373       * @param string $itemid
 374       * @param string $value
 375       */
 376      public static function update_inplace_editable($component, $itemtype, $itemid, $value) {
 377          global $PAGE;
 378          // Validate and normalize parameters.
 379          $params = self::validate_parameters(self::update_inplace_editable_parameters(),
 380                        array('component' => $component, 'itemtype' => $itemtype, 'itemid' => $itemid, 'value' => $value));
 381          if (!$functionname = component_callback_exists($component, 'inplace_editable')) {
 382              throw new \moodle_exception('inplaceeditableerror');
 383          }
 384          $tmpl = component_callback($params['component'], 'inplace_editable',
 385              array($params['itemtype'], $params['itemid'], $params['value']));
 386          if (!$tmpl || !($tmpl instanceof \core\output\inplace_editable)) {
 387              throw new \moodle_exception('inplaceeditableerror');
 388          }
 389          return $tmpl->export_for_template($PAGE->get_renderer('core'));
 390      }
 391  
 392      /**
 393       * Return structure for update_inplace_editable()
 394       *
 395       * @since Moodle 3.1
 396       * @return external_description
 397       */
 398      public static function update_inplace_editable_returns() {
 399          return new external_single_structure(
 400              array(
 401                  'displayvalue' => new external_value(PARAM_RAW, 'display value (may contain link or other html tags)'),
 402                  'component' => new external_value(PARAM_NOTAGS, 'component responsible for the update', VALUE_OPTIONAL),
 403                  'itemtype' => new external_value(PARAM_NOTAGS, 'itemtype', VALUE_OPTIONAL),
 404                  'value' => new external_value(PARAM_RAW, 'value of the item as it is stored', VALUE_OPTIONAL),
 405                  'itemid' => new external_value(PARAM_RAW, 'identifier of the updated item', VALUE_OPTIONAL),
 406                  'edithint' => new external_value(PARAM_NOTAGS, 'hint for editing element', VALUE_OPTIONAL),
 407                  'editlabel' => new external_value(PARAM_NOTAGS, 'label for editing element', VALUE_OPTIONAL),
 408                  'type' => new external_value(PARAM_ALPHA, 'type of the element (text, toggle, select)', VALUE_OPTIONAL),
 409                  'options' => new external_value(PARAM_RAW, 'options of the element, format depends on type', VALUE_OPTIONAL),
 410                  'linkeverything' => new external_value(PARAM_INT, 'Should everything be wrapped in the edit link or link displayed separately', VALUE_OPTIONAL),
 411              )
 412          );
 413      }
 414  
 415      /**
 416       * Returns description of fetch_notifications() parameters.
 417       *
 418       * @return external_function_parameters
 419       * @since Moodle 3.1
 420       */
 421      public static function fetch_notifications_parameters() {
 422          return new external_function_parameters(
 423              array(
 424                  'contextid' => new external_value(PARAM_INT, 'Context ID', VALUE_REQUIRED),
 425              ));
 426      }
 427  
 428      /**
 429       * Returns description of fetch_notifications() result value.
 430       *
 431       * @return external_description
 432       * @since Moodle 3.1
 433       */
 434      public static function fetch_notifications_returns() {
 435          return new external_multiple_structure(
 436              new external_single_structure(
 437                  array(
 438                      'template'      => new external_value(PARAM_RAW, 'Name of the template'),
 439                      'variables'     => new external_single_structure(array(
 440                          'message'       => new external_value(PARAM_RAW, 'HTML content of the Notification'),
 441                          'extraclasses'  => new external_value(PARAM_RAW, 'Extra classes to provide to the tmeplate'),
 442                          'announce'      => new external_value(PARAM_RAW, 'Whether to announce'),
 443                          'closebutton'   => new external_value(PARAM_RAW, 'Whether to close'),
 444                      )),
 445                  )
 446              )
 447          );
 448      }
 449  
 450      /**
 451       * Returns the list of notifications against the current session.
 452       *
 453       * @return array
 454       * @since Moodle 3.1
 455       */
 456      public static function fetch_notifications($contextid) {
 457          global $PAGE;
 458  
 459          self::validate_parameters(self::fetch_notifications_parameters(), [
 460                  'contextid' => $contextid,
 461              ]);
 462  
 463          $context = \context::instance_by_id($contextid);
 464          self::validate_context($context);
 465  
 466          return \core\notification::fetch_as_array($PAGE->get_renderer('core'));
 467      }
 468  }