Skip to content

Latest commit

 

History

History
170 lines (116 loc) · 7.2 KB

README.md

File metadata and controls

170 lines (116 loc) · 7.2 KB
Raw

Deprecation

🚨 play-ui has been deprecated in favour of play-frontend-hmrc. 🚨

This library is no longer supported, and teams need to be aware of the vulnerabilities via the dependency on assets-frontend. There are also known accessibility issues with play-ui which will cause delays with going live. As of 13th October 2021, we won't be making updates to play-ui so we recommend moving over to the latest play-frontend-hmrc

play-ui

Deprecated micro-library containing core for HMRC's Play UI:

Formatters

  • Dates provides various human-readable date formats
  • Money formats pounds and pence
  • Strings changes the case of phrases and hyphenates

Form Mappers & Validators

  • DateTuple maps year, month, day fields to a LocalDate
  • StopOnFirstFail applies constraints in order and fails fast
  • Validators contains multiple small validation functions such as addressTuple, positiveInteger & nonEmptySmallText

Helper Templates

Has many standard snippets for form fields, such as: address, dateFields, dropdown, fieldGroup. Each helper correctly adds labels, error messages and CSS classes.

Layout Templates

Contains templates for components used across frontend applications such as: header, footer, sidebar, betaBanner.

Accessibility Statements

The FooterLinks component generates the standard list of links for passing into Gov.UK template.

To configure this component to link to the new Accessibility Statement service, provide the key accessibility-statement.service-path in your application.conf. This key is the path to your accessibility statement under https://www.tax.service.gov.uk/accessibility-statement.

For example, if your accessibility statement is https://www.tax.service.gov.uk/accessibility-statement/discounted-icecreams, this property must be set to /discounted-icecreams as follows:

accessibility-statement.service-path = "/discounted-icecreams"

Integrating with Tracking Consent

If you intend to use Google Analytics to measure usage of your service, you will need to integrate with tracking consent. The HeadWithTrackingConsent component is a replacement to the existing Head component and generates the HTML SCRIPT tags necessary to integrate with tracking-consent-frontend

Before integrating, it is important to remove any existing snippets relating to GTM or Optimizely, for example, through use of the Head or GTMSnippet components. Tracking consent manages the enabling of these third-party solutions based on the user's tracking preferences. If they are not removed there is a risk the user's tracking preferences will not be honoured.

Configure your service's GTM container in conf/application.conf. For example, if you have been instructed to use GTM container a, the configuration would appear as:

tracking-consent-frontend {
  gtm.container = "a"
}

gtm.container can be one of: a, b, c, d, e, f or sdes. Consult with the CIPSAGA team to understand which GTM container you should be using in your service.

If you are already using the Head template, simply replace with HeadWithTrackingConsent.

If you are not using Head, locate in your frontend code the location where common Javascripts and stylesheets are added to the HTML HEAD element. Add TrackingConsentSnippet above the other assets in the HEAD tag. For example,

@this(trackingConsentSnippet: TrackingConsentSnippet)

...

@trackingConsentSnippet()

<link href='path-to-asset.css' media="all" rel="stylesheet" type="text/css" />
...

If using Play 2.7 and CSPFilter, the nonce can be passed to tracking consent as follows:

@import views.html.helper.CSPNonce
...
@trackingConsentSnippet(nonce = CSPNonce.get)
...

Adding to your service

Add the library to the project dependencies:

libraryDependencies += "uk.gov.hmrc" %% "play-language" % "[INSERT VERSION]"

Ensure to add the resolvers to your plugins.sbt:

resolvers += MavenRepository("HMRC-open-artefacts-maven2", "https://open.artefacts.tax.service.gov.uk/maven2")
resolvers += Resolver.url("HMRC-open-artefacts-ivy", url("https://open.artefacts.tax.service.gov.uk/ivy2"))(Resolver.ivyStylePatterns)

addSbtPlugin("uk.gov.hmrc" % "sbt-auto-build" % "[INSERT VERSION 3.0.0 OR HIGHER]")

If you require either Head or Footer you'll also need to add some config to your application.conf file in order to build the complete urls for assets:

assets {
  version = "x.x.x"
  url = ""
}

Play Framework and Scala compatibility notes

This library is currently compatible with:

  • Scala 2.12
  • Play 2.6, Play 2.7, Play 2.8

And with the addition of support for Play 2.8 we have had to remove compatibility with Scala 2.11.

Additionally, the deprecated static helpers for components available in versions targeting up to Play 2.7 have been excluded from versions targeting Play 2.8. When upgrading your service to Play 2.8 you will now need to include components via Dependency Injection within templates instead.

How to test changes locally

Publish the library locally with

sbt clean compile publishLocal

This will build and install the library into your local Ivy cache. The final lines of the output will contain the version number.

Then update the configuration of your frontend application to use this version number. This is in different files depending on the application. In business-tax-account, it is in FrontendBuild.scala. In one-time-password-frontend, it is in MicroServiceBuild.scala. The line will look like "uk.gov.hmrc" %% "play-ui" % "4.10"

now restart your frontend application, and you will see your local changes.

n.b. you will need to run the sbt command to publish locally each time you make a change.

License

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