govuk_web_banners 0.4.0 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ddede52ca24adcae2aa28d4dc5f449c53be00ab21806415acaaa6b49a740f27a
-  data.tar.gz: e87d8c81b5efd160291082c460a7136454be0fc5fc2f981ea065a1dfba10d48d
+  metadata.gz: bb07dddf7ac05db797217587e7f2c33f08bf95e237744e9b8a9ef5fc5b0ed6b6
+  data.tar.gz: 8ad155d095c70dbbc54bd1998ead9cffb2a26c8be03dfeb7911cc58b49e40ac4
 SHA512:
-  metadata.gz: d2c9d65a8a83b580c26dd1867a06f8cc00e0dae232994c853e43ddcc32818f8dec30346e9486b234d4dc6cb6a97b070f4072b127053b3212f7e1e3a45842f8a9
-  data.tar.gz: d87961bc141844b15a3666f0b33a29c023c0c6b9515378497e5a77069a1e70ec873bbb970bc8c165f9fe86e101effc6d4ead173c52b22f1ecb5fce19028283de
+  metadata.gz: 4d1c6549546b14a2db797bd2b2ac4fbfc5335b96b7e2f9be8f1b63da7fb9496771bbea9aa3e45a2f72f885f1180015b27ccba97b7e86910690b31c3bb0e22ba8
+  data.tar.gz: 85c422e6d1658f144fd275fecf15f26bdd8408421ed9cb7096d55a850df2eeaeb972fdb2ea5235eeb346b3c1c4376d2bd506c90e86d46be7de98047ac0def595

data/README.md

@@ -3,7 +3,6 @@ Proof of Concept for centralising handling of Recruitment, Global, and Emergency
 banners (currently spread across apps)
 
 ## Usage
-Currently supports the emergency banner and recruitment banners.
 
 ## Adding the gem to your application
 Add this line to your application's Gemfile:
@@ -30,7 +29,13 @@ Add the JS dependencies to your existing asset dependencies file:
 
 ## Adding emergency banners
 
-Emergency banners are passed to the [Layout for Public](https://components.publishing.service.gov.uk/component-guide/layout_for_public) component, which is currently applied to each frontend app by the slimmer/static wrapping code - so you will only need to handle emergency banners in your app when Slimmer is removed from it. Once Slimmer is removed and you are calling the layout_for_public component directly in your app, add the emergency banner partial to the component's `emergency_banner:` key:
+Emergency banners are passed to the [Layout for
+Public](https://components.publishing.service.gov.uk/component-guide/layout_for_public)
+component, which is currently applied to each frontend app by the slimmer/static
+wrapping code - so you will only need to handle emergency banners in your app
+when Slimmer is removed from it. Once Slimmer is removed and you are calling the
+layout_for_public component directly in your app, add the emergency banner
+partial to the component's `emergency_banner:` key:
 
 ```
 <%= render "govuk_publishing_components/components/layout_for_public", {
@@ -40,7 +45,8 @@ Emergency banners are passed to the [Layout for Public](https://components.publi
   ...etc
 ```
 
-if you want the homepage variant of the banner, you can add `homepage: true` to the render call:
+if you want the homepage variant of the banner, you can add `homepage: true` to
+the render call:
 
 ```
 <%= render "govuk_publishing_components/components/layout_for_public", {
@@ -50,9 +56,16 @@ if you want the homepage variant of the banner, you can add `homepage: true` to
   ...etc
 ```
 
-Your app will also need access to the whitehall shared redis cluster (which is used to signal the emergency banner is up), via the `EMERGENCY_BANNER_REDIS_URL` environment variable (here is an example of [setting this in govuk-helm-charts](https://github.com/alphagov/govuk-helm-charts/blob/7818eaa22fc194d21548f316bcc5a46c2023dcb6/charts/app-config/values-staging.yaml#L3337-L3338)). You'll need to allow this in all three environments.
+Your app will also need access to the whitehall shared redis cluster (which is
+used to signal the emergency banner is up), via the `EMERGENCY_BANNER_REDIS_URL`
+environment variable (here is an example of [setting this in
+govuk-helm-charts](https://github.com/alphagov/govuk-helm-charts/blob/7818eaa22fc194d21548f316bcc5a46c2023dcb6/charts/app-config/values-staging.yaml#L3337-L3338)).
+You'll need to allow this in all three environments.
 
-Finally, you'll need to configure a connection to the redis cluster, available at `Rails.application.config.emergency_banner_redis_client`. The suggested way of doing this is creating an initializer at `/config/initializers/govuk_web_banners.rb` with the content:
+Finally, you'll need to configure a connection to the redis cluster, available
+at `Rails.application.config.emergency_banner_redis_client`. The suggested way
+of doing this is creating an initializer at
+`/config/initializers/govuk_web_banners.rb` with the content:
 
 ```
 Rails.application.config.emergency_banner_redis_client = Redis.new(
@@ -61,11 +74,100 @@ Rails.application.config.emergency_banner_redis_client = Redis.new(
 )
 ```
 
+## Adding global banners
+
+Global banners are passed to the [Layout for
+Public](https://components.publishing.service.gov.uk/component-guide/layout_for_public)
+component, which is currently applied to each frontend app by the slimmer/static
+wrapping code - so you will only need to handle global banners in your app when
+Slimmer is removed from it. Once Slimmer is removed and you are calling the
+layout_for_public component directly in your app, add the global banner partial
+to the component's `global_banner:` key:
+
+```
+<%= render "govuk_publishing_components/components/layout_for_public", {
+  draft_watermark: draft_environment,
+  global_banner: render("govuk_web_banners/global_banner"), # <-- Add this line
+  full_width: false,
+  ...etc
+```
+
+## Updating banner information in the gem
+
+Data for the global banners can be found at
+`config/govuk_web_banners/global_banners.yml`. To add a banner to the config,
+add an entry under the banners: array. Note that this array must always be
+valid, so if there are no banners in the file, it must contain at least
+`global_banners: []`
+
+### Example banner entry
+
+```
+global_banners:
+- name: Banner 1
+  title: "Register to Vote"
+  title_href: /register-to-vote
+  text: "You must register to vote before the election"
+  permanent: false
+  exclude_paths:
+  - /find-your-local-electoral-office
+  start_date: 2024/10/21
+  end_date: 2024/11/18
+```
+Each banner must include a `title`, `title_href`, `text`, and a valid `start_date`.
+`title_href` can be either a valid URL or a path on gov.uk.
+
+> [!NOTE]
+>
+> `start_date` is **mandatory** here (unlike in recruitment banners) because it's
+> needed to create a banner_version to pass to the underlying component. This lets
+> the component reset the cookie that records how many times a banner has been seen
+> (by default banners are shown only three times, see the `permanent` option below.)
+
+Optional keys are:
+- `name` (an identifying name for this banner, not rendered
+  anywhere)
+- `permanent` (defaults to false. If false, banner is hidden if the user
+  has consented to cookies and has seen this banner more than 3 times)
+- `exclude_paths` an array of paths on which the banner should not be shown.
+  Note that the banner is never shown on the path it points to, this
+  list is to include any additional pages.
+- `end_date` (the banner stops being active at the *start* of the day
+  specified as `end_date`). Start and end dates must be in the YYYY/MM/DD
+  format parsable as a YAML -> Date.
+
+### Validations on the global banners config file
+
+The config file will be checked during CI, so an invalid file can't be released
+as a gem and we are nudged to make sure it's kept tidy. These checks include:
+
+* the global_banners array must be a valid YAML array
+* all banners have a `title`, `title_href`, and `info_text`.
+* all banners must have a valid `start_date`.
+
+It will also display warnings (but not fail CI)
+
+* if there are banners that have expired - you are encouraged to remove
+  obsolete config, but it will not prevent you merging changes.
+* if `title_href` of any banner points to a page that are not currently live on
+  GOV.UK - this may be intentional (if the banner points to a page that isn't
+  yet published), or it may indicate a typo in the path.
+* if any `exclude_paths` value points to a page that is not currently live on
+  GOV.UK - this may be intentional, or it may indicate a typo in the path.
+* if two global banners will be active on the same day (this is only a warning
+  because ultimately we may need this, but the current iteration of the
+  component does not support it)
+
+Note that some of this validation code is in the
+`/lib/govuk_web_banners/validators/global_banner.rb` file, which should be
+tested to ensure the checking is valid, but will not be bundled into the
+released gem.
+
 ## Adding recruitment banners
 
 Add a call to the partial in the layout or view that you want banners to appear
-in (typically recruitment banners should be in the layout, below the breadcrumbs
-and just above the `main` element):
+in (typically recruitment banners should be in the layout, below the
+breadcrumbs and just above the `main` element):
 
 ```
   <%= render "govuk_web_banners/recruitment_banner" %>
@@ -102,8 +204,8 @@ banners:
   page_paths:
   - /
   - /foreign-travel-advice
-  start_date: 21/10/2024
-  end_date: 18/11/2024
+  start_date: 2024/10/21
+  end_date: 2024/11/18
 ```
 
 The required keys are `suggestion_text`, `suggestion_link_text`, and
@@ -113,10 +215,10 @@ paths on which the banner should be shown).
 Optional keys are `name` (an identifying name for this banner, not rendered
 anywhere), and `start_date` / `end_date` (the banner becomes active at the start
 of the day specified as `start_date`, and stops at the *start* of the day
-specified as `end_date`). Start and end dates must be in the DD/MM/YYYY format
+specified as `end_date`). Start and end dates must be in the YYYY/MM/DD format
 parsable as a YAML -> Date.
 
-### Keeping the config file valid and tidy
+### Validations on the recruitment banners config file
 
 The config file will be checked during CI, so an invalid file can't be released
 as a gem and we are forced to make sure it's kept tidy. These checks include:
@@ -137,8 +239,9 @@ It will also display warnings (but not fail CI)
   may indicate a typo in the path.
 
 Note that some of this validation code is in the
-lib/govuk_web_banners/validators path, which should be tested to ensure the
-checking is valid, but will not be bundled into the released gem.
+`lib/govuk_web_banners/validator/recruitment_banner.rb` file, which should be
+tested to ensure the checking is valid, but will not be bundled into the
+released gem.
 
 ## License
 The gem is available as open source under the terms of the [MIT

data/Rakefile

@@ -12,15 +12,13 @@ require "bundler/gem_tasks"
 RuboCop::RakeTask.new
 RSpec::Core::RakeTask.new
 
+require "govuk_web_banners/validators/global_banner"
 require "govuk_web_banners/validators/recruitment_banner"
 require "rainbow"
 
-desc "show errors in the live config"
-task :check_config do
-  validator = GovukWebBanners::Validators::RecruitmentBanner.new(GovukWebBanners::RecruitmentBanner.all_banners)
-
+def output_validator_info(validator, name)
   if !validator.valid?
-    puts Rainbow("\nLive config contains errors!").red
+    puts Rainbow("\nLive #{name} config contains errors!").red
     validator.errors.each_key do |key|
       puts(key)
       validator.errors[key].each { |error| puts(" - #{error}") }
@@ -28,19 +26,35 @@ task :check_config do
     puts
     exit(1)
   elsif validator.warnings?
-    puts Rainbow("\nLive config is valid, but with warnings").yellow
+    puts Rainbow("\nLive #{name} config is valid, but with warnings").yellow
     validator.warnings.each_key do |key|
       puts(key)
       validator.warnings[key].each { |warnings| puts(" - #{warnings}") }
     end
     puts
   else
-    puts Rainbow("\nLive config is valid!\n").green
+    puts Rainbow("\nLive #{name} config is valid!\n").green
   end
+end
+
+desc "show errors in the live global banner config"
+task :check_global_config do
+  validator = GovukWebBanners::Validators::GlobalBanner.new(GovukWebBanners::GlobalBanner.all_banners)
+  output_validator_info(validator, "global banner")
+rescue StandardError => e
+  puts(e)
+  puts Rainbow("Live global banner config could not be read (if there are no banners, check global_banner key is marked as an empty array - global_banners: [])").red
+  exit(1)
+end
+
+desc "show errors in the live recruitment banner config"
+task :check_recruitment_config do
+  validator = GovukWebBanners::Validators::RecruitmentBanner.new(GovukWebBanners::RecruitmentBanner.all_banners)
+  output_validator_info(validator, "recruitment banner")
 rescue StandardError => e
   puts(e)
-  puts("Live config could not be read (if there are no banners, check banner key is marked as an empty array - banners: [])")
+  puts Rainbow("Live recruitment banner config could not be read (if there are no banners, check banner key is marked as an empty array - banners: [])").red
   exit(1)
 end
 
-task default: %i[check_config rubocop spec]
+task default: %i[check_global_config check_recruitment_config rubocop spec]

data/app/assets/javascripts/govuk_web_banners/dependencies.js

@@ -1 +1,2 @@
 //= require govuk_publishing_components/components/intervention
+//= require govuk_publishing_components/components/global-banner

data/app/views/govuk_web_banners/_global_banner.html.erb

@@ -0,0 +1,10 @@
+<% global_banners = GovukWebBanners::GlobalBanner.for_path(request.path) %>
+<% if global_banners.any? %>
+  <%= render "govuk_publishing_components/components/global_banner", {
+      title: global_banners.first.title,
+      title_path: global_banners.first.title_href,
+      text: global_banners.first.text,
+      permanent: global_banners.first.permanent,
+      banner_version: global_banners.first.version,
+  } %>
+<% end %>

data/config/govuk_web_banners/global_banners.yml

@@ -0,0 +1,2 @@
+# Check README.md for how to format this file
+global_banners: []

data/config/govuk_web_banners/recruitment_banners.yml

@@ -1,38 +1,6 @@
-# Example usage of adding a banner to the banners list
-
-  # banners:
-  # - name: Banner 1
-  #   suggestion_text: "Help improve GOV.UK"
-  #   suggestion_link_text: "Sign up to take part in user research (opens in a new tab)"
-  #   survey_url: https://google.com
-  #   page_paths:
-  #   - /
-  #   - /foreign-travel-advice
-  #   start_date: 21/10/2024
-  #   end_date: 18/11/2024
-
-# start_date and end_date are optional, everything else is mandatory.
-#
-# Note that this file must contain a valid banners array, so if there are no banners
-# currently included, the file should at least contain banners: []
+# Check README.md for how to format this file
 banners:
-- name: HMRC banner 03/01/2025
-  suggestion_text: "Help improve GOV.UK"
-  suggestion_link_text: "Sign up to take part in user research (opens in a new tab)"
-  survey_url: https://survey.take-part-in-research.service.gov.uk/jfe/form/SV_74GjifgnGv6GsMC?Source=BannerList_HMRC_CCG_Compliance
-  page_paths:
-    # government-frontend
-    - /government/collections/tax-compliance-detailed-information
-    - /government/collections/hm-revenue-and-customs-compliance-checks-factsheets
-    - /difficulties-paying-hmrc
-    - /tax-help
-    - /get-help-hmrc-extra-support
-    - /guidance/voluntary-and-community-sector-organisations-who-can-give-you-extra-support
-    - /tax-appeals
-    - /guidance/tax-disputes-alternative-dispute-resolution-adr
-  start_date: 03/01/2025
-  end_date: 31/01/2025
-- name: UKVI banner 30/12/2025
+- name: UKVI banner 2025/12/30
   suggestion_text: "Help improve GOV.UK"
   suggestion_link_text: "Take part in user research (opens in a new tab)"
   survey_url: https://surveys.publishing.service.gov.uk/s/XYVRGN/
@@ -42,5 +10,37 @@ banners:
     # collections
     - /browse/visas-immigration
     - /government/organisations/uk-visas-and-immigration
-  start_date: 30/12/2024
-  end_date: 24/02/2025
+  start_date: 2024/12/30
+  end_date: 2025/02/24
+- name: HMRC banner 2025/02/13
+  suggestion_text: "Help improve GOV.UK"
+  suggestion_link_text: "Sign up to take part in user research (opens in a new tab)"
+  survey_url: https://survey.take-part-in-research.service.gov.uk/jfe/form/SV_74GjifgnGv6GsMC?Source=BannerList_HMRC_Maternity_Pay_TAD
+  page_paths:
+    # government-frontend
+    - /shared-parental-leave-and-pay
+    - /maternity-pay-leave
+    - /paternity-pay-leave
+    - /working-when-pregnant-your-rights
+    - /employee-rights-when-on-leave
+    # smart-answers
+    - /maternity-paternity-pay-leave
+    # frontend
+    - /plan-shared-parental-leave-pay
+  start_date: 2025/02/13
+  end_date: 2025/03/13
+- name: HMRC banner (employers) 2025/02/13
+  suggestion_text: "Help improve GOV.UK"
+  suggestion_link_text: "Sign up to take part in user research (opens in a new tab)"
+  survey_url: https://survey.take-part-in-research.service.gov.uk/jfe/form/SV_74GjifgnGv6GsMC?Source=BannerList_HMRC_Maternity_Pay_Employers_TAD
+  page_paths:
+    # government-frontend
+    - /shared-parental-leave-and-pay-employer-guide
+    - /employers-maternity-pay-leave
+    - /employers-paternity-pay-leave
+    - /employers-parental-bereavement-pay-leave
+    - /employers-adoption-pay-leave
+    # smart-answers
+    - /maternity-paternity-calculator
+  start_date: 2025/02/13
+  end_date: 2025/03/13

data/lib/govuk_web_banners/global_banner.rb

@@ -0,0 +1,46 @@
+module GovukWebBanners
+  class GlobalBanner
+    BANNER_CONFIG_FILE = "../../config/govuk_web_banners/global_banners.yml".freeze
+
+    def self.for_path(path)
+      active_banners.reject { |b| b.exclude_paths.include?(path) }
+    end
+
+    def self.active_banners
+      all_banners.select(&:active?)
+    end
+
+    def self.all_banners
+      global_banners_file_path = Rails.root.join(__dir__, BANNER_CONFIG_FILE)
+      global_banners_data = YAML.load_file(global_banners_file_path)
+      global_banners_data["global_banners"].map { |attributes| GlobalBanner.new(attributes:) }
+    end
+
+    attr_reader :name, :title, :title_href, :text, :start_date, :end_date, :show_arrows, :permanent, :exclude_paths
+
+    def initialize(attributes:)
+      @name = attributes["name"]
+
+      @title = attributes["title"]
+      @title_href = attributes["title_href"]
+      @text = attributes["text"]
+
+      @start_date = attributes["start_date"] ? ActiveSupport::TimeZone[GovukWebBanners::TIME_ZONE].parse(attributes["start_date"]) : nil
+      @end_date = attributes["end_date"] ? ActiveSupport::TimeZone[GovukWebBanners::TIME_ZONE].parse(attributes["end_date"]) : Time.now + 10.years
+      @show_arrows = attributes["show_arrows"] == "true"
+      @permanent = attributes["permanent"] == "true"
+      @exclude_paths = attributes["exclude_paths"] || []
+      @exclude_paths << title_href if title_href&.start_with?("/")
+    end
+
+    # NB: .between? is inclusive. To make it exclude the end date, we set the end range as
+    #     1 second earlier.
+    def active?
+      Time.zone.now.between?(start_date, end_date - 1.second)
+    end
+
+    def version
+      start_date.getutc.to_i
+    end
+  end
+end

data/lib/govuk_web_banners/recruitment_banner.rb

@@ -26,8 +26,8 @@ module GovukWebBanners
       @suggestion_link_text = attributes["suggestion_link_text"]
       @survey_url = attributes["survey_url"]
       @page_paths = attributes["page_paths"]
-      @start_date = attributes["start_date"] ? Time.parse(attributes["start_date"]) : Time.at(0)
-      @end_date = attributes["end_date"] ? Time.parse(attributes["end_date"]) : Time.now + 10.years
+      @start_date = attributes["start_date"] ? ActiveSupport::TimeZone[GovukWebBanners::TIME_ZONE].parse(attributes["start_date"]) : Time.at(0)
+      @end_date = attributes["end_date"] ? ActiveSupport::TimeZone[GovukWebBanners::TIME_ZONE].parse(attributes["end_date"]) : Time.now + 10.years
     end
 
     # NB: .between? is inclusive. To make it exclude the end date, we set the end range as

data/lib/govuk_web_banners/version.rb

@@ -1,3 +1,3 @@
 module GovukWebBanners
-  VERSION = "0.4.0".freeze
+  VERSION = "1.0.0".freeze
 end

data/lib/govuk_web_banners.rb

@@ -1,9 +1,11 @@
 require "govuk_publishing_components"
 
+require "govuk_web_banners/global_banner"
 require "govuk_web_banners/emergency_banner"
 require "govuk_web_banners/engine"
 require "govuk_web_banners/recruitment_banner"
 require "govuk_web_banners/version"
 
 module GovukWebBanners
+  TIME_ZONE = "London".freeze
 end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: govuk_web_banners
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 1.0.0
 platform: ruby
 authors:
 - GOV.UK Dev
 bindir: bin
 cert_chain: []
-date: 2025-01-20 00:00:00.000000000 Z
+date: 2025-02-04 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: govuk_app_config
@@ -176,11 +176,14 @@ files:
 - app/assets/config/govuk_web_banners_manifest.js
 - app/assets/javascripts/govuk_web_banners/dependencies.js
 - app/views/govuk_web_banners/_emergency_banner.html.erb
+- app/views/govuk_web_banners/_global_banner.html.erb
 - app/views/govuk_web_banners/_recruitment_banner.html.erb
+- config/govuk_web_banners/global_banners.yml
 - config/govuk_web_banners/recruitment_banners.yml
 - lib/govuk_web_banners.rb
 - lib/govuk_web_banners/emergency_banner.rb
 - lib/govuk_web_banners/engine.rb
+- lib/govuk_web_banners/global_banner.rb
 - lib/govuk_web_banners/recruitment_banner.rb
 - lib/govuk_web_banners/version.rb
 homepage: https://github.com/alphagov/govuk_web_banners