Search moodle.org's
Developer Documentation

  • Bug fixes for general core bugs in 3.11.x will end 14 Nov 2022 (12 months plus 6 months extension).
  • Bug fixes for security issues in 3.11.x will end 13 Nov 2023 (18 months plus 12 months extension).
  • PHP version: minimum PHP 7.3.0 Note: minimum PHP version has increased since Moodle 3.10. PHP 7.4.x is supported too.
  • Differences Between: [Versions 311 and 400] [Versions 37 and 311] [Versions 38 and 311] [Versions 39 and 311]

       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              ], 'Tour config', VALUE_OPTIONAL)
     108          ]);
     109      }
     110  
     111      /**
     112       * Reset the specified tour for the current user.
     113       *
     114       * @param   int     $tourid     The ID of the tour.
     115       * @param   int     $context    The Context ID of the current page.
     116       * @param   string  $pageurl    The path of the current page requesting the reset.
     117       * @return  array               As described in reset_tour_returns
     118       */
     119      public static function reset_tour($tourid, $context, $pageurl) {
     120          $params = self::validate_parameters(self::reset_tour_parameters(), [
     121                  'tourid'    => $tourid,
     122                  'context'   => $context,
     123                  'pageurl'   => $pageurl,
     124              ]);
     125  
     126          $context = \context_helper::instance_by_id($params['context']);
     127          self::validate_context($context);
     128  
     129          $tour = tourinstance::instance($params['tourid']);
     130          $tour->request_user_reset();
     131  
     132          $result = [];
     133  
     134          $matchingtours = \tool_usertours\manager::get_matching_tours(new \moodle_url($params['pageurl']));
     135          foreach ($matchingtours as $match) {
     136              if ($tour->get_id() === $match->get_id()) {
     137                  $result['startTour'] = $tour->get_id();
     138  
     139                  \tool_usertours\event\tour_reset::create([
     140                      'contextid' => $context->id,
     141                      'objectid'  => $params['tourid'],
     142                      'other'     => [
     143                          'pageurl'   => $params['pageurl'],
     144                      ],
     145                  ])->trigger();
     146                  break;
     147              }
     148          }
     149  
     150          return $result;
     151      }
     152  
     153      /**
     154       * The parameters for reset_tour.
     155       *
     156       * @return external_function_parameters
     157       */
     158      public static function reset_tour_parameters() {
     159          return new external_function_parameters([
     160              'tourid'    => new external_value(PARAM_INT, 'Tour ID'),
     161              'context'   => new external_value(PARAM_INT, 'Context ID'),
     162              'pageurl'   => new external_value(PARAM_URL, 'Current page location'),
     163          ]);
     164      }
     165  
     166      /**
     167       * The return configuration for reset_tour.
     168       *
     169       * @return external_single_structure
     170       */
     171      public static function reset_tour_returns() {
     172          return new external_single_structure([
     173              'startTour'     => new external_value(PARAM_INT, 'Tour ID', VALUE_OPTIONAL),
     174          ]);
     175      }
     176  
     177      /**
     178       * Mark the specified tour as completed for the current user.
     179       *
     180       * @param   int     $tourid     The ID of the tour.
     181       * @param   int     $context    The Context ID of the current page.
     182       * @param   string  $pageurl    The path of the current page.
     183       * @param   int     $stepid     The step id
     184       * @param   int     $stepindex  The step index
     185       * @return  array               As described in complete_tour_returns
     186       */
     187      public static function complete_tour($tourid, $context, $pageurl, $stepid, $stepindex) {
     188          $params = self::validate_parameters(self::complete_tour_parameters(), [
     189                  'tourid'    => $tourid,
     190                  'context'   => $context,
     191                  'pageurl'   => $pageurl,
     192                  'stepid'    => $stepid,
     193                  'stepindex' => $stepindex,
     194              ]);
     195  
     196          $context = \context_helper::instance_by_id($params['context']);
     197          self::validate_context($context);
     198  
     199          $tour = tourinstance::instance($params['tourid']);
     200          $tour->mark_user_completed();
     201  
     202          \tool_usertours\event\tour_ended::create([
     203              'contextid' => $context->id,
     204              'objectid'  => $params['tourid'],
     205              'other'     => [
     206                  'pageurl'   => $params['pageurl'],
     207                  'stepid'    => $params['stepid'],
     208                  'stepindex' => $params['stepindex'],
     209              ],
     210          ])->trigger();
     211  
     212          return [];
     213      }
     214  
     215      /**
     216       * The parameters for complete_tour.
     217       *
     218       * @return external_function_parameters
     219       */
     220      public static function complete_tour_parameters() {
     221          return new external_function_parameters([
     222              'tourid'    => new external_value(PARAM_INT, 'Tour ID'),
     223              'context'   => new external_value(PARAM_INT, 'Context ID'),
     224              'pageurl'   => new external_value(PARAM_LOCALURL, 'Page URL'),
     225              'stepid'    => new external_value(PARAM_INT, 'Step ID'),
     226              'stepindex' => new external_value(PARAM_INT, 'Step Number'),
     227          ]);
     228      }
     229  
     230      /**
     231       * The return configuration for complete_tour.
     232       *
     233       * @return external_single_structure
     234       */
     235      public static function complete_tour_returns() {
     236          return new external_single_structure([]);
     237      }
     238  
     239      /**
     240       * Mark the specified toru step as shown for the current user.
     241       *
     242       * @param   int     $tourid     The ID of the tour.
     243       * @param   int     $context    The Context ID of the current page.
     244       * @param   string  $pageurl    The path of the current page.
     245       * @param   int     $stepid     The step id
     246       * @param   int     $stepindex  The step index
     247       * @return  array               As described in complete_tour_returns
     248       */
     249      public static function step_shown($tourid, $context, $pageurl, $stepid, $stepindex) {
     250          $params = self::validate_parameters(self::step_shown_parameters(), [
     251                  'tourid'    => $tourid,
     252                  'context'   => $context,
     253                  'pageurl'   => $pageurl,
     254                  'stepid'    => $stepid,
     255                  'stepindex' => $stepindex,
     256              ]);
     257  
     258          $context = \context_helper::instance_by_id($params['context']);
     259          self::validate_context($context);
     260  
     261          $step = step::instance($params['stepid']);
     262          if ($step->get_tourid() != $params['tourid']) {
     263              throw new \moodle_exception('Incorrect tour specified.');
     264          }
     265  
     266          \tool_usertours\event\step_shown::create([
     267              'contextid' => $context->id,
     268              'objectid'  => $params['stepid'],
     269  
     270              'other'     => [
     271                  'pageurl'   => $params['pageurl'],
     272                  'tourid'    => $params['tourid'],
     273                  'stepindex' => $params['stepindex'],
     274              ],
     275          ])->trigger();
     276  
     277          return [];
     278      }
     279  
     280      /**
     281       * The parameters for step_shown.
     282       *
     283       * @return external_function_parameters
     284       */
     285      public static function step_shown_parameters() {
     286          return new external_function_parameters([
     287              'tourid'    => new external_value(PARAM_INT, 'Tour ID'),
     288              'context'   => new external_value(PARAM_INT, 'Context ID'),
     289              'pageurl'   => new external_value(PARAM_URL, 'Page URL'),
     290              'stepid'    => new external_value(PARAM_INT, 'Step ID'),
     291              'stepindex' => new external_value(PARAM_INT, 'Step Number'),
     292          ]);
     293      }
     294  
     295      /**
     296       * The return configuration for step_shown.
     297       *
     298       * @return external_single_structure
     299       */
     300      public static function step_shown_returns() {
     301          return new external_single_structure([]);
     302      }
     303  
     304      /**
     305       * The standard return structure for a step.
     306       *
     307       * @return external_multiple_structure
     308       */
     309      public static function step_structure_returns() {
     310          return new external_single_structure([
     311              'title'             => new external_value(PARAM_RAW,
     312                      'Step Title'),
     313              'content'           => new external_value(PARAM_RAW,
     314                      'Step Content'),
     315              'element'           => new external_value(PARAM_TEXT,
     316                      'Step Target'),
     317              'placement'         => new external_value(PARAM_TEXT,
     318                      'Step Placement'),
     319              'delay'             => new external_value(PARAM_INT,
     320                      'Delay before showing the step (ms)', VALUE_OPTIONAL),
     321              'backdrop'          => new external_value(PARAM_BOOL,
     322                      'Whether a backdrop should be used', VALUE_OPTIONAL),
     323              'reflex'            => new external_value(PARAM_BOOL,
     324                      'Whether to move to the next step when the target element is clicked', VALUE_OPTIONAL),
     325              'orphan'            => new external_value(PARAM_BOOL,
     326                      'Whether to display the step even if it could not be found', VALUE_OPTIONAL),
     327              'stepid'            => new external_value(PARAM_INT,
     328                      'The actual ID of the step', VALUE_OPTIONAL),
     329          ]);
     330      }
     331  }