diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/intro/_images/admin13t.png | bin | 26713 -> 25985 bytes | |||
| -rw-r--r-- | docs/ref/contrib/admin/_images/list_filter.png | bin | 40590 -> 40350 bytes | |||
| -rw-r--r-- | docs/ref/contrib/admin/filters.txt | 11 | ||||
| -rw-r--r-- | docs/ref/contrib/admin/index.txt | 48 | ||||
| -rw-r--r-- | docs/releases/5.0.txt | 8 |
5 files changed, 67 insertions, 0 deletions
diff --git a/docs/intro/_images/admin13t.png b/docs/intro/_images/admin13t.png Binary files differindex 3fed5f1985..de20217f2d 100644 --- a/docs/intro/_images/admin13t.png +++ b/docs/intro/_images/admin13t.png diff --git a/docs/ref/contrib/admin/_images/list_filter.png b/docs/ref/contrib/admin/_images/list_filter.png Binary files differindex 8b6a5a7a54..35d30b8381 100644 --- a/docs/ref/contrib/admin/_images/list_filter.png +++ b/docs/ref/contrib/admin/_images/list_filter.png 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 (<select>) for diff --git a/docs/releases/5.0.txt b/docs/releases/5.0.txt index 84689f223d..254654eb7d 100644 --- a/docs/releases/5.0.txt +++ b/docs/releases/5.0.txt @@ -37,6 +37,14 @@ compatible with Django 5.0. What's new in Django 5.0 ======================== +Facet filters in the admin +-------------------------- + +Facet counts are now show for applied filters in the admin changelist when +toggled on via the UI. This behavior can be changed via the new +:attr:`.ModelAdmin.show_facets` attribute. For more information see +:ref:`facet-filters`. + Minor features -------------- |
