Metadata-Version: 2.5
Name: django-admin-inline-controls
Version: 0.1.1
Summary: Pagination, filtering and ordering for Django admin inlines.
Project-URL: Homepage, https://github.com/rodolvbg/django-admin-inline-controls
Project-URL: Issues, https://github.com/rodolvbg/django-admin-inline-controls/issues
Project-URL: Repository, https://github.com/rodolvbg/django-admin-inline-controls
Author-email: Rodolfo Valentín Becerra García <rodolvbg@gmail.com>
Maintainer-email: Rodolfo Valentín Becerra García <rodolvbg@gmail.com>
License-Expression: MIT
License-File: LICENSE
Keywords: admin,django,filter,inline,ordering,pagination
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Web Environment
Classifier: Framework :: Django
Classifier: Framework :: Django :: 4.2
Classifier: Framework :: Django :: 5.0
Classifier: Framework :: Django :: 5.1
Classifier: Framework :: Django :: 5.2
Classifier: Framework :: Django :: 6.0
Classifier: Framework :: Django :: 6.1
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: django>=4.2
Provides-Extra: dev
Requires-Dist: coverage[toml]>=7.4; extra == 'dev'
Requires-Dist: django-stubs[compatible-mypy]>=5; extra == 'dev'
Requires-Dist: mypy>=1.10; extra == 'dev'
Requires-Dist: pre-commit>=4; extra == 'dev'
Requires-Dist: pytest-cov>=5; extra == 'dev'
Requires-Dist: pytest-django>=4.8; extra == 'dev'
Requires-Dist: pytest-playwright>=0.5; extra == 'dev'
Requires-Dist: pytest>=8; extra == 'dev'
Requires-Dist: ruff>=0.6; extra == 'dev'
Requires-Dist: tox-uv>=1; extra == 'dev'
Requires-Dist: tox>=4; extra == 'dev'
Provides-Extra: filters
Requires-Dist: django-filter>=23.2; extra == 'filters'
Provides-Extra: nested
Requires-Dist: django-nested-admin>=4.1; extra == 'nested'
Provides-Extra: unfold
Requires-Dist: django-unfold>=0.108; (python_version >= '3.12') and extra == 'unfold'
Description-Content-Type: text/markdown

# django-admin-inline-controls

[![Build status](https://github.com/rodolvbg/django-admin-inline-controls/actions/workflows/pytest.yml/badge.svg)](https://github.com/rodolvbg/django-admin-inline-controls/actions/workflows/pytest.yml)
[![PyPI version](https://img.shields.io/pypi/v/django-admin-inline-controls.svg)](https://pypi.org/project/django-admin-inline-controls/)
[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/django-admin-inline-controls)](https://pypi.org/project/django-admin-inline-controls/)
[![PyPI - Django Version](https://img.shields.io/pypi/djversions/django-admin-inline-controls)](https://pypi.org/project/django-admin-inline-controls/)
[![Downloads](https://static.pepy.tech/personalized-badge/django-admin-inline-controls?period=month&units=international_system&left_color=black&right_color=blue&left_text=Downloads/month)](https://pepy.tech/project/django-admin-inline-controls)

Pagination, filtering and sortable columns for Django admin inlines —
without leaving the change form.

![A tabular inline with an action menu and two selected rows, filters, sorting by pages, View/Feature/Delete buttons on each row, Total and Average rows, page links and the Save books button](https://raw.githubusercontent.com/rodolvbg/django-admin-inline-controls/HEAD/docs/screenshots/hero.png)

- **Pagination**: page links, or infinite scroll that appends rows as you
  reach the end of the inline.
- **Filters**: generated from lookups (`"status"`, `"title__icontains"`,
  `"published__gte"`), your own `forms.Form`, or a django-filter `FilterSet`.
- **Sortable columns**: click a tabular header (or the toolbar links on
  stacked inlines); multi-column, like the changelist.
- Filters, sorting and page links refresh **only that inline** in place.
  Several controlled inlines on the same page keep independent state.
- Rows loaded from several pages are saved together, and unsaved edits are
  never silently thrown away.
- Optional **"Save books" button** that saves only that inline, without
  submitting (or reloading) the rest of the page.
- **Actions** on the selected rows, like the changelist's: checkboxes,
  "select all", an action menu and a built-in `delete_selected`.
- **Footer rows** for totals, averages…: `Sum("pages")` below its column.
- Only depends on Django. No jQuery plugins, no htmx; works with
  `TabularInline` and `StackedInline`.

## Install

```bash
pip install django-admin-inline-controls
```

Add to `INSTALLED_APPS`:

```python
INSTALLED_APPS = [
    ...
    "django_admin_inline_controls",
]
```

## Usage

Mix `InlineControlsMixin` in before `TabularInline` or `StackedInline`:

```python
from django.contrib import admin
from django.db.models.functions import Lower

from django_admin_inline_controls.mixins import InlineControlsMixin


class BookInline(InlineControlsMixin, admin.TabularInline):
    model = Book
    extra = 0
    inline_per_page = 20
    inline_ordering_fields = {
        "title": Lower("title"),  # column name -> ordering expression
        "published": "published",
        "pages": "pages",
    }
    inline_filter_fields = ["title__icontains", "status", "featured", "published__gte"]


@admin.register(Author)
class AuthorAdmin(admin.ModelAdmin):
    inlines = [BookInline]
```

State lives in the URL, namespaced by the formset prefix
(`?books-page=2&books-o=-pages&books-f-status=published`), so links are
shareable and several inlines never clash.

### Options

| Attribute | Default | |
|---|---|---|
| `inline_per_page` | `None` | Rows per page. `None` disables pagination. |
| `inline_pagination` | `"pages"` | `"pages"` or `"infinite"` (load more on scroll). |
| `inline_ordering_fields` | `()` | Sortable columns: a list of field names, or `{column: expression}`. The expression can be a field path, an ORM expression (`Lower("title")`, `F("date").asc(nulls_last=True)`) or an explicit `(ascending, descending)` pair. |
| `inline_default_ordering` | `()` | Applied after the user's ordering. Defaults to the queryset's / model's ordering; `pk` is always appended so pages are stable. |
| `inline_filter_fields` | `()` | Filter lookups. A form is generated from them. |
| `inline_filter_form` | `None` | Your own filter `forms.Form`. |
| `inline_controls_ajax` | `True` | Refresh the inline in place instead of reloading the page. |
| `inline_save_button` | `False` | Show a button that saves only this inline. See [Saving only the inline](#saving-only-the-inline). |
| `inline_bulk_actions` | `()` | Actions for the selected rows. See [Bulk actions](#bulk-actions). |
| `inline_actions` | `()` | Buttons on each saved row, as in django-inline-actions. See [Row actions](#row-actions). |
| `inline_footer_rows` | `()` | Rows of totals, averages… below the table. See [Footer rows](#footer-rows). |
| `inline_footer_scope` | `"filtered"` | What the footer rows add up: `"filtered"` or `"page"`. |
| `inline_footer_tfoot` | `True` | Render the footer rows in the table's `<tfoot>` (tabular inlines); `False` shows them as a summary line. |
| `inline_footer_tfoot_template` | `django_admin_inline_controls/tfoot.html` | Template of that `<tfoot>`. |

Only columns declared in `inline_ordering_fields` can be sorted: ordering
by an arbitrary field from the URL would let anyone infer the values of
fields the inline never shows.

### Custom filters

Generated fields depend on the model field and lookup (choices → select,
`BooleanField` → Yes/No/any, dates → date input, relations →
`ModelChoiceField`, `__in` → multiple select, `__isnull` → Yes/No/any…).
Override `get_inline_filter_formfield(lookup)` to change one, or bring
your own form and handle the fields that aren't plain lookups:

```python
class BookFilterForm(forms.Form):
    q = forms.CharField(required=False, label="Search")
    status = forms.ChoiceField(
        required=False, choices=[("", "---"), *Book.Status.choices]
    )


class BookInline(InlineControlsMixin, admin.TabularInline):
    model = Book
    inline_per_page = 20
    inline_filter_form = BookFilterForm
    inline_filter_fields = ["status"]  # applied as lookups; "q" is handled below

    def filter_inline_queryset(self, request, queryset, filters):
        if search := filters.get("q"):
            queryset = queryset.filter(Q(title__icontains=search) | Q(isbn=search))
        return super().filter_inline_queryset(request, queryset, filters)
```

Every option also has a `get_*` hook taking `(request, obj)` —
`get_inline_per_page`, `get_inline_ordering_fields`,
`get_inline_filter_fields`, `get_inline_filter_form_class`,
`get_inline_filter_form_kwargs` (e.g. to pass the parent object to your
form) — and `get_inline_filtered_queryset()` is the single seam to plug in
any other filtering backend.

### Infinite scroll

```python
class ArticleInline(InlineControlsMixin, admin.TabularInline):
    model = Article
    inline_per_page = 30
    inline_pagination = "infinite"
```

The next page is appended when the "Load more" link scrolls into view (or
is clicked). Loaded rows join the formset, so everything visible is saved
with the object. Keep in mind Django's formset limits: by default a
formset accepts at most 1000 forms per submission (`max_num`).

### Saving only the inline

```python
from django_admin_inline_controls.mixins import (
    InlineControlsAdminMixin,
    InlineControlsMixin,
)


class BookInline(InlineControlsMixin, admin.TabularInline):
    model = Book
    inline_per_page = 20
    inline_save_button = True


@admin.register(Author)
class AuthorAdmin(InlineControlsAdminMixin, admin.ModelAdmin):
    inlines = [BookInline]
```

A **"Save books"** button (named after the inline's `verbose_name_plural`)
appears in the inline's footer, next to the pagination.

![The "Save books" button after saving an edited row](https://raw.githubusercontent.com/rodolvbg/django-admin-inline-controls/HEAD/docs/screenshots/save-inline.png)

**How it works**

- Only that inline is sent: the JS posts its fields (files included), its
  management form and the CSRF token with `fetch`. Nothing from the parent
  form or from the other inlines.
- The server builds just that formset against the parent object **as
  stored in the database** (not the unsaved parent form), checks the
  permissions, validates it and calls your `save_formset()` inside a
  transaction. The change is recorded in the parent's history ("Changed
  Title for book X"), like a regular admin save; a save with no changes
  records nothing.
- The response is the re-rendered inline, swapped in place:
  - on errors, they are shown on their rows, as in a normal save, and the
    submitted values are kept so they can be fixed and saved again;
  - on success, a "Saved." status is shown and the inline no longer counts
    as having unsaved changes.
- Unsaved changes elsewhere on the page (the parent form, other inlines)
  are left untouched: still on screen, still unsaved.
- The current filters, ordering and page are kept. In infinite mode, as
  many pages as were loaded are shown again after saving.

**Requirements and caveats**

1. **The parent `ModelAdmin` needs `InlineControlsAdminMixin`.** An inline
   cannot register URLs of its own, so the endpoint lives on the parent
   admin (`<object_id>/inline-controls/<prefix>/save/`). A system check
   (`admin_inline_controls.E008`) reports a missing mixin; without it no
   button is shown.
2. **Permissions:** the user needs change permission on the parent object
   (as for any save from the change form) and add, change or delete
   permission on the inline's model. Within the formset, the inline's own
   permissions apply exactly as in the change form (view-only rows are
   not validated, rows can only be deleted with delete permission, …).
3. **`save_formset(request, form, formset, change)` gets an unchanged
   parent form**, built from the saved instance (`changed_data` is empty),
   because the real one was not submitted. If you override `save_formset()`
   and read `form.cleaned_data`, that won't work from this button.
   `save_model()` and `save_related()` are not called, so the parent's own
   fields (e.g. an `auto_now` "modified" date) are not updated.
4. **Changes to the parent form are not saved** by this button. It says so
   in its tooltip; use the admin's regular "Save" buttons to save
   everything.
5. Not available on nested_admin inlines (`admin_inline_controls.E102`).

### Bulk actions

Like `ModelAdmin.actions`, for the rows of one inline:

```python
from django.contrib import admin, messages
from django_admin_inline_controls.actions import inline_action
from django_admin_inline_controls.mixins import (
    InlineControlsAdminMixin,
    InlineControlsMixin,
)


class BookInline(InlineControlsMixin, admin.TabularInline):
    model = Book
    inline_per_page = 20
    inline_bulk_actions = ["mark_published", "export_csv", "delete_selected"]

    @inline_action(
        permissions=["change"],
        description="Mark selected %(verbose_name_plural)s as published",
    )
    def mark_published(self, request, queryset):
        count = queryset.update(status=Book.Status.PUBLISHED)
        self.message_user(request, f"{count} books published.", messages.SUCCESS)

    @inline_action(description="Export selected %(verbose_name_plural)s to CSV")
    def export_csv(self, request, queryset):
        response = HttpResponse(content_type="text/csv")
        response["Content-Disposition"] = 'attachment; filename="books.csv"'
        ...
        return response


@admin.register(Author)
class AuthorAdmin(InlineControlsAdminMixin, admin.ModelAdmin):
    inlines = [BookInline]
```

![Inline actions: row checkboxes, the action menu and the selection count](https://raw.githubusercontent.com/rodolvbg/django-admin-inline-controls/HEAD/docs/screenshots/actions.png)

**How it works**

- Every saved row gets a checkbox next to its name; the action bar at the
  top of the inline has a "select all rows on this page" checkbox, the
  action menu, **Go** and the "2 of 25 selected" count. When the whole
  page is selected and there are more rows, **"Select all 25"** extends the
  selection to every row matching the current filters, on every page.
- The checkboxes and the menu are not part of the change form: they are
  never submitted when the object is saved, and ticking them doesn't count
  as an unsaved change.
- **Go** posts only the action name and the selected primary keys. The
  action runs on a queryset that is always restricted to children of the
  object being edited (and to the current filters), so a tampered primary
  key can't reach other rows.
- If the inline has unsaved edits, you are asked first: the inline is
  re-rendered after the action, so they would be lost.

**Writing actions**

- Same signature as changelist actions: `action(inline, request,
  queryset)`. Entries of `inline_bulk_actions` can be method names, callables or
  `"delete_selected"`. The parent object is `request.inline_controls_parent`.
- `@inline_action` is `@admin.action` (`permissions`, `description`) plus
  `confirmation`: a prompt shown before running. `description` and
  `confirmation` may use `%(verbose_name)s` and `%(verbose_name_plural)s`;
  `confirmation` also `%(count)s`, the number of rows it will run on.
  Plain `@admin.action` functions work too.
- `permissions=["change"]` checks the inline's `has_change_permission()`
  (with the parent object); actions the user may not run are not offered,
  and are refused if posted anyway.
- Use `self.message_user()` as in a `ModelAdmin`: the messages are shown
  next to the action menu.
- Return `None` to re-render the inline (keeping the page, filters and
  ordering; in infinite mode, the loaded rows), a file response (it is
  downloaded and the page stays as is), or a redirect (followed). Any other
  response replaces the page.
- Actions don't record anything in the history by themselves, as in the
  changelist. The built-in **`delete_selected`** deletes the rows one by
  one (so `delete()` overrides and signals run), asks "Delete 3 selected
  books? This cannot be undone.", records the deletions in the parent's
  history and reports rows protected by `on_delete=PROTECT` instead of
  failing.

**Requirements:** like the save button, `InlineControlsAdminMixin` on the
parent `ModelAdmin` (`admin_inline_controls.E010`), and the user needs view
or change permission on the parent object. Not available on nested_admin
inlines (`admin_inline_controls.E103`).

### Row actions

Buttons on each saved row, in an **Actions** column: no selection, no menu,
no "Go". The API is [django-inline-actions](https://github.com/escaped/django-inline-actions)'s
— `inline_actions`, `get_inline_actions(request, obj)`, `ViewAction`,
`DeleteAction`, `(request, obj, parent_obj=None)` — so its inlines move
here by changing the imports.

![Row actions: View, Feature/Unfeature and Delete on each row](https://raw.githubusercontent.com/rodolvbg/django-admin-inline-controls/HEAD/docs/screenshots/row-actions.png)

```python
from django_admin_inline_controls.actions import DefaultActionsMixin


class BookInline(DefaultActionsMixin, InlineControlsMixin, admin.TabularInline):
    model = Book
    inline_actions = ["toggle_featured"]  # plus View and Delete

    def toggle_featured(self, request, obj, parent_obj=None):
        obj.featured = not obj.featured
        obj.save(update_fields=["featured"])
        self.message_user(request, f"“{obj}” updated.", messages.SUCCESS)

    def get_toggle_featured_label(self, obj):
        return "Unfeature" if obj.featured else "Feature"
```

- **`inline_actions`** lists method names or callables, and is gathered
  from every class of the inline (bases first): mixins add theirs.
  `inline_actions = None` removes the column.
- **Built-in:** the mixins `ViewAction` (`view_action`: a link to the row's
  change view, when its model has one on the site and the user may view
  it), `DeleteAction` (`delete_action`: asks "Delete “Book 01”? This cannot
  be undone.", deletes it like `delete_selected` and records it in the
  parent's history; needs the delete permission) and `DefaultActionsMixin`
  (both). Without a mixin, list `"view"` / `"delete"`.
- **Your own**, as methods or callables, in either form:
  - `action(self, request, obj, parent_obj=None)` for one row;
  - `action(self, request, queryset)`, like a [bulk action](#bulk-actions)
    (`@inline_action`, `permissions`, `confirmation`…), run on a queryset
    with only that row: the same function can be in both lists.
- **Per row:** the label, CSS classes and HTML attributes come from the
  function's `short_description`, `css_classes` and `attribute_properties`
  (a dict, escaped, or a string), or from `get_<action>_label(obj)`,
  `get_<action>_css(obj)` and `get_<action>_attr(obj)` on the inline.
  Override `get_inline_actions(request, obj)` to offer some actions on
  some rows only (`obj` is the row; the parent is
  `request.inline_controls_parent`), as `DeleteAction` does.
- They return what bulk actions do: `None` re-renders the inline with the
  messages from `self.message_user()` (shown in its footer), a file is
  downloaded, a redirect is followed.
- The buttons are rendered by the server, in a read-only column added to
  the inline's fields (`render_inline_actions`, as in django-inline-actions;
  put it in your `fields` or `fieldsets` to place it yourself), and shown
  once the JS is ready. Its template is `inline_actions_template`
  (`django_admin_inline_controls/row_actions.html`).

**Coming from django-inline-actions:** change
`inline_actions.admin.InlineActionsMixin` for `InlineControlsMixin`,
`inline_actions.actions` for `django_admin_inline_controls.actions`, and put
`InlineControlsAdminMixin` on the parent `ModelAdmin` instead of
`InlineActionsModelAdminMixin`. The actions run without submitting the
whole change form (unsaved changes elsewhere on the page are kept), only
the inline is refreshed, and each action's `permissions` are checked by the
server before it runs. Buttons on the changelist's rows aren't covered:
keep `InlineActionsModelAdminMixin` for those, next to
`InlineControlsAdminMixin` (they don't clash on a `ModelAdmin`).

**Requirements:** as for bulk actions, `InlineControlsAdminMixin` on the
parent `ModelAdmin` (`admin_inline_controls.E019`); not available on
nested_admin inlines (`admin_inline_controls.E105`). They only appear in
the change view, once the parent exists.

### Footer rows

Totals, averages or any other summary below the inline's columns:

```python
from django.db.models import Avg, Count, Sum


class BookInline(InlineControlsMixin, admin.TabularInline):
    model = Book
    inline_per_page = 20
    inline_footer_rows = [
        ("Total", {"title": Count("pk"), "pages": Sum("pages")}),
        ("Average", {"pages": Avg("pages")}),
    ]
```

![Total and Average rows below the Pages column](https://raw.githubusercontent.com/rodolvbg/django-admin-inline-controls/HEAD/docs/screenshots/footer-rows.png)

- Each row is a label and `{column: value}`. A value is an **aggregate**
  (`Sum`, `Avg`, `Count`, `Max`…, `filter=` included), a
  **`callable(queryset)`** for anything else, or a constant. All the
  aggregates of all the rows run in **one query**.
- **What is added up** — `inline_footer_scope`:
  - `"filtered"` (default): every row matching the current filters, on
    every page. With infinite scroll it doesn't depend on what is loaded.
  - `"page"`: the rows shown (not available with infinite scroll,
    `admin_inline_controls.E016`).
- Values come from the **database**. The rows follow filtering, sorting,
  paging, saving the inline and actions, since they arrive with the
  refreshed inline — with `inline_save_button`, saving the inline updates
  them without reloading the page.
- **Where they go — rendered by the server, no JS:** on tabular inlines,
  the rows are the table's own `<tfoot>`, each value under its column; the
  label spans the columns before the first value. The inline's template is
  rendered as usual (Django's, a theme's or your own) and the `<tfoot>` is
  inserted before its `</table>`, so there is no copy of Django's template
  to keep in sync. On stacked inlines, with `inline_footer_tfoot = False`,
  or when a value's column isn't a column of the table, they are a summary
  line in the footer ("Total: Pages 3250").
- **In the add view** there are no saved rows to aggregate yet: tabular
  inlines get the same `<tfoot>`, labels and `data-*` attributes with empty
  values (`data-value=""`), for your JS to fill in from the new rows if you
  want; `get_inline_footer_rows(request, obj)` gets `obj=None`. Stacked
  inlines show nothing until the object is saved.

#### Changing how they look

- **The values' format**, in Python: by default the plain value, floats
  and decimals rounded to 2 decimals at most (`1234.5`). Override
  `format_inline_footer_value(column, value)` for currencies, units,
  localized numbers… (return safe HTML for markup):

  ```python
  from django.utils.formats import number_format

  def format_inline_footer_value(self, column, value):
      if column == "amount":
          return format_html("{} <small>USD</small>", number_format(value, 2))
      return super().format_inline_footer_value(column, value)
  ```

- **Which rows**, in Python: `get_inline_footer_rows(request, obj)` — e.g.
  one row per VAT rate from your own model method.
- **The markup**, in templates: the `<tfoot>` is
  `django_admin_inline_controls/tfoot.html` (blocks `tfoot`, `tfoot_row`,
  `tfoot_label`, `tfoot_cell`, `tfoot_value`), chosen per inline with
  `inline_footer_tfoot_template`; the summary line is in `footer.html`
  (blocks `footer_rows`, `footer_row`, `footer_cell`). Extend them and
  override only the block you need:

  ```django
  {% extends "django_admin_inline_controls/tfoot.html" %}
  {% block tfoot_value %}<strong>{{ slot.cell.value }}</strong>{% endblock %}
  ```

#### Using the values from your own JS

Every value is in the HTML the server renders, with its raw number, for
your scripts to read — nothing to call:

| Attribute / selector | What it is |
|---|---|
| `[data-footer-key="<row index>:<column>"]` | A value's element (in the `<tfoot>` or the summary). |
| `data-footer-row`, `data-column` | Its row label and column. |
| `data-value` | Its number as plain digits (`"1234.5"`), `""` when it isn't a number; the element's text is the formatted value. |

```js
const total = document.querySelector(
    '#books-inline-controls [data-footer-row="Total"][data-column="pages"]',
);
Number(total.dataset.value); // 3250
```

When the inline is refreshed in place (filtering, paging, saving it,
actions) the footer comes back re-rendered, and `inline-controls:updated`
bubbles from the new content: read the values again there.

## Optional extras

The core only depends on Django. Integrations with third-party packages are
opt-in.

### django-filter

```bash
pip install django-admin-inline-controls[filters]
```

```python
from django_admin_inline_controls.contrib.filters import FilterSetInlineControlsMixin


class BookInline(FilterSetInlineControlsMixin, admin.TabularInline):
    model = Book
    inline_per_page = 20
    inline_filterset_class = BookFilterSet

    def get_inline_filterset_kwargs(self, request, obj):
        return {"parent": obj}  # extra kwargs for your FilterSet's __init__
```

The filterset gets the request too (`self.request`).

### django-nested-admin

```bash
pip install django-admin-inline-controls[nested]
```

```python
import nested_admin
from django_admin_inline_controls.contrib.nested import NestedInlineControlsMixin


class BookInline(NestedInlineControlsMixin, nested_admin.NestedTabularInline):
    model = Book
    inline_per_page = 20
```

nested_admin keeps its own client-side formset state, so with it filters,
sorting and page links reload the page instead of swapping the inline, and
infinite scroll, the save-inline button and bulk and row actions are not
available.

### Themes

- [django-unfold](https://github.com/rodolvbg/django-admin-inline-controls/blob/HEAD/docs/themes/unfold.md): `UnfoldInlineControlsMixin` (the
  `unfold` extra).

## Customizing templates

Three templates render the controls around the inline's own `template`
(which is left untouched: `admin/edit_inline/tabular.html`, a custom one,
…). Each is chosen per inline, so a template of yours can extend the
library's and override only the blocks it needs:

| Option | Default | Renders |
|---|---|---|
| `inline_controls_template` | `django_admin_inline_controls/inline.html` | The wrapper: toolbar, the inline itself, footer. |
| `inline_controls_toolbar_template` | `django_admin_inline_controls/toolbar.html` | Actions, filters, sort links. |
| `inline_controls_footer_template` | `django_admin_inline_controls/footer.html` | Pagination / infinite scroll, save button. |

```python
class BookInline(InlineControlsMixin, admin.TabularInline):
    model = Book
    inline_controls_toolbar_template = "admin/demo/book_inline_toolbar.html"
```

```django
{# templates/admin/demo/book_inline_toolbar.html #}
{% extends "django_admin_inline_controls/toolbar.html" %}

{% block filter_apply_label %}Search{% endblock %}

{% block filter_field %}
  <div class="my-filter">{{ block.super }}</div>
{% endblock %}

{% block toolbar_end %}
  <a href="{% url 'book-help' %}">Help</a>
{% endblock %}
```

To change them for every inline, put templates with the same paths in your
project's `templates/` directory (before the app templates), or set the
options on a base inline class of your own.

In all three, `controls` is the inline's state (filter form, ordering
columns, page links, actions, URLs…) and `inline_admin_formset` is
Django's. The JS finds its elements by the `inline-controls-*` classes, the
`data-inline-controls-*` attributes and the container's id: keep them when
you replace a block's markup (`{{ block.super }}` keeps the original).

**`inline.html`**

| Block | Contains |
|---|---|
| `container` | The whole wrapper `<div>`. |
| `container_classes`, `container_attrs` | Extra classes / attributes for the wrapper (empty). |
| `before_toolbar`, `before_inline`, `after_inline`, `after_footer` | Empty slots between the parts. |
| `toolbar` | Includes `inline_controls_toolbar_template`. |
| `inline` | Includes the inline's own template. |
| `footer` | Includes `inline_controls_footer_template`. |
| `inline_without_controls` | What is rendered when the controls are off (the add view): the inline and, if it has footer rows, their empty `<tfoot>`. |

**`toolbar.html`**

| Block | Contains |
|---|---|
| `toolbar` | The whole toolbar. |
| `toolbar_classes` | Extra classes (empty). |
| `toolbar_start`, `toolbar_end` | Empty slots at both ends. |
| `actions` | The action bar. |
| `action_menu`, `action_label`, `action_empty_option`, `action_option` | The "Action:" select and its options (`action_option` is rendered once per action, with `action`). |
| `action_button`, `action_button_label` | The **Go** button. |
| `action_selection` | The "2 of 25 selected" count and the "Select all" link. |
| `action_status` | Where action messages appear. |
| `filters` | The filter form. |
| `filter_fields`, `filter_field` | All fields / one field (once per field, with `field`). |
| `filter_buttons`, `filter_apply_button`, `filter_apply_label`, `filter_clear_button`, `filter_clear_label` | The **Filter** and **Clear** buttons. |
| `ordering`, `ordering_label`, `ordering_column` | The "Sort by:" links (once per column, with `column`). |

**`footer.html`**

| Block | Contains |
|---|---|
| `footer` | The whole footer. |
| `footer_classes` | Extra classes (empty). |
| `footer_start`, `footer_end` | Empty slots at both ends. |
| `footer_rows`, `footer_row`, `footer_cell` | The footer rows' summary line (`footer_row` once per row, with `row`; `footer_cell` once per value, with `cell`), when they aren't in the table's `<tfoot>`. |
| `pagination` | Page links or the infinite-scroll status. |
| `page_links`, `page_link` | The page links (`page_link` once per link, with `link`). |
| `result_count` | "25 results". |
| `infinite`, `infinite_count`, `load_more`, `load_more_label` | Infinite mode: "Showing 15 of 70" and "Load more". |
| `save`, `save_status`, `save_button`, `save_label` | The save-inline button and its status. |
| `row_actions_status` | Where the row actions' messages appear. |

**`row_actions.html`** (one row's buttons): `row_actions`, `row_action`
(once per action, with `action`: `name`, `label`, `css_classes`, `attrs`,
`confirmation` and, for `view`, `url`).

**`inline_response.html`** (the save/action endpoints' response):
`response`, `inlines`. Set `inline_controls_response_template` on the
`ModelAdmin` to use another one.

## Adapting to another admin markup

The templates decide the HTML of the controls, but the JS also has to find
its way in the **inline's** markup — Django's `tabular.html` /
`stacked.html`, or whatever your theme (Unfold, Jazzmin, Grappelli…) or
your own inline template renders. Where to look is configurable per inline
with `inline_controls_selectors`, merged over these defaults
(`DEFAULT_SELECTORS` in `django_admin_inline_controls.controls`):

| Key | Default | Used for |
|---|---|---|
| `container` | `.inline-group fieldset` | Where the toolbar and footer are moved to. |
| `heading` | `h2` | Inside `container`: the toolbar goes right after it (or its `<summary>`). |
| `footer_parent` | `:scope > details` | Inside `container`: the footer is appended here, else to `container`. |
| `table_head` | `.inline-group table thead` | The header row with the sortable columns. |
| `column_header` | `th.column-{name}` | A sortable column's header (`{name}`: the column). |
| `form_rows` | `[id]` | Inside the inline group: each form's container (`{prefix}`: the formset's). Its index comes from its id (`<prefix>-<n>`) or, without one, from its fields' names. |
| `saved_row` | `.has_original` | A form container of a saved object (not a new one). |
| `row_label` | `:scope > td.original > p`, `:scope > h3`, `:scope > td.original` | Inside a saved row: where its action checkbox goes. |
| `tabular_rows` | `{group} .tabular.inline-related tbody:first > tr.form-row` | jQuery selector of the rows Django's `inlines.js` manages, re-initialized after a refresh (`{group}`: `#<prefix>-group`). |
| `stacked_rows` | `{group} .inline-related` | The same for stacked inlines. |

Each value is one selector or a list tried in order. Only set the keys that
differ:

```python
class BookInline(InlineControlsMixin, admin.TabularInline):
    model = Book
    template = "admin/my_theme/tabular.html"
    inline_ordering_fields = ["title", "pages"]
    inline_controls_selectors = {
        "container": ".card",
        "heading": ".card-title",
        "table_head": "table.grid thead",
        "column_header": 'th[data-col="{name}"]',
        "row_label": ":scope > td.row-name > .label",
        "tabular_rows": "{group} table.grid tbody > tr.form-row",
    }
```

For a whole theme, set it on a base inline class of your own. When
something isn't found, the controls degrade instead of breaking: sort links
stay in the toolbar if a column header is missing, checkboxes go into the
row itself, and the toolbar and footer stay around the inline. The
management form and the fields' names come from Django's formset, so they
are never configured. On tabular inlines, the footer rows are laid out
under the header cells with the `column-<field>` class, whatever columns
come before or after them.

To place the toolbar and footer yourself, listen for
`inline-controls:place` (it bubbles from the controls' wrapper,
`.inline-controls`, before they are moved) and cancel it:

```js
document.addEventListener("inline-controls:place", (event) => {
    const { toolbar, footer } = event.detail;
    event.target.querySelector(".my-panel-header").append(toolbar);
    event.target.querySelector(".my-panel-footer").append(footer);
    event.preventDefault();
});
```

## System checks

Misconfigurations are reported by `manage.py check` (and at startup):

| ID | Problem |
|---|---|
| `admin_inline_controls.E001` | `inline_pagination` is not `"pages"` or `"infinite"`. |
| `admin_inline_controls.E002` | `inline_per_page` is not a positive integer or `None`. |
| `admin_inline_controls.E003` | `inline_pagination = "infinite"` without `inline_per_page`. |
| `admin_inline_controls.E004` | `inline_filter_fields` is a string instead of a list or tuple. |
| `admin_inline_controls.E005` | `inline_filter_fields` refers to a field the model doesn't have. |
| `admin_inline_controls.E006` | `inline_ordering_fields` is not a list, tuple or dict. |
| `admin_inline_controls.E007` | An `inline_ordering_fields` column starts with `-` or contains a comma. |
| `admin_inline_controls.E008` | `inline_save_button = True` but the parent `ModelAdmin` lacks `InlineControlsAdminMixin`. |
| `admin_inline_controls.E009` | An `inline_bulk_actions` entry is not a method of the inline, a callable or a built-in action. |
| `admin_inline_controls.E010` | `inline_bulk_actions` is set but the parent `ModelAdmin` lacks `InlineControlsAdminMixin`. |
| `admin_inline_controls.E018` | An `inline_actions` entry is not a method of the inline, a callable or a built-in row action. |
| `admin_inline_controls.E019` | `inline_actions` is set but the parent `ModelAdmin` lacks `InlineControlsAdminMixin`. |
| `admin_inline_controls.E011` | `inline_controls_selectors` is not a dict. |
| `admin_inline_controls.E012` | An `inline_controls_selectors` key is unknown, or its value is not a selector or a non-empty list of selectors. |
| `admin_inline_controls.E013` | `inline_footer_rows` is not a list of `(label, {column: value})` pairs. |
| `admin_inline_controls.E014` | An `inline_footer_rows` column is not a field of the model or of the inline. |
| `admin_inline_controls.E015` | `inline_footer_scope` is not `"filtered"` or `"page"`. |
| `admin_inline_controls.E016` | `inline_footer_scope = "page"` with infinite scroll. |
| `admin_inline_controls.E017` | `inline_footer_tfoot` is not `True` or `False`. |
| `admin_inline_controls.E101` | `inline_pagination = "infinite"` on a nested_admin inline. |
| `admin_inline_controls.E102` | `inline_save_button = True` on a nested_admin inline. |
| `admin_inline_controls.E103` | `inline_bulk_actions` on a nested_admin inline. |
| `admin_inline_controls.E104` | Unfold's `per_page` on an inline with `UnfoldInlineControlsMixin`. |
| `admin_inline_controls.E105` | `inline_actions` on a nested_admin inline. |

## JavaScript files

Each inline loads only the scripts it uses, through its `media`: `core.js`
(pagination, filters, sorting, placing the controls) always, `save.js`
with `inline_save_button`, `actions.js` with `inline_bulk_actions` or
`inline_actions`, and
`contrib/unfold.js` with `UnfoldInlineControlsMixin`. The admin merges the
media of every inline on the page, so each file loads at most once.

## JavaScript events

After an inline is refreshed in place, or rows are appended, an
`inline-controls:updated` event bubbles from the new content: hook your own
widget initialization there (or read the footer values again, see
[Using the values from your own JS](#using-the-values-from-your-own-js)).
Before the toolbar and footer are placed, a
cancelable `inline-controls:place` event bubbles from the controls'
wrapper (see [Adapting to another admin markup](#adapting-to-another-admin-markup)). The admin's own inline machinery, autocomplete,
date/time shortcuts and `filter_horizontal` widgets are re-initialized
automatically.

## Demo

```bash
cd example
python manage.py migrate
python manage.py seed_demo      # admin/admin + an author with many books
python manage.py runserver

```

## Translations

Ships a Spanish (`es`) translation; every text of the controls — the
toolbar, the footer, the generated filter labels ("Title (contains)"), the
action messages and the JS prompts, which the server sends already
translated — follows the admin's active language.

Messages identical to Django admin's own ("Filter", "Delete selected
%(verbose_name_plural)s", …) use the admin's translation, since
`django.contrib.admin` comes first in `INSTALLED_APPS`: the inline then
reads exactly like the changelist.

## Compatibility

Django 4.2 – 6.1, Python 3.10+.

## License

MIT
