hmrc/play-ui

Core for HMRC's UI, incl. formatters, validators, mappers and helper templates

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.

play-ui's Issues

Input Id should not contain dot characters, should use Play Framework's method field.id.

Input Id should not contain dot characters and should use Play Framework's inbuilt method field.id rather than using field.name. field.id essentially replaces . characters with _

. characters cause problems with Javascript/Jquery as anything after the dot is incorrectly treated as a class.

I have fixed the issues for my use case, however there are more places in Play-UI where id=field.name instead of field.id

Please see my forked commit linked below:
https://github.com/LukeDeighton/play-ui/commit/806023bfec292d71781d088fd053cf6d1fc0d019

Shared view templates are not mentioned in README

Following #3, we have shared view templates in this library but they're not described in the README.md.

@alexanderjamesking

Add support for Welsh language

Welsh language support is a common business requirement that many teams have to implement. This has lead to different teams creating different ways to achieve the same result. I propose moving the logic into play-ui so that it is common across all teams and can be easily implemented. Alternatively, would this be better within its own 'play-language-support' project?

errorSummary does not support Messages with arguments

https://github.com/hmrc/play-ui/blob/master/src/main/twirl/uk/gov/hmrc/play/views/helpers/errorSummary.scala.html

Does not support ValidationErrors with a message and args.
So when using the Play validation defaults like text(maxLength = 1200)) the resulting message is "Maximum Length is {0}" instead of "Maximum Length is 1200"

Datefields could use an input text variant

Currently the date helper use drop downs for each field.

A text box variant could be useful.

validDateTuple references a non existent message

When entering all letters for a date using validDateTuple (eg a bb cccc) the validation message seen on screen is "error.enter_numbers".
This is because in messages.en, there is a typo where an extra underscore is included at the end - "error.enter_numbers_"

Footer missing an h2 for meta links

An internal accessibility review found that our footer was missing an h2.
"Check that you are using the most recent code to generate the footer. The H2 text ‘Support links’ looks to be missing - h2 class="govuk-visually-hidden"/>Support links h2/>
See GOV.UK design system https://design-system.service.gov.uk/components/footer/ the section ‘Footer with links to meta information’ seems to match the layout you have."

<legend> ending up beneath <label>

Hi, I'm not sure if this is due to the way our team used it but we were experiencing a problem with the elements when rendered. The issue was two fold.

The Yes on the first label, or any first element was dropping to the next line when rendered and the legend was being covered by the . I attempted a couple of workarounds using CSS and Z-Index and all failed. In the end I took the out of the Helper and put it directly in front of the helper so it rendered then the helper. This solved both problems.
Using firebug I think the issue is with the Clear:none; on the block-label

Add a CONTRIBUTING.md file and a "Contributing" section to the README

There's no explanation on how to run this library locally to see changes before opening a PR.

Also a CONTRIBUTING.md file is missing

Whitespace padding on <option> display values

The dropdown helper adds whitespace padding to the option display values. This is more noticeable when used in conjunction with the accessible-autocomplete component (https://github.com/alphagov/accessible-autocomplete)

Currently it looks like:-

After the code change:-

I created a unit test which failed and then the dropdown helper was modified to remove the whitespace

[info] @helpers.dropDown
[info] - should render element options *** FAILED ***
[info] "...ntry-AU" value="AU">[ Australia ]" was not equal to "...ntry-AU" value="AU">[Australia]" (DropDownSpec.scala:45)

The PR for this is #77

Textarea helper does not support setting of HTML standard tags.

When using the textArea helper it is not possible to set the tags laid out in its specification.

The fields the helper supports are: _labelAfter, _divClass, _labelClass, _label, _info, _inputClass, and _help

This does not include things like rows or maxlength etc.

Because the maxlength and data tags cannot be defined, the helper cannot be used in conjunction with the Character Counter in assets-frontend.

Layout of @sidebar as aside within main is failing DAC assessment

https://github.com/hmrc/play-ui/blob/master/src/main/twirl/uk/gov/hmrc/play/views/layouts/MainContent.scala.html accepts Html content for sidebar - it then renders an aside element within the main element to contain the Html content.

Our DAC assessment is failing us because of this layout, we have been pointed to wai-aria guidance on usage of asides: https://www.w3.org/TR/wai-aria-practices-1.1/#aria_lh_complementary

Inline style attributes need refactoring

Problem

There are a number of places where inline style attributes have been used instead of using the correct element.

• singleCheckbox.scala.html
• simpleFieldConstructor.scala.html
• dropdown.scala.html
• dropdown.scala.html

Solution

Change the span elements to div elements and remove the style attributes

Remove global JS variable once everyone moves to url-builder

play-ui/src/main/twirl/uk/gov/hmrc/play/views/layouts/footer.scala.html

Line 42 in 163b6f3

<script type="text/javascript">var ssoUrl = "@ssoUrl.getOrElse("")";</script>

Question on Feildset

Hi is there anyway I can stop the fieldset getting written as I've already got a

before so I end up with fieldet -> legend -> feildset.
Any help appreciated.

The reportAProblemLink helper uses object Messages instead of implicit instance.

Instead of the implicit instance of Messages class, the helper still uses the Messages object:
https://github.com/hmrc/play-ui/blob/master/src/main/twirl/uk/gov/hmrc/play/views/helpers/reportAProblemLink.scala.html#L19
https://github.com/hmrc/play-ui/blob/master/src/main/twirl/uk/gov/hmrc/play/views/helpers/reportAProblemLink.scala.html#L20