Defining Filters

Djing filters are simple classes that allow you to scope your Djing index queries with custom conditions.

Select Filters

The most common type of Djing filter is the “select” filter, which allows the user to select a filter option from a drop-down selection menu:

You may generate a select filter using the djing:filter CLI command. By default, Djing will place newly generated filters in the djing_admin/app/Djing/Filters directory:

commander djing:filter UserType

Each select filter generated by Djing contains two methods: apply and options. The apply method is responsible for modifying the underlying Eloquent query to achieve the desired filter state, while the options method defines the “values” the filter may have. Let’s take a look at an example UserType filter:

djing_admin/app/Djing/Filters/UserType.py
from djing.core.Filters.Filter import Filter
from djing.core.Http.Requests.DjingRequest import DjingRequest
from django.db.models import QuerySet


class UserType(Filter):
    component = "select-filter"

    def apply(self, request: DjingRequest, query: QuerySet, value):
        return query.filter(type=value)

    def options(self, request: DjingRequest):
        return {
            "Administrator": "admin",
            "Editor": "editor",
        }

The options method should return an array of keys and values. The array’s keys will be used as the “human-friendly” text that will be displayed in the Djing UI, while the array’s values will be passed into the apply method as the value argument. This filter defines two possible values: admin and editor.

As you can see in the example above, you may leverage the incoming value to modify your query, and the apply method should return the modified query instance.

Boolean Filters

Djing also supports “boolean” filters, which allow the user to select multiple filter options via a list of check-boxes:

You may generate a boolean filter using the djing:filter --boolean CLI command. By default, Djing will place newly generated filters in the djing_admin/app/Djing/Filters directory:

commander djing:filter --boolean

Each boolean filter generated by Djing contains two methods: apply and options. The apply method is responsible for modifying the Eloquent query to achieve the desired filter state, while the options method defines the “values” the filter may have.

When building boolean filters, the value argument passed to the apply method is an associative array containing the boolean value of each of your filter’s options. Let’s take a look at an example UserType filter:

djing_admin/app/Djing/Filters/UserType.py
from djing.core.Filters.Filter import Filter
from djing.core.Http.Requests.DjingRequest import DjingRequest
from django.db.models import QuerySet


class UserType(Filter):
    component = "boolean-filter"

    def apply(self, request: DjingRequest, query: QuerySet, value):
        return query.filter(admin=value['admin']).filter(editor=value['editor'])

The options method should return an array of keys and values. The array’s keys will be used as the “human-friendly” text that will be displayed in the Djing UI. The array’s values will be passed into the apply method as the value argument. This filter defines two possible values: admin and editor.

As you can see in the example above, you may leverage the incoming value to modify your query. The apply method should return the modified query instance.

Date Filters

Djing also supports “date” filters, which allow the user to select the filter’s value via a date selection calendar:

You may generate a date filter using the djing:filter --date CLI command. By default, Djing will place newly generated filters in the djing_admin/app/Djing/Filters directory:

commander djing:filter BirthdayFilter --date

Each date filter generated by Djing contains one method: apply. The apply method is responsible for modifying the query to achieve the desired filter state.

When building date filters, the value argument passed to the apply method is the string representation of the selected date. Let’s take a look at an example BirthdayFilter filter:

djing_admin/app/Djing/Filters/UserType.py
import pendulum

from djing.core.Filters.Filter import Filter
from djing.core.Http.Requests.DjingRequest import DjingRequest
from django.db.models import QuerySet


class UserType(Filter):
    component = "date-filter"

    def apply(self, request: DjingRequest, query: QuerySet, value):
        return query.filter(birthdate__gte=pendulum.parse(value))

Filter Titles

If you would like to change the filter title that is displayed in Djing’s filter selection menu, you may define a name property on the filter class:

djing_admin/app/Djing/Filters/UserType.py
import pendulum

from djing.core.Filters.Filter import Filter
from djing.core.Http.Requests.DjingRequest import DjingRequest
from django.db.models import QuerySet


class UserType(Filter):
    component = "date-filter"
    name = "Filter by User Type"

    # ...

Filter Default Values

If you would like to set the default value of a filter, you may define a default method on the filter class:

djing_admin/app/Djing/Filters/UserType.py
from djing.core.Filters.Filter import Filter
from djing.core.Http.Requests.DjingRequest import DjingRequest
from django.db.models import QuerySet


class UserType(Filter):
    component = "date-filter"
    
    # ...

    def default(self):
        return {
            "admin": True,
            "editor": True,
        }

Last updated