Metadata-Version: 2.5
Name: django-admin-loading
Version: 0.1.0
Summary: Shows a loading spinner whenever a form is submitted in the Django admin (works with django-unfold).
Project-URL: Homepage, https://github.com/cheverebe/django-admin-loading
License: MIT
License-File: LICENSE
Keywords: admin,django,loading,spinner,unfold
Classifier: Framework :: Django
Classifier: Framework :: Django :: 4.2
Classifier: Framework :: Django :: 5.0
Classifier: Framework :: Django :: 5.1
Classifier: Framework :: Django :: 5.2
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Requires-Python: >=3.10
Requires-Dist: django>=4.2
Provides-Extra: unfold
Requires-Dist: django-unfold; extra == 'unfold'
Description-Content-Type: text/markdown

# django-admin-loading

Shows a full-page loading spinner whenever a form is submitted in the Django admin.
Works with the stock admin and with [django-unfold](https://github.com/unfoldadmin/django-unfold).

## Install

```bash
pip install git+https://github.com/cheverebe/django-admin-loading.git
```

## Setup

Add the app to `INSTALLED_APPS` **before** `unfold` and `django.contrib.admin`:

```python
INSTALLED_APPS = [
    "django_admin_loading",  # must come first
    "unfold",                # optional
    "django.contrib.admin",
    ...
]
```

That's it. The app overrides `admin/base.html` (and, for Unfold, `unfold/layouts/skeleton.html`,
which Unfold's login page extends directly). Each override extends the next template of the
same name, so the original admin or Unfold layout is still used. Ordering matters
because Django picks the first matching template in `INSTALLED_APPS` order.

## Behaviour

- The spinner appears on any `submit` event that wasn't cancelled with `preventDefault()`,
  so client-side validation and confirm dialogs don't leave it stuck.
- It fades in after a short delay (150 ms), so instant responses don't flash it.
- Forms or buttons opening a new tab (`target="_blank"`) or using `method="dialog"` are ignored.
- It is hidden again when a page is restored from the back/forward cache.
- It follows light/dark mode (Django admin and Unfold) and uses the Unfold primary colour when present.

### Opt out

```html
<form data-no-spinner> ... </form>
<button type="submit" data-no-spinner>Export</button>
```

Use this for responses that download a file (e.g. CSV export actions): the page doesn't
navigate away, so the spinner would otherwise stay up. You can also control it from JS:

```js
DjangoAdminLoading.show();
DjangoAdminLoading.hide();
```

### Customise

Override the CSS variables on `#dal-overlay` (`--dal-color`, `--dal-bg`) in your own stylesheet.

## Development

```bash
uv pip install django django-unfold
DJANGO_SETTINGS_MODULE=tests.settings python -m django test tests                 # stock admin
WITH_UNFOLD=1 DJANGO_SETTINGS_MODULE=tests.settings python -m django test tests   # with unfold
```

## License

MIT
