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:

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.