Merge pull request #1187 from alphagov/add-tracking-details-component

Allow tracking of the details component

CHANGELOG.md

@@ -7,6 +7,10 @@
   useful summary for people upgrading their application, not a replication
   of the commit log.
 
+## Unreleased
+
+* Allow tracking on the details component ([PR #1187](https://github.com/alphagov/govuk_publishing_components/pull/1187))
+
 ## 21.9.0
 
 * Fix string merge in summary-list component ([PR #1188](https://github.com/alphagov/govuk_publishing_components/pull/1188))

app/assets/javascripts/govuk_publishing_components/components/details.js

@@ -0,0 +1,48 @@
+/* eslint-env jquery */
+// = require govuk/components/details/details.js
+window.GOVUK = window.GOVUK || {}
+window.GOVUK.Modules = window.GOVUK.Modules || {};
+
+(function (Modules) {
+  'use strict'
+
+  Modules.GovukDetails = function () {
+    this.start = function (element) {
+      var customTrackLabel = element[0].getAttribute('data-track-label')
+
+      // If a custom label has been provided, we can simply call the tracking module
+      if (customTrackLabel) {
+        var trackDetails = new window.GOVUK.Modules.TrackClick()
+        trackDetails.start(element)
+      } else {
+        // If no custom label is set, we use the open/close status as the label
+        var detailsComponent = element[0]
+        var detailsClick = detailsComponent.querySelector('[data-details-track-click]')
+        var that = this
+
+        $(detailsClick).click(function (e) {
+          that.trackDefault(detailsComponent)
+        })
+      }
+    }
+
+    this.trackDefault = function (element) {
+      if (window.GOVUK.analytics && window.GOVUK.analytics.trackEvent) {
+        var componentStatus = (element.getAttribute('open') == null) ? 'open' : 'closed'
+        var trackCategory = element.getAttribute('data-track-category')
+        var trackAction = element.getAttribute('data-track-action')
+        var trackOptions = element.getAttribute('data-track-options')
+
+        if (typeof trackOptions !== 'object' || trackOptions === null) {
+          trackOptions = {}
+        }
+
+        trackOptions['label'] = componentStatus
+
+        if (trackAction && trackCategory) {
+          window.GOVUK.analytics.trackEvent(trackCategory, trackAction, trackOptions)
+        }
+      }
+    }
+  }
+})(window.GOVUK.Modules)

app/views/govuk_publishing_components/components/_details.html.erb

@@ -10,7 +10,7 @@
   data_attributes[:module] = 'govuk-details'
 %>
 <%= tag.details class: css_classes, data: data_attributes, open: open do %>
-  <summary class="govuk-details__summary">
+  <summary class="govuk-details__summary" data-details-track-click>
     <span class="govuk-details__summary-text">
       <%= title %>
     </span>

app/views/govuk_publishing_components/components/docs/details.yml

@@ -22,6 +22,18 @@ examples:
       block: |
         We need to know your nationality so we can work out which elections you’re entitled to vote in. If you can’t provide your nationality, you’ll have to send copies of identity documents through the post.
   with_data_attributes:
+    description: Can be used for tracking. By default, `track-label` is set to the status ("open" or "closed") unless a track_label is passed into the component.
+    data:
+      title: Help with nationality
+      data_attributes:
+        track_category: "checker-qa"
+        track_action: "business-question"
+        track_label: "custom label here"
+        track_options:
+          dimension20: "custom dimension"
+      block: |
+        We need to know your nationality so we can work out which elections you’re entitled to vote in. If you can’t provide your nationality, you’ll have to send copies of identity documents through the post.
+  with_GTM_tracking:
     data:
       title: Help with nationality
       data_attributes:

spec/components/details_spec.rb

@@ -32,6 +32,21 @@ def component_name
     assert_select '.govuk-details.govuk-\!-margin-bottom-0'
   end
 
+  it "applies data attributes when provided" do
+    render_component(
+      title: "Some title",
+      data_attributes: {
+        track_category: "track-category",
+        track_action: "track-action",
+        track_label: "track-label"
+      }
+    )
+
+    assert_select '.govuk-details[data-track-category="track-category"]'
+    assert_select '.govuk-details[data-track-action="track-action"]'
+    assert_select '.govuk-details[data-track-label="track-label"]'
+  end
+
   it "defaults to the initial bottom margin if an incorrect value is passed" do
     render_component(
       title: "Some title",

spec/javascripts/components/details-spec.js

@@ -0,0 +1,79 @@
+/* eslint-env jasmine, jquery */
+/* global GOVUK */
+
+describe('Details component', function () {
+  var FIXTURE
+
+  GOVUK.analytics = {
+    trackEvent: function () {}
+  }
+
+  var callback = jasmine.createSpy()
+  GOVUK.Modules.TrackClick = function () {
+    this.start = function () {
+      callback()
+    }
+  }
+
+  function loadDetailsComponent () {
+    var details = new GOVUK.Modules.GovukDetails()
+    details.start($('.gem-c-details'))
+  }
+
+  beforeEach(function () {
+    spyOn(GOVUK.analytics, 'trackEvent')
+
+    FIXTURE =
+      '<details class="gem-c-details govuk-details govuk-!-margin-bottom-3" data-track-category="track-category" data-track-action="track-action" data-track-label="track-label" data-module="govuk-details">' +
+        '<summary class="govuk-details__summary" data-details-track-click="">' +
+        '<span>Toggle text</span>' +
+        '</summary>' +
+      '</details>'
+
+    window.setFixtures(FIXTURE)
+  })
+
+  afterEach(function () {
+    GOVUK.analytics.trackEvent.calls.reset()
+  })
+
+  it('uses built in tracking module when provided with a track-label', function () {
+    loadDetailsComponent()
+
+    $('.govuk-details__summary').click()
+
+    expect(GOVUK.analytics.trackEvent.calls.count()).toEqual(0)
+    expect(callback).toHaveBeenCalled()
+  })
+
+  it('does not fire an event if track category and track action are not present', function () {
+    $('.gem-c-details').attr('data-track-action', null)
+    $('.gem-c-details').attr('data-track-category', null)
+    $('.gem-c-details').attr('data-track-label', null)
+
+    loadDetailsComponent()
+
+    $('.govuk-details__summary').click()
+
+    expect(GOVUK.analytics.trackEvent.calls.count()).toEqual(0)
+  })
+
+  it('tracks open state by default if no track label provided', function () {
+    $('.gem-c-details').attr('data-track-label', null)
+    loadDetailsComponent()
+
+    $('.govuk-details__summary').click()
+
+    expect(GOVUK.analytics.trackEvent).toHaveBeenCalledWith('track-category', 'track-action', { label: 'open' })
+  })
+
+  it('tracks closed state by default if no track label provided', function () {
+    $('.gem-c-details').attr('data-track-label', null)
+    $('.gem-c-details').attr('open', true)
+    loadDetailsComponent()
+
+    $('.govuk-details__summary').click()
+
+    expect(GOVUK.analytics.trackEvent).toHaveBeenCalledWith('track-category', 'track-action', { label: 'closed' })
+  })
+})