Version 5 release notes #469

peteryates · 2023-11-28T12:53:22Z

Draft release notes

⚠️ This is a breaking change release

Version 5.0.0 of the ruby govuk-components gem supports version 5.0.0 of the govuk-frontend npm package. Both contain breaking changes, and are dependent on each other – so you should update both at the same time.

These release notes for the ruby gem should be read alongside the release notes for govuk-frontend.

Upgrade instructions

1. Install both the gem AND the node package

Update the version of govuk-component in your Gemfile and run bundle install:

gem "govuk-components", "~> 5.0.0b4"

Update your version of govuk-frontend in your package.json and then run npm install or yarn install (depending on which you use).

"govuk-frontend": "5.0.0-beta.2",

2. Check that your app still builds

The way that assets have been packaged in govuk-frontend has changed, so you may need to update your build process.

If you're using Sass, change

@import "govuk-frontend/govuk/all";

to

@import "govuk-frontend/dist/govuk/all";

If you are using a javascript compiler, change govuk-frontend/govuk to govuk-frontend/dist/govuk.

See release notes for govuk-frontend 5.0.0 for details.

3. Update your application layout file

In your application layout file (normally layouts/application.html.erb), update the code snippet which adds a class to the document body.

Update it from this:

<script>document.body.className = ((document.body.className) ? document.body.className + ' js-enabled' : 'js-enabled');</script>

to this:

<script>document.body.className += ' js-enabled' + ('noModule' in HTMLScriptElement.prototype ? ' govuk-frontend-supported' : '');</script>

Once this is done, things like accordions and conditionally-revealing form elements should work as before.

4. Update any links using controller and action references

TODO: Pete to write this?

5. Check capitalisation of any tag components

The Tag component no longer uses CSS to make the text UPPERCASE.

If you use any tags, check that the text has an initial capital letter only in the HTML.

The colours have also changed, so check they still have sufficient contrast against any background.

6. Check the logo in the header

The way the GOV.UK logo is rendered within an SVG image has changed.

If you are using the govuk_header component, there should be no need for any further changes unless you previously set custom logotype text. This is no longer supported. If you need to change the logo, you should set the custom_logo slot within the header component instead.

7. Update asset pipeline

If you use Rails’s asset pipeline to import the images and fonts from govuk-frontend, you’ll need to add the dist folder to the path.

Within config/initalizers/assets.rb, change this:

Rails.application.config.assets.paths << Rails.root.join("node_modules/govuk-frontend/govuk/assets/images")
Rails.application.config.assets.paths << Rails.root.join("node_modules/govuk-frontend/govuk/assets/fonts")

to this:

Rails.application.config.assets.paths << Rails.root.join("node_modules/govuk-frontend/dist/govuk/assets/images")
Rails.application.config.assets.paths << Rails.root.join("node_modules/govuk-frontend/dist/gov/assets/fonts")

If you use sprockets to compile javascript or CSS, update the path in the manifest.

Within app/assets/config/manifest.js, change this:

//= link_directory ../../../node_modules/govuk-frontend/govuk/assets/images
//= link_directory ../../../node_modules/govuk-frontend/govuk/assets/fonts

to this:

//= link_directory ../../../node_modules/govuk-frontend/dist/govuk/assets/images
//= link_directory ../../../node_modules/govuk-frontend/dist/govuk/assets/fonts

8. Update favicon references in your application layout file

The included icons within govuk-frontend have been updated, with some of the old ones removed.

Within your layouts/application.html.erb layout file, change these lines:

    <%= favicon_link_tag image_path('favicon.ico') %>
    <%= favicon_link_tag image_path('govuk-mask-icon.svg'), rel: 'mask-icon', type: 'image/svg', color: "#0b0c0c" %>
    <%= favicon_link_tag image_path('govuk-apple-touch-icon.png'), rel: 'apple-touch-icon', type: 'image/png' %>
    <%= favicon_link_tag image_path('govuk-apple-touch-icon-152x152.png'), rel: 'apple-touch-icon', type: 'image/png', size: '152x152' %>
    <%= favicon_link_tag image_path('govuk-apple-touch-icon-167x167.png'), rel: 'apple-touch-icon', type: 'image/png', size: '167x167' %>
    <%= favicon_link_tag image_path('govuk-apple-touch-icon-180x180.png'), rel: 'apple-touch-icon', type: 'image/png', size: '180x180' %>

to this:

    <%= favicon_link_tag image_path('favicon.ico'), type: nil, sizes: "48x48" %>
    <%= favicon_link_tag image_path('favicon.svg'), type: 'image/svg+xml', sizes: "any" %>
    <%= favicon_link_tag image_path('govuk-icon-mask.svg'), rel: 'mask-icon', color: "#0b0c0c", type: nil %>
    <%= favicon_link_tag image_path('govuk-icon-180.png'), rel: 'apple-touch-icon', type: nil %>

New features

Task list

The gem now supports the new Task list component within govuk-frontend.

If your service features a task list, you can take advantage of this by swapping out your custom task list code for the govuk_task_list component.

Here’s an example of how this can be used:

 <%= govuk_task_list(id_prefix: "coloured-tags-example") do |task_list| %>
   <% task_list.with_item(
      title: "Design", 
      href: "#", 
      status: govuk_tag(text: "Green", colour: "green")
    ) %>
 <% end %>

New link helpers

The following helpers: #govuk_link_to, #govuk_button_link_to, #govuk_button_to and #govuk_mail_to, plus the class helpers #govuk_link_classes and #govuk_button_classes have been rewritten to use keyword arguments instead of trying to juggle the arguments based on what's passed in, like the old Rails-style ones.

This is a breaking change because the new implementations don't support all the features the Rails ones do,
mainly that govuk_link_to("Peanuts", controller: "snacks", action: "show", id: "peanuts") style invocation won't work. The Rails documentation has advised against using this form of link for many years - pass in the path instead, i.e.,govuk_link_to("Peanuts", snack_path("peanuts"))

The new helpers allow us to easily add extra GOV.UK specific arguments, these include:

new_tab: true - open the page in a new tab, adds rel="noreferrer noopener" and target="_blank" automatically to links New link helpers #419
visually_hidden_prefix and visually_hidden_suffix - add .govuk-visually-hidden text before or after the link text Add visually hidden prefix and suffix text to links and buttons #465

If you don't want to upgrade and continue using the old style link helpers for now, manually include GovukRailsCompatibleLinkHelper.

Visually hidden helper

There's a new helper called govuk_visually_hidden which takes either a text argument or a block of HTML and wraps it in <span class="govuk-visually-hidden">.

<%= govuk_visually_hidden("This text won't appear on the page but will be read out by a screenreader") %>

The text was updated successfully, but these errors were encountered:

frankieroberto · 2023-11-28T15:40:03Z

Draft release notes:

⚠️ This is a breaking change release

Upgrade instructions

1. Install both the gem AND the node package

Update the version of govuk-component in your Gemfile and run bundle install:

gem "govuk-components", "~> 5.0.0b1"

Update your version of govuk-frontene in your package.json and then run npm install or yarn install (depending on which you use).

"govuk-frontend": "5.0.0-beta.2",

2. Check that your app still builds

The way that assets have been packaged in govuk-frontend has changed, so you may need to update your build process.

If you're using Sass, change

@import "govuk-frontend/govuk/all";

to

@import "govuk-frontend/dist/govuk/all";

If you are using a javascript compiler, change govuk-frontend/govuk to govuk-frontend/dist/govuk.

See release notes for govuk-frontend 5.0.0 for details.

3. Update your application layout file

In your application layout file (normally layouts/application.html.erb), update the code snippet which adds a class to the document body.

Update it from this:

<script>document.body.className = ((document.body.className) ? document.body.className + ' js-enabled' : 'js-enabled');</script>

to this:

<script>document.body.className += ' js-enabled' + ('noModule' in HTMLScriptElement.prototype ? ' govuk-frontend-supported' : '');</script>

Once this is done, things like accordions and conditionally-revealing form elements should work as before.

4. Update any links using controller and action references

TODO: Pete to write this?

5. Check capitalisation of any tag components

The Tag component no longer uses CSS to make the text UPPERCASE.

If you use any tags, check that the text has an initial capital letter only in the HTML.

The colours have also changed, so check they still have sufficient contrast against any background.

6. Check the logo in the header

The way the GOV.UK logo is rendered within an SVG image has changed.

If you are using the govuk_header component, there should be no need for any further changes unless you previously set custom logotype text. This is no longer supported. If you need to change the logo, you should set the custom_logo slot within the header component instead.

New features

Task list

The gem now supports the new Task list component within govuk-frontend.

If your service features a task list, you can take advantage of this by swapping out your custom task list code for the govuk_task_list component.

Here’s an example of how this can be used:

 <%= govuk_task_list(id_prefix: "coloured-tags-example") do |task_list| %>
   <% task_list.with_item(
      title: "Design", 
      href: "#", 
      status: govuk_tag(text: "Green", colour: "green")
    ) %>
 <% end %>

Visually-hidden text within links

TODO

peteryates · 2023-11-28T17:16:37Z

New features

New link helpers

The following helpers: #govuk_link_to, #govuk_button_link_to, #govuk_button_to and #govuk_mail_to, plus the class helpers #govuk_link_classes and #govuk_button_classes have been rewritten to use keyword arguments instead of trying to juggle the arguments based on what's passed in, like the old Rails-style ones.

This is a breaking change because the new implementations don't support all the features the Rails ones do,
mainly that govuk_link_to("Peanuts", controller: "snacks", action: "show", id: "peanuts") style invocation won't work. The Rails documentation has advised against using this form of link for many years - pass in the path instead, i.e.,govuk_link_to("Peanuts", snack_path("peanuts"))

The new helpers allow us to easily add extra GOV.UK specific arguments, these include:

new_tab: true - open the page in a new tab, adds rel="noreferrer noopener" and target="_blank" automatically to links New link helpers #419
visually_hidden_prefix and visually_hidden_suffix - add .govuk-visually-hidden text before or after the link text Add visually hidden prefix and suffix text to links and buttons #465

Visually hidden helper

There's a new helper called govuk_visually_hidden which takes either a text argument or a block of HTML and wraps it in <span class="govuk-visually-hidden">. Visually hidden elements can be made focusable by passing focusable: true

<%= govuk_visually_hidden("This text won't appear on the page but will be read out by a screenreader") %>

frankieroberto · 2023-11-28T22:29:44Z

Another upgrade step for the release notes:

7. Update asset pipeline

If you use Rails’s asset pipeline to import the images and fonts from govuk-frontend, you’ll need to add the dist folder to the path.

Within config/initalizers/assets.rb, change this:

Rails.application.config.assets.paths << Rails.root.join("node_modules/govuk-frontend/govuk/assets/images")
Rails.application.config.assets.paths << Rails.root.join("node_modules/govuk-frontend/govuk/assets/fonts")

to this:

Rails.application.config.assets.paths << Rails.root.join("node_modules/govuk-frontend/dist/govuk/assets/images")
Rails.application.config.assets.paths << Rails.root.join("node_modules/govuk-frontend/dist/gov/assets/fonts")

If you use sprockets to compile javascript or CSS, update the path in the manifest.

Within app/assets/config/manifest.js, change this:

//= link_directory ../../../node_modules/govuk-frontend/govuk/assets/images
//= link_directory ../../../node_modules/govuk-frontend/govuk/assets/fonts

to this:

//= link_directory ../../../node_modules/govuk-frontend/dist/govuk/assets/images
//= link_directory ../../../node_modules/govuk-frontend/dist/govuk/assets/fonts

frankieroberto · 2023-11-28T22:32:29Z

Another step:

8. Update favicon references in your application layout file

The included icons within govuk-frontend have been updated, with some of the old ones removed.

Within your layouts/application.html.erb layout file, change these lines:

    <%= favicon_link_tag image_path('favicon.ico') %>
    <%= favicon_link_tag image_path('govuk-mask-icon.svg'), rel: 'mask-icon', type: 'image/svg', color: "#0b0c0c" %>
    <%= favicon_link_tag image_path('govuk-apple-touch-icon.png'), rel: 'apple-touch-icon', type: 'image/png' %>
    <%= favicon_link_tag image_path('govuk-apple-touch-icon-152x152.png'), rel: 'apple-touch-icon', type: 'image/png', size: '152x152' %>
    <%= favicon_link_tag image_path('govuk-apple-touch-icon-167x167.png'), rel: 'apple-touch-icon', type: 'image/png', size: '167x167' %>
    <%= favicon_link_tag image_path('govuk-apple-touch-icon-180x180.png'), rel: 'apple-touch-icon', type: 'image/png', size: '180x180' %>

to this:

    <%= favicon_link_tag image_path('favicon.ico'), type: nil, sizes: "48x48" %>
    <%= favicon_link_tag image_path('favicon.svg'), type: 'image/svg+xml', sizes: "any" %>
    <%= favicon_link_tag image_path('govuk-icon-mask.svg'), rel: 'mask-icon', color: "#0b0c0c", type: nil %>
    <%= favicon_link_tag image_path('govuk-icon-180.png'), rel: 'apple-touch-icon', type: nil %>

Following the release of [GOV.UK Design System v5.0](https://github.com/alphagov/govuk-design-system/milestone/16), govuk-components v5.0.0 will be released. The headline features are: * support for GOV.UK Design System v5.0 * inclusion of [the task list component](alphagov/govuk-frontend#2261) #425 * all new link helpers #419 * update header to use new SVG which combines the crown and the GOV.UK test #466 Release notes will be drafted in #469.

peteryates added this to GOV.UK frontend 5.0.0 Nov 28, 2023

peteryates moved this to Todo in GOV.UK frontend 5.0.0 Nov 28, 2023

peteryates moved this from Todo to In Progress in GOV.UK frontend 5.0.0 Nov 28, 2023

frankieroberto added this to the version 5.0.0 milestone Nov 28, 2023

peteryates mentioned this issue Nov 29, 2023

Version 5.0.0 #456

Merged

peteryates added the v5.0.0 label Dec 9, 2023

peteryates moved this from In Progress to Done in GOV.UK frontend 5.0.0 Dec 11, 2023

peteryates closed this as completed Dec 13, 2023

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Version 5 release notes #469

Version 5 release notes #469

peteryates commented Nov 28, 2023 •

edited

Loading

frankieroberto commented Nov 28, 2023

peteryates commented Nov 28, 2023 •

edited

Loading

frankieroberto commented Nov 28, 2023 •

edited

Loading

frankieroberto commented Nov 28, 2023

Version 5 release notes #469

Version 5 release notes #469

Comments

peteryates commented Nov 28, 2023 • edited Loading

Draft release notes

Upgrade instructions

1. Install both the gem AND the node package

2. Check that your app still builds

3. Update your application layout file

4. Update any links using controller and action references

5. Check capitalisation of any tag components

6. Check the logo in the header

7. Update asset pipeline

8. Update favicon references in your application layout file

New features

Task list

New link helpers

Visually hidden helper

frankieroberto commented Nov 28, 2023

Upgrade instructions

1. Install both the gem AND the node package

2. Check that your app still builds

3. Update your application layout file

4. Update any links using controller and action references

5. Check capitalisation of any tag components

6. Check the logo in the header

New features

Task list

Visually-hidden text within links

peteryates commented Nov 28, 2023 • edited Loading

New features

New link helpers

Visually hidden helper

frankieroberto commented Nov 28, 2023 • edited Loading

7. Update asset pipeline

frankieroberto commented Nov 28, 2023

8. Update favicon references in your application layout file

peteryates commented Nov 28, 2023 •

edited

Loading

peteryates commented Nov 28, 2023 •

edited

Loading

frankieroberto commented Nov 28, 2023 •

edited

Loading