Merge pull request #447 from x-govuk/add-title-with-error-prefix

Add helper: title_with_error_prefix

app/helpers/title_with_error_prefix_helper.rb

@@ -0,0 +1,7 @@
+module TitleWithErrorPrefixHelper
+  def title_with_error_prefix(title, error:, error_prefix: Govuk::Components.config.default_error_prefix)
+    "#{error_prefix if error}#{title}"
+  end
+end
+
+ActiveSupport.on_load(:action_view) { include TitleWithErrorPrefixHelper }

guide/content/helpers/title-with-error-prefix.slim

@@ -0,0 +1,28 @@
+---
+title: Title with error prefix
+---
+
+markdown:
+  If you have a page containing a form, you should add the "Error: " prefix to the page title if there is a validation error on the page.
+
+  This means that screen readers will read it out as soon as possible.
+
+  To do this, you can use the `title_with_error_prefix` helper.
+
+  If you are using a Rails form, you can set the error attribute by calling `errors.any?` on the form object:
+
+  ```
+    = title_with_error_prefix("Personal details", error: @personal_details_form.errors.any?)
+  ```
+
+== render('/partials/example.*',
+  caption: "Title with an error present",
+  code: title_containing_error)
+
+== render('/partials/example.*',
+  caption: "Title with an error present",
+  code: title_not_containing_error)
+
+== render('/partials/example.*',
+  caption: "Title with a custom error prefix",
+  code: title_containing_error_and_custom_error_prefix)

guide/layouts/partials/links.slim

@@ -18,6 +18,7 @@ section#links.govuk-width-container
         li== govuk_link_to('Link', '/helpers/link')
         li== govuk_link_to('Skip link', '/helpers/skip-link')
         li== govuk_link_to('Back to top link', '/helpers/back-to-top-link')
+        li== govuk_link_to('Title with error prefix', '/helpers/title-with-error-prefix')
 
     .govuk-grid-column-two-thirds
       h2.govuk-heading-m Components

guide/lib/examples/title_with_error_prefix_helpers.rb

@@ -0,0 +1,23 @@
+require 'ostruct'
+
+module Examples
+  module TitleWithErrorPrefixHelpers
+    def title_containing_error
+      <<~TITLE_WITH_ERROR_PREFIX
+        = title_with_error_prefix("Personal details", error: true)
+      TITLE_WITH_ERROR_PREFIX
+    end
+
+    def title_not_containing_error
+      <<~TITLE_WITH_ERROR_PREFIX
+        = title_with_error_prefix("Personal details", error: false)
+      TITLE_WITH_ERROR_PREFIX
+    end
+
+    def title_containing_error_and_custom_error_prefix
+      <<~TITLE_WITH_ERROR_PREFIX
+        = title_with_error_prefix("Manylion personol", error: true, error_prefix: "Gwall: ")
+      TITLE_WITH_ERROR_PREFIX
+    end
+  end
+end

guide/lib/helpers.rb

@@ -108,3 +108,4 @@ class Application < Rails::Application; end
 use_helper Examples::WarningTextHelpers
 use_helper Examples::CommonOptionsHelpers
 use_helper Examples::BackToTopLinkHelpers
+use_helper Examples::TitleWithErrorPrefixHelpers

lib/govuk/components/engine.rb

@@ -38,6 +38,7 @@ def reset!
     # +:default_breadcrumbs_hide_in_print+ false
     # +:default_cookie_banner_aria_label+ "Cookie banner"
     # +:default_cookie_banner_hide_in_print+ true
+    # +:default_error_prefix+ Text to use at the start of the page title tag when there is an error on the page. Default is 'Error: '
     # +:default_exit_this_page_redirect_url+ The URL that the exit this page component links to by default. Defaults to https://www.bbc.co.uk/weather
     # +:default_exit_this_page_text+ The default text that forms the link. Defaults to 'Exit this page'
     # +:default_exit_this_page_activated_text+ Text announced by screen readers when Exit this Page has been activated via the keyboard shortcut. Default in govuk-frontend is 'Exiting page.' Defaults to nil so govuk-frontend value is used unless overridden.
@@ -79,6 +80,7 @@ def reset!
       default_breadcrumbs_hide_in_print: false,
       default_cookie_banner_aria_label: "Cookie banner",
       default_cookie_banner_hide_in_print: true,
+      default_error_prefix: "Error: ",
       default_exit_this_page_redirect_url: "https://www.bbc.co.uk/weather",
       default_exit_this_page_text: "Exit this page",
       default_exit_this_page_activated_text: nil,
@@ -110,9 +112,7 @@ def reset!
       default_notification_title_success: false,
       default_warning_text_icon_fallback_text: "Warning",
       default_warning_text_icon: "!",
-
       default_link_new_tab_text: "(opens in new tab)",
-
       require_summary_list_action_visually_hidden_text: false,
       enable_auto_table_scopes: true,
     }.freeze

spec/helpers/title_with_error_prefix_helper_spec.rb

@@ -0,0 +1,37 @@
+require 'spec_helper'
+
+RSpec.describe(TitleWithErrorPrefixHelper, type: 'helper') do
+  describe '#title_with_error_prefix' do
+    context 'when there is an error' do
+      subject { title_with_error_prefix('What is their name?', error: true) }
+
+      it 'should include the Error: prefix' do
+        expect(subject).to eql('Error: What is their name?')
+      end
+    end
+
+    context 'when there is not an error' do
+      subject { title_with_error_prefix('What is their name?', error: false) }
+
+      it 'should not include a prefix' do
+        expect(subject).to eql('What is their name?')
+      end
+    end
+
+    context 'when error is not specified' do
+      subject { title_with_error_prefix('What is their name?') }
+
+      it 'should raise an argument error' do
+        expect { subject }.to raise_error(ArgumentError)
+      end
+    end
+
+    context 'when an alternative error prefix is given' do
+      subject { title_with_error_prefix('What is their name?', error: true, error_prefix: "Opps: ") }
+
+      it 'should include the alternative error prefix' do
+        expect(subject).to eql('Opps: What is their name?')
+      end
+    end
+  end
+end

spec/spec_helper.rb

@@ -16,6 +16,7 @@
 include GovukBackToTopLinkHelper
 include GovukSkipLinkHelper
 include GovukExitThisPageLinkHelper
+include TitleWithErrorPrefixHelper
 
 module Pagy::UrlHelpers
   def request