govuk_web_banners 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: da77b3f454b15e59feb67dd5e9bf18fef636b3bda1bf874d049c8df3b6399ac1
+  data.tar.gz: 7c2ccf8b6bf5cdfba1a0aea1580f31c8ed24b9f9d2238dddf3c020ddbe418250
+SHA512:
+  metadata.gz: 20fe2fe0e6c23f98145a36ce5e5139ff3c8f7d58f1e6d53e13731ddfafa13b712917fc13b1aadccaf76fe2d291254377e3691ed3d4292e293d681bd0f2167102
+  data.tar.gz: 30cd8b18cb423dd66517abb9ff6a58cdcba830ea76bc0d81376564b1680865ad751b7853eaa09c5157afe837273cf31e1a64a5b0b3bfc575343b1806de2720e5

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright (C) 2024 Crown Copyright (Government Digital Service)
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,88 @@
+# GovukWebBanners
+Proof of Concept for centralising handling of Recruitment, Global, and Emergency banners (currently spread across apps)
+
+## Usage
+Currently, supports recruitment banners
+
+## Adding the gem to your application
+Add this line to your application's Gemfile:
+
+```ruby
+gem "govuk_web_banners"
+```
+
+And then execute:
+```bash
+$ bundle
+```
+
+Or install it yourself as:
+```bash
+$ gem install govuk_web_banners
+```
+
+Add the JS dependencies to your existing asset dependencies file:
+
+```
+//= require govuk_web_banners/dependencies
+```
+
+Add a call to the partial in the layout or view that you want banners to appear in:
+
+```
+  <%= render "govuk_web_banners/recruitment_banner" %>
+```
+
+You should make sure this line is above the call to render_component_stylesheets call if your
+app is using individual component stylesheets.
+
+## Updating banner information in the gem
+
+Data for the current set of live banners can be found at `config/govuk_web_banners/recruitment_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 `banners: []`
+
+### Example banner entry
+
+```
+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
+```
+
+The required keys are `suggestion_text`, `suggestion_link_text`, and `survey_url` (the values to appear in the
+banner), and `page_paths` (an array of 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 parsable as a YAML -> Date.
+
+### Keeping the config file valid and tidy
+
+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:
+
+* the banners array must be a valid YAML array
+* all banners have a suggestion_text, suggestion_link_text, survey_url and page_paths
+* the same page_path is not present on two banners that are active at the same time
+* paths must start with a forward-slash (/)
+
+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 page_paths point to pages that are not currently live on GOV.UK - this may be intentional (if the banner
+  is for a page that isn't yet published), or it 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.
+
+## License
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,46 @@
+require "bundler/setup"
+require "rubocop/rake_task"
+require "rspec/core/rake_task"
+
+APP_RAKEFILE = File.expand_path("spec/dummy/Rakefile", __dir__)
+load "rails/tasks/engine.rake"
+
+load "rails/tasks/statistics.rake"
+
+require "bundler/gem_tasks"
+
+RuboCop::RakeTask.new
+RSpec::Core::RakeTask.new
+
+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)
+
+  if !validator.valid?
+    puts Rainbow("\nLive config contains errors!").red
+    validator.errors.each_key do |key|
+      puts(key)
+      validator.errors[key].each { |error| puts(" - #{error}") }
+    end
+    puts
+    exit(1)
+  elsif validator.warnings?
+    puts Rainbow("\nLive 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
+  end
+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: [])")
+  exit(1)
+end
+
+task default: %i[check_config rubocop spec]

data/app/assets/config/govuk_web_banners_manifest.js

@@ -0,0 +1 @@
+// Nothing to include here.

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

@@ -0,0 +1 @@
+//= require govuk_publishing_components/components/intervention

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

@@ -0,0 +1,11 @@
+<% recruitment_banner = GovukWebBanners::RecruitmentBanner.for_path(request.path) %>
+<% if recruitment_banner.present? %>
+  <div class="govuk-width-container govuk-!-margin-top-4">
+    <%= render "govuk_publishing_components/components/intervention", {
+      new_tab: true,
+      suggestion_text: recruitment_banner.suggestion_text,
+      suggestion_link_text: recruitment_banner.suggestion_link_text,
+      suggestion_link_url: recruitment_banner.survey_url,
+    } %>
+  </div>
+<% end %>

data/config/govuk_web_banners/recruitment_banners.yml

@@ -0,0 +1,17 @@
+# Example usage of adding a banner to the banners list
+
+  # - 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: []
+banners: []

data/lib/govuk_web_banners/engine.rb

@@ -0,0 +1,5 @@
+module GovukWebBanners
+  class Engine < ::Rails::Engine
+    isolate_namespace GovukWebBanners
+  end
+end

data/lib/govuk_web_banners/recruitment_banner.rb

@@ -0,0 +1,39 @@
+module GovukWebBanners
+  class RecruitmentBanner
+    BANNER_CONFIG_FILE = "../../config/govuk_web_banners/recruitment_banners.yml".freeze
+
+    def self.for_path(path)
+      active_banners.find do |banner|
+        return banner if banner.page_paths.include?(path)
+      end
+    end
+
+    def self.active_banners
+      all_banners.select(&:active?)
+    end
+
+    def self.all_banners
+      recruitment_banners_urls_file_path = Rails.root.join(__dir__, BANNER_CONFIG_FILE)
+      recruitment_banners_data = YAML.load_file(recruitment_banners_urls_file_path)
+      recruitment_banners_data["banners"].map { |attributes| RecruitmentBanner.new(attributes:) }
+    end
+
+    attr_reader :name, :suggestion_text, :suggestion_link_text, :survey_url, :page_paths, :start_date, :end_date
+
+    def initialize(attributes:)
+      @name = attributes["name"]
+      @suggestion_text = attributes["suggestion_text"]
+      @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
+    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
+  end
+end

data/lib/govuk_web_banners/version.rb

@@ -0,0 +1,3 @@
+module GovukWebBanners
+  VERSION = "0.1.0".freeze
+end

data/lib/govuk_web_banners.rb

@@ -0,0 +1,8 @@
+require "govuk_publishing_components"
+
+require "govuk_web_banners/engine"
+require "govuk_web_banners/recruitment_banner"
+require "govuk_web_banners/version"
+
+module GovukWebBanners
+end

metadata

@@ -0,0 +1,183 @@
+--- !ruby/object:Gem::Specification
+name: govuk_web_banners
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- GOV.UK Dev
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2024-11-25 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: govuk_publishing_components
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7'
+- !ruby/object:Gem::Dependency
+  name: byebug
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: govuk_test
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rainbow
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rspec-rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rubocop-govuk
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: simplecov
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: webmock
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: A gem to support banners on GOV.UK frontend applications
+email:
+- govuk-dev@digital.cabinet-office.gov.uk
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- MIT-LICENSE
+- README.md
+- Rakefile
+- app/assets/config/govuk_web_banners_manifest.js
+- app/assets/javascripts/govuk_web_banners/dependencies.js
+- app/views/govuk_web_banners/_recruitment_banner.html.erb
+- config/govuk_web_banners/recruitment_banners.yml
+- lib/govuk_web_banners.rb
+- lib/govuk_web_banners/engine.rb
+- lib/govuk_web_banners/recruitment_banner.rb
+- lib/govuk_web_banners/version.rb
+homepage: https://github.com/alphagov/govuk_web_banners
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/alphagov/govuk_web_banners
+  source_code_uri: https://www.github.com/alphagov/govuk_web_banners
+  changelog_uri: https://www.github.com/alphagov/govuk_web_banners/CHANGELOG.md
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.1'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.23
+signing_key: 
+specification_version: 4
+summary: A gem to support banners on GOV.UK frontend applications
+test_files: []