@dwp/govuk-casa 8.7.12 → 8.9.0

package/views/casa/components/radios/README.md

@@ -13,45 +13,66 @@ Custom parameters:
 Basic example:
 
 ```nunjucks
-{% from "casa/components/radios/macro.njk" import casaGovukRadios with context %}
+{% from 'casa/components/radios/macro.njk' import casaGovukRadios with context %}
 
 {{ casaGovukRadios({
-  name: 'myInput',
-  casaValue: formData.myInput,
+  name: 'preference',
+  casaValue: formData.preference,
   casaErrors: formErrors,
-  items: [{
-    text: 'Yes',
-    value: 'yes'
-  }, {
-    text: 'No',
-    value: 'no'
-  }]
+  fieldset: {
+    legend: {
+      text: 'Choose your preference',
+      isPageHeading: true,
+      classes: 'govuk-fieldset__legend--xl'
+    }
+  },
+  hint: {
+    text: 'Some instructive hints'
+  },
+  items: [
+    {
+      value: 'twoReeds',
+      text: 'Two Reeds'
+    }, {
+      value: 'twistedFlax',
+      text: 'Twisted Flax'
+    }, {
+      value: 'water',
+      text: 'Water'
+    }, {
+      value: 'eyeOfHorus',
+      text: 'Eye of Horus'
+    }
+  ]
 }) }}
 ```
 
 If you want one of the radio items to toggle the display of an element:
 
 ```nunjucks
-{% from "casa/components/radios/macro.njk" import casaGovukRadios with context %}
+{% from 'casa/components/radios/macro.njk' import casaGovukRadios with context %}
 
 {% set panel %}
-  This panel will remain hidden until the "Yes" radio button is chosen
+  This panel will remain hidden until the 'Yes' radio button is chosen
 {% endset %}
 
 {{ casaGovukRadios({
-  name: 'myInput',
-  casaValue: formData.myInput,
+  name: 'preference',
+  casaValue: formData.preference,
   casaErrors: formErrors,
-  items: [{
-    text: 'Yes',
-    value: 'yes',
-    conditional: {
-      html: panel
+  items: [
+    {
+      value: 'yes',
+      text: 'Yes',
+      conditional: {
+        html: panel
+      }
+    },
+    {
+      value: 'no',
+      text: 'No'
     }
-  }, {
-    text: 'No',
-    value: 'no'
-  }]
+  ]
 }) }}
 ```
 
@@ -61,13 +82,17 @@ ref: <https://design-system.service.gov.uk/components/error-summary/>
 
 The error summary link must set focus on the first radio in the group. Unless you have specified an explicit `id` for the first item in the list, this macro will explicitly set that `id` to `f-<name>`, e.g. `f-preferences` in order for links from the error summary to work as expected.
 
-## Google Tag Manager
+## Google Analytics
 
 The following attributes will be attached to each `<input>` option if `casaWithAnalytics` is `true`:
 
 * `data-ga-question`: Holds the fieldset legend's content
 * `data-ga-answer`: Holds the specific answer's text/html value
 
+The following attributes will be attached to the error `<p>` tag if `casaWithAnalytics` is `true`:
+
+* `data-ga-question`: Holds the fieldset legend's content after removing all html tags
+
 These are the conventions used by DWP.
 
 > **IMPORTANT:** DO NOT ENABLE this option if the question or answer may contain personally-identifiable information as values will be pushed to Google

package/views/casa/components/radios/template.njk

@@ -1,4 +1,4 @@
-{% from "govuk/components/radios/macro.njk" import govukRadios %}
+{% from 'govuk/components/radios/macro.njk' import govukRadios %}
 
 {% set fieldErrors = params.casaErrors[params.name] %}
 
@@ -10,7 +10,7 @@
   }) %}
 {% endif %}
 
-{# Add checked flag to chosen input #}
+{# Add checked flag to chosen item #}
 {% set mergedItems = [] %}
 {% for item in params.items %}
   {% set item = mergeObjects({
@@ -30,7 +30,10 @@
   attributes: mergedAttributes,
   items: mergedItems,
   errorMessage: {
-    text: t(params.casaErrors[params.name][0].inline, params.casaErrors[params.name][0].variables)
+    text: t(params.casaErrors[params.name][0].inline, params.casaErrors[params.name][0].variables),
+    attributes: {
+      'data-ga-question': params.fieldset.legend.text or params.fieldset.legend.html | striptags
+    } if params.casaWithAnalytics else {}
   } if params.casaErrors[params.name].length
 }) %}
 

package/views/casa/components/select/README.md

@@ -0,0 +1,65 @@
+# `casaGovukSelect()`
+
+Extends the [`govukSelect()`](https://design-system.service.gov.uk/components/select/) macro.
+
+Custom parameters:
+
+* `casaValue` - the value of the selected option. This is a convenience for toggling the `selected` flag on the appropriate `item`, but you can also manually set `selected` on each item of you need to use more specific logic for determining selected state.
+* `casaErrors` - form errors (just pass `formErrors`)
+* `casaWithAnalytics` - enable DWP's conventional Google Analytics attributes (`data-ga-question` and `data-ga-answer`) - `false` by default; **IMPORTANT: DO NOT ENABLE this option if the question or answer may contain personally-identifiable information as values will be pushed to Google**
+
+## Example usage
+
+Basic example:
+
+```nunjucks
+{% from 'casa/components/select/macro.njk' import casaGovukSelect with context %}
+
+{{ casaGovukSelect({
+  name: 'preference',
+  casaValue: formData.preference,
+  casaErrors: formErrors,
+  label: {
+    text: 'Choose your preference'
+  },
+  hint: {
+    text: 'Some instructive hints'
+  },
+  items: [
+    {
+      value: 'twoReeds',
+      text: 'Two Reeds'
+    }, {
+      value: 'twistedFlax',
+      text: 'Twisted Flax'
+    }, {
+      value: 'water',
+      text: 'Water'
+    }, {
+      value: 'eyeOfHorus',
+      text: 'Eye of Horus'
+    }
+  ]
+}) }}
+```
+
+<!-- ## Displaying errors
+
+ref: <https://design-system.service.gov.uk/components/error-summary/>
+
+The error summary link must set focus on the select item in the group. Unless you have specified an explicit `id` for the first item in the list, this macro will explicitly set that `id` to `f-<name>`, e.g. `f-preferences` in order for links from the error summary to work as expected. -->
+
+## Google Analytics
+
+The following attributes will be attached to each `<input>` option if `casaWithAnalytics` is `true`:
+
+* `data-ga-question`: Holds the fieldset legend's content
+* `data-ga-answer`: Holds the specific answer's text/html value
+
+The following attributes will be attached to the error `<p>` tag if `casaWithAnalytics` is `true`:
+
+* `data-ga-question`: Holds the fieldset legend's content after removing all html tags
+
+These are the conventions used by DWP.
+
+> **IMPORTANT:** DO NOT ENABLE this option if the question or answer may contain personally-identifiable information as values will be pushed to Google

package/views/casa/components/select/macro.njk

@@ -0,0 +1,3 @@
+{% macro casaGovukSelect(params) %}
+  {%- include './template.njk' -%}
+{% endmacro %}

package/views/casa/components/select/template.njk

@@ -0,0 +1,49 @@
+{% from 'govuk/components/select/macro.njk' import govukSelect %}
+
+{% set fieldErrors = params.casaErrors[params.name] %}
+
+{# Generate validation data- attributes #}
+{% set mergedAttributes = params.attributes or {} %}
+{% if fieldErrors %}
+  {% set mergedAttributes = mergeObjects(mergedAttributes, {
+    'data-validation': {fn: params.name, va: fieldErrors[0].validator} | dump
+  }) %}
+{% endif %}
+
+{# Add selected flag to chosen item #}
+{% set mergedItems = [] %}
+{% for item in params.items %}
+  {% set item = mergeObjects({
+    attributes: {
+      'data-ga-question': params.label.text or params.label.html,
+      'data-ga-answer': item.text or item.html
+    }
+  } if params.casaWithAnalytics else {}, item, {
+    selected: true if item.selected or item.value == params.casaValue else false
+  }) %}
+  {% set mergedItems = (mergedItems.push(item), mergedItems) %}
+{% endfor %}
+
+{# Merge parameters #}
+{% set mergedParams = mergeObjects(params, {
+  id: params.id if params.id else 'f-' + params.name,
+  attributes: mergedAttributes,
+  items: mergedItems,
+  errorMessage: {
+    text: t(params.casaErrors[params.name][0].inline, params.casaErrors[params.name][0].variables),
+    attributes: {
+      'data-ga-question': params.label.text or params.label.html | striptags
+    } if params.casaWithAnalytics else {}
+  } if params.casaErrors[params.name].length
+}) %}
+
+{# Ensure that the first item has the id matching `f-<name>` in order for error summary linkage to work
+{% if not mergedParams.items[0].id %}
+  {% set mergedParams = mergeObjects(mergedParams, {
+    items: [{
+      id: 'f-' + params.name
+    }]
+  }) %}
+{% endif %} #}
+
+{{ govukSelect(mergedParams) }}

package/views/casa/components/textarea/README.md

@@ -19,3 +19,12 @@ casaGovukTextarea({
   casaErrors: formErrors
 })
 ```
+## Google Tag Manager
+
+The following attributes will be attached to the error `<p>` tag if `casaWithAnalytics` is `true`:
+
+* `data-ga-question`: Holds the fieldset label's text content after removing all html tags
+
+These are the conventions used by DWP.
+
+> **IMPORTANT:** DO NOT ENABLE this option if the question or answer may contain personally-identifiable information as values will be pushed to Google

package/views/casa/components/textarea/template.njk

@@ -1,4 +1,4 @@
-{% from "govuk/components/textarea/macro.njk" import govukTextarea %}
+{% from 'govuk/components/textarea/macro.njk' import govukTextarea %}
 
 {% set fieldErrors = params.casaErrors[params.name] %}
 
@@ -10,11 +10,15 @@
   }) %}
 {% endif %}
 
+{# Merge parameters #}
 {% set mergedParams = mergeObjects(params, {
   id: params.id if params.id else 'f-' + params.name,
   attributes: mergedAttributes,
   errorMessage: {
-    text: t(params.casaErrors[params.name][0].inline, params.casaErrors[params.name][0].variables)
+    text: t(params.casaErrors[params.name][0].inline, params.casaErrors[params.name][0].variables),
+    attributes: {
+      'data-ga-question': params.label.text or params.label.html | striptags
+    } if params.casaWithAnalytics else {}
   } if params.casaErrors[params.name].length
 }) %}
 

package/views/casa/layouts/journey.njk

@@ -22,7 +22,7 @@
 
 {# Use `casaPageTitle` instead of `pageTitle` if you want CASA to automatically prefix with `Error` when appropriate #}
 {% block pageTitle -%}
-  {{- t("error:documentTtlePrefix") if formErrors -}}
+  {{- t("error:documentTitlePrefix") if formErrors -}}
   {% block casaPageTitle %}{% endblock %}
 {%- endblock %}