lib/external/externallib.php

   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_TEXT,'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_TEXT, '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_TEXT, '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_TEXT, '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
 323         // Hack alert: Forcing bootstrap_renderer to initiate moodle page.
 324         $OUTPUT->header();
 325
 326         // Overwriting page_requirements_manager with the fragment one so only JS included from
 327         // this point is returned to the user.
 328         $PAGE->start_collecting_javascript_requirements();
 329         $data = component_callback($params['component'], 'output_fragment_' . $params['callback'], $arguments);
 330         $jsfooter = $PAGE->requires->get_end_code();
 331         $output = array('html' => $data, 'javascript' => $jsfooter);
 332         return $output;
 333     }
 334
 335     /**
 336      * Returns description of get_fragment() result value
 337      *
 338      * @return array
 339      * @since Moodle 3.1
 340      */
 341     public static function get_fragment_returns() {
 342         return new external_single_structure(
 343             array(
 344                 'html' => new external_value(PARAM_RAW, 'HTML fragment.'),
 345                 'javascript' => new external_value(PARAM_RAW, 'JavaScript fragment')
 346             )
 347         );
 348     }
 349
 350     /**
 351      * Parameters for function update_inplace_editable()
 352      *
 353      * @since Moodle 3.1
 354      * @return external_function_parameters
 355      */
 356     public static function update_inplace_editable_parameters() {
 357         return new external_function_parameters(
 358             array(
 359                 'component' => new external_value(PARAM_COMPONENT, 'component responsible for the update', VALUE_REQUIRED),
 360                 'itemtype' => new external_value(PARAM_NOTAGS, 'type of the updated item inside the component', VALUE_REQUIRED),
 361                 'itemid' => new external_value(PARAM_INT, 'identifier of the updated item', VALUE_REQUIRED),
 362                 'value' => new external_value(PARAM_RAW, 'new value', VALUE_REQUIRED),
 363             ));
 364     }
 365
 366     /**
 367      * Update any component's editable value assuming that component implements necessary callback
 368      *
 369      * @since Moodle 3.1
 370      * @param string $component
 371      * @param string $itemtype
 372      * @param string $itemid
 373      * @param string $value
 374      */
 375     public static function update_inplace_editable($component, $itemtype, $itemid, $value) {
 376         global $PAGE;
 377         // Validate and normalize parameters.
 378         $params = self::validate_parameters(self::update_inplace_editable_parameters(),
 379                       array('component' => $component, 'itemtype' => $itemtype, 'itemid' => $itemid, 'value' => $value));
 380         if (!$functionname = component_callback_exists($component, 'inplace_editable')) {
 381             throw new \moodle_exception('inplaceeditableerror');
 382         }
 383         $tmpl = component_callback($params['component'], 'inplace_editable',
 384             array($params['itemtype'], $params['itemid'], $params['value']));
 385         if (!$tmpl || !($tmpl instanceof \core\output\inplace_editable)) {
 386             throw new \moodle_exception('inplaceeditableerror');
 387         }
 388         return $tmpl->export_for_template($PAGE->get_renderer('core'));
 389     }
 390
 391     /**
 392      * Return structure for update_inplace_editable()
 393      *
 394      * @since Moodle 3.1
 395      * @return external_description
 396      */
 397     public static function update_inplace_editable_returns() {
 398         return new external_single_structure(
 399             array(
 400                 'displayvalue' => new external_value(PARAM_RAW, 'display value (may contain link or other html tags)'),
 401                 'component' => new external_value(PARAM_NOTAGS, 'component responsible for the update', VALUE_OPTIONAL),
 402                 'itemtype' => new external_value(PARAM_NOTAGS, 'itemtype', VALUE_OPTIONAL),
 403                 'value' => new external_value(PARAM_RAW, 'value of the item as it is stored', VALUE_OPTIONAL),
 404                 'itemid' => new external_value(PARAM_RAW, 'identifier of the updated item', VALUE_OPTIONAL),
 405                 'edithint' => new external_value(PARAM_NOTAGS, 'hint for editing element', VALUE_OPTIONAL),
 406                 'editlabel' => new external_value(PARAM_NOTAGS, 'label for editing element', VALUE_OPTIONAL),
 407             )
 408         );
 409     }
 410 }