Proyectos de Subversion Moodle

Rev

| Ultima modificación | Ver Log |

Rev Autor Línea Nro. Línea
1 efrain 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
 
193
        $tour->mark_user_completed();
194
 
195
        \tool_usertours\event\tour_ended::create([
196
            'contextid' => $context->id,
197
            'objectid' => $params['tourid'],
198
            'other' => [
199
                'pageurl' => $params['pageurl'],
200
                'stepid' => $params['stepid'],
201
                'stepindex' => $params['stepindex'],
202
            ],
203
        ])->trigger();
204
 
205
        return [];
206
    }
207
 
208
    /**
209
     * The parameters for complete_tour.
210
     *
211
     * @return external_function_parameters
212
     */
213
    public static function complete_tour_parameters() {
214
        return new external_function_parameters([
215
            'tourid' => new external_value(PARAM_INT, 'Tour ID'),
216
            'context' => new external_value(PARAM_INT, 'Context ID'),
217
            'pageurl' => new external_value(PARAM_LOCALURL, 'Page URL'),
218
            'stepid' => new external_value(PARAM_INT, 'Step ID'),
219
            'stepindex' => new external_value(PARAM_INT, 'Step Number'),
220
        ]);
221
    }
222
 
223
    /**
224
     * The return configuration for complete_tour.
225
     *
226
     * @return external_single_structure
227
     */
228
    public static function complete_tour_returns() {
229
        return new external_single_structure([]);
230
    }
231
 
232
    /**
233
     * Mark the specified toru step as shown for the current user.
234
     *
235
     * @param   int     $tourid     The ID of the tour.
236
     * @param   int     $context    The Context ID of the current page.
237
     * @param   string  $pageurl    The path of the current page.
238
     * @param   int     $stepid     The step id
239
     * @param   int     $stepindex  The step index
240
     * @return  array               As described in complete_tour_returns
241
     */
242
    public static function step_shown($tourid, $context, $pageurl, $stepid, $stepindex) {
243
        $params = self::validate_parameters(self::step_shown_parameters(), [
244
            'tourid' => $tourid,
245
            'context' => $context,
246
            'pageurl' => $pageurl,
247
            'stepid' => $stepid,
248
            'stepindex' => $stepindex,
249
        ]);
250
 
251
        $context = \context_helper::instance_by_id($params['context']);
252
        self::validate_context($context);
253
 
254
        $step = step::instance($params['stepid']);
255
        if ($step->get_tourid() != $params['tourid']) {
256
            throw new \moodle_exception('Incorrect tour specified.');
257
        }
258
 
259
        \tool_usertours\event\step_shown::create([
260
            'contextid' => $context->id,
261
            'objectid' => $params['stepid'],
262
 
263
            'other' => [
264
                'pageurl' => $params['pageurl'],
265
                'tourid' => $params['tourid'],
266
                'stepindex' => $params['stepindex'],
267
            ],
268
        ])->trigger();
269
 
270
        return [];
271
    }
272
 
273
    /**
274
     * The parameters for step_shown.
275
     *
276
     * @return external_function_parameters
277
     */
278
    public static function step_shown_parameters() {
279
        return new external_function_parameters([
280
            'tourid' => new external_value(PARAM_INT, 'Tour ID'),
281
            'context' => new external_value(PARAM_INT, 'Context ID'),
282
            'pageurl' => new external_value(PARAM_URL, 'Page URL'),
283
            'stepid' => new external_value(PARAM_INT, 'Step ID'),
284
            'stepindex' => new external_value(PARAM_INT, 'Step Number'),
285
        ]);
286
    }
287
 
288
    /**
289
     * The return configuration for step_shown.
290
     *
291
     * @return external_single_structure
292
     */
293
    public static function step_shown_returns() {
294
        return new external_single_structure([]);
295
    }
296
 
297
    /**
298
     * The standard return structure for a step.
299
     *
300
     * @return external_multiple_structure
301
     */
302
    public static function step_structure_returns() {
303
        return new external_single_structure([
304
            'title' => new external_value(
305
                PARAM_RAW,
306
                'Step Title'
307
            ),
308
            'content' => new external_value(
309
                PARAM_RAW,
310
                'Step Content'
311
            ),
312
            'element' => new external_value(
313
                PARAM_TEXT,
314
                'Step Target'
315
            ),
316
            'placement' => new external_value(
317
                PARAM_TEXT,
318
                'Step Placement'
319
            ),
320
            'delay' => new external_value(
321
                PARAM_INT,
322
                'Delay before showing the step (ms)',
323
                VALUE_OPTIONAL
324
            ),
325
            'backdrop' => new external_value(
326
                PARAM_BOOL,
327
                'Whether a backdrop should be used',
328
                VALUE_OPTIONAL
329
            ),
330
            'reflex' => new external_value(
331
                PARAM_BOOL,
332
                'Whether to move to the next step when the target element is clicked',
333
                VALUE_OPTIONAL
334
            ),
335
            'orphan' => new external_value(
336
                PARAM_BOOL,
337
                'Whether to display the step even if it could not be found',
338
                VALUE_OPTIONAL
339
            ),
340
            'stepid' => new external_value(
341
                PARAM_INT,
342
                'The actual ID of the step',
343
                VALUE_OPTIONAL
344
            ),
345
        ]);
346
    }
347
}