Merge pull request #815 from alphagov/add-activewhen-callback-for-sma…

…llsurveys

Add activeWhen callback for small surveys and use for 9th/10th of August

app/assets/javascripts/surveys.js

@@ -13,6 +13,7 @@
                  '  </div>' +
                  '</section>';
 
+  /* This data structure is explained in `doc/surveys.md` */
   var userSurveys = {
     defaultSurvey: {
       url: 'https://www.surveymonkey.com/s/2MRDLTW',
@@ -22,18 +23,31 @@
     },
     smallSurveys: [
       {
-        url: 'https://www.surveymonkey.com/s/VQ5X2SL',
-        template: '<section id="user-satisfaction-survey" class="visible" aria-hidden="false">' +
-                  '  <div class="wrapper">' +
-                  '    <h1>Which three words describe how you feel about your visit to GOV.UK today?</h1>' +
-                  '    <p class="right"><a href="#survey-no-thanks" id="survey-no-thanks">No thanks</a></p>' +
-                  '    <p><a href="javascript:void()" id="take-survey" target="_blank">Take the 1 question survey</a> This will open a short survey on another website</p>' +
-                  '  </div>' +
-                  '</section>',
-        identifier: 'three_word_survey',
-        frequency: 50,
-        startTime: new Date("July 26, 2016").getTime(),
-        endTime: new Date("July 27, 2016 23:59:59").getTime()
+        url: 'https://www.surveymonkey.com/s/2MRDLTW',
+        identifier: 'user_satisfaction_survey',
+        template: TEMPLATE,
+        frequency: 10,
+        activeWhen: function() {
+          function breadcrumbMatches() {
+            var text = $('#global-breadcrumb').text() || "";
+            return (/Education/i.test(text) || /Schools/i.test(text) || /Childcare/i.test(text));
+          }
+
+          function sectionMatches() {
+            var sectionName = $('meta[name="govuk:section"]').attr('content');
+            return (sectionName === 'education and learning' || sectionName === 'childcare and parenting');
+          }
+
+          function organisationMatches() {
+            var orgMatchingExpr = /<D6>|<D106>|<D109>|<EA243>|<EA86>|<EA242>|<EA541>/;
+            var metaText = $('meta[name="govuk:analytics:organisations"]').attr('content') || "";
+            return orgMatchingExpr.test(metaText);
+          }
+
+          return (sectionMatches() || breadcrumbMatches() || organisationMatches());
+        },
+        startTime: new Date("August 9, 2016").getTime(),
+        endTime: new Date("August 10, 2016 23:59:59").getTime()
       }
     ],
 
@@ -49,7 +63,11 @@
 
       $.each(smallSurveys, function(_index, survey) {
         if(userSurveys.currentTime() >= survey.startTime && userSurveys.currentTime() <= survey.endTime) {
-          activeSurvey = survey;
+          if(typeof(survey.activeWhen) === 'function') {
+            if(survey.activeWhen()) { activeSurvey = survey; }
+          } else {
+            activeSurvey = survey;
+          }
         }
       });
 

doc/surveys.md

@@ -0,0 +1,62 @@
+# Running test surveys on GOV.UK
+
+Across GOV.UK, a "survey" will pop up for one in 50 visitors, asking them what they thought of GOV.UK. This is known as the "user satisfaction survey".
+
+Sometimes, a "small survey" or "test survey" needs to be run across GOV.UK for a short time to evaluate content changes or taxonomy changes.
+
+This can easily be done by adding an entry to `GOVUK.userSurveys.smallSurveys` in `app/assets/javascripts/surveys.js`.
+
+## Example
+
+```javascript
+{
+  url: 'https://www.surveymonkey.com/s/2AAAAAA/',
+  identifier: 'education_only_survey',
+  frequency: 50,
+  template: TEMPLATE,
+  activeWhen: function() {
+    function sectionMatches() {
+      return $('meta[property="govuk:section"]').attr('content') === 'education and learning';
+    }
+    function pageClassMatches() { return $('#page').hasClass('magic-content'); }
+
+    return (sectionMatches() || pageClassMatches());
+  },
+  startTime: new Date("July 25, 2016").getTime(),
+  endTime: new Date("August 3, 2016 23:59:50").getTime()
+}
+```
+
+## About the data structure
+
+### `url`
+This should link to a surveymonkey -- or other survey page -- that allows the visitor to take the survey.
+
+### `identifier`
+This is used both as the Google Analytics tag to record events against, and used (after being transformed to camelCase) to set a cookie so a visitor is not prompted to take the survey more than once.
+
+### `frequency`
+How frequently to show the survey. A frequency of `1` means the survey shows to every visitor. A frequency of `50` means the survey shows to 1 in 50 visitors.
+
+### `template`
+An HTML fragment representing the contents of the survey box. This **MUST** conform to the following minimum structure:
+
+```html
+<section id="user-satisfaction-survey" class="visible" aria-hidden="false">
+  <div class="wrapper">
+    <h1>Heading copy</h1>
+    <p class="right"><a href="#survey-no-thanks" id="survey-no-thanks">No thanks</a></p>
+    <p><a href="javascript:void()" id="take-survey" target="_blank">Link text</a> This will open a short survey on another website</p>
+  </div>
+</section>
+```
+
+### `activeWhen` - OPTIONAL
+A callback function returning true or false allowing further scoping of when the survey is considered "active".
+
+In the example above, the survey will only be considered "active" on pages with a section of "education and learning", and will not display on pages where this function evaluates to false.
+
+Not providing this argument has the same effect as setting it to `return true`. The survey will therefore apply to all pages on GOV.UK between `startTime` and `endTime`.
+
+### `startTime` and `endTime`
+The survey will only be considered "active" between these dates and times. Where an explicit time is not provided (e.g. startTime) note that JavaScript will assume 00:00:00.000 i.e. just after midnight.

spec/javascripts/surveys-spec.js

@@ -97,6 +97,7 @@ describe("Surveys", function() {
       spyOn(surveys, 'randomNumberMatches').and.returnValue(true);
       expect(surveys.isSurveyToBeDisplayed(defaultSurvey)).toBeTruthy();
     });
+
   });
 
   describe("userCompletedTransaction", function() {
@@ -196,5 +197,33 @@ describe("Surveys", function() {
       var activeSurvey = surveys.getActiveSurvey(defaultSurvey, smallSurveys);
       expect(activeSurvey).toBe(smallSurvey);
     });
+
+    describe("activeWhen function call", function() {
+      it("returns the test survey when the callback returns true", function() {
+        spyOn(surveys, 'currentTime').and.returnValue(new Date("July 9, 2016 10:00:00").getTime());
+        var testSurvey = {
+          startTime: new Date("July 5, 2016").getTime(),
+          endTime: new Date("July 10, 2016 23:50:00").getTime(),
+          activeWhen: function() { return true; },
+          url: 'example.com/small-survey'
+        };
+
+        var activeSurvey = surveys.getActiveSurvey(defaultSurvey, [testSurvey]);
+        expect(activeSurvey).toBe(testSurvey);
+      });
+
+      it("returns the default when the callback returns false", function() {
+        spyOn(surveys, 'currentTime').and.returnValue(new Date("July 9, 2016 10:00:00").getTime());
+        var testSurvey = {
+          startTime: new Date("July 5, 2016").getTime(),
+          endTime: new Date("July 10, 2016 23:50:00").getTime(),
+          activeWhen: function() { return false; },
+          url: 'example.com/small-survey'
+        };
+
+        var activeSurvey = surveys.getActiveSurvey(defaultSurvey, [testSurvey]);
+        expect(activeSurvey).toBe(defaultSurvey);
+      });
+    });
   });
 });