Automatically generated installer lang files
[moodle.git] / admin / tool / usertours / amd / src / usertours.js
1 /**
2  * User tour control library.
3  *
4  * @module     tool_usertours/usertours
5  * @class      usertours
6  * @package    tool_usertours
7  * @copyright  2016 Andrew Nicols <andrew@nicols.co.uk>
8  */
9 define(
10 ['core/ajax', 'tool_usertours/tour', 'jquery', 'core/templates', 'core/str', 'core/log', 'core/notification'],
11 function(ajax, BootstrapTour, $, templates, str, log, notification) {
12     var usertours = {
13         tourId: null,
15         currentTour: null,
17         context: null,
19         /**
20          * Initialise the user tour for the current page.
21          *
22          * @method  init
23          * @param   {Number}    tourId      The ID of the tour to start.
24          * @param   {Bool}      startTour   Attempt to start the tour now.
25          * @param   {Number}    context     The context of the current page.
26          */
27         init: function(tourId, startTour, context) {
28             // Only one tour per page is allowed.
29             usertours.tourId = tourId;
31             usertours.context = context;
33             if (typeof startTour === 'undefined') {
34                 startTour = true;
35             }
37             if (startTour) {
38                 // Fetch the tour configuration.
39                 usertours.fetchTour(tourId);
40             }
42             usertours.addResetLink();
43             // Watch for the reset link.
44             $('body').on('click', '[data-action="tool_usertours/resetpagetour"]', function(e) {
45                 e.preventDefault();
46                 usertours.resetTourState(usertours.tourId);
47             });
48         },
50         /**
51          * Fetch the configuration specified tour, and start the tour when it has been fetched.
52          *
53          * @method  fetchTour
54          * @param   {Number}    tourId      The ID of the tour to start.
55          */
56         fetchTour: function(tourId) {
57             $.when(
58                 ajax.call([
59                     {
60                         methodname: 'tool_usertours_fetch_and_start_tour',
61                         args: {
62                             tourid:     tourId,
63                             context:    usertours.context,
64                             pageurl:    window.location.href,
65                         }
66                     }
67                 ])[0],
68                 templates.render('tool_usertours/tourstep', {})
69             ).then(function(response, template) {
70                 usertours.startBootstrapTour(tourId, template[0], response.tourconfig);
71                 return;
72             }).fail(notification.exception);
73         },
75         /**
76          * Add a reset link to the page.
77          *
78          * @method  addResetLink
79          */
80         addResetLink: function() {
81             var ele;
82             // Append the link to the most suitable place on the page
83             // with fallback to legacy selectors and finally the body
84             // if there is no better place.
85             if ($('.tool_usertours-resettourcontainer').length) {
86                 ele = $('.tool_usertours-resettourcontainer');
87             } else if ($('.logininfo').length) {
88                 ele = $('.logininfo');
89             } else if ($('footer').length) {
90                 ele = $('footer');
91             } else {
92                 ele = $('body');
93             }
94             templates.render('tool_usertours/resettour', {})
95                 .done(function(html, js) {
96                     templates.appendNodeContents(ele, html, js);
97                 });
98         },
100         /**
101          * Start the specified tour.
102          *
103          * @method  startBootstrapTour
104          * @param   {Number}    tourId      The ID of the tour to start.
105          * @param   {String}    template    The template to use.
106          * @param   {Object}    tourConfig  The tour configuration.
107          */
108         startBootstrapTour: function(tourId, template, tourConfig) {
109             if (usertours.currentTour) {
110                 // End the current tour, but disable end tour handler.
111                 tourConfig.onEnd = null;
112                 usertours.currentTour.endTour();
113                 delete usertours.currentTour;
114             }
116             // Normalize for the new library.
117             tourConfig.eventHandlers = {
118                 afterEnd: [usertours.markTourComplete],
119                 afterRender: [usertours.markStepShown],
120             };
122             // Sort out the tour name.
123             tourConfig.tourName = tourConfig.name;
124             delete tourConfig.name;
126             // Add the template to the configuration.
127             // This enables translations of the buttons.
128             tourConfig.template = template;
130             tourConfig.steps = tourConfig.steps.map(function(step) {
131                 if (typeof step.element !== 'undefined') {
132                     step.target = step.element;
133                     delete step.element;
134                 }
136                 if (typeof step.reflex !== 'undefined') {
137                     step.moveOnClick = !!step.reflex;
138                     delete step.reflex;
139                 }
141                 if (typeof step.content !== 'undefined') {
142                     step.body = step.content;
143                     delete step.content;
144                 }
146                 return step;
147             });
149             usertours.currentTour = new BootstrapTour(tourConfig);
150             usertours.currentTour.startTour();
151         },
153         /**
154          * Mark the specified step as being shownd by the user.
155          *
156          * @method  markStepShown
157          */
158         markStepShown: function() {
159             var stepConfig = this.getStepConfig(this.getCurrentStepNumber());
160             $.when(
161                 ajax.call([
162                     {
163                         methodname: 'tool_usertours_step_shown',
164                         args: {
165                             tourid:     usertours.tourId,
166                             context:    usertours.context,
167                             pageurl:    window.location.href,
168                             stepid:     stepConfig.stepid,
169                             stepindex:  this.getCurrentStepNumber(),
170                         }
171                     }
172                 ])[0]
173             ).fail(log.error);
174         },
176         /**
177          * Mark the specified tour as being completed by the user.
178          *
179          * @method  markTourComplete
180          */
181         markTourComplete: function() {
182             var stepConfig = this.getStepConfig(this.getCurrentStepNumber());
183             $.when(
184                 ajax.call([
185                     {
186                         methodname: 'tool_usertours_complete_tour',
187                         args: {
188                             tourid:     usertours.tourId,
189                             context:    usertours.context,
190                             pageurl:    window.location.href,
191                             stepid:     stepConfig.stepid,
192                             stepindex:  this.getCurrentStepNumber(),
193                         }
194                     }
195                 ])[0]
196             ).fail(log.error);
197         },
199         /**
200          * Reset the state, and restart the the tour on the current page.
201          *
202          * @method  resetTourState
203          * @param   {Number}    tourId      The ID of the tour to start.
204          */
205         resetTourState: function(tourId) {
206             $.when(
207                 ajax.call([
208                     {
209                         methodname: 'tool_usertours_reset_tour',
210                         args: {
211                             tourid:     tourId,
212                             context:    usertours.context,
213                             pageurl:    window.location.href,
214                         }
215                     }
216                 ])[0]
217             ).then(function(response) {
218                 if (response.startTour) {
219                     usertours.fetchTour(response.startTour);
220                 }
221                 return;
222             }).fail(notification.exception);
223         }
224     };
226     return /** @alias module:tool_usertours/usertours */ {
227         /**
228          * Initialise the user tour for the current page.
229          *
230          * @method  init
231          * @param   {Number}    tourId      The ID of the tour to start.
232          * @param   {Bool}      startTour   Attempt to start the tour now.
233          */
234         init: usertours.init,
236         /**
237          * Reset the state, and restart the the tour on the current page.
238          *
239          * @method  resetTourState
240          * @param   {Number}    tourId      The ID of the tour to restart.
241          */
242         resetTourState: usertours.resetTourState
243     };
244 });