landregistry / govuk-frontend-jinja

GOV.UK Frontend Jinja Macros

GOV.UK Frontend Jinja Macros

GOV.UK Frontend Jinja is a community tool of the GOV.UK Design System. The Design System team is not responsible for it and cannot support you with using it. Contact the maintainers directly if you need help or you want to request a feature.

This repository provides a complete set of Jinja macros that are kept up-to-date and 100% compliant with the original GOV.UK Frontend Nunjucks macros. Porting is intentionally manual rather than automated to make updates simpler than maintaining an automated conversion routine. A comprehensive test suite ensures compliance against the latest, and every subsequent, GOV.UK Frontend release.

If you are looking to build a fully featured Flask app that integrates with GOV.UK Frontend Jinja and GOV.UK Frontend WTForms please use the GOV.UK Frontend Flask template repository to generate your app.

Compatibility

The following table shows the version of GOV.UK Frontend Jinja that you should use for your targeted version of GOV.UK Frontend:

GOV.UK Frontend Jinja Version	Target GOV.UK Frontend Version
3.0.0	5.1.0
2.8.0	4.8.0
2.7.0	4.7.0
2.6.0	4.6.0
2.5.0	4.5.0
2.4.0	4.4.1
2.3.0	4.2.0
2.2.0	4.1.0
2.1.0	4.0.1
2.0.0	4.0.0
1.6.0	3.15.0
1.5.1	3.14.0
1.4.0	3.13.0
1.3.0	3.12.0
1.2.1	3.11.0
1.1.0	3.10.2
1.0.0	3.8.1
0.2.1	3.7.0

Any other versions of GOV.UK Frontend not shown above may still be compatible, but have not been specifically tested and verified.

How to use

After running pip install govuk-frontend-jinja, ensure that you tell Jinja where to load the templates from using the PackageLoader as follows:

from flask import Flask
from jinja2 import ChoiceLoader, PackageLoader, PrefixLoader

app = Flask(__name__)

app.jinja_loader = ChoiceLoader(
    [
        PackageLoader("app"),
        PrefixLoader({"govuk_frontend_jinja": PackageLoader("govuk_frontend_jinja")}),
    ]
)

Calling a Macro in your template

To use a component in your project templates you must import and call the component macro and pass the relevant options, for example:

{%- from 'govuk_frontend_jinja/components/button/macro.html' import govukButton -%}

{{ govukButton({
  'text': "Save and continue"
}) }}

The options available to each component macro can be found in the original GOV.UK Design System Components documentation. Since this project is a like-for-like port, the only difference between the Nunjucks examples and their Jinja equivalents is having to quote key names, e.g. 'text' instead of text.

Running the tests

The tests are run in a GitHub actions pipeline but if you want to run them locally you will need to install govuk-frontend-diff.

There is a test server at tests/utils/app.py which you will need to run using the following command:

(cd tests/utils && python -m flask run --port 3000)

You can then run the tests using govuk-frontend-diff as follows:

./govuk-frontend-diff http://localhost:3000 --govuk-frontend-version=v4.8.0

This is all wrapped up in ./test.sh for simplified running (Requires Docker).

Versioning

We use SemVer for versioning. For the versions available, see the tags on this repository.

How to contribute

We welcome contribution from the community. If you want to contribute to this project, please review the code of conduct and contribution guidelines.

Update methodology

How to update this package following a new release of GOV.UK Frontend:

1. On govuk-frontend, compare the last compatible tag and the latest tag, e.g. https://github.com/alphagov/govuk-frontend/compare/v4.3.1...v4.4.0
2. If there are any changes to templates in package/govuk/components/<component>/template.njk read the diff and apply the same changes to the Jinja equivalent templates in govuk_frontend_jinja/templates/components/<component>/macro.html
3. Take into account any idiosyncrasies between how Nunjucks and Jinja would interpret that template. E.g. None checking nested attributes, checking array items lengths or logic operators such as is, not and in.
4. Run the tests as described above
5. Resolve any failing tests by comparing the expected HTML output with the actual HTML reported by the test tool
6. Add a new row to the compatibility table above to show which version of GOV.UK Frontend the next release of this package will be targeting.
7. Once all tests are passing follow the contribution guidelines to raise a pull request.
8. After the pull request has been merged, create a new release and tag following SemVer conventions.
9. GitHub Actions will run on the new tag to build the package and publish it to PyPI. Verify that the package has been updated with the latest release tag by checking the project page

Contributors

• Matt Shaw (Primary maintainer)
• Andy Mantell (Original author)

See the full list of contributors on GitHub

Support

This software is provided "as-is" without warranty. Support is provided on a "best endeavours" basis by the maintainers and open source community.

If you are a civil servant you can sign up to the UK Government Digital Slack workspace to contact the maintainers listed above and the community of people using this project in the #govuk-design-system channel.

Otherwise, please see the contribution guidelines for how to raise a bug report or feature request.

govuk-frontend-jinja's Issues

Add dependency scanning tools into pipeline

Add dependency scanning tools into pipeline to check for up to date packages, security vulns etc

'isPageHeading': True does not work with file-upload macro

Describe the bug
'isPageHeading': True does not work with file-upload macro

To Reproduce
Steps to reproduce the behavior:
Go to "With label as page heading" on https://govuk-frontend-jinja.herokuapp.com/components/file-upload

Expected behavior
"Upload a file" should look like a heading

Screenshots
If applicable, add screenshots to help explain your problem.

Desktop (please complete the following information):

• OS: iOS
• Browser: chrome
• Version: 97.0.4692.71

Upgrade GOV.UK Frontend to 5.3.0

GOV.UK Frontend should be upgraded from 5.1.0 to 5.3.0.

Testing approach

          Hi @matthew-shaw I work at Crown Commercial Service and look after the Digital Marketplace (which used to be managed by GDS).

We have a frontend repo for Digital Marketplace components (like GOV.UK Frontend) which contains Nunjucks components and the Flask apps would do some magic (as far as I'm concerned) to allow Jinja to parse the Nunjucks templates. Because this is not going to be maintainable long term I've created a project, inspired by this project, Digital Marketplace Jinja Templates which contains Jinja Templates.

Now I originally looked at forking govuk-frontend-diff and doing something similar for Digital Marketplace but I saw in the README that the GOV.UK Frontend package now includes fixtures (i.e. the expected HTML for the component with different params). So for the next release of Digital Marketplace Frontend, because it was not already, I made it generated fixtures with the HTML for all the components.

I've created an app which responds to requests to generate the components. Within the test it gets all of the fixtures from the node module and generates a set of pytest fixtures to test. It then sends the request to the app and then compares the response.

Now, because there can be difference in how things are rendered (i.e. the indent is slightly different or Nunjucks having true where as Jinja will have True) I have added a method html_to_one_line which "normalises" the results so they can be compared.

This not a perfect solution by any means and may not be what you want with this project but I thought it might be useful to share considering you seem to be at a bit of bottleneck with how you're going to test from v5 onward.

Originally posted by @tim-s-ccs in #70 (comment)

Passing bodyAttributes to main template throws error

If you pass bodyAttributes to the base page template you get the following error thrown by Jinja2:

Traceback (most recent call last):
  File "/Users/andym/work/govuk-frontend-jinja/tests/utils/render.py", line 58, in <module>
    print(template.render(**context))
  File "/Users/andym/work/govuk-frontend-jinja/venv/lib/python3.7/site-packages/jinja2/environment.py", line 1090, in render
    self.environment.handle_exception()
  File "/Users/andym/work/govuk-frontend-jinja/venv/lib/python3.7/site-packages/jinja2/environment.py", line 832, in handle_exception
    reraise(*rewrite_traceback_stack(source=source))
  File "/Users/andym/work/govuk-frontend-jinja/venv/lib/python3.7/site-packages/jinja2/_compat.py", line 28, in reraise
    raise value.with_traceback(tb)
  File "<template>", line 2, in top-level template code
  File "/Users/andym/work/govuk-frontend-jinja/tests/utils/../../govuk_frontend_jinja/templates/template.html", line 30, in top-level template code
    <body class="govuk-template__body {{ bodyClasses }}" {%- for attribute, value in bodyAttributes %} {{attribute}}="{{value}}"{% endfor %}>
ValueError: too many values to unpack (expected 2)

Create pipeline for publishing to PyPi

Should run the tests, linting, dependency checks etc before finally publishing to PyPi

Inject html classes to macros

Is your feature request related to a problem? Please describe.
I would like to be able to add classes to HTML generated by macros. I am trying to follow the logic in 'govuk_frontend_jinja/templates/components/select/macro.html' in order to include an extra class to the select field definition, however there doesn't appear to be a clear logic to do this alongside govuk wtforms. I am perhaps missing something.

Describe the solution you'd like
Documentation/guidance on how to include additional classes into a GovUk wtforms field definition

Describe alternatives you've considered

• Writing my own version of the macro to include the additional class I need (but this is clearly not a good idea)
• Injecting the class into the raw html outputted by the widget (but this is clearly an even worse idea)

Additional context
Add any other context or screenshots about the feature request here.

In-line JS blocked by CSP

When using a strict CSP such as default-src: 'self', the in-line JS in the default GOV.UK page template is blocked, leading to components that rely on JS such as the accordion not functioning properly. This requires a nonce to be passed on each request to the script-src CSP header and the <script> tag.

A second instance of this problem occurs within the bodyEnd block, but can be overridden within inherited templates, allowing the nonce to be added. However the first instance lives within the base template in the package itself.

Need to be able to pass the nonce to the default template, but in a way that isn't exclusive to just one extension such as Flask Talisman, which implements a specific Jinja macro call.