django-admin-filter-kit

Русский · English

Небольшие дополнения к фильтрам списков в админке Django:

• AutocompleteFilter — фильтр по связанной записи с подсказками по мере набора. Для справочников, которые не помещаются в панель фильтров списком ссылок.
• Сворачиваемая панель фильтров — щелчок по заголовку «Фильтр» прячет фильтры, и таблица занимает всю ширину. Браузер запоминает выбор для всех списков. Включено по умолчанию.
• Курсор сразу в поле поиска, когда открываются подсказки — в фильтрах и в полях autocomplete_fields на странице записи. Select2 4.0.13, который идёт с Django, с новым jQuery ставит фокус не всегда, и набранные буквы теряются: в Django 4.2 (jQuery 3.6) — после щелчка, в Django 5.0+ (jQuery 3.7) — когда подсказки открывают с клавиатуры.

Пакет на PyPI: pip install django-admin-filter-kit. Зависимостей, кроме Django, нет. Поддерживаются Django 4.2, 5.2, 6.0 и 6.1 на Python 3.10+.

Установка

pip install django-admin-filter-kit

INSTALLED_APPS = [
    "admin_filter_kit",  # выше django.contrib.admin
    "django.contrib.admin",
    # ...
]

Приложение должно стоять выше django.contrib.admin. Скрипты пакета подключают его собственные шаблоны admin/change_list.html и admin/change_form.html — они расширяют шаблоны Django, а Django берёт первый найденный. Если порядок неверный, об этом предупредит проверка admin_filter_kit.W001.

Фильтр с подсказками

from django.contrib import admin

from admin_filter_kit.filters import AutocompleteFilter


@admin.register(Book)
class BookAdmin(admin.ModelAdmin):
    list_filter = [
        ("author", AutocompleteFilter),           # ForeignKey
        ("tags", AutocompleteFilter),             # ManyToManyField
        ("author__country", AutocompleteFilter),  # через связь
    ]


@admin.register(Author)
class AuthorAdmin(admin.ModelAdmin):
    search_fields = ["name"]  # обязательно: подсказки ищут по этим полям

Подсказки приходят из встроенного автокомплита админки — того же, что работает у autocomplete_fields. Поэтому своих адресов у пакета нет, а правила те же:

• у админки связанной модели должны быть search_fields;
• подсказки видит тот, у кого есть право просмотра связанной модели; поиск и сортировка — как в её админке, учитывается limit_choices_to поля;
• подсказки подгружаются по 20 при наборе и прокрутке, подпись записи — str(obj).

Страница списка не загружает справочник целиком — только выбранную запись, чтобы показать её название. Выбор записи перезагружает список с фильтром, × снимает фильтр. Остальные фильтры, поиск и сортировка сохраняются.

Заголовок фильтра по умолчанию — название поля. Свой заголовок и свою логику отбора задают в подклассе: value() возвращает id выбранной записи или None.

class CompanyFilter(AutocompleteFilter):
    title = "компании"

    def queryset(self, request, queryset):
        if self.value() is None:
            return queryset
        # например, документ связан с компанией через любую из двух таблиц
        return queryset.filter(Q(act__company=self.value()) | Q(invoice__company=self.value())).distinct()


list_filter = [("act__company", CompanyFilter)]  # подсказки — по полю act.company

Пока не умеет: выбрать несколько записей сразу и отобрать записи без связи.

Сворачиваемая панель

Работает во всех списках админки, где есть фильтры, — код писать не нужно. Выключить:

ADMIN_FILTER_KIT_COLLAPSIBLE = False

Свои шаблоны админки

Если в проекте переопределён admin/change_list.html или у ModelAdmin задан change_list_template, этот шаблон должен расширять "admin/change_list.html" — как обычно и делают. Иначе скрипты пакета на страницу не попадут, и фильтр с подсказками не заработает. То же со страницей записи: admin/change_form.html и change_form_template должны расширять "admin/change_form.html", иначе курсор в поиске подсказок там ставиться не будет.

Разработка

pip install -e .
python -m django test --settings=tests.settings

Лицензия

MIT