Make it easier to add a hint or an error message to a fieldset

[colinrotherham]

This feature adds a new macro govukFormGroup() to resolve #1166.

Because govukFieldset() is a wrapper only, it's up to services to manage the hint and error message markup themselves when making more complex multi-field pages.

Duplicated inside almost all form control macros is Nunjucks code to generate a govukLabel() label, a govukHint() hint an a govukErrorMessage() error message:

  {{ govukLabel({
    html: params.label.html,
    text: params.label.text,
    classes: params.label.classes,
    isPageHeading: params.label.isPageHeading,
    attributes: params.label.attributes,
    for: params.id
  }) | indent(2) | trim }}
{% if params.hint %}
  {% set hintId = params.id + '-hint' %}
  {% set describedBy = describedBy + ' ' + hintId if describedBy else hintId %}
  {{ govukHint({
    id: hintId,
    classes: params.hint.classes,
    attributes: params.hint.attributes,
    html: params.hint.html,
    text: params.hint.text
  }) | indent(2) | trim }}
{% endif %}
{% if params.errorMessage %}
  {% set errorId = params.id + '-error' %}
  {% set describedBy = describedBy + ' ' + errorId if describedBy else errorId %}
  {{ govukErrorMessage({
    id: errorId,
    classes: params.errorMessage.classes,
    attributes: params.errorMessage.attributes,
    html: params.errorMessage.html,
    text: params.errorMessage.text,
    visuallyHiddenText: params.errorMessage.visuallyHiddenText
  }) | indent(2) | trim }}
{% endif %}

It's used by textarea, select, radios, checkboxes, text input, file upload and date input.

This allows us to port existing services with more complex multi-field pages (often with some fields nested inside other fieldsets) like this:

With little markup like:

{% call govukFormGroup({
  fieldset: {
    legend: {
      text: "Pick one of the following options:",
      classes: "govuk-fieldset__legend--m"
    }
  }
}) %}

{{ govukRadios({
  "fieldset": {
    "legend": {
      text: "Group 1",
      classes: "govuk-fieldset__legend--s"
    }
  },
  "idPrefix": "radio-stacked-sub-headings-group-1",
  "name": "radio-stacked-sub-headings",
  "items": [
    {
      "value": "a",
      "text": "Option A"
    },
    {
      "value": "b",
      "text": "Option B"
    },
    {
      "value": "c",
      "text": "Option C"
    }
  ]
}) }}

{{ govukRadios({
  "fieldset": {
    "legend": {
      text: "Group 2",
      classes: "govuk-fieldset__legend--s"
    }
  },
  "idPrefix": "radio-stacked-sub-headings-group-2",
  "name": "radio-stacked-sub-headings",
  "items": [
    {
      "value": "a",
      "text": "Option A"
    },
    {
      "value": "b",
      "text": "Option B"
    },
    {
      "value": "c",
      "text": "Option C"
    }
  ]
}) }}

{{ govukRadios({
  "fieldset": {
    "legend": {
      text: "Group 3",
      classes: "govuk-fieldset__legend--s"
    }
  },
  "idPrefix": "radio-stacked-sub-headings-group-3",
  "name": "radio-stacked-sub-headings",
  "items": [
    {
      "value": "a",
      "text": "Option A"
    },
    {
      "value": "b",
      "text": "Option B"
    },
    {
      "value": "c",
      "text": "Option C"
    }
  ]
}) }}

{% endcall %}

This merge request demonstrates how we might remove the management of hints and error messages making new Nunjucks macros and form layouts a little easier to write in future.

[colinrotherham]

This change moves:

govuk/objects/form-group

Into a macro:

govuk/component/form-group

So will need documenting here (to be created):
https://design-system.service.gov.uk/components/form-group

[NickColley]

Hey Colin,

We are currently prioritising work to make GOV.UK Frontend pass WCAG 2.1 requirements and we have an external audit soon.

This work looks really well done, we want to discuss it as a team and make sure it's the right approach, and then give some proper feedback.

We're not going to be able to follow up on this until we've done the audit so thanks a lot for your patience. :)

Nick

[colinrotherham]

Moved the aria-describedby param changes separately into #1347

[36degrees]

Hey @colinrotherham,

Thanks again for your work on this.

This change makes a lot of sense, but because of the limitations of Nunjucks it ends up breaking a lot of the conventions we’ve built for how components should work. For that reason, we're going to close it.

We have got an epic next quarter to look at improving the way the macros work, and we’ll definitely be looking to do something similar if we can work out how to make it fit (for example, by finding a way to do merge objects)

Thanks for your patience - we’ve been somewhat preoccupied with the work on 3.0, but we need to work out how to better handle contributions like this so we don’t leave people hanging.

Ollie