www.aleph1.co.uk Git - yaffs-website/blob - web/core/modules/tour/js/tour.es6.js

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