tour.es6.js 7.8 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278
  1. /**
  2. * @file
  3. * Attaches behaviors for the Tour module's toolbar tab.
  4. */
  5. (function($, Backbone, Drupal, document) {
  6. const queryString = decodeURI(window.location.search);
  7. /**
  8. * Attaches the tour's toolbar tab behavior.
  9. *
  10. * It uses the query string for:
  11. * - tour: When ?tour=1 is present, the tour will start automatically after
  12. * the page has loaded.
  13. * - tips: Pass ?tips=class in the url to filter the available tips to the
  14. * subset which match the given class.
  15. *
  16. * @example
  17. * http://example.com/foo?tour=1&tips=bar
  18. *
  19. * @type {Drupal~behavior}
  20. *
  21. * @prop {Drupal~behaviorAttach} attach
  22. * Attach tour functionality on `tour` events.
  23. */
  24. Drupal.behaviors.tour = {
  25. attach(context) {
  26. $('body')
  27. .once('tour')
  28. .each(() => {
  29. const model = new Drupal.tour.models.StateModel();
  30. new Drupal.tour.views.ToggleTourView({
  31. el: $(context).find('#toolbar-tab-tour'),
  32. model,
  33. });
  34. model
  35. // Allow other scripts to respond to tour events.
  36. .on('change:isActive', (model, isActive) => {
  37. $(document).trigger(
  38. isActive ? 'drupalTourStarted' : 'drupalTourStopped',
  39. );
  40. })
  41. // Initialization: check whether a tour is available on the current
  42. // page.
  43. .set('tour', $(context).find('ol#tour'));
  44. // Start the tour immediately if toggled via query string.
  45. if (/tour=?/i.test(queryString)) {
  46. model.set('isActive', true);
  47. }
  48. });
  49. },
  50. };
  51. /**
  52. * @namespace
  53. */
  54. Drupal.tour = Drupal.tour || {
  55. /**
  56. * @namespace Drupal.tour.models
  57. */
  58. models: {},
  59. /**
  60. * @namespace Drupal.tour.views
  61. */
  62. views: {},
  63. };
  64. /**
  65. * Backbone Model for tours.
  66. *
  67. * @constructor
  68. *
  69. * @augments Backbone.Model
  70. */
  71. Drupal.tour.models.StateModel = Backbone.Model.extend(
  72. /** @lends Drupal.tour.models.StateModel# */ {
  73. /**
  74. * @type {object}
  75. */
  76. defaults: /** @lends Drupal.tour.models.StateModel# */ {
  77. /**
  78. * Indicates whether the Drupal root window has a tour.
  79. *
  80. * @type {Array}
  81. */
  82. tour: [],
  83. /**
  84. * Indicates whether the tour is currently running.
  85. *
  86. * @type {bool}
  87. */
  88. isActive: false,
  89. /**
  90. * Indicates which tour is the active one (necessary to cleanly stop).
  91. *
  92. * @type {Array}
  93. */
  94. activeTour: [],
  95. },
  96. },
  97. );
  98. Drupal.tour.views.ToggleTourView = Backbone.View.extend(
  99. /** @lends Drupal.tour.views.ToggleTourView# */ {
  100. /**
  101. * @type {object}
  102. */
  103. events: { click: 'onClick' },
  104. /**
  105. * Handles edit mode toggle interactions.
  106. *
  107. * @constructs
  108. *
  109. * @augments Backbone.View
  110. */
  111. initialize() {
  112. this.listenTo(this.model, 'change:tour change:isActive', this.render);
  113. this.listenTo(this.model, 'change:isActive', this.toggleTour);
  114. },
  115. /**
  116. * {@inheritdoc}
  117. *
  118. * @return {Drupal.tour.views.ToggleTourView}
  119. * The `ToggleTourView` view.
  120. */
  121. render() {
  122. // Render the visibility.
  123. this.$el.toggleClass('hidden', this._getTour().length === 0);
  124. // Render the state.
  125. const isActive = this.model.get('isActive');
  126. this.$el
  127. .find('button')
  128. .toggleClass('is-active', isActive)
  129. .prop('aria-pressed', isActive);
  130. return this;
  131. },
  132. /**
  133. * Model change handler; starts or stops the tour.
  134. */
  135. toggleTour() {
  136. if (this.model.get('isActive')) {
  137. const $tour = this._getTour();
  138. this._removeIrrelevantTourItems($tour, this._getDocument());
  139. const that = this;
  140. const close = Drupal.t('Close');
  141. if ($tour.find('li').length) {
  142. $tour.joyride({
  143. autoStart: true,
  144. postRideCallback() {
  145. that.model.set('isActive', false);
  146. },
  147. // HTML segments for tip layout.
  148. template: {
  149. link: `<a href="#close" class="joyride-close-tip" aria-label="${close}">&times;</a>`,
  150. button:
  151. '<a href="#" class="button button--primary joyride-next-tip"></a>',
  152. },
  153. });
  154. this.model.set({ isActive: true, activeTour: $tour });
  155. }
  156. } else {
  157. this.model.get('activeTour').joyride('destroy');
  158. this.model.set({ isActive: false, activeTour: [] });
  159. }
  160. },
  161. /**
  162. * Toolbar tab click event handler; toggles isActive.
  163. *
  164. * @param {jQuery.Event} event
  165. * The click event.
  166. */
  167. onClick(event) {
  168. this.model.set('isActive', !this.model.get('isActive'));
  169. event.preventDefault();
  170. event.stopPropagation();
  171. },
  172. /**
  173. * Gets the tour.
  174. *
  175. * @return {jQuery}
  176. * A jQuery element pointing to a `<ol>` containing tour items.
  177. */
  178. _getTour() {
  179. return this.model.get('tour');
  180. },
  181. /**
  182. * Gets the relevant document as a jQuery element.
  183. *
  184. * @return {jQuery}
  185. * A jQuery element pointing to the document within which a tour would be
  186. * started given the current state.
  187. */
  188. _getDocument() {
  189. return $(document);
  190. },
  191. /**
  192. * Removes tour items for elements that don't have matching page elements.
  193. *
  194. * Or that are explicitly filtered out via the 'tips' query string.
  195. *
  196. * @example
  197. * <caption>This will filter out tips that do not have a matching
  198. * page element or don't have the "bar" class.</caption>
  199. * http://example.com/foo?tips=bar
  200. *
  201. * @param {jQuery} $tour
  202. * A jQuery element pointing to a `<ol>` containing tour items.
  203. * @param {jQuery} $document
  204. * A jQuery element pointing to the document within which the elements
  205. * should be sought.
  206. *
  207. * @see Drupal.tour.views.ToggleTourView#_getDocument
  208. */
  209. _removeIrrelevantTourItems($tour, $document) {
  210. let removals = false;
  211. const tips = /tips=([^&]+)/.exec(queryString);
  212. $tour.find('li').each(function() {
  213. const $this = $(this);
  214. const itemId = $this.attr('data-id');
  215. const itemClass = $this.attr('data-class');
  216. // If the query parameter 'tips' is set, remove all tips that don't
  217. // have the matching class.
  218. if (tips && !$(this).hasClass(tips[1])) {
  219. removals = true;
  220. $this.remove();
  221. return;
  222. }
  223. // Remove tip from the DOM if there is no corresponding page element.
  224. if (
  225. (!itemId && !itemClass) ||
  226. (itemId && $document.find(`#${itemId}`).length) ||
  227. (itemClass && $document.find(`.${itemClass}`).length)
  228. ) {
  229. return;
  230. }
  231. removals = true;
  232. $this.remove();
  233. });
  234. // If there were removals, we'll have to do some clean-up.
  235. if (removals) {
  236. const total = $tour.find('li').length;
  237. if (!total) {
  238. this.model.set({ tour: [] });
  239. }
  240. $tour
  241. .find('li')
  242. // Rebuild the progress data.
  243. .each(function(index) {
  244. const progress = Drupal.t('!tour_item of !total', {
  245. '!tour_item': index + 1,
  246. '!total': total,
  247. });
  248. $(this)
  249. .find('.tour-progress')
  250. .text(progress);
  251. })
  252. // Update the last item to have "End tour" as the button.
  253. .eq(-1)
  254. .attr('data-text', Drupal.t('End tour'));
  255. }
  256. },
  257. },
  258. );
  259. })(jQuery, Backbone, Drupal, document);