README.rst

Django Dynamic Filters

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

creating filters

using filters

Requirements

• Django >= 4.0 on Python 3.9+/PyPy3
• django-admin-sortable2 and furl

Installation & Set up

1. Run pip install django-dynamic-filters to install dynfilters.

2. Add "dynfilters" to your INSTALLED_APPS setting like this:

   INSTALLED_APPS = [
       ...
       'adminsortable2',
       'dynfilters',
   ]
   

3. Add "dynfilters" URL to your urls.py file:

   urlpatterns = [
       ...
       path('dynfilters/', include('dynfilters.urls')),
   ]
   

4. Run python manage.py migrate to create the dynfilters models.

5. Run python manage.py collectstatic to install the dynfilters media.

Integration Example

models.py

class Address(models.Model):
    town = models.CharField(max_length=32)

class Person(models.Model):
    first_name = models.CharField(max_length=32)
    last_name = models.CharField(max_length=32)
    birth_date = models.DateField()
    address = models.ForeignKey(Address, on_delete=models.CASCADE)

admin.py

from dynfilters.filters import DynamicFilter

@admin.register(Person)
class PersonAdmin(admin.ModelAdmin):
    ...
    list_filter = (DynamicFilter,)

    dynfilters_fields = [
        '-',
        'first_name',
        'last_name',
        ('first_name|last_name', 'Name'),   # Will generate: Q(first_name=<value>) | Q(last_name=<value>)
        ('birth_date', 'Date of birth'),    # Requires the value to be: DD/MM/YYYY
        '-',
        ('address__town', 'City'),
    ]

    dynfilters_select_related = ['address'] # Optional
    dynfilters_prefetch_related = []        # Optional

Operators & Lookups

The following operators and lookups are supported:

operators

OP_CHOICES = [
    ('-', '-'),
    ('!', 'NOT'),
    ('&', 'AND'),
    ('|', 'OR'),
    ('(', '('),
    (')', ')'),
]

lookups

LOOKUP_CHOICES = [
    ('-', '---------'),
    ('=', 'Equals'),
    ('icontains', 'Contains'),
    ('istartswith', 'Starts with'),
    ('iendswith', 'Ends with'),
    ('in', 'One of'),          # Requires the value to be: aaa,bbb,ccc
    ('-', '---------'),
    ('range', 'Date Range'),   # Requires the value to be: DD/MM/YYYY,DD/MM/YYYY
    ('year', 'Date Year'),
    ('month', 'Date Month'),
    ('day', 'Date Day'),
    ('-', '---------'),
    ('isnull', 'Is NULL'),
    ('isnotnull', 'Is not NULL'),
    ('istrue', 'Is TRUE'),
    ('isfalse', 'Is FALSE'),
    ('-', '---------'),
    ('lt', 'Less Than'),
    ('gt', 'Greater Than'),
    ('lte', 'Less Than or Equal To'),
    ('gte', 'Greater Than or Equal To'),
]

Sharing

There are two ways dynamic filters can be shared:

1. By marking a filter global. The filter will be available to all admin users.
2. By pressing the share icon. The filter can then be shared by email. When the recipients clicks on the received link, a copy of the filter will be created. The edits made to the copy will not affect the original filter.

Alternatives

• Dynfilters was inspired by the look and feel of django-advanced-filters, but is based purely on admin forms and inlines (no JSON).
• Another interesting package is django-filter.
• And yet another one is django-admin-search-builder.