[Summary view]

Differences Between: [Versions 310 and 401] [Versions 311 and 401] [Versions 39 and 401] [Versions 401 and 402] [Versions 401 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   * Web Service functions for steps.
  19   *
  20   * @package    tool_usertours
  21   * @copyright  2016 Andrew Nicols <andrew@nicols.co.uk>
  22   * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  23   */
  24  
  25  namespace tool_usertours\external;
  26  
  27  defined('MOODLE_INTERNAL') || die();
  28  
  29  use external_api;
  30  use external_function_parameters;
  31  use external_single_structure;
  32  use external_multiple_structure;
  33  use external_value;
  34  use tool_usertours\tour as tourinstance;
  35  use tool_usertours\step;
  36  
  37  /**
  38   * Web Service functions for steps.
  39   *
  40   * @copyright  2016 Andrew Nicols <andrew@nicols.co.uk>
  41   * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  42   */
  43  class tour extends external_api {
  44      /**
  45       * Fetch the tour configuration for the specified tour.
  46       *
  47       * @param   int     $tourid     The ID of the tour to fetch.
  48       * @param   int     $context    The Context ID of the current page.
  49       * @param   string  $pageurl    The path of the current page.
  50       * @return  array               As described in fetch_and_start_tour_returns
  51       */
  52      public static function fetch_and_start_tour($tourid, $context, $pageurl) {
  53          global $PAGE;
  54  
  55          $params = self::validate_parameters(self::fetch_and_start_tour_parameters(), [
  56                  'tourid'    => $tourid,
  57                  'context'   => $context,
  58                  'pageurl'   => $pageurl,
  59              ]);
  60  
  61          $context = \context_helper::instance_by_id($params['context']);
  62          self::validate_context($context);
  63  
  64          $tour = tourinstance::instance($params['tourid']);
  65          if (!$tour->should_show_for_user()) {
  66              return [];
  67          }
  68  
  69          $touroutput = new \tool_usertours\output\tour($tour);
  70  
  71          \tool_usertours\event\tour_started::create([
  72              'contextid' => $context->id,
  73              'objectid'  => $tour->get_id(),
  74              'other'     => [
  75                  'pageurl' => $params['pageurl'],
  76              ],
  77          ])->trigger();
  78  
  79          return [
  80              'tourconfig' => $touroutput->export_for_template($PAGE->get_renderer('core')),
  81          ];
  82      }
  83  
  84      /**
  85       * The parameters for fetch_and_start_tour.
  86       *
  87       * @return external_function_parameters
  88       */
  89      public static function fetch_and_start_tour_parameters() {
  90          return new external_function_parameters([
  91              'tourid'    => new external_value(PARAM_INT, 'Tour ID'),
  92              'context'   => new external_value(PARAM_INT, 'Context ID'),
  93              'pageurl'   => new external_value(PARAM_URL, 'Page URL'),
  94          ]);
  95      }
  96  
  97      /**
  98       * The return configuration for fetch_and_start_tour.
  99       *
 100       * @return external_single_structure
 101       */
 102      public static function fetch_and_start_tour_returns() {
 103          return new external_single_structure([
 104              'tourconfig'        => new external_single_structure([
 105                  'name'          => new external_value(PARAM_RAW, 'Tour Name'),
 106                  'steps'         => new external_multiple_structure(self::step_structure_returns()),
 107                  'endtourlabel'  => new external_value(PARAM_RAW, 'Label of the end tour button'),
 108                  'displaystepnumbers' => new external_value(PARAM_BOOL, 'display step number'),
 109              ], 'Tour config', VALUE_OPTIONAL)
 110          ]);
 111      }
 112  
 113      /**
 114       * Reset the specified tour for the current user.
 115       *
 116       * @param   int     $tourid     The ID of the tour.
 117       * @param   int     $context    The Context ID of the current page.
 118       * @param   string  $pageurl    The path of the current page requesting the reset.
 119       * @return  array               As described in reset_tour_returns
 120       */
 121      public static function reset_tour($tourid, $context, $pageurl) {
 122          $params = self::validate_parameters(self::reset_tour_parameters(), [
 123                  'tourid'    => $tourid,
 124                  'context'   => $context,
 125                  'pageurl'   => $pageurl,
 126              ]);
 127  
 128          $context = \context_helper::instance_by_id($params['context']);
 129          self::validate_context($context);
 130  
 131          $tour = tourinstance::instance($params['tourid']);
 132          $tour->request_user_reset();
 133  
 134          $result = [];
 135  
 136          $matchingtours = \tool_usertours\manager::get_matching_tours(new \moodle_url($params['pageurl']));
 137          foreach ($matchingtours as $match) {
 138              if ($tour->get_id() === $match->get_id()) {
 139                  $result['startTour'] = $tour->get_id();
 140  
 141                  \tool_usertours\event\tour_reset::create([
 142                      'contextid' => $context->id,
 143                      'objectid'  => $params['tourid'],
 144                      'other'     => [
 145                          'pageurl'   => $params['pageurl'],
 146                      ],
 147                  ])->trigger();
 148                  break;
 149              }
 150          }
 151  
 152          return $result;
 153      }
 154  
 155      /**
 156       * The parameters for reset_tour.
 157       *
 158       * @return external_function_parameters
 159       */
 160      public static function reset_tour_parameters() {
 161          return new external_function_parameters([
 162              'tourid'    => new external_value(PARAM_INT, 'Tour ID'),
 163              'context'   => new external_value(PARAM_INT, 'Context ID'),
 164              'pageurl'   => new external_value(PARAM_URL, 'Current page location'),
 165          ]);
 166      }
 167  
 168      /**
 169       * The return configuration for reset_tour.
 170       *
 171       * @return external_single_structure
 172       */
 173      public static function reset_tour_returns() {
 174          return new external_single_structure([
 175              'startTour'     => new external_value(PARAM_INT, 'Tour ID', VALUE_OPTIONAL),
 176          ]);
 177      }
 178  
 179      /**
 180       * Mark the specified tour as completed for the current user.
 181       *
 182       * @param   int     $tourid     The ID of the tour.
 183       * @param   int     $context    The Context ID of the current page.
 184       * @param   string  $pageurl    The path of the current page.
 185       * @param   int     $stepid     The step id
 186       * @param   int     $stepindex  The step index
 187       * @return  array               As described in complete_tour_returns
 188       */
 189      public static function complete_tour($tourid, $context, $pageurl, $stepid, $stepindex) {
 190          $params = self::validate_parameters(self::complete_tour_parameters(), [
 191                  'tourid'    => $tourid,
 192                  'context'   => $context,
 193                  'pageurl'   => $pageurl,
 194                  'stepid'    => $stepid,
 195                  'stepindex' => $stepindex,
 196              ]);
 197  
 198          $context = \context_helper::instance_by_id($params['context']);
 199          self::validate_context($context);
 200  
 201          $tour = tourinstance::instance($params['tourid']);
 202          $tour->mark_user_completed();
 203  
 204          \tool_usertours\event\tour_ended::create([
 205              'contextid' => $context->id,
 206              'objectid'  => $params['tourid'],
 207              'other'     => [
 208                  'pageurl'   => $params['pageurl'],
 209                  'stepid'    => $params['stepid'],
 210                  'stepindex' => $params['stepindex'],
 211              ],
 212          ])->trigger();
 213  
 214          return [];
 215      }
 216  
 217      /**
 218       * The parameters for complete_tour.
 219       *
 220       * @return external_function_parameters
 221       */
 222      public static function complete_tour_parameters() {
 223          return new external_function_parameters([
 224              'tourid'    => new external_value(PARAM_INT, 'Tour ID'),
 225              'context'   => new external_value(PARAM_INT, 'Context ID'),
 226              'pageurl'   => new external_value(PARAM_LOCALURL, 'Page URL'),
 227              'stepid'    => new external_value(PARAM_INT, 'Step ID'),
 228              'stepindex' => new external_value(PARAM_INT, 'Step Number'),
 229          ]);
 230      }
 231  
 232      /**
 233       * The return configuration for complete_tour.
 234       *
 235       * @return external_single_structure
 236       */
 237      public static function complete_tour_returns() {
 238          return new external_single_structure([]);
 239      }
 240  
 241      /**
 242       * Mark the specified toru step as shown for the current user.
 243       *
 244       * @param   int     $tourid     The ID of the tour.
 245       * @param   int     $context    The Context ID of the current page.
 246       * @param   string  $pageurl    The path of the current page.
 247       * @param   int     $stepid     The step id
 248       * @param   int     $stepindex  The step index
 249       * @return  array               As described in complete_tour_returns
 250       */
 251      public static function step_shown($tourid, $context, $pageurl, $stepid, $stepindex) {
 252          $params = self::validate_parameters(self::step_shown_parameters(), [
 253                  'tourid'    => $tourid,
 254                  'context'   => $context,
 255                  'pageurl'   => $pageurl,
 256                  'stepid'    => $stepid,
 257                  'stepindex' => $stepindex,
 258              ]);
 259  
 260          $context = \context_helper::instance_by_id($params['context']);
 261          self::validate_context($context);
 262  
 263          $step = step::instance($params['stepid']);
 264          if ($step->get_tourid() != $params['tourid']) {
 265              throw new \moodle_exception('Incorrect tour specified.');
 266          }
 267  
 268          \tool_usertours\event\step_shown::create([
 269              'contextid' => $context->id,
 270              'objectid'  => $params['stepid'],
 271  
 272              'other'     => [
 273                  'pageurl'   => $params['pageurl'],
 274                  'tourid'    => $params['tourid'],
 275                  'stepindex' => $params['stepindex'],
 276              ],
 277          ])->trigger();
 278  
 279          return [];
 280      }
 281  
 282      /**
 283       * The parameters for step_shown.
 284       *
 285       * @return external_function_parameters
 286       */
 287      public static function step_shown_parameters() {
 288          return new external_function_parameters([
 289              'tourid'    => new external_value(PARAM_INT, 'Tour ID'),
 290              'context'   => new external_value(PARAM_INT, 'Context ID'),
 291              'pageurl'   => new external_value(PARAM_URL, 'Page URL'),
 292              'stepid'    => new external_value(PARAM_INT, 'Step ID'),
 293              'stepindex' => new external_value(PARAM_INT, 'Step Number'),
 294          ]);
 295      }
 296  
 297      /**
 298       * The return configuration for step_shown.
 299       *
 300       * @return external_single_structure
 301       */
 302      public static function step_shown_returns() {
 303          return new external_single_structure([]);
 304      }
 305  
 306      /**
 307       * The standard return structure for a step.
 308       *
 309       * @return external_multiple_structure
 310       */
 311      public static function step_structure_returns() {
 312          return new external_single_structure([
 313              'title'             => new external_value(PARAM_RAW,
 314                      'Step Title'),
 315              'content'           => new external_value(PARAM_RAW,
 316                      'Step Content'),
 317              'element'           => new external_value(PARAM_TEXT,
 318                      'Step Target'),
 319              'placement'         => new external_value(PARAM_TEXT,
 320                      'Step Placement'),
 321              'delay'             => new external_value(PARAM_INT,
 322                      'Delay before showing the step (ms)', VALUE_OPTIONAL),
 323              'backdrop'          => new external_value(PARAM_BOOL,
 324                      'Whether a backdrop should be used', VALUE_OPTIONAL),
 325              'reflex'            => new external_value(PARAM_BOOL,
 326                      'Whether to move to the next step when the target element is clicked', VALUE_OPTIONAL),
 327              'orphan'            => new external_value(PARAM_BOOL,
 328                      'Whether to display the step even if it could not be found', VALUE_OPTIONAL),
 329              'stepid'            => new external_value(PARAM_INT,
 330                      'The actual ID of the step', VALUE_OPTIONAL),
 331          ]);
 332      }
 333  }