TNA Frontend Jinja

TNA Frontend Jinja templates are a Jinja implementation of the templates provided as part of TNA Frontend as well as widgets for WTForms.

# Install with Poetry
poetry add tna-frontend-jinja

# Install with pip
pip install tna-frontend-jinja

See the documentation.

Quickstart for Flask projects

Use the Flask application's jinja_loader to allow templates included from either your app (in the below example called app) and the tna_frontend_jinja package.

Ensure your application is first on the list. This means you can overwrite the standard templates by creating a template with the same filename in your project.

from flask import Flask
from jinja2 import ChoiceLoader, PackageLoader


def create_app():
    app = Flask(__name__)

    app.jinja_loader = ChoiceLoader(
        [
            PackageLoader("app"),  # Use your application directory here
            PackageLoader("tna_frontend_jinja"),
        ]
    )

Quickstart for Django projects

Update the TEMPLATES setting in your application config:

TEMPLATES = [
    # Add the Jinja2 backend first
    {
        "BACKEND": "django.template.backends.jinja2.Jinja2",
        "DIRS": [
            os.path.join(BASE_DIR, "app/templates"),  # Use your application directory here
            os.path.join(get_path("platlib"), "tna_frontend_jinja/templates"),
        ],
        "APP_DIRS": True,
        "OPTIONS": {
            "environment": "config.jinja2.environment",
        },
    },
    # The DjangoTemplates backend is still needed for tools like Django admin and the debug toolbar
    {
        "BACKEND": "django.template.backends.django.DjangoTemplates",
        "DIRS": [],
        "APP_DIRS": True,
        "OPTIONS": {
            "context_processors": [
                "django.template.context_processors.debug",
                "django.template.context_processors.request",
                "django.contrib.auth.context_processors.auth",
                "django.contrib.messages.context_processors.messages",
            ],
        },
    },
]

Ensure your application is first on the list of template directories. This means you can overwrite the standard templates by creating a template with the same filename in your project.

Using the templates

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

{{ tnaButton({
  'text': 'Save and continue'
}) }}

The options available to each component macro can be found in the National Archives Design System Components documentation.

⚠️ The included templates are 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.

We test each component against its published component fixtures to ensure complete compatibility.

Overriding templates

To make modifications to the templates, create a new file in your applciation templates directory with the same name as the template you want to customise.

For example, if your application templates directory is app/templates, create app/templates/components/button/macro.html and insert your own HTML using the same macro name (e.g. tnaButton).

This way you can continue to use the same import (e.g. {%- from 'components/button/macro.html' import tnaButton -%}) but introduce your own bespoke functionality.

WTForms support

# Install with Poetry
poetry add tna-frontend-jinja[wtforms]

# Install with pip
pip install tna-frontend-jinja[wtforms]

See the TNA Frontend Jinja WTForms docs for more information.

Running tests

# Start the test server
docker compose up -d

# Install the dependencies
npm install

# Run the fixture tests
npm run test:fixtures

# Run the Playwright tests
npm run test:playwright

# Run the Python tests
docker compose exec app poetry run python -m pytest

Styles and JavaScript

The CSS and JavaScript are not included in the PyPI package. You must install them separately.

Install and use the @nationalarchives/frontend package from npm with npm install @nationalarchives/frontend.

Ensure you install the correct version of TNA Frontend for the version of the templates you are using.

Compatibility with TNA Frontend

v1+

v0.3.x

v0.2.x

v0.1.x