From 868e2fcddae6720d5713924a785339d1665f1bb9 Mon Sep 17 00:00:00 2001 From: sarahboyce Date: Thu, 16 Feb 2023 13:23:24 +0100 Subject: Fixed #32539 -- Added toggleable facet filters to ModelAdmin. Thanks Carlton Gibson, Simon Willison, David Smith, and Mariusz Felisiak for reviews. --- docs/ref/contrib/admin/_images/list_filter.png | Bin 40590 -> 40350 bytes docs/ref/contrib/admin/filters.txt | 11 ++++++ docs/ref/contrib/admin/index.txt | 48 +++++++++++++++++++++++++ 3 files changed, 59 insertions(+) (limited to 'docs/ref') diff --git a/docs/ref/contrib/admin/_images/list_filter.png b/docs/ref/contrib/admin/_images/list_filter.png index 8b6a5a7a54..35d30b8381 100644 Binary files a/docs/ref/contrib/admin/_images/list_filter.png and b/docs/ref/contrib/admin/_images/list_filter.png differ diff --git a/docs/ref/contrib/admin/filters.txt b/docs/ref/contrib/admin/filters.txt index ca8881a645..fc70a1d6b2 100644 --- a/docs/ref/contrib/admin/filters.txt +++ b/docs/ref/contrib/admin/filters.txt @@ -210,3 +210,14 @@ It is possible to specify a custom template for rendering a list filter:: See the default template provided by Django (``admin/filter.html``) for a concrete example. + +.. _facet-filters: + +Facets +====== + +.. versionadded:: 5.0 + +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. diff --git a/docs/ref/contrib/admin/index.txt b/docs/ref/contrib/admin/index.txt index 67007baef2..aa3044e66b 100644 --- a/docs/ref/contrib/admin/index.txt +++ b/docs/ref/contrib/admin/index.txt @@ -1002,6 +1002,54 @@ subclass:: editing, or deleting an object. You can have filters cleared by setting this attribute to ``False``. +.. attribute:: ModelAdmin.show_facets + + .. versionadded:: 5.0 + + Controls whether facet counts are displayed for filters in the admin + changelist. Defaults to :attr:`.ShowFacets.ALLOW`. + + When displayed, facet counts update in line with currently applied filters. + + .. class:: ShowFacets + + .. versionadded:: 5.0 + + Enum of allowed values for :attr:`.ModelAdmin.show_facets`. + + .. attribute:: ALWAYS + + Always show facet counts. + + .. attribute:: ALLOW + + Show facet counts when the ``_facets`` query string parameter is + provided. + + .. attribute:: NEVER + + Never show facet counts. + + Set ``show_facets`` to the desired :class:`.ShowFacets` value. For example, + to always show facet counts without needing to provide the query + parameter:: + + from django.contrib import admin + + + class MyModelAdmin(admin.ModelAdmin): + ... + # Have facets always shown for this model admin. + show_facets = admin.ShowFacets.ALWAYS + + .. admonition:: Performance considerations with facets + + Enabling facet filters will increase the number of queries on the admin + changelist page in line with the number of filters. These queries may + cause performance problems, especially for large datasets. In these + cases it may be appropriate to set ``show_facets`` to + :attr:`.ShowFacets.NEVER` to disable faceting entirely. + .. attribute:: ModelAdmin.radio_fields By default, Django's admin uses a select-box interface (