govuk-frontend-jinja 1.5.1

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.

• Package: https://pypi.org/project/govuk-frontend-jinja/
• Demo app: https://github.com/LandRegistry/govuk-frontend-jinja-demo
• Live demo: https://govuk-frontend-jinja.herokuapp.com/

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
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 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 Desing 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=v3.14.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.

Contributors

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

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.