Add advanced filtering abilities to Django admin





GitHub Stars



Last Commit

4mos ago










Django Advanced Filters

+-----------+------------------+---------------------+----------+------------+ | Branch | Build | Coverage | PyPI | Gitter | +===========+==================+=====================+==========+============+ | Master | |Build-Master| | |Coverage-Master| | |PyPI| | |Gitter| | +-----------+------------------+---------------------+----------+------------+ | Develop | |Build-Develop| | |Coverage-Develop| | | | +-----------+------------------+---------------------+----------+------------+

A django ModelAdmin mixin which adds advanced filtering abilities to the admin.

Mimics the advanced search feature in VTiger <>, see here for more info <>

.. figure:: :alt: Creating via a modal :width: 768 px

For release notes, see Changelog <>__


  • Django >= 1.9 (Django 1.9 - 3.0 on Python 2/3/PyPy3)
  • simplejson >= 3.6.5, < 4

Installation & Set up

  1. Install from pypi: pip install django-advanced-filters
  2. Add 'advanced_filters' to INSTALLED_APPS.
  3. Add url(r'^advanced_filters/', include('advanced_filters.urls')) to your project's urlconf.
  4. Run python syncdb or python migrate (for django >= 1.7)

Integration Example

Extending a ModelAdmin is pretty straightforward:

.. code-block:: python

from advanced_filters.admin import AdminAdvancedFiltersMixin

class ProfileAdmin(AdminAdvancedFiltersMixin, models.ModelAdmin):
    list_filter = ('name', 'language', 'ts')   # simple list filters

    # specify which fields can be selected in the advanced filter
    # creation form
    advanced_filter_fields = (

        # even use related fields as lookup fields

Adding a new advanced filter (see below) will display a new list filter named "Advanced filters" which will list all the filter the currently logged in user is allowed to use (by default only those he/she created).

Custom naming of fields

Initially, each field in advanced_filter_fields is resolved into an actual model field. That field's verbose_name attribute is then used as the text of the displayed option. While uncommon, it occasionally makes sense to use a custom name, especially when following a relationship, as the context then changes.

For example, when a profile admin allows filtering by a user name as well as a sales representative name, it'll get confusing:

.. code-block:: python

class ProfileAdmin(AdminAdvancedFiltersMixin, models.ModelAdmin):
    advanced_filter_fields = ('name', 'sales_rep__name')

In this case the field options will both be named "name" (by default).

To fix this, use custom naming:

.. code-block:: python

class ProfileAdmin(AdminAdvancedFiltersMixin, models.ModelAdmin):
    advanced_filter_fields = ('name', ('sales_rep__name', 'assigned rep'))

Now, you will get two options, "name" and "assigned rep".

Adding new advanced filters

By default the mixin uses a template which extends django's built-in change_list template. This template is based off of grapelli's fork of this template (hence the 'grp' classes and funny looking javascript).

The default template also uses the superb magnificPopup <dimsemenov/Magnific-Popup>__ which is currently bundled with the application.

Regardless of the above, you can easily write your own template which uses context variables {{ advanced_filters }} and {{ advanced_filters.formset }}, to render the advanced filter creation form.


Each advanced filter has only a couple of required fields when constructed with the form; namely the title and a formset (consisting of a form for each sub-query or rule of the filter query).

Each form in the formset requires the following fields: field, operator, value

And allows the optional negate and remove fields.

Let us go over each of the fields in a rule fieldset.


The list of all available fields for this specific instance of the ModelAdmin as specific by the `advanced_filter_fields property. <#integration-example>`__

The OR field

``OR`` is an additional field that is added to every rule's available

It allows constructing queries with `OR
statements <>`__.
You can use it by creating an "empty" rule with this field "between" a
set of 1 or more rules.


Query field suffixes which specify how the ``WHERE`` query will be

The currently supported are as follows: ``iexact``, ``icontains``,
``iregex``, ``range``, ``isnull``, ``istrue`` and ``isfalse``

For more detail on what they mean and how they function, see django's
`documentation on field
lookups <>`__.


The value which the specific sub-query will be looking for, i.e the
value of the field specified above, or in django query syntax:


A boolean (check-box) field to specify whether this rule is to be
negated, effectively making it a "exclude" sub-query.


Similarly to other `django
formsets <>`__,
used to remove the selected line on submit.

Editing previously created advanced filters

The ``AdvancedFilterAdmin`` class (a subclass of ``ModelAdmin``) is
provided and registered with ``AdvancedFilter`` in module.

The model's change\_form template is overridden from grapelli's/django's
standard template, to mirror the add form modal as closely as possible.

*Note:* currently, adding new filters from the ModelAdmin change page is
not supported.

Query Serialization

**TODO:** write a few words on how serialization of queries is done.

Model correlation

Since version 1.0, ``AdvancedFilter`` are tightly coupled with a specific model
using the ``model`` field and the app\_label.Name template.
On creation, ``model`` is populated based on the admin changelist it's created

This change has a few benefits:

1. The mixin can be used with multiple ``ModelAdmin`` classes while
   performing specific query serialization and field validation that are
   at the base of the filter functionality.

2. Users can edit previously created filters outside of the
   context of a changelist, as we do in the
   ```AdvancedFilterAdmin`` <#editing-previously-created-advanced-filters>`__.

3. Limit the ``AdvancedListFilters`` to limit queryset (and thus, the
   underlying options) to a specified model.


The GetFieldChoices view is required to dynamically (using javascript)
fetch a list of valid field choices when creating/changing an


-  Add permission user/group selection functionality to the filter form
-  Allow toggling of predefined templates (grappelli / vanilla django
   admin), and front-end features.
-  Support more (newer) python/django versions

.. |Build-Master| image::
.. |Coverage-Master| image::
.. |PyPI| image::
.. |Gitter| image::
.. |Build-Develop| image::
.. |Coverage-Develop| image::

Rate & Review

Great Documentation0
Easy to Use0
Highly Customizable0
Bleeding Edge0
Responsive Maintainers0
Poor Documentation0
Hard to Use0
Unwelcoming Community0