1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221
|
.. _modeladmin-list-filters:
===========================
``ModelAdmin`` List Filters
===========================
.. currentmodule:: django.contrib.admin
``ModelAdmin`` classes can define list filters that appear in the right sidebar
of the change list page of the admin, as illustrated in the following
screenshot:
.. image:: _images/list_filter.png
To activate per-field filtering, set :attr:`ModelAdmin.list_filter` to a list
or tuple of elements, where each element is one of the following types:
- A field name.
- A subclass of ``django.contrib.admin.SimpleListFilter``.
- A 2-tuple containing a field name and a subclass of
``django.contrib.admin.FieldListFilter``.
See the examples below for discussion of each of these options for defining
``list_filter``.
Using a field name
==================
The simplest option is to specify the required field names from your model.
Each specified field should be either a ``BooleanField``, ``CharField``,
``DateField``, ``DateTimeField``, ``IntegerField``, ``ForeignKey`` or
``ManyToManyField``, for example::
class PersonAdmin(admin.ModelAdmin):
list_filter = ["is_staff", "company"]
Field names in ``list_filter`` can also span relations
using the ``__`` lookup, for example::
class PersonAdmin(admin.UserAdmin):
list_filter = ["company__name"]
Using a ``SimpleListFilter``
============================
For custom filtering, you can define your own list filter by subclassing
``django.contrib.admin.SimpleListFilter``. You need to provide the ``title``
and ``parameter_name`` attributes, and override the ``lookups`` and
``queryset`` methods, e.g.::
from datetime import date
from django.contrib import admin
from django.utils.translation import gettext_lazy as _
class DecadeBornListFilter(admin.SimpleListFilter):
# Human-readable title which will be displayed in the
# right admin sidebar just above the filter options.
title = _("decade born")
# Parameter for the filter that will be used in the URL query.
parameter_name = "decade"
def lookups(self, request, model_admin):
"""
Returns a list of tuples. The first element in each
tuple is the coded value for the option that will
appear in the URL query. The second element is the
human-readable name for the option that will appear
in the right sidebar.
"""
return [
("80s", _("in the eighties")),
("90s", _("in the nineties")),
]
def queryset(self, request, queryset):
"""
Returns the filtered queryset based on the value
provided in the query string and retrievable via
`self.value()`.
"""
# Compare the requested value (either '80s' or '90s')
# to decide how to filter the queryset.
if self.value() == "80s":
return queryset.filter(
birthday__gte=date(1980, 1, 1),
birthday__lte=date(1989, 12, 31),
)
if self.value() == "90s":
return queryset.filter(
birthday__gte=date(1990, 1, 1),
birthday__lte=date(1999, 12, 31),
)
class PersonAdmin(admin.ModelAdmin):
list_filter = [DecadeBornListFilter]
.. note::
As a convenience, the ``HttpRequest`` object is passed to the ``lookups``
and ``queryset`` methods, for example::
class AuthDecadeBornListFilter(DecadeBornListFilter):
def lookups(self, request, model_admin):
if request.user.is_superuser:
return super().lookups(request, model_admin)
def queryset(self, request, queryset):
if request.user.is_superuser:
return super().queryset(request, queryset)
Also as a convenience, the ``ModelAdmin`` object is passed to the
``lookups`` method, for example if you want to base the lookups on the
available data::
class AdvancedDecadeBornListFilter(DecadeBornListFilter):
def lookups(self, request, model_admin):
"""
Only show the lookups if there actually is
anyone born in the corresponding decades.
"""
qs = model_admin.get_queryset(request)
if qs.filter(
birthday__gte=date(1980, 1, 1),
birthday__lte=date(1989, 12, 31),
).exists():
yield ("80s", _("in the eighties"))
if qs.filter(
birthday__gte=date(1990, 1, 1),
birthday__lte=date(1999, 12, 31),
).exists():
yield ("90s", _("in the nineties"))
Using a field name and an explicit ``FieldListFilter``
======================================================
Finally, if you wish to specify an explicit filter type to use with a field you
may provide a ``list_filter`` item as a 2-tuple, where the first element is a
field name and the second element is a class inheriting from
``django.contrib.admin.FieldListFilter``, for example::
class PersonAdmin(admin.ModelAdmin):
list_filter = [
("is_staff", admin.BooleanFieldListFilter),
]
Here the ``is_staff`` field will use the ``BooleanFieldListFilter``. Specifying
only the field name, fields will automatically use the appropriate filter for
most cases, but this format allows you to control the filter used.
The following examples show available filter classes that you need to opt-in
to use.
You can limit the choices of a related model to the objects involved in
that relation using ``RelatedOnlyFieldListFilter``::
class BookAdmin(admin.ModelAdmin):
list_filter = [
("author", admin.RelatedOnlyFieldListFilter),
]
Assuming ``author`` is a ``ForeignKey`` to a ``User`` model, this will
limit the ``list_filter`` choices to the users who have written a book,
instead of listing all users.
You can filter empty values using ``EmptyFieldListFilter``, which can
filter on both empty strings and nulls, depending on what the field
allows to store::
class BookAdmin(admin.ModelAdmin):
list_filter = [
("title", admin.EmptyFieldListFilter),
]
By defining a filter using the ``__in`` lookup, it is possible to filter for
any of a group of values. You need to override the ``expected_parameters``
method, and the specify the ``lookup_kwargs`` attribute with the appropriate
field name. By default, multiple values in the query string will be separated
with commas, but this can be customized via the ``list_separator`` attribute.
The following example shows such a filter using the vertical-pipe character as
the separator::
class FilterWithCustomSeparator(admin.FieldListFilter):
# custom list separator that should be used to separate values.
list_separator = "|"
def __init__(self, field, request, params, model, model_admin, field_path):
self.lookup_kwarg = "%s__in" % field_path
super().__init__(field, request, params, model, model_admin, field_path)
def expected_parameters(self):
return [self.lookup_kwarg]
.. note::
The :class:`~django.contrib.contenttypes.fields.GenericForeignKey` field is
not supported.
List filters typically appear only if the filter has more than one choice. A
filter's ``has_output()`` method controls whether or not it appears.
It is possible to specify a custom template for rendering a list filter::
class FilterWithCustomTemplate(admin.SimpleListFilter):
template = "custom_template.html"
See the default template provided by Django (``admin/filter.html``) for a
concrete example.
.. _facet-filters:
Facets
======
By default, counts for each filter, known as facets, can be shown by toggling
on via the admin UI. These counts will update according to the currently
applied filters. See :attr:`ModelAdmin.show_facets` for more details.
|