NHS.UK frontend jinja templates

A Jinja implementation of the NHS.UK frontend components.

NHS.UK frontend contains the code you need to start building user interfaces for NHS websites and services.

Installation

pip install nhsuk-frontend-jinja

Compatibility

The following table shows the version of NHS.UK frontend jinja that you should use for your targeted version of NHS.UK frontend:

NHS.UK frontend version	NHS.UK frontend jinja version
9.3.0	0.1.0
9.5.2	0.2.0
9.6.1	0.3.0
9.6.2	0.3.1
10.0.0	0.4.1
10.1.0	0.5.0
10.2.0	0.6.0
10.2.2	0.6.1
10.3.0	0.7.0
10.3.1	0.7.2
10.4.0	0.8.0

Configuration

Configure your Jinja environment to load templates from this package and use ChainableUndefined.

Flask example:

from jinja2 import FileSystemLoader, ChoiceLoader, PackageLoader, ChainableUndefined

app.jinja_options = {
    "undefined": ChainableUndefined,  # This is needed to prevent jinja from throwing an error when chained parameters are undefined
    "loader": ChoiceLoader(
        [
            FileSystemLoader(PATH_TO_YOUR_TEMPLATES),
            PackageLoader("nhsuk_frontend_jinja"),
        ]
    ),
    "autoescape": True
}

Plain Jinja example:

from jinja2 import Environment, FileSystemLoader, ChoiceLoader, PackageLoader, ChainableUndefined

jinja_env = Environment(
    undefined=ChainableUndefined,
    loader=ChoiceLoader([
        FileSystemLoader(PATH_TO_YOUR_TEMPLATES),
        PackageLoader("nhsuk_frontend_jinja"),
    ]),
    autoescape=True,
)

Alternatively, if you want to reference components without the 'nhsuk/components' or 'nhsuk/macros' prefixes, you can include additional PackageLoaders that specify package_path:

ChoiceLoader([
    FileSystemLoader(PATH_TO_YOUR_TEMPLATES),

    PackageLoader("nhsuk_frontend_jinja", package_path="templates/nhsuk/components"),
    PackageLoader("nhsuk_frontend_jinja", package_path="templates/nhsuk/macros"),

    PackageLoader("nhsuk_frontend_jinja"),
])

You should then be able to extend the default page template:

{% extends 'nhsuk/template.jinja' %}

{% block pageTitle %}Example - NHS.UK Frontend{% endblock %}

{% block content %}
{% endblock %}

See Page Template in the service manual for details of all the options.

Usage

Visit the NHS digital service manual for examples of components and guidance for when to use them.

All our macros take identical arguments to the Nunjucks ones, except you need to quote the parameter names.

{% from 'nhsuk/warning-callout/macro.jinja' import warningCallout %}

{{ warningCallout({
  "heading": "Quotey McQuoteface",
  "HTML": "<p>Don't forget to quote your parameter names!</p>"
}) }}

Note that all macro paths use the .jinja extension.

Contribute

Read our contributing guidelines to contribute to NHS.UK frontend jinja.

Development environment

Get in touch

This repo is maintained by NHS England. Open a GitHub issue if you need to get in touch.

Licence

The codebase is released under the MIT Licence, unless stated otherwise. This covers both the codebase and any sample code in the documentation. The documentation is © NHS England and available under the terms of the Open Government 3.0 licence.