govuk-flask-admin 0.2.7
Add your description here
Requires Python: >=3.12

# A "GOV.UK Frontend" theme for Flask-Admin

This package is designed to make it trivial to re-skin a [Flask-Admin](https://github.com/pallets-eco/flask-admin) 
extension to have a consistent look and feel to many UK Government services, by using layouts, components and 
patterns from the great [GOV.UK Design System](https://design-system.service.gov.uk/) (among other x-gov resources).

## How to integrate with Flask-Admin

Make sure your Flask app's Jinja environment is configured to load templates from at least the sources listed below.
Then initialise Flask-Admin and govuk-flask-admin appropriately, making sure to pass the GOV.UK Frontend Theme to
Flask-Admin.

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

from flask_admin import Admin
from govuk_flask_admin import GovukFlaskAdmin, GovukFrontendTheme

app = Flask(...)
app.jinja_options = {
    "loader": ChoiceLoader(
        [
            PrefixLoader({"govuk_frontend_jinja": PackageLoader("govuk_frontend_jinja")}),
            PrefixLoader({"govuk_frontend_wtf": PackageLoader("govuk_frontend_wtf")}),
            PackageLoader("govuk_flask_admin"),
        ]
    )
}

admin = Admin(app, theme=GovukFrontendTheme())
govuk_flask_admin = GovukFlaskAdmin(app)
```

All of your SQLAlchemy model fields should derive from govuk-flask-admin's `GovukModelView`, not from Flask-Admin's
`sqla.ModelView`.

## Recognition / attribution

This extension / theme has only been made possible by standing on a huge corpus of existing work across government, 
including but not limited to:

- [GOV.UK Design System](https://design-system.service.gov.uk/)
- [Ministry of Justice Frontend](https://design-patterns.service.justice.gov.uk/)
- [Accessible autocomplete](https://alphagov.github.io/accessible-autocomplete/examples/)
- [GOV.UK Publishing Components](https://components.publishing.service.gov.uk/component-guide)
- HMLR's [govuk-frontend-jinja](https://github.com/LandRegistry/govuk-frontend-jinja) and [govuk-frontend-wtf] 
  (https://github.com/LandRegistry/govuk-frontend-wtf) libraries

And, of course, [Flask-Admin](https://github.com/pallets-eco/flask-admin) itself.

## Compatibility

### Python

`govuk-flask-admin` will aim to be compatible with all supported versions of Python released from 2025, but this 
package was put together in 2025 and I'm placing a lower bound of support on Python 3.12.

### Flask-Admin
Not all features of Flask-Admin are currently supported, or likely to be supported in the future.

| Feature                                    | Support status | Notes                                                                   |
|--------------------------------------------|----------------|-------------------------------------------------------------------------|
| Nested service navigation menu items       | Future         | Support Flask-Admin's "menu category" better, probably JS-only          |
| Create new records                         | Yes            |                                                                         |
| List existing records                      | Yes            |                                                                         |
| Keyword search when listing records        | Yes            |                                                                         |
| Apply filters when listing records         | Yes            |                                                                         |
| Custom filters when listing records        | ~              |                                                                         |
| Sort results                               | Yes            |                                                                         |
| Changing page size when listing results    | Yes            |                                                                         |
| Custom page sizes                          | Yes            |                                                                         |
| Performing bulk actions on results         | Yes            |                                                                         |
| View existing records                      | Yes            |                                                                         |
| Edit existing records                      | Yes            |                                                                         |
| Delete existing records                    | Yes            |                                                                         |
| Edit relationships                         | Yes            |                                                                         |
| Edit 'large' relationships                 | Future         | If a related table is large, performance will degrade rapidly           |
|                                            |                | because every related record is a choice in the select/dropdown menu.   |
|                                            |                | A future approach might be to dynamically load results from an API call | 
| Edit datetime fields                       | Yes            |                                                                         |
| Edit one-to-many relationships             | Yes            |                                                                         |
| Standardised default GOV.UK error messages | Future         |                                                                         | 

### GOV.UK Frontend

`govuk-flask-admin` is packaged with compiled static assets that are served directly by the extension. This is a 
technical constraint applied because `govuk-frontend-jinja` and `govuk-frontend-wtf` are themselves designed for 
specific versions of GOV.UK Frontend.

Since `govuk-flask-admin` compiles assets from GOV.UK Frontend (and other x-gov frontend components), it will be 
locked to specific versions of `govuk-frontend-jinja` and `govuk-frontend-wtf`.

It may be possible to compile bundles for various versions of GOV.UK Frontend, in order to support various 
combinations of `govuk-frontend-jinja` and `govuk-frontend-wtf` in the future, but this is not currently planned.

The latest release of `govuk-flask-admin` will generally track the latest release of GOV.UK Frontend, 
`govuk-frontend-jinja`, and `govuk-frontend-wtf`.

| Package              | Currently supported version |
|----------------------|-----------------------------|
| GOV.UK Frontend      | 5.12.0                      |
| govuk-frontend-jinja | 3.8.0                       |
| govuk-frontend-wtf   | 3.2.0                       |

## Developing this extension

### Running tests

Tests can be run against multiple Python versions (eg 3.13 and 3.14) using tox. The test suite is split into 
unit/integration tests and e2e tests to avoid async loop conflicts with playwright:

```bash
# Run all tests (unit, integration, and e2e) across all Python versions
uv run tox

# Run only unit and integration tests
uv run tox -e py313,py314

# Run only e2e tests
uv run tox -e py313-e2e,py314-e2e

# Run tests for a specific Python version
uv run tox -e py313           # unit + integration only
uv run tox -e py313-e2e       # e2e only
```

### Rebuilding GOV.UK Frontend assets

GOV.UK Flask Admin uses and extends the GOV.UK Frontend CSS and JS in order to add functionality required to display 
information and action dense admin pages.

These assets are compiled using Flask-Vite.

#### One-off setup

1. Install Node LTS (currently v20)
2. Run `flask vite install`
3. Run `flask vite build` to compile GOV.UK Frontend assets and copy them into `govuk_flask_admin/static`
4. Commit the newly compiled assets.

### Doing a release