Description

Django-admin-filter is a generic form-based filter for the django-admin-page. It is based on django-filter. It provides a flexible and direct way to filter the items of your changelist and to save and reuse your queries.

Installation

Install from pypi.org:

pip install django-admin-filter

Setup

There are a few things you need to do to use a custom filter-form for your model in your admin changelist:

Add django_admin_filter to your INSTALLED_APPS:

INSTALLED_APPS = [
   'django_admin_filter',
   ...
]

Include the django_admin_filter.urls into your project urlpatterns. The django_admin_filter.urls must precede the admin.site.urls:

urlpatterns = [
   path('admin/', include('django_admin_filter.urls')),
   path('admin/', admin.site.urls),
   ...
]

Add the CustomFilter to the list_filter of your ModelAdmin:

from django_admin_filter.filters import CustomFilter

class MyAdmin(admin.ModelAdmin):
   list_filter = [CustomFilter, ...]
   ...

And setup the filter-class you want to use with your model. This works exactly as described in the django-filter-docs. But to use your filter-class with the django-admin-filter there is one thing to mind: Instead of subclass django_filters.FilterSet:

import django_filters

class MyFilter(django_filters.FilterSet):
   ...

use the AdminFilterSet:

from django_admin_filter.filterset import AdminFilterSet

class MyFilter(AdminFilterSet):
   ...

Configuration

django_admin_filter defines some settings by its own. These settings and their default values are:

ADMIN_FILTER_HISTORY_LIMIT = 3
ADMIN_FILTER_TRUNCATE_HISTORY = True
ADMIN_FILTER_URL_PATH = 'filter/'

<app-label>/<model>/filter/[<pk>]

Usage

The CustomFilter will show up on the right with all the other list filters. It allows you to create new queries - based on your AdminFilterSet - or apply existing queries - either recent ones from the history, or those you created. It is also possible to create globel filter queries that can be used by every user. To do so a user must have an extra permission defined with the FilterQuery model:

"Can handle global FilterQueries"

Users with this permission can commonly create edit and delete global filters.