/admin/tool/usertours/classes/external/tour.php
PHP | 333 lines | 187 code | 38 blank | 108 comment | 5 complexity | 2eadd8708c49068b11956abdfd287f7c MD5 | raw file
- <?php
- // This file is part of Moodle - http://moodle.org/
- //
- // Moodle is free software: you can redistribute it and/or modify
- // it under the terms of the GNU General Public License as published by
- // the Free Software Foundation, either version 3 of the License, or
- // (at your option) any later version.
- //
- // Moodle is distributed in the hope that it will be useful,
- // but WITHOUT ANY WARRANTY; without even the implied warranty of
- // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
- // GNU General Public License for more details.
- //
- // You should have received a copy of the GNU General Public License
- // along with Moodle. If not, see <http://www.gnu.org/licenses/>.
- /**
- * Web Service functions for steps.
- *
- * @package tool_usertours
- * @copyright 2016 Andrew Nicols <andrew@nicols.co.uk>
- * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
- */
- namespace tool_usertours\external;
- defined('MOODLE_INTERNAL') || die();
- use external_api;
- use external_function_parameters;
- use external_single_structure;
- use external_multiple_structure;
- use external_value;
- use tool_usertours\tour as tourinstance;
- use tool_usertours\step;
- /**
- * Web Service functions for steps.
- *
- * @copyright 2016 Andrew Nicols <andrew@nicols.co.uk>
- * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
- */
- class tour extends external_api {
- /**
- * Fetch the tour configuration for the specified tour.
- *
- * @param int $tourid The ID of the tour to fetch.
- * @param int $context The Context ID of the current page.
- * @param string $pageurl The path of the current page.
- * @return array As described in fetch_and_start_tour_returns
- */
- public static function fetch_and_start_tour($tourid, $context, $pageurl) {
- global $PAGE;
- $params = self::validate_parameters(self::fetch_and_start_tour_parameters(), [
- 'tourid' => $tourid,
- 'context' => $context,
- 'pageurl' => $pageurl,
- ]);
- $context = \context_helper::instance_by_id($params['context']);
- self::validate_context($context);
- $tour = tourinstance::instance($params['tourid']);
- if (!$tour->should_show_for_user()) {
- return [];
- }
- $touroutput = new \tool_usertours\output\tour($tour);
- \tool_usertours\event\tour_started::create([
- 'contextid' => $context->id,
- 'objectid' => $tour->get_id(),
- 'other' => [
- 'pageurl' => $params['pageurl'],
- ],
- ])->trigger();
- return [
- 'tourconfig' => $touroutput->export_for_template($PAGE->get_renderer('core')),
- ];
- }
- /**
- * The parameters for fetch_and_start_tour.
- *
- * @return external_function_parameters
- */
- public static function fetch_and_start_tour_parameters() {
- return new external_function_parameters([
- 'tourid' => new external_value(PARAM_INT, 'Tour ID'),
- 'context' => new external_value(PARAM_INT, 'Context ID'),
- 'pageurl' => new external_value(PARAM_URL, 'Page URL'),
- ]);
- }
- /**
- * The return configuration for fetch_and_start_tour.
- *
- * @return external_single_structure
- */
- public static function fetch_and_start_tour_returns() {
- return new external_single_structure([
- 'tourconfig' => new external_single_structure([
- 'name' => new external_value(PARAM_RAW, 'Tour Name'),
- 'steps' => new external_multiple_structure(self::step_structure_returns()),
- 'endtourlabel' => new external_value(PARAM_RAW, 'Label of the end tour button'),
- 'displaystepnumbers' => new external_value(PARAM_BOOL, 'display step number'),
- ], 'Tour config', VALUE_OPTIONAL)
- ]);
- }
- /**
- * Reset the specified tour for the current user.
- *
- * @param int $tourid The ID of the tour.
- * @param int $context The Context ID of the current page.
- * @param string $pageurl The path of the current page requesting the reset.
- * @return array As described in reset_tour_returns
- */
- public static function reset_tour($tourid, $context, $pageurl) {
- $params = self::validate_parameters(self::reset_tour_parameters(), [
- 'tourid' => $tourid,
- 'context' => $context,
- 'pageurl' => $pageurl,
- ]);
- $context = \context_helper::instance_by_id($params['context']);
- self::validate_context($context);
- $tour = tourinstance::instance($params['tourid']);
- $tour->request_user_reset();
- $result = [];
- $matchingtours = \tool_usertours\manager::get_matching_tours(new \moodle_url($params['pageurl']));
- foreach ($matchingtours as $match) {
- if ($tour->get_id() === $match->get_id()) {
- $result['startTour'] = $tour->get_id();
- \tool_usertours\event\tour_reset::create([
- 'contextid' => $context->id,
- 'objectid' => $params['tourid'],
- 'other' => [
- 'pageurl' => $params['pageurl'],
- ],
- ])->trigger();
- break;
- }
- }
- return $result;
- }
- /**
- * The parameters for reset_tour.
- *
- * @return external_function_parameters
- */
- public static function reset_tour_parameters() {
- return new external_function_parameters([
- 'tourid' => new external_value(PARAM_INT, 'Tour ID'),
- 'context' => new external_value(PARAM_INT, 'Context ID'),
- 'pageurl' => new external_value(PARAM_URL, 'Current page location'),
- ]);
- }
- /**
- * The return configuration for reset_tour.
- *
- * @return external_single_structure
- */
- public static function reset_tour_returns() {
- return new external_single_structure([
- 'startTour' => new external_value(PARAM_INT, 'Tour ID', VALUE_OPTIONAL),
- ]);
- }
- /**
- * Mark the specified tour as completed for the current user.
- *
- * @param int $tourid The ID of the tour.
- * @param int $context The Context ID of the current page.
- * @param string $pageurl The path of the current page.
- * @param int $stepid The step id
- * @param int $stepindex The step index
- * @return array As described in complete_tour_returns
- */
- public static function complete_tour($tourid, $context, $pageurl, $stepid, $stepindex) {
- $params = self::validate_parameters(self::complete_tour_parameters(), [
- 'tourid' => $tourid,
- 'context' => $context,
- 'pageurl' => $pageurl,
- 'stepid' => $stepid,
- 'stepindex' => $stepindex,
- ]);
- $context = \context_helper::instance_by_id($params['context']);
- self::validate_context($context);
- $tour = tourinstance::instance($params['tourid']);
- $tour->mark_user_completed();
- \tool_usertours\event\tour_ended::create([
- 'contextid' => $context->id,
- 'objectid' => $params['tourid'],
- 'other' => [
- 'pageurl' => $params['pageurl'],
- 'stepid' => $params['stepid'],
- 'stepindex' => $params['stepindex'],
- ],
- ])->trigger();
- return [];
- }
- /**
- * The parameters for complete_tour.
- *
- * @return external_function_parameters
- */
- public static function complete_tour_parameters() {
- return new external_function_parameters([
- 'tourid' => new external_value(PARAM_INT, 'Tour ID'),
- 'context' => new external_value(PARAM_INT, 'Context ID'),
- 'pageurl' => new external_value(PARAM_LOCALURL, 'Page URL'),
- 'stepid' => new external_value(PARAM_INT, 'Step ID'),
- 'stepindex' => new external_value(PARAM_INT, 'Step Number'),
- ]);
- }
- /**
- * The return configuration for complete_tour.
- *
- * @return external_single_structure
- */
- public static function complete_tour_returns() {
- return new external_single_structure([]);
- }
- /**
- * Mark the specified toru step as shown for the current user.
- *
- * @param int $tourid The ID of the tour.
- * @param int $context The Context ID of the current page.
- * @param string $pageurl The path of the current page.
- * @param int $stepid The step id
- * @param int $stepindex The step index
- * @return array As described in complete_tour_returns
- */
- public static function step_shown($tourid, $context, $pageurl, $stepid, $stepindex) {
- $params = self::validate_parameters(self::step_shown_parameters(), [
- 'tourid' => $tourid,
- 'context' => $context,
- 'pageurl' => $pageurl,
- 'stepid' => $stepid,
- 'stepindex' => $stepindex,
- ]);
- $context = \context_helper::instance_by_id($params['context']);
- self::validate_context($context);
- $step = step::instance($params['stepid']);
- if ($step->get_tourid() != $params['tourid']) {
- throw new \moodle_exception('Incorrect tour specified.');
- }
- \tool_usertours\event\step_shown::create([
- 'contextid' => $context->id,
- 'objectid' => $params['stepid'],
- 'other' => [
- 'pageurl' => $params['pageurl'],
- 'tourid' => $params['tourid'],
- 'stepindex' => $params['stepindex'],
- ],
- ])->trigger();
- return [];
- }
- /**
- * The parameters for step_shown.
- *
- * @return external_function_parameters
- */
- public static function step_shown_parameters() {
- return new external_function_parameters([
- 'tourid' => new external_value(PARAM_INT, 'Tour ID'),
- 'context' => new external_value(PARAM_INT, 'Context ID'),
- 'pageurl' => new external_value(PARAM_URL, 'Page URL'),
- 'stepid' => new external_value(PARAM_INT, 'Step ID'),
- 'stepindex' => new external_value(PARAM_INT, 'Step Number'),
- ]);
- }
- /**
- * The return configuration for step_shown.
- *
- * @return external_single_structure
- */
- public static function step_shown_returns() {
- return new external_single_structure([]);
- }
- /**
- * The standard return structure for a step.
- *
- * @return external_multiple_structure
- */
- public static function step_structure_returns() {
- return new external_single_structure([
- 'title' => new external_value(PARAM_RAW,
- 'Step Title'),
- 'content' => new external_value(PARAM_RAW,
- 'Step Content'),
- 'element' => new external_value(PARAM_TEXT,
- 'Step Target'),
- 'placement' => new external_value(PARAM_TEXT,
- 'Step Placement'),
- 'delay' => new external_value(PARAM_INT,
- 'Delay before showing the step (ms)', VALUE_OPTIONAL),
- 'backdrop' => new external_value(PARAM_BOOL,
- 'Whether a backdrop should be used', VALUE_OPTIONAL),
- 'reflex' => new external_value(PARAM_BOOL,
- 'Whether to move to the next step when the target element is clicked', VALUE_OPTIONAL),
- 'orphan' => new external_value(PARAM_BOOL,
- 'Whether to display the step even if it could not be found', VALUE_OPTIONAL),
- 'stepid' => new external_value(PARAM_INT,
- 'The actual ID of the step', VALUE_OPTIONAL),
- ]);
- }
- }