Merge pull request #579 from alphagov/add-expand-collapse-to-send-guidance

On page load, hide the instructions for uploading a file

app/assets/javascripts/detailsPolyfill.js

@@ -0,0 +1,198 @@
+// From
+// https://github.com/alphagov/govuk_elements/blob/4926897dc7734db2fc5e5ebb6acdc97f86e22e50/public/javascripts/vendor/details.polyfill.js
+//
+// ---
+//
+// <details> polyfill
+// http://caniuse.com/#feat=details
+
+// FF Support for HTML5's <details> and <summary>
+// https://bugzilla.mozilla.org/show_bug.cgi?id=591737
+
+// http://www.sitepoint.com/fixing-the-details-element/
+
+(function () {
+  'use strict';
+
+  var NATIVE_DETAILS = typeof document.createElement('details').open === 'boolean';
+
+  // Add event construct for modern browsers or IE
+  // which fires the callback with a pre-converted target reference
+  function addEvent(node, type, callback) {
+    if (node.addEventListener) {
+      node.addEventListener(type, function (e) {
+        callback(e, e.target);
+      }, false);
+    } else if (node.attachEvent) {
+      node.attachEvent('on' + type, function (e) {
+        callback(e, e.srcElement);
+      });
+    }
+  }
+
+  // Handle cross-modal click events
+  function addClickEvent(node, callback) {
+    // Prevent space(32) from scrolling the page
+    addEvent(node, 'keypress', function (e, target) {
+      if (target.nodeName === 'SUMMARY') {
+        if (e.keyCode === 32) {
+          if (e.preventDefault) {
+            e.preventDefault();
+          } else {
+            e.returnValue = false;
+          }
+        }
+      }
+    });
+    // When the key comes up - check if it is enter(13) or space(32)
+    addEvent(node, 'keyup', function (e, target) {
+      if (e.keyCode === 13 || e.keyCode === 32) { callback(e, target); }
+    });
+    addEvent(node, 'mouseup', function (e, target) {
+      callback(e, target);
+    });
+  }
+
+  // Get the nearest ancestor element of a node that matches a given tag name
+  function getAncestor(node, match) {
+    do {
+      if (!node || node.nodeName.toLowerCase() === match) {
+        break;
+      }
+    } while ((node = node.parentNode));
+
+    return node;
+  }
+
+  // Create a started flag so we can prevent the initialisation
+  // function firing from both DOMContentLoaded and window.onload
+  var started = false;
+
+  // Initialisation function
+  function addDetailsPolyfill(list) {
+
+    // If this has already happened, just return
+    // else set the flag so it doesn't happen again
+    if (started) {
+      return;
+    }
+    started = true;
+
+    // Get the collection of details elements, but if that's empty
+    // then we don't need to bother with the rest of the scripting
+    if ((list = document.getElementsByTagName('details')).length === 0) {
+      return;
+    }
+
+    // else iterate through them to apply their initial state
+    var n = list.length, i = 0;
+    for (i; i < n; i++) {
+      var details = list[i];
+
+      // Save shortcuts to the inner summary and content elements
+      details.__summary = details.getElementsByTagName('summary').item(0);
+      details.__content = details.getElementsByTagName('div').item(0);
+
+      // If the content doesn't have an ID, assign it one now
+      // which we'll need for the summary's aria-controls assignment
+      if (!details.__content.id) {
+        details.__content.id = 'details-content-' + i;
+      }
+
+      // Add ARIA role="group" to details
+      details.setAttribute('role', 'group');
+
+      // Add role=button to summary
+      details.__summary.setAttribute('role', 'button');
+
+      // Add aria-controls
+      details.__summary.setAttribute('aria-controls', details.__content.id);
+
+      // Set tabIndex so the summary is keyboard accessible for non-native elements
+      // http://www.saliences.com/browserBugs/tabIndex.html
+      if (!NATIVE_DETAILS) {
+        details.__summary.tabIndex = 0;
+      }
+
+      // Detect initial open state
+      var openAttr = details.getAttribute('open') !== null;
+      if (openAttr === true) {
+        details.__summary.setAttribute('aria-expanded', 'true');
+        details.__content.setAttribute('aria-hidden', 'false');
+      } else {
+        details.__summary.setAttribute('aria-expanded', 'false');
+        details.__content.setAttribute('aria-hidden', 'true');
+        if (!NATIVE_DETAILS) {
+          details.__content.style.display = 'none';
+        }
+      }
+
+      // Create a circular reference from the summary back to its
+      // parent details element, for convenience in the click handler
+      details.__summary.__details = details;
+
+      // If this is not a native implementation, create an arrow
+      // inside the summary
+      if (!NATIVE_DETAILS) {
+
+        var twisty = document.createElement('i');
+
+        if (openAttr === true) {
+          twisty.className = 'arrow arrow-open';
+          twisty.appendChild(document.createTextNode('\u25bc'));
+        } else {
+          twisty.className = 'arrow arrow-closed';
+          twisty.appendChild(document.createTextNode('\u25ba'));
+        }
+
+        details.__summary.__twisty = details.__summary.insertBefore(twisty, details.__summary.firstChild);
+        details.__summary.__twisty.setAttribute('aria-hidden', 'true');
+
+      }
+    }
+
+    // Define a statechange function that updates aria-expanded and style.display
+    // Also update the arrow position
+    function statechange(summary) {
+
+      var expanded = summary.__details.__summary.getAttribute('aria-expanded') === 'true';
+      var hidden = summary.__details.__content.getAttribute('aria-hidden') === 'true';
+
+      summary.__details.__summary.setAttribute('aria-expanded', (expanded ? 'false' : 'true'));
+      summary.__details.__content.setAttribute('aria-hidden', (hidden ? 'false' : 'true'));
+
+      if (!NATIVE_DETAILS) {
+        summary.__details.__content.style.display = (expanded ? 'none' : '');
+
+        var hasOpenAttr = summary.__details.getAttribute('open') !== null;
+        if (!hasOpenAttr) {
+          summary.__details.setAttribute('open', 'open');
+        } else {
+          summary.__details.removeAttribute('open');
+        }
+      }
+
+      if (summary.__twisty) {
+        summary.__twisty.firstChild.nodeValue = (expanded ? '\u25ba' : '\u25bc');
+        summary.__twisty.setAttribute('class', (expanded ? 'arrow arrow-closed' : 'arrow arrow-open'));
+      }
+
+      return true;
+    }
+
+    // Bind a click event to handle summary elements
+    addClickEvent(document, function(e, summary) {
+      if (!(summary = getAncestor(summary, 'summary'))) {
+        return true;
+      }
+      return statechange(summary);
+    });
+  }
+
+  // Bind two load events for modern and older browsers
+  // If the first one fires it will set a flag to block the second one
+  // but if it's not supported then the second one will fire
+  addEvent(document, 'DOMContentLoaded', addDetailsPolyfill);
+  addEvent(window, 'load', addDetailsPolyfill);
+
+})();

app/assets/stylesheets/app.scss

@@ -61,11 +61,11 @@ a {
   }
 
   > .grid-row  {
-    
+
     .heading-large {
       margin-top: $gutter;
     }
-    
+
   }
 
 }
@@ -104,7 +104,7 @@ td {
 #footer {
 
   .footer-categories {
-    
+
     @extend %site-width-container;
 
     &-wrapper {
@@ -148,3 +148,8 @@ a[rel='external'] {
   }
 
 }
+
+details summary {
+  text-decoration: underline;
+  margin-bottom: $gutter-half;
+}

app/templates/views/send.html

@@ -35,44 +35,52 @@
   <div class="page-footer bottom-gutter">
     {{file_upload(
       form.file,
-      button_text='Upload a .csv file',
+      button_text='Upload a file of recipients',
       alternate_link=url_for(".send_test", service_id=current_service.id, template_id=template.id),
       alternate_link_text='send yourself a test'
     )}}
   </div>
 
-  <h2 class="heading-medium" style="margin: 45px 0 15px 0">
-    Example file
-  </h2>
+  <details role="group">
+    <summary role="button" aria-controls="how-to-format-your-file" aria-expanded="false">
+      <span class="summary">How to format your file</span>
+    </summary>
 
-  {% call(item, row_number) list_table(
-    example,
-    caption="Example",
-    caption_visible=False,
-    field_headings=['1'] + [
-      '<span class="placeholder">{}</span>'.format(recipient_column)|safe
-    ] + template.placeholders_as_markup|list
-  ) %}
-    {{ index_field(row_number) }}
-    {% for column in item %}
-      {{ text_field(column) }}
-    {% endfor %}
-  {% endcall %}
+    <div id="how-to-format-your-file" aria-hidden="true">
+      <ul class="list list-bullet">
+        <li>
+          put one recipient per row
+        </li>
+        <li>
+          save or export your data as a
+          <acronym title="Comma Separated Values">CSV</acronym>,
+          <acronym title="Comma Separated Values">TSV</acronym>,
+          Open Document Spreadsheet (.ods)
+          or Microsoft Excel (.xls, .xlsx, .xlsm) file
+        </li>
+      </ul>
 
-  <p class="table-show-more-link">
-    <a href="{{ url_for('.get_example_csv', service_id=current_service.id, template_id=template.id) }}">Download this example</a>
-  </p>
+      <h2 class="heading-small">
+        Example file
+      </h2>
 
-  <h2 class="heading-medium">
-    Formatting
-  </h2>
-  <ul class="list list-bullet">
-    <li>
-      put one recipient per row
-    </li>
-    <li>
-      save or export your data as a .csv (comma separated values) file
-    </li>
-  </ul>
+      {% call(item, row_number) list_table(
+        example,
+        caption="Example",
+        caption_visible=False,
+        field_headings=['1'] + [
+          '<span class="placeholder">{}</span>'.format(recipient_column)|safe
+        ] + template.placeholders_as_markup|list
+      ) %}
+        {{ index_field(row_number) }}
+        {% for column in item %}
+          {{ text_field(column) }}
+        {% endfor %}
+      {% endcall %}
+      <p class="table-show-more-link">
+        <a href="{{ url_for('.get_example_csv', service_id=current_service.id, template_id=template.id) }}">Download this example</a>
+      </p>
+    </div>
+  </details>
 
 {% endblock %}

gulpfile.babel.js

@@ -53,6 +53,7 @@ gulp.task('javascripts', () => gulp
   .src([
     paths.toolkit + 'javascripts/govuk/modules.js',
     paths.toolkit + 'javascripts/govuk/selection-buttons.js',
+    paths.src + 'javascripts/detailsPolyfill.js',
     paths.src + 'javascripts/apiKey.js',
     paths.src + 'javascripts/autofocus.js',
     paths.src + 'javascripts/highlightTags.js',