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