README.md

CCS GOV.UK Frontend Jinja Macros

This is a fork of GOV.UK Frontend Jinja Macros which has not been updated beyond GOV.UK Frontend v5.1. This is for use in the Digital Marketplace until it starts to get updated again.

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.

Compatibility

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

CCS GOV.UK Frontend Jinja Version	Target GOV.UK Frontend Version
1.3.0	5.7.1
1.2.2	5.5.0
1.2.1	5.4.1
1.2.0	5.4.0
1.1.0	5.4.0
1.0.0	5.3.1

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

Use GOV.UK Frontend Jinja Macros for older versions of GOV.UK Frontend

How to use

After running pip install ccs-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 and you can run them locally with pytest.

You will need to download the GOV.UK Frontend package via npm with:

npm i

You can install the requirements for your chosen version of Python with:

pip install -r requirements-test-<YOUR_PYTHON_VERSION>.txt

You can then run the tests with:

pytest

The tests compare the HTML for each component fixture, which are within the GOV.UK Frontend package, with HTML generated by the Jinja macros.

Versioning

Releases of this project follow semantic versioning, ie

Given a version number MAJOR.MINOR.PATCH, increment the:

• MAJOR version when you make incompatible API changes,
• MINOR version when you add functionality in a backwards-compatible manner, and
• PATCH version when you make backwards-compatible bug fixes.

To make a new version:

• update the version in the digitalmarketplace_frontend_jinja/__init__.py file
• if you are making a major change, also update the change log;

When the pull request is merged a GitHub Action will tag the new version.

Pre-commit hooks

This project has a pre-commit hook to do some general file checks and check the pyproject.toml. Follow the Quick start to see how to set this up in your local checkout of this project.

Licence

Unless stated otherwise, the codebase is released under the MIT License. This covers both the codebase and any sample code in the documentation.

The documentation is © Crown copyright and available under the terms of the Open Government 3.0 licence.