play-frontend-govuk

Twirl implementation of the govuk-frontend components library as documented in the GOV.UK Design System.

Table of Contents

• Background
• Getting Started
• Usage
• API
• Dependencies
• Contributing
• Useful Links
• Owning Team Readme
• License

Background

This library provides accessibility-compliant Twirl basic building blocks as originally implemented in the govuk-frontend library. Additionally, it provides a layout that wraps the GovukTemplate, used across all frontends, and we plan to include more helpers built on top of Play's own helpers and the basic components. The following figure illustrates the components and their dependencies (zoom in for a better view).

Getting started

Installation

For most developers, this library should be brought in via play-frontend-hmrc. This means that you do NOT need to add this library as a dependency of your project. Instead, follow the instructions to add play-frontend-hmrc to your project, and that library will manage asset compilations, routes, etc.

If you do need to use this library directly, follow the standalone instructions.

Using govuk-frontend Components in Twirl

To use the govuk-frontend Twirl components and all the types needed to construct them, import the following:

@import uk.gov.hmrc.govukfrontend.views.html.components._

Twirl HTML helper methods and implicits

The above import will also bring into scope the available Twirl helpers and layouts.

The following import will summon implicits that provide extension methods on Play's FormError to convert between Play's form errors and view models used by GovukErrorMessage and GovukErrorSummary (E.g. form.errors.asTextErrorLinks, form.errors.asTextErrorMessageForField):

@import uk.gov.hmrc.govukfrontend.views.html.components.implicits._

...
    @formWithCSRF(action = routes.NameController.onSubmit(mode)) {

    @if(form.errors.nonEmpty) {
      @errorSummary(ErrorSummary(errorList = form.errors.asTextErrorLinks, title = Text(messages("error.summary.title"))))
    }

      @input(Input(id = "value", name = "value", value = form.value,
        errorMessage = form.errors.asTextErrorMessageForField(fieldKey = "value"),
        label = Label(isPageHeading = true, classes = "govuk-label--l", content = Text(messages("name.heading"))))) 
 }
...

It also provides extension methods on Play's Html objects. This includes HTML trims, pads, indents and handling HTML emptiness.

An example usage of GovukLayout template

A convenient way of setting up a view with standard structure and Govuk design elements is provided. Instead of directly invoking GovukTemplate, use GovukLayout and pass in GovUk assets wiring in head and scripts elements. The following example snippet sets up a common local layout shared by view pages which then delegates to the standard GovukLayout.

@this(
  govukLayout: GovukLayout,
  head: head,
  scripts: scripts
)

@(pageTitle: Option[String] = None,
  beforeContentBlock: Option[Html] = None
)(contentBlock: Html)(implicit request: Request[_], messages: Messages)

@govukLayout(
  pageTitle = pageTitle,
  headBlock = Some(head()),
  beforeContentBlock = beforeContentBlock,
  footerItems = Seq(FooterItem(
    href = Some("https://govuk-prototype-kit.herokuapp.com/"), 
    text = Some("GOV.UK Prototype Kit v9.1.0"))),
  bodyEndBlock = Some(scripts()))(contentBlock)

The above snippet uses some sensible defaults (e.g. initial language) and configs (e.g. header config) to render a page. One of the optional parameters of GovukLayout is headerBlock. It can be composed of Header element. However, if no header block is passed in but simply the following i18n message keys being present, the following Header element is constructed:

Header(
  homepageUrl = Some(messages("service.homePageUrl")),
  serviceName = Some(messages("service.name")),
  serviceUrl = Some(messages("service.homePageUrl")),
  containerClasses = Some("govuk-width-container")
)

The above snippet is based on the premise that a header could be in different languages when supporting i18n standards.
GovukLayout leverages local head and scripts template for assets wiring. The local head view template looks like the following:

@this()

@()
<!--[if lte IE 8]><link href='@controllers.routes.Assets.versioned("stylesheets/application-ie-8.css")' rel="stylesheet" type="text/css" /><![endif]-->
<!--[if gt IE 8]><!--><link href='@controllers.routes.Assets.versioned("stylesheets/application.css")' media="all" rel="stylesheet" type="text/css" /><!--<![endif]-->

The local scripts view template looks like the following:

@this()

@()
<script src='@controllers.routes.Assets.versioned("lib/govuk-frontend/govuk/all.js")'></script>
<script>window.GOVUKFrontend.initAll();</script>

The head view template requires the following application.scss in app/assets/stylesheets folder which gets compiled to application.css by sbt-sassify

$govuk-assets-path: "/play-mtp-frontend/assets/lib/govuk-frontend/govuk/assets/";

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

.app-reference-number {
  display: block;
  font-weight: bold;
}

Please note that the /play-mtp-frontend/ in $govuk-assets-path is the context root path of the frontend using the library.

A reference implementation can be found in play-mtp-twirl-frontend

Usage

The library is cross-compiled for Play 2.6 and Play 2.7.

As of v0.57.0 (January 2021), this library will no longer be cross-compiled against Play 2.5.

Play 2.6

The same namespace exposes type aliases prefixed with Govuk (ex: the type GovukButton) so that components can be injected into a controller or template. It also exposes values of the same name (ex: GovukButton) if you wish to use the component template directly, though it is preferable to use dependency injection.

Same button using DI:

@import uk.gov.hmrc.govukfrontend.views.html.components._

@this(govukButton: GovukButton)

@()
@govukButton(Button(
  disabled = true,
  content = Text("Disabled button")
))

Example Templates

We provide example templates using the Twirl components through a Chrome extension. Please refer to the extension's github repository for installation instructions.

With the extension installed, you should be able to go to the GOV.UK Design System, click on a component on the sidebar and see the Twirl examples matching the provided Nunjucks templates.

Note: Currently there are examples only for the following components:

• Back link
• Button
• Details
• Error message
• Error summary
• Fieldset
• Footer
• Header
• Panel
• Radios
• Summary list
• Textarea
• Text input

API

As of v0.63.0, a method withFormField(field: play.api.data.Field) method has been added to the following classes:

• CharacterCount
• Checkboxes
• Input
• Radios
• Select
• Textarea

This new method allows a Play forms Field to be passed through when creating an instance of play-frontend-govuk form input, which will enrich the input with the following:

• Using the Field name for the input name
• Using the Field name for the input id or idPrefix
• Using the Field error message
• Using the Field value as pre-filled value (for CharacterCount, Input, Textarea) or pre-selected value (Checkboxes, Radios, Select)

The methods can be used as methods in a Twirl template as demonstrated below:

@import uk.gov.hmrc.govukfrontend.views.html.components.implicits._

@this(govukInput)

@(label: String, field: Field)(implicit messages: Messages)

@govukInput(
  Input(
    label = Label(classes = labelClasses, content = Text(label))
  ).withFormField(field)
)

If a value is passed though to the input .apply() method during construction, it will NOT be overwritten by the Field values. These are only used if the object parameters are not set to the default parameters.

Note that you will need to pass through an implicit Messages to your template.

TODO: link to scaladoc

Dependencies

sbt Dependencies

The library depends on a govuk-frontend artifact published as a webjar.

"org.webjars.npm" % "govuk-frontend" % "x.y.z"

Currently GDS does not automate the publishing of the webjar so it has to be manually published from WebJars after a govuk-frontend release.

Getting help

Please report any issues with this library in Slack at #event-play-frontend-beta.

For other issues or wider discussions, please use #team-plat-ui.

Contributing

PlatUI and this repository is responsible for providing a means to access GOV.UK components in Play/Twirl. However, the underlying components, their design and surrounding user research are owned by GDS under GOV.UK.

If you would like to propose a feature, you should raise this with GDS and the wider design community.

If you have an issue with the underlying govuk-frontend implementation, you can create an issue for them to address directly. You could also look at raising a feature request there too.

Should GOV.UK accept your feature request, it will then be available in Twirl once the appropriate upgrade is made in this repository to match that version upgrade.

Useful Links

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

Owning team README

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

License

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