play-frontend-hmrc

This library contains all the Twirl components and helpers needed to implement frontend microservices on the HMRC tax platform.

play-frontend-hmrc is a Scala Twirl implementation of govuk-frontend and hmrc-frontend, adding to it Play, HMRC and tax platform-specific components and helpers that make the process of implementing frontend microservices straightforward and idiomatic for Scala developers.

Table of Contents

• Getting started
  • Compatible Scala and Play Framework versions
  • Understanding library changes between versions
  • Integrating with play-frontend-hmrc
  • Troubleshooting
  • Useful Links
• Using components
• Creating pages
• Advanced configuration
• Owning team README
• Getting help
• License

Getting started

Compatible Scala and Play Framework versions

This library is currently compatible with:

• Play 3.0 - Scala 2.13 / 3

Understanding library changes between versions

We summarise what's changed between versions, and importantly any actions that may be required when upgrading past a specific version within our changelog.

Integrating with play-frontend-hmrc

1. Add the library to the project dependencies:

   libraryDependencies += "uk.gov.hmrc" %% "play-frontend-hmrc-play-30" % "x.y.z"

   Where play-xx is your version of Play (e.g. play-30).

2. Add a route for the hmrc-frontend static assets in conf/app.routes:

   ->         /hmrc-frontend                      hmrcfrontend.Routes

3. Define your service name in your messages files. For example,

   service.name = Any tax service

   If you have a dynamic service name you can skip this step and pass the serviceName into HmrcStandardPage or HmrcStandardHeader.

4. Create a layout template for your pages using the HMRC standard page template

5. Problems with styling? Check our Troubleshooting section.

Troubleshooting

If you are adding HTML elements to your page such as <h1> or <p>, you will need to add the CSS classes for the GDS Transport fonts from the GOV.UK Design System. A full list of the CSS classes can be found at https://design-system.service.gov.uk/styles/type-scale/.

These styles have already been applied to the components supplied in play-frontend-hmrc, but you will need to manually add the styles to your service's own HTML elements.

Useful Links

• HMRC Design Patterns - documentation for the use of hmrc-frontend components
• hmrc-frontend - reusable Nunjucks HTML components for HMRC design patterns
• GOV.UK Design System - documentation for the use of govuk-frontend components
• govuk-frontend - reusable Nunjucks HTML components from GOV.UK
• GOV.UK Design System Chrome extension - Chrome extension to add a Twirl tab for each example in the GOV.UK Design System

Using components

Information how to use some of the components like banners, implicit methods can be found in a separate Markdown file.

• Finding Twirl templates for GOV.UK and HMRC design system components
• Using the components
• Using Content
• Useful implicits
  • withFormField
  • withHeading and withHeadingAndCaption
  • RichDateInput
  • RichErrorSummary
  • RichStringSupport
• Adding a beta feedback banner
• Adding a User Research Banner
• Helping users report technical issues
• Adding dynamic character count with Welsh translations to a text input
• Adding accessible autocomplete to a select input
  • Transforming a <select> element into an Accessible Autocomplete element
• Opening links in a new tab

Creating pages

Information how to enable GOV.UK brand refresh, link your accessibility statement, GTM/tracking consent configuration can be found in a separate Markdown file.

• Using the refreshed GOV.UK brand
• Creating HMRC-style pages
  • Using the HMRC standard page template
  • Adding a sidebar to your Layout
    • Finding working examples
• Integrating with shared HMRC services
  • Linking to your accessibility statement
  • Allowing users to enable or disable tracking cookies
    • Integrating with tracking consent
    • Adding GTM to internal services
• Warning users before timing them out
  • Integrating with the timeout dialog
  • Synchronising session between tabs
  • Customising the timeout dialog

Advanced configuration

Information how to add your own SASS compilation pipeline, configuring non-HMRC project to resolve play-frontend-hmrc artefacts or using Tudor Crown on GOV.UK and HMRC components can be found in a separate Markdown file.

• Adding your own SASS compilation pipeline
• Configuring non-HMRC projects to resolve play-frontend-hmrc artefacts
• Using the Tudor Crown on GOV.UK and HMRC components

Owning team README

Rationale for code and translation decisions, dependencies, as well as instructions for team members maintaining this repository can be found here.

Getting help

Please report any issues with this library in Slack at #team-plat-ui.

License

This code is open source software licensed under the Apache 2.0 License.