@dwp/govuk-casa 8.7.9 → 8.8.0

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 %}
 

package/views/casa/layouts/main.njk

@@ -7,7 +7,7 @@
 
 
 {% block skipLink %}
-  {# Harcoding content for the skip link as t() may not be availble on some error pages #}
+  {# Hardcoding content for the skip link as t() may not be available on some error pages #}
   {{ govukSkipLink({
     href: '#main-content',
     text: "Neidio i'r prif gynnwys" if locale === 'cy' else 'Skip to main content'